SpringAI+Docker Model Runner实现本地运行LLM

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 应用。

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 框架集成，从而降低开发开销。

设置环境
本节概述了使用 Docker Model Runner 和 Maven 依赖项创建使用 Model Runner 的 Spring AI 应用程序的先决条件。

1. 先决条件
要使用 Docker Model Runner，我们需要一些东西：

Docker Desktop 4.40 或更高版本：安装在带有 Apple Silicon 的 Mac 上。

Java 21 或更高版本：Spring AI 开发所需。

与 Model Runner 兼容的 LLM：与 Docker Model Runner 兼容的模型，例如 LLaMA 或 Gemma 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>

启用并配置 Docker Model Runner
本节概述了启用 Docker Model Runner 并使用两种不同的方法提取特定模型的步骤。

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/gemma3

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");
        };
    }
}

3. 提取并验证 Gemma 3 模型
现在，使用其中一个选项启用 Model Runner 后，我们拉取 Gemma 3 模型：

docker model pull ai/gemma3

然后，我们可以确认它在本地可用：

docker model list

此命令列出所有本地可用的模型，包括ai/gemma3。

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

1. 使用特定 TCP 端口测试模型运行器
要使用 Docker Model Runner，我们需要配置 OpenAI 客户端以指向正确的端点，并使用之前拉取的模型。现在，我们启动应用程序并测试/chat端点：

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

响应将由在 Model Runner 中运行的 Gemma 3 模型生成。

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 服务端点。