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

news2025/5/11 12:57:04

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

    @Bean
    CommandLineRunner 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;

    @Autowired
    public 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），减少无效重试。