Spring AI 與 Docker 模型運行器
1. 簡介
Docker Model Runner是在搭載 Apple Silicon 的 Mac 版 Docker Desktop 4.40 中引入的（截至本文撰寫時），它透過簡化大型語言模型 (LLM) 的部署和管理，徹底改變了本地 AI 開發。它解決了一些常見的挑戰，例如複雜的設定流程、高昂的雲端推理成本以及資料隱私問題。
透過提供與 OpenAI 相容的推理 API，Model Runner 能夠與 Spring AI 等框架無縫集成，讓開發者能夠輕鬆地在本地建立 AI 應用。在本教程中，我們將學習如何設定 Docker Model Runner 並建立一個連接到它的 Spring AI 應用程式。最終，我們將擁有一個功能齊全、利用強大 LLM 的本地 AI 應用程式。
2. Docker 模型運行器
Docker Model Runner 是一款旨在簡化 Docker 容器內 LLM 部署和執行的工具。它是一個 AI 推理引擎，提供來自不同供應商的多種模型。
讓我們看看 Docker Model Runner 包含的主要功能：
簡化的模型部署：模型作為標準開放容器計劃 (OCI) 工件分發到 Docker Hub 上的ai 命名空間下。這使得在 Docker Desktop 中直接提取、運行和管理 AI 模型變得非常容易。
廣泛的模型支援：支援來自多個提供者的各種 LLM，例如 Mistral、LLaMA 和 Phi-4，確保模型選擇的靈活性。
本地推理：在本地運行模型，增強資料隱私並消除對基於雲端的推理的依賴。
OpenAI 相容 API ：提供標準化 API，可輕鬆與現有 AI 框架集成，從而降低開發開銷。
3. 設定環境
本節概述了使用 Docker Model Runner 和 Maven 依賴項建立使用 Model Runner 的 Spring AI 應用程式的先決條件。
3.1. 先決條件
要使用 Docker Model Runner，我們需要一些東西：
Docker Desktop 4.40 或更高版本：安裝在具有 Apple Silicon 的 Mac 上。
Java 21 或更高版本：Spring AI 開發所需。
與 Model Runner 相容的 LLM ：與 Docker Model Runner 相容的模型，例如 LLaMA 或 Gemma 3。
3.2. Maven 依賴項
讓我們先將spring-boot-starter-web 、 spring-ai-openai-spring-boot-starter 、 spring-ai-spring-boot-testcontainers和junit-jupiter依賴項匯入pom.xml ：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>1.0.0-M6</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
<version>1.0.0-M6</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-spring-boot-testcontainers</artifactId>
<version>1.0.0-M6</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<version>1.19.8</version>
<scope>test</scope>
</dependency>4. 啟用並配置 Docker Model Runner
本節概述了啟用 Docker Model Runner 並使用兩種不同的方法來提取特定模型的步驟。
4.1. 使用特定 TCP 連接埠啟用模型運行器
首先，讓我們啟用 Model Runner 並將其公開在特定的 TCP 連接埠上（例如 12434）：
docker desktop enable model-runner --tcp 12434這將配置 Model Runner 監聽http://localhost:12434/engines 。在我們的 Spring AI 應用程式中，我們需要配置api-key 、 model和 base URL 以指向 Model Runner 端點：
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.base-url=http://localhost:12434/engines
spring.ai.openai.chat.options.model=ai/gemma34.2. 使用測試容器啟用模型運行器
我們可以運行以下命令來啟用 Model Runner，而無需指定連接埠：
docker desktop enable model-runner這將設定 Model Runner 在預設的內部 Docker 網路上運行。然後，我們使用 Testcontainers 並設定base-url 、 api-key和model ，如下所示：
@TestConfiguration(proxyBeanMethods = false)
class TestcontainersConfiguration {
@Bean
DockerModelRunnerContainer socat() {
return new DockerModelRunnerContainer("alpine/socat:1.8.0.1");
}
@Bean
DynamicPropertyRegistrar properties(DockerModelRunnerContainer dmr) {
return (registrar) -> {
registrar.add("spring.ai.openai.base-url", dmr::getOpenAIEndpoint);
registrar.add("spring.ai.openai.api-key", () -> "test-api-key");
registrar.add("spring.ai.openai.chat.options.model", () -> "ai/gemma3");
};
}
}提供的TestcontainersConfiguration類別是 Spring Boot @TestConfiguration專為與 Testcontainers 進行整合測試而設計。它定義了兩個 bean：一個DockerModelRunnerContainer ，它使用alpine/socat:1.8.0.1映像啟動 Docker 容器，可能代理或模擬 AI 服務端點；以及一個DynamicPropertyRegistrar ，它動態地設定 Spring AI 屬性。這些屬性使用來自容器端點的基本 URL（透過getOpenAIEndpoint() ）、測試 API 金鑰（ test-api-key ）和模型識別碼（ ai/gemma3 ）來配置 AI 用戶端。 @TestConfiguration(proxyBeanMethods = false)註解確保建立輕量級 bean 以進行測試而無需代理。此設定使socat能夠模擬沒有外部相依性的 AI 服務環境，使用socat容器來處理請求。 socat 將流量轉送到內部model-runner.docker.internal服務。
4.3. 擷取並驗證 Gemma 3 模型
現在，使用其中一個選項啟用 Model Runner 後，我們拉取 Gemma 3 模型：
docker model pull ai/gemma3然後，我們可以確認它在本地可用：
docker model list此命令列出所有本地可用的模型，包括ai/gemma3 。
5. 與 Spring AI 集成
現在，讓我們建立一個簡單的控制器來與模型互動：
@RestController
class ModelRunnerController {
private final ChatClient chatClient;
public ModelRunnerController(ChatClient.Builder chatClientBuilder) {
this.chatClient = chatClientBuilder.build();
}
@GetMapping("/chat")
public String chat(@RequestParam("message") String message) {
return this.chatClient.prompt()
.user(message)
.call()
.content();
}
}5.1. 使用特定 TCP 連接埠測試模型運行器
要使用 Docker Model Runner，我們需要配置 OpenAI 用戶端以指向正確的端點，並使用先前拉取的模型。現在，我們啟動應用程式並測試/chat端點：
curl "http://localhost:8080/chat?prompt=What%20is%20the%20future%20of%20AI%20development?"響應將由在 Model Runner 中運行的 Gemma 3 模型產生。
5.2. 使用 Testcontainers 測試模型運行器
讓我們建立ModelRunnerApplicationTest類別。它將導入TestcontainersConfiguration類別並呼叫範例控制器：
@Import(TestcontainersConfiguration.class)
class ModelRunnerApplicationTest {
// ...
@Test
void givenMessage_whenCallChatController_thenSuccess() {
// given
String userMessage = "Hello, how are you?";
// when
ResponseEntity<String> response = restTemplate.getForEntity(
baseUrl + "/chat?message=" + userMessage, String.class);
// then
assertThat(response.getStatusCode().is2xxSuccessful()).isTrue();
assertThat(response.getBody()).isNotEmpty();
}
}
@Import(TestcontainersConfiguration.class)導入TestcontainersConfiguration類，該類定義了一個DockerModelRunnerContainer （運行alpine/socat:1.8.0.1 ）。此外，它還動態註冊了 Spring AI 屬性（例如spring.ai.openai.base-url 、 spring.ai.openai.api-key 、 spring.ai.openai.chat.options.model ）。這確保測試環境配置了由 Testcontainers 管理的容器提供的模擬 AI 服務端點。
6. 結論
Docker Model Runner 提供了一種開發者友好、注重隱私且經濟高效的本地運行 LLM 解決方案，尤其適合在 Docker 生態系統中建立 GenAI 應用程式的用戶。在本文中，我們探討了 Docker Model Runner 的功能，並展示了它與 Spring AI 的整合。與往常一樣，原始碼可在 GitHub 上取得。