|
此版本仍在开发中，尚未被视为稳定版。为了获取最新的快照版本，请使用Spring AI 1.1.3！ |
Docker 模型运行器聊天
Docker模型运行器是一个AI推理引擎，提供了来自多个提供商的广泛模型选择。
Spring AI 通过复用现有的由 OpenAI 支持的 ChatClient，与 Docker Model Runner 集成。
要实现这一点，请将基础 URL 设置为 localhost:12434/engines，并选择提供的 LLM 模型 之一。
查看DockerModelRunnerWithOpenAiChatModelIT.java测试 中的示例，了解如何在Spring AI中使用Docker模型运行器。
前提条件
-
下载适用于Mac的Docker Desktop 4.40.0版本。
请选择以下选项之一以启用模型运行器：
选项 1:
-
启用模型运行器
docker desktop enable model-runner --tcp 12434. -
将基础网址设置为
localhost:12434/engines
选项2:
-
启用模型运行器
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 OpenAiApi chatCompletionApi() {
var baseUrl = DMR.getOpenAIEndpoint();
return OpenAiApi.builder().baseUrl(baseUrl).apiKey("test").build();
}您可以了解更多关于Docker模型运行器的信息，通过阅读使用Docker在本地运行LLMs的博客文章。
自动配置
|
Spring AI 启动模块的工件ID自1.0.0.M7版本以来已被重命名。依赖项名称现在应遵循针对模型、向量存储和MCPStarters的更新命名模式。 更多详细信息，请参阅升级说明。 |
Spring AI 为 OpenAI 聊天客户端提供了 Spring Boot 自动配置功能。要启用此功能，请在项目的 Maven pom.xml 文件中添加以下依赖项：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>或在您的Gradle 构建文件中添加以下内容。
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
}| 参考以下依赖管理部分，添加Spring AI BOM到你的构建文件中。 |
聊天属性
重试属性
前缀 spring.ai.retry 用于作为属性前缀，允许您配置OpenAI聊天模型的重试机制。
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.retry.max-attempts |
最大重试次数。 |
10 |
spring.ai.retry.backoff.initial-interval |
指数退避策略的初始睡眠时长。 |
2 秒 |
spring.ai.retry.backoff.multiplier |
退避间隔乘数。 |
5 |
spring.ai.retry.backoff.max-interval |
最大退避时长。 |
3 分钟。 |
spring.ai.retry.on-client-errors |
如果为false，则抛出NonTransientAiException，且不重试客户端错误代码 |
false |
spring.ai.retry.exclude-on-http-codes |
不应触发重试的HTTP状态代码列表（例如，用于抛出非暂时性AI异常）。 |
empty |
spring.ai.retry.on-http-codes |
应触发重试的HTTP状态码列表（例如，用于抛出TransientAiException）。 |
empty |
连接属性
前缀 spring.ai.openai 用于作为属性前缀，以便您连接到OpenAI。
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai.base-url |
连接到的URL。必须设置为 |
- |
spring.ai.openai.api-key |
任何字符串 |
- |
配置属性
|
启用和禁用聊天自动配置现在通过带有前缀 启用时， 要禁用，请使用 此更改允许在您的应用程序中配置多个模型。 |
前缀 spring.ai.openai.chat 是属性前缀，用于配置OpenAI聊天模型的实现方式。
| 属性 | 描述 | 默认 |
|---|---|---|
spring.ai.openai.chat.enabled（已移除，不再有效） |
启用OpenAI聊天模型。 |
true |
spring.ai.model.chat |
启用OpenAI聊天模型。 |
开源人工智能 |
spring.ai.openai.chat.base-url |
可选地覆盖，默认为 |
- |
spring.ai.openai.chat.api-key |
可选地，覆盖 `spring.ai.openai.api-key` 以提供聊天特定的 API 密钥。 |
- |
spring.ai.openai.chat.options.model |
要使用的LLM模型 |
- |
spring.ai.openai.chat.options.temperature |
生成完成内容时控制其表面创新性的采样温度。较高的值会使输出更加随机，而较低的值将使结果更集中且确定性更强。不建议在同一完成请求中同时修改温度和top_p，因为这两个设置的相互作用难以预测。 |
0.8 |
spring.ai.openai.chat.options.frequencyPenalty |
介于-2.0和2.0之间的数值。正值会根据新词在文本中已有的出现频率对其进行惩罚，从而降低模型重复相同行文的确切概率。 |
0.0f |
spring.ai.openai.chat.options.maxTokens |
聊天补全时生成的最大Tokens数量。输入Tokens和生成Tokens的总长度受到模型上下文长度的限制。 |
- |
spring.ai.openai.chat.options.n |
针对每条输入消息生成的聊天补全选项数量。请注意，您将根据所有选项生成的Tokens总数来计费。为了最小化成本，请将 n 保持为 1。 |
1 |
spring.ai.openai.chat.options.presencePenalty |
介于-2.0和2.0之间的数值。正值会根据新词是否已出现在文本中对其进行惩罚，从而增加模型谈论新主题的可能性。 |
- |
spring.ai.openai.chat.options.responseFormat |
指定模型输出格式的对象。设置为 |
- |
spring.ai.openai.chat.options.seed |
此功能处于测试阶段。如果指定了，我们的系统将尽力进行确定性采样，以便使用相同的种子和参数的重复请求应返回相同的结果。 |
- |
spring.ai.openai.chat.options.stop |
最多4个序列，到达这些序列后API将停止生成更多Tokens。 |
- |
spring.ai.openai.chat.options.topP |
一种替代温度采样的方法称为核采样，模型会考虑具有前p概率质量的Tokens的结果。因此，0.1意味着只考虑构成前10%概率质量的Tokens。我们通常建议调整这个参数或温度，但不建议同时调整两者。 |
- |
spring.ai.openai.chat.options.tools |
模型可能调用的工具列表。当前，仅支持函数作为工具。使用此功能来提供模型可能为其生成JSON输入的函数列表。 |
- |
spring.ai.openai.chat.options.toolChoice |
控制模型调用（如有）哪个函数。none 表示模型将不调用任何函数，而直接生成消息。auto 表示模型可以在生成消息或调用函数之间进行选择。通过 {"type": "function", "function": {"name": "my_function"}} 指定特定函数会强制模型调用该函数。当没有提供函数时，默认为 none。如果存在函数，则默认为 auto。 |
- |
spring.ai.openai.chat.options.user |
代表您终端用户的唯一标识符，有助于OpenAI监控和检测滥用行为。 |
- |
spring.ai.openai.chat.options.stream-usage |
（仅限流式处理）设置此选项可添加一个额外的块，用于统计整个请求的Tokens使用情况。此块的 |
false |
spring.ai.openai.chat.options.tool-names |
用于在单个提示请求中启用函数调用的工具列表，这些工具通过它们的名称来识别。具有这些名称的工具必须存在于ToolCallback注册表中。 |
- |
spring.ai.openai.chat.options.tool-callbacks |
向ChatModel注册的工具回调。 |
- |
spring.ai.openai.chat.options.internal-tool-execution-enabled |
如果为 false，Spring AI 将不内部处理工具调用，而是将它们代理给客户端。此后，处理工具调用、将其分派给适当函数并返回结果的责任在于客户端。如果为 true（默认值），Spring AI 将内部处理函数调用。此设置仅适用于支持函数调用的聊天模型。 |
true |
所有以spring.ai.openai.chat.options为前缀的属性都可以通过向Prompt调用中添加特定于请求的运行时选项在运行时覆盖。 |
运行时选项
OpenAiChatOptions.java 文件提供了模型配置，如使用的模型、温度、频率惩罚等参数。
On start-up, the default options can be configured with the OpenAiChatModel(api, options) constructor or the spring.ai.openai.chat.options.* properties.
在运行时，您可以通过向Prompt调用添加新的、请求特定的选项来覆盖默认选项。
例如，要为特定请求覆盖默认模型和温度：
ChatResponse response = chatModel.call(
new Prompt(
"Generate the names of 5 famous pirates.",
OpenAiChatOptions.builder()
.model("ai/gemma3:4B-F16")
.build()
));| 除了特定于模型的OpenAiChatOptions之外，您还可以使用通过ChatOptions#builder()创建的可移植ChatOptions实例。 |
函数调用
Docker Model Runner 支持在选择支持此功能的模型时调用工具/函数。
您可以向ChatModel注册自定义的Java函数，并让提供的模型智能地选择输出一个JSON对象，该对象包含调用一个或多个已注册函数的参数。 这是一种强大的技术，用于将LLM功能与外部工具和API连接起来。
工具示例
下面是一个使用Docker模型运行器功能调用Spring AI的简单示例：
spring.ai.openai.api-key=test
spring.ai.openai.base-url=http://localhost:12434/engines
spring.ai.openai.chat.options.model=ai/gemma3:4B-F16@SpringBootApplication
public class DockerModelRunnerLlmApplication {
public static void main(String[] args) {
SpringApplication.run(DockerModelRunnerLlmApplication.class, args);
}
@Bean
CommandLineRunner runner(ChatClient.Builder chatClientBuilder) {
return args -> {
var chatClient = chatClientBuilder.build();
var response = chatClient.prompt()
.user("What is the weather in Amsterdam and Paris?")
.functions("weatherFunction") // reference by bean name.
.call()
.content();
System.out.println(response);
};
}
@Bean
@Description("Get the weather in location")
public Function<WeatherRequest, WeatherResponse> weatherFunction() {
return new MockWeatherService();
}
public static class MockWeatherService implements Function<WeatherRequest, WeatherResponse> {
public record WeatherRequest(String location, String unit) {}
public record WeatherResponse(double temp, String unit) {}
@Override
public WeatherResponse apply(WeatherRequest request) {
double temperature = request.location().contains("Amsterdam") ? 20 : 25;
return new WeatherResponse(temperature, request.unit);
}
}
}在此示例中，当模型需要天气信息时，它将自动调用weatherService bean，后者可以获取实时天气数据。
预期的响应为："阿姆斯特丹当前的天气是20摄氏度，巴黎当前的天气是25摄氏度。"
了解更多关于OpenAI的函数调用功能。
示例控制器
创建一个新的Spring Boot项目，并将spring-boot-starter-web添加到您的pom（或gradle）依赖中。
在src/main/resources目录下添加一个application.properties文件，以启用和配置OpenAi聊天模型：
spring.ai.openai.api-key=test
spring.ai.openai.base-url=http://localhost:12434/engines
spring.ai.openai.chat.options.model=ai/gemma3:4B-F16
# Docker Model Runner doesn't support embeddings, so we need to disable them.
spring.ai.openai.embedding.enabled=false这是一个使用聊天模型进行文本生成的简单@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);
}
}