当前位置：首页 > news >正文

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

news 来源：原创 2025/8/7 8:36:26

【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

五、最佳实践与注意事项

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

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

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

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

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

延伸阅读：

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