本部落格文章由 Eddú Meléndez 撰寫。

Docker 最近在 Apple silicon 上釋出了 Docker Desktop for Mac 4.40.0 中的 Model Runner。Docker Model Runner 提供了一個設計用於相容 OpenAI API 的本地推理 API，作為 Spring AI 1.0.0-M7 版本的一部分，可以輕鬆與 Spring AI 整合。模型以標準的 OCI artifact 形式分發在 Docker Hub 的 ai 名稱空間下。

先決條件

• 下載 Docker Desktop for Mac 4.40.0。

• 選擇以下任一選項啟用 Model Runner

  選項 1

• 啟用 Model Runner `docker desktop enable model-runner --tcp 12434`。

• 將 base-url 設定為 `https://:12434/engines\`

  選項 2

• 啟用 Model Runner `docker desktop enable model-runner`。

• 使用 Testcontainers 並按如下設定 base-url

@Container
private static final SocatContainer socat = new SocatContainer().withTarget(80, "model-runner.docker.internal");

@Bean
public OpenAiApi chatCompletionApi() {
	var baseUrl = "http://%s:%d/engines".formatted(socat.getHost(), socat.getMappedPort(80));
	return OpenAiApi.builder().baseUrl(baseUrl).apiKey("test").build();
}

接下來，拉取模型 `docker model pull ai/gemma3` 並透過 `docker model list` 確認其在本地可用

依賴

訪問 start.spring.io，選擇 Spring Web、OpenAI 和 Testcontainers，然後生成專案。

必須列出以下依賴

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-spring-boot-testcontainers</artifactId>
	<scope>test</scope>
</dependency>

此外，請確保 Spring AI BOM 已包含

<dependencyManagement>
	<dependencies>
		<dependency>
			<groupId>org.springframework.ai</groupId>
			<artifactId>spring-ai-bom</artifactId>
			<version>${spring-ai.version}</version>
			<type>pom</type>
			<scope>import</scope>
		</dependency>
	</dependencies>
</dependencyManagement>

配置 Spring AI

要使用 Docker Model Runner，我們需要配置 OpenAI 客戶端指向正確的端點，並使用之前拉取的模型

對於選項 1：讓我們配置 src/main/resources/application.properties

spring.ai.openai.api-key=ignored
spring.ai.openai.base-url=https://:12434/engines
spring.ai.openai.chat.options.model=ai/gemma3

對於選項 2（使用 Testcontainers）：讓我們前往 `TestcontainersConfiguration`，定義 `SocatContainer` bean 並使用 `DynamicPropertyRegistrar` bean 註冊屬性。

@TestConfiguration(proxyBeanMethods = false)
class TestcontainersConfiguration {

    @Bean
    SocatContainer socat() {
        return new SocatContainer(DockerImageName.parse("alpine/socat:1.8.0.1"))
                .withTarget(80, "model-runner.docker.internal");
    }
    
    @Bean
    DynamicPropertyRegistrar properties(SocatContainer socat) {
        return (registrar) -> {
            registrar.add("spring.ai.openai.base-url", () -> "http://%s:%d/engines".formatted(socat.getHost(), socat.getMappedPort(80)));
            registrar.add("spring.ai.openai.api-key", () -> "test-api-key");
            registrar.add("spring.ai.openai.chat.options.model", () -> "ai/gemma3");
        };
    }
}

聊天示例

現在，讓我們建立一個簡單的控制器

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return this.chatClient.prompt()
                .user(message)
                .call()
                .content();
    }

   @GetMapping("/chat-stream")
    public Flux<String> chatStream(@RequestParam String message) {
        return this.chatClient.prompt()
                .user(message)
                .stream()
                .content();
    }

}

使用 `./mvnw spring-boot:test-run` 執行應用程式

使用 httpie 呼叫 `/chat` 端點

http :8080/chat message=="tell me a joke"

我們也可以呼叫 `/chat-stream` 端點

http :8080/chat-stream message=="tell me a haiku about docker containers"

工具示例

如果與支援工具呼叫的模型一起使用，Docker Model Runner 當然也支援工具呼叫。

建立一個 `FunctionCallConfig` 類並新增一個簡單函式

@Configuration(proxyBeanMethods = false)
class FunctionCallConfig {

    @Bean
    @Description("Get the stock price")
    public Function<MockStockService.StockRequest, MockStockService.StockResponse> stockFunction() {
        return new MockStockService();
    }

    static class MockStockService implements Function<MockStockService.StockRequest, MockStockService.StockResponse> {

        public record StockRequest(String symbol) {}
        public record StockResponse(double price) {}

        @Override
        public StockResponse apply(StockRequest request) {
            double price = request.symbol().contains("AAPL") ? 198 : 114;
            return new StockResponse(price);
        }
    }
    
}

現在，讓我們註冊 `stockFunction` 函式

@GetMapping("/stocks")
public String stocks(@RequestParam String message) {
    return this.chatClient.prompt()
            .user(message)
            .tools("stockFunction")
            .call()
            .content();
}

執行應用程式 `./mvnw spring-boot:test-run` 並呼叫 `/stocks` 端點

http :8080/stocks message=="What's AAPL and NVDA stock price?"

根據我們設定的硬編碼值，響應應類似於 `AAPL stock price is 198.0 and NVDA stock price is 114.0.`。

參考資料

• 引入 Docker Model Runner https://www.docker.com/blog/introducing-docker-model-runner/

• 使用 Docker 在本地執行 LLMs：Model Runner 快速入門指南 https://www.docker.com/blog/run-llms-locally/

• Docker Model Runner 文件 https://docs.container.club.tw/desktop/features/model-runner/

• Spring AI Docker Model Runner 示例 https://github.com/eddumelendez/spring-ai-dmr

結論

Docker Model Runner 使您能夠更快地迭代，保持本地化並訪問相容 OpenAI 的 API。它透過實現與 Spring AI 的 OpenAI 模組的無縫整合來簡化開發體驗，讓開發人員能夠在其熟悉的內部開發迴圈工具中工作。這使團隊能夠以自己的節奏在本地、安全、高效地構建和測試 AI 應用程式。未來，與 Testcontainers 的整合將使得按需拉取和執行模型變得更加容易，進一步簡化了設定和測試工作流程。