【Spring AI 实战】基于 Docker Model Runner 构建本地化 AI 聊天服务：从配置到函数调用全解析

【Spring AI 实战】基于 Docker Model Runner 构建本地化 AI 聊天服务：从配置到函数调用全解析

前沿：本地化 AI 推理的新范式

随着大语言模型（LLM）应用的普及，本地化部署与灵活扩展成为企业级 AI 开发的核心需求。Docker Model Runner 作为 Docker 官方推出的 AI 推理引擎，支持集成多厂商模型并提供标准化 API，结合 Spring AI 的强大生态，可快速构建低成本、高可控的本地化聊天服务。本文将深入解析如何通过 Spring AI 与 Docker Model Runner 的无缝集成，实现开箱即用的 LLM 功能，涵盖环境配置、属性调优、函数调用等核心技术点。

一、环境准备：搭建 Docker Model Runner 基础架构

1. 前提条件

• Docker Desktop 安装：下载并安装适用于 Mac 的 Docker Desktop 4.40.0（其他平台请对应选择）。
• 启用 Model Runner：
  选项 1（直接启用）：

  docker desktop enable model-runner --tcp 12434
  

  基 URL 配置为 http://localhost:12434/engines。
  选项 2（Testcontainers 容器化）：
  通过 Socat 容器映射端口，适用于自动化测试：

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

2. Spring AI 依赖配置

在 pom.xml 或 build.gradle 中引入最新 Starter：

<!-- Maven -->
<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

// Gradle
implementation 'org.springframework.ai:spring-ai-starter-model-openai'

二、核心配置：从连接到模型调优

1. 基础连接配置

通过 application.properties 配置 Docker Model Runner 端点：

spring.ai.openai.api-key=test          # 任意有效字符串（非真实 OpenAI Key）
spring.ai.openai.base-url=http://localhost:12434/engines  # Model Runner 引擎端点
spring.ai.openai.chat.options.model=ai/gemma3:4B-F16      # 选择目标模型（需与 Model Runner 支持的镜像匹配）

2. 聊天属性深度解析

Spring AI 提供细粒度配置，支持重试策略、连接参数及模型行为调优，以下为核心属性表：

重试策略（前缀：spring.ai.retry）

属性名称	描述	默认值
max-attempts	最大重试次数	10
backoff.initial-interval	初始回退间隔（秒）	2
backoff.multiplier	回退间隔乘数（指数增长因子）	5
backoff.max-interval	最大回退间隔（秒）	180
on-client-errors	是否重试 4xx 错误	false

模型行为配置（前缀：spring.ai.openai.chat.options）

属性名称	描述	默认值
temperature	输出随机性控制（0-1，越高越随机）	0.8
max-tokens	最大生成令牌数	无限制（受模型上下文限制）
frequencyPenalty	重复令牌惩罚（-2.0~2.0）	0.0
responseFormat	强制输出 JSON 格式	无
tools	允许调用的工具列表	无

多模型管理

通过 spring.ai.model.chat 开关启用/禁用 OpenAI 聊天模型：

spring.ai.model.chat=openai  # 启用 OpenAI 聊天模型（默认）
# spring.ai.model.chat=none  # 禁用聊天模型

三、进阶功能：函数调用与流式响应

1. 智能工具集成（函数调用）

Docker Model Runner 支持模型自动触发注册函数，实现外部服务交互。
示例代码：

@SpringBootApplication
public class DockerModelRunnerDemo {@Bean@Description("获取指定地点天气")public Function<WeatherRequest, WeatherResponse> weatherFunction() {return request -> {double temp = "Amsterdam".equals(request.location()) ? 20 : 25;return new WeatherResponse(temp, request.unit());};}@BeanCommandLineRunner runner(ChatClient chatClient) {return args -> {String response = chatClient.prompt().user("巴黎和阿姆斯特丹的天气如何？").functions("weatherFunction")  // 引用 Bean 名称.call().content();System.out.println(response);  // 输出：阿姆斯特丹 20℃，巴黎 25℃};}
}record WeatherRequest(String location, String unit) {}
record WeatherResponse(double temp, String unit) {}

2. 流式响应实现

通过 stream() 方法支持实时逐令牌输出，提升交互体验：

@RestController
public class ChatController {private final OpenAiChatModel chatModel;@GetMapping("/ai/generateStream")public Flux<ChatResponse> generateStream(@RequestParam String message) {Prompt prompt = new Prompt(new UserMessage(message));return chatModel.stream(prompt);  // 流式返回响应}
}

四、实战示例：构建基础聊天接口

1. 控制器实现

创建 REST 端点处理用户输入并返回生成结果：

@RestController
public class ChatController {private final OpenAiChatModel chatModel;@Autowiredpublic ChatController(OpenAiChatModel chatModel) {this.chatModel = chatModel;}@GetMapping("/ai/generate")public Map<String, String> generate(@RequestParam String message) {String response = chatModel.call(message);  // 同步调用模型return Collections.singletonMap("result", response);}
}

2. 禁用无关功能（如 Embedding）

由于 Docker Model Runner 暂不支持 Embedding，需显式关闭：

spring.ai.openai.embedding.enabled=false

五、最佳实践与注意事项

1. 模型选择：确保 spring.ai.openai.chat.options.model 与 Model Runner 中加载的镜像标签一致（如 ai/gemma3:4B-F16）。
2. 性能优化：通过降低 temperature（如 0.5）提升输出确定性，或调整 max-tokens 避免超长响应。
3. 错误处理：利用 retry.exclude-on-http-codes 排除无需重试的状态码（如 404），减少无效重试。

总结：本地化 AI 开发的破局之道

本文通过 Docker Model Runner 与 Spring AI 的集成实践，展示了如何快速构建可控、可扩展的本地化聊天服务。核心优势包括：

• 低成本部署：无需依赖云端 API，降低数据传输延迟与成本；
• 灵活扩展：支持多模型热插拔，通过函数调用无缝连接外部服务；
• 企业级适配：细粒度的配置体系满足高可用、高性能需求。

随着 AI 应用的落地深化，本地化推理与框架级集成将成为企业构建智能应用的核心竞争力。通过 Spring AI 的标准化接口与 Docker Model Runner 的模型管理能力，开发者可聚焦业务逻辑，加速 AI 功能落地。

延伸阅读：

• Spring AI 升级指南
• OpenAI 函数调用规范