知識庫 / Spring / Spring AI RSS 訂閱

1. 簡介

Docker Model Runner，於 Docker Desktop 4.40 for Mac with Apple Silicon（當時撰寫本文時）推出，通過簡化大型語言模型（LLM）的部署和管理，徹底改變了本地 AI 開發方式。它解決了諸如複雜的設置流程、高昂的雲端推理成本和數據隱私問題等常見挑戰。

通過提供 OpenAI 兼容的 Inference API，Model Runner 能夠實現無縫集成，例如與 Spring AI 等框架的集成，從而使開發者能夠輕鬆地在本地構建 AI 驅動的應用。在本教程中，我們將學習如何設置 Docker Model Runner 並創建一個與之連接的 Spring AI 應用。 屆時，我們將會擁有一個完全功能完備的本地 AI 應用，它將利用一個強大的 LLM。

2. Docker 模型運行器

Docker 模型運行器是一個旨在簡化 LLM 在 Docker 容器內的部署和執行的工具。它是一個 AI 推理引擎，提供來自各種提供商的大量模型。

讓我們看看 Docker 模型運行器包含的主要功能：

• 簡化模型部署：模型以標準開放容器倡議 (OCI) 規範的 Artifact 在 Docker Hub 上發佈，在 ai 命名空間 下，這使得在 Docker Desktop 中輕鬆拉取、運行和管理 AI 模型。

• 廣泛的模型支持：支持來自多個提供商的各種 LLM，例如 Mistral、LLaMA 和 Phi-4，確保模型選擇的靈活性。

• 本地推理：模型在本地運行，增強了數據隱私並消除了對基於雲的推理的依賴。

• OpenAI 兼容 API：提供標準化的 API，可以無縫地與現有 AI 框架集成，從而減少開發負擔。

3. 環境搭建

本節概述了使用 Docker Model Runner 和 Maven 依賴項創建 Spring AI 應用（該應用使用 Model Runner）的先決條件。

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 依賴

讓我們首先導入以下依賴項到 <pom.xml> 中：spring-boot-starter-web, spring-ai-openai-spring-boot-starter, spring-ai-spring-boot-testcontainers, 以及 junit-jupiter。

<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 模型運行器

本部分概述了使用兩種不同方法啓用 Docker 模型運行器並拉取特定模型所需的步驟。

4.1. 使用特定 TCP 端口啓用 Model Runner

首先，啓用 Model Runner 並將其暴露在特定 TCP 端口上（例如，12434）：

docker desktop enable model-runner --tcp 12434

此配置使 Model Runner 監聽 http://localhost:12434/engines。 在我們的 Spring AI 應用程序中，我們需要配置 api-key、model 和基本 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/gemma3

4.2. 啓用模型運行器與 Testcontainers

可以使用以下命令啓用模型運行器，無需指定端口：

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 配置 AI 客户端，一個測試 API 密鑰 (test-api-key)，以及一個模型標識符 (ai/gemma3)。@TestConfiguration(proxyBeanMethods = false) 註解確保在測試期間輕量級 Bean 創建，無需進行代理。這種設置使測試能夠模擬 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 端口測試 Model Runner

要使用 Docker Model Runner，我們需要配置 OpenAI 客户端指向正確的端點，並使用之前拉取的模型。 現在，我們啓動應用程序並測試 chat/em> 端點：

curl "http://localhost:8080/chat?prompt=What%20is%20the%20future%20of%20AI%20development?"

@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();
    }
}