云虚拟机可以做几个网站网站seo基础

【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 函数调用规范