Docker Model Runner 聊天

Docker Model Runner 是一个 AI 推理引擎，提供来自各类服务商的广泛模型。

Spring AI 通过复用现有的、由 OpenAI 支撑的 ChatClient 来与 Docker Model Runner 集成。 为此，把基础 URL 设为 http://localhost:12434/engines/v1，并从所提供的 LLM 模型中选择一个。

查看 DockerModelRunnerWithOpenAiChatModelIT.java 测试 以获取如何在 Spring AI 中使用 Docker Model Runner 的示例。

前置条件

• 下载 Docker Desktop for Mac 4.40.0。

选择以下选项之一来启用 Model Runner：

选项 1：

• 启用 Model Runner docker desktop enable model-runner --tcp 12434。
• 把 base-url 设为 http://localhost:12434/engines/v1

选项 2：

• 启用 Model Runner docker desktop enable model-runner。
• 使用 Testcontainers 并按如下方式设置 base-url：

@Container
private static final DockerModelRunnerContainer DMR = new DockerModelRunnerContainer("alpine/socat:1.7.4.3-r0");

@Bean
public OpenAiChatModel chatModel() {
	var baseUrl = DMR.getOpenAIEndpoint();
	return OpenAiChatModel.builder()
		.options(OpenAiChatOptions.builder().baseUrl(baseUrl).apiKey("test").build())
		.build();
}

你可以通过阅读 Run LLMs Locally with Docker 博客文章，更多了解 Docker Model Runner。

自动配置

NOTE

自 1.0.0.M7 起，Spring AI starter 模块的 artifact ID 已重命名。依赖名现在应遵循为模型、向量库和 MCP starters 更新的命名模式。 更多信息请参阅升级说明。

Spring AI 为 OpenAI 聊天客户端提供 Spring Boot 自动配置。 要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 文件：

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

或将以下内容添加到你的 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

聊天属性

重试属性

前缀 spring.ai.retry 用作配置 OpenAI 聊天模型重试机制的属性前缀。

属性	描述	默认值
spring.ai.retry.max-attempts	最大重试尝试次数。	10
spring.ai.retry.backoff.initial-interval	指数退避策略的初始等待时长。	2 sec.
spring.ai.retry.backoff.multiplier	退避间隔乘数。	5
spring.ai.retry.backoff.max-interval	最大退避时长。	3 min.
spring.ai.retry.on-client-errors	若为 false，则抛出 NonTransientAiException，不对 4xx 客户端错误码尝试重试	false
spring.ai.retry.exclude-on-http-codes	不应触发重试的 HTTP 状态码列表（例如抛出 NonTransientAiException）。	empty
spring.ai.retry.on-http-codes	应触发重试的 HTTP 状态码列表（例如抛出 TransientAiException）。	empty

连接属性

前缀 spring.ai.openai 用作连接 OpenAI 的属性前缀。

属性	描述	默认值
spring.ai.openai.base-url	要连接到的 URL。必须设为 http://localhost:12434/engines/v1	-
spring.ai.openai.api-key	任意字符串	-

配置属性

NOTE

聊天自动配置的启用与禁用，现通过以 spring.ai.model.chat 为前缀的顶层属性来完成。

要启用，spring.ai.model.chat=openai（默认启用）

要禁用，spring.ai.model.chat=none（或任何不匹配 openai 的值）

此变更允许在你的应用中配置多个模型。

前缀 spring.ai.openai.chat 是为 OpenAI 配置聊天模型实现的属性前缀。

属性	描述	默认值
spring.ai.openai.chat.enabled (Removed and no longer valid)	启用 OpenAI 聊天模型。	true
spring.ai.model.chat	启用 OpenAI 聊天模型。	openai
spring.ai.openai.chat.base-url	可选，覆盖 spring.ai.openai.base-url 以提供一个聊天专用 url。必须设为 http://localhost:12434/engines/v1	-
spring.ai.openai.chat.api-key	可选，覆盖 spring.ai.openai.api-key 以提供一个聊天专用 api-key	-
spring.ai.openai.chat.model	要使用的 LLM 模型	-
spring.ai.openai.chat.temperature	用于控制的采样温度，影响生成补全的表观创造性。较高的值使输出更随机，较低的值使结果更聚焦、更确定。不建议在同一补全请求中同时修改 temperature 与 top_p，因为这两个设置的相互作用难以预测。	0.8
spring.ai.openai.chat.frequency-penalty	-2.0 到 2.0 之间的数。正值依据新令牌在迄今文本中的既有频率对其加以惩罚，降低模型逐字重复同一行的可能性。	0.0f
spring.ai.openai.chat.max-tokens	在聊天补全中要生成的最大令牌数。输入令牌与生成令牌的总长度受模型上下文窗口长度限制。	-
spring.ai.openai.chat.n	为每个输入消息生成的聊天补全候选数。注意，你会依据所有候选生成的令牌总数被计费。保持 n 为 1 以最小化成本。	1
spring.ai.openai.chat.presence-penalty	-2.0 到 2.0 之间的数。正值依据新令牌是否已在迄今文本中出现对其加以惩罚，提升模型谈论新话题的可能性。	-
spring.ai.openai.chat.response-format	指定模型必须输出格式的對象。设为 { "type": "json_object" } 会启用 JSON 模式，保证模型生成的消息是合法 JSON。	-
spring.ai.openai.chat.seed	此特性处于 Beta。若指定，我们的系统会尽力做确定性采样，使带相同 seed 与参数的重复请求返回相同结果。	-
spring.ai.openai.chat.stop	最多 4 个序列，API 到此处会停止生成更多令牌。	-
spring.ai.openai.chat.top-p	temperature 采样的替代方案，即核采样，模型会考虑具有 top_p 概率质量的那些令牌的结果。所以 0.1 意味着只考虑构成前 10% 概率质量的令牌。我们通常建议调整此项或 temperature，但不要同时调整两者。	-
spring.ai.openai.chat.tools	模型可调用工具列表。目前作为工具只支持函数。用它提供一个模型可为其生成 JSON 输入的函数列表。	-
spring.ai.openai.chat.tool-choice	控制模型调用哪个（若有）函数。none 表示模型不会调用函数而生成一条消息。auto 表示模型可在生成消息或调用函数之间选择。通过 {"type: "function", "function": {"name": "my_function"}} 指定某个特定函数会强制模型调用该函数。无函数存在时 none 为默认；有函数存在时 auto 为默认。	-
spring.ai.openai.chat.user	表示你最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用。	-
spring.ai.openai.chat.stream-usage	（仅流式）设置后会为整个请求附加一个带令牌用量统计的额外块。该块的 choices 字段为空数组，其余所有块也会包含一个 usage 字段但值为 null。	false
spring.ai.openai.chat.tool-callbacks	注册到 ChatModel 的工具回调。	-

TIP

所有以 spring.ai.openai.chat 为前缀的属性，都可通过在 Prompt 调用中添加一个请求专用的 chat-options 在运行时被覆盖。

运行时选项

OpenAiChatOptions.java 提供模型配置，例如要使用的模型、温度、频率惩罚等。

在启动时，可通过 OpenAiChatModel(api, options) 构造器或 spring.ai.openai.chat.* 属性配置默认选项。

在运行时，你可以通过向 Prompt 调用添加新的、请求特定的选项来覆盖默认选项。 例如，要为某个特定请求覆盖默认的模型和温度：

ChatResponse response = chatModel.call(
    new Prompt(
        "Generate the names of 5 famous pirates.",
        OpenAiChatOptions.builder()
            .model("ai/gemma3:4B-F16")
        .build()
    ));

TIP

除模型特定的 OpenAiChatOptions 外，你还可以使用一个可移植的 ChatOptions 实例，通过 ChatOptions#builder() 创建。

工具调用

当所选模型支持时，Docker Model Runner 支持工具调用。Spring AI 处理工具执行循环。

对于大多数应用，请搭配自动注册的 ToolCallingAdvisor 使用 ChatClient —— 参见工具调用。若需要由你自己驱动该循环的底层控制，参见 ChatModel 工具调用。

示例控制器

创建 一个新的 Spring Boot 项目，并把 spring-ai-starter-model-openai 添加到你的 pom（或 gradle）依赖。

在 src/main/resources 目录下添加一个 application.properties 文件，以启用并配置 OpenAi 聊天模型：

spring.ai.openai.api-key=test
spring.ai.openai.base-url=http://localhost:12434/engines/v1
spring.ai.openai.chat.model=ai/gemma3:4B-F16

# Docker Model Runner doesn't support embeddings, so we need to disable them.
spring.ai.model.embedding=none

下面是一个简单 @Controller 类的示例，它使用聊天模型进行文本生成。

@RestController
public class ChatController {

    private final OpenAiChatModel chatModel;

    @Autowired
    public ChatController(OpenAiChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }

    @GetMapping("/ai/generateStream")
	public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }
}