Spring AI 参考文档模型聊天模型DeepSeekDeepSeek 聊天Spring AI 支持来自 DeepSeek 的各种 AI 语言模型。您可以与 DeepSeek 语言模型交互并基于 DeepSeek 模型创建多语言对话式助手。先决条件您需要在 DeepSeek 创建一个 API 密钥才能访问 DeepSeek 语言模型。在 DeepSeek 注册页面创建账户并在 API 密钥页面生成令牌。Spring AI 项目定义了一个名为spring.ai.deepseek.api-key的配置属性您应将其设置为从 API 密钥页面获取的 API 密钥值。您可以在application.properties文件中设置此配置属性spring.ai.deepseek.api-key您的-deepseek-api-密钥为了在处理 API 密钥等敏感信息时增强安全性您可以使用 Spring Expression Language (SpEL) 来引用自定义环境变量# 在 application.yml 中spring:ai:deepseek:api-key:${DEEPSEEK_API_KEY}# 在您的环境或 .env 文件中exportDEEPSEEK_API_KEY您的-deepseek-api-密钥您也可以在应用程序代码中以编程方式设置此配置// 从安全来源或环境变量中检索 API 密钥StringapiKeySystem.getenv(DEEPSEEK_API_KEY);添加仓库和 BOMSpring AI 工件发布在 Spring Milestone 和 Snapshot 仓库中。请参阅工件仓库部分将这些仓库添加到您的构建系统中。为了帮助进行依赖管理Spring AI 提供了一个 BOM物料清单以确保在整个项目中始终使用一致版本的 Spring AI。请参阅依赖管理部分将 Spring AI BOM 添加到您的构建系统中。自动配置Spring AI 为 DeepSeek 聊天模型提供了 Spring Boot 自动配置。要启用它请将以下依赖项添加到您项目的 Mavenpom.xml文件中dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-deepseek/artifactId/dependency或添加到您的 Gradlebuild.gradle文件中dependencies { implementation org.springframework.ai:spring-ai-starter-model-deepseek }请参阅依赖管理部分将 Spring AI BOM 添加到您的构建文件中。聊天属性重试属性前缀spring.ai.retry用作属性前缀允许您配置 DeepSeek 聊天模型的重试机制。属性描述默认值spring.ai.retry.max-attempts最大重试次数。10spring.ai.retry.backoff.initial-interval指数退避策略的初始睡眠持续时间。2 秒spring.ai.retry.backoff.multiplier退避间隔乘数。5spring.ai.retry.backoff.max-interval最大退避持续时间。3 分钟spring.ai.retry.on-client-errors如果为 false则抛出 NonTransientAiException并且不会对 4xx 客户端错误代码进行重试。falsespring.ai.retry.exclude-on-http-codes不应触发重试的 HTTP 状态码列表例如抛出 NonTransientAiException。空spring.ai.retry.on-http-codes应触发重试的 HTTP 状态码列表例如抛出 TransientAiException。空连接属性前缀spring.ai.deepseek用作属性前缀允许您连接到 DeepSeek。属性描述默认值spring.ai.deepseek.base-url连接 URLhttps://api.deepseek.comspring.ai.deepseek.api-keyAPI 密钥-配置属性聊天自动配置的启用和禁用现在通过前缀为spring.ai.model.chat的顶级属性进行配置。启用时spring.ai.model.chatdeepseek默认启用禁用时spring.ai.model.chatnone或任何与 deepseek 不匹配的值此更改是为了允许配置多个模型。前缀spring.ai.deepseek.chat是用于配置 DeepSeek 聊天模型实现的属性前缀。属性描述默认值spring.ai.deepseek.chat.enabled已移除不再有效启用 DeepSeek 聊天模型。truespring.ai.model.chat启用 DeepSeek 聊天模型。deepseekspring.ai.deepseek.chat.base-url可选覆盖spring.ai.deepseek.base-url以提供聊天特定的 URL。https://api.deepseek.com/spring.ai.deepseek.chat.api-key可选覆盖spring.ai.deepseek.api-key以提供聊天特定的 API 密钥。-spring.ai.deepseek.chat.completions-path聊天补全端点路径。/chat/completionsspring.ai.deepseek.chat.beta-prefix-pathBeta 功能端点的前缀路径。/betaspring.ai.deepseek.chat.model要使用的模型 ID。您可以使用 deepseek-v4-flash、deepseek-v4-pro、deepseek-chat 或 deepseek-reasoner。deepseek-v4-flashspring.ai.deepseek.chat.frequency-penalty-2.0 到 2.0 之间的数字。正值会根据新标记在文本中现有的频率对其进行惩罚从而降低模型逐字重复同一行的可能性。0.0fspring.ai.deepseek.chat.max-tokens聊天补全中生成的最大标记数。输入标记和生成标记的总长度受模型上下文长度的限制。-spring.ai.deepseek.chat.presence-penalty-2.0 到 2.0 之间的数字。正值会根据新标记是否出现在文本中来惩罚它们从而增加模型谈论新主题的可能性。0.0fspring.ai.deepseek.chat.stop最多 4 个序列API 将在此处停止生成更多标记。-spring.ai.deepseek.chat.temperature使用的采样温度介于 0 和 2 之间。较高的值如 0.8会使输出更随机而较低的值如 0.2会使输出更集中和确定。我们通常建议更改此参数或 top_p但不要同时更改两者。1.0Fspring.ai.deepseek.chat.top-p用温度采样的替代方法称为核采样模型考虑 top_p 概率质量的标记结果。因此0.1 意味着只考虑前 10% 概率质量的标记。我们通常建议更改此参数或温度但不要同时更改两者。1.0Fspring.ai.deepseek.chat.logprobs是否返回输出标记的日志概率。如果为 true则返回消息内容中每个输出标记的日志概率。-spring.ai.deepseek.chat.top-logprobs介于 0 和 20 之间的整数指定在每个标记位置返回的最可能标记的数量每个标记都有相关的日志概率。如果使用此参数logprobs 必须设置为 true。-spring.ai.deepseek.chat.tool-callbacks要注册到 ChatModel 的工具回调。-您可以覆盖常见的spring.ai.deepseek.base-url和spring.ai.deepseek.api-key用于 ChatModel 实现。如果设置了spring.ai.deepseek.chat.base-url和spring.ai.deepseek.chat.api-key属性则优先于公共属性。如果您想为不同的模型和不同的模型端点使用不同的 DeepSeek 账户这将非常有用。所有前缀为spring.ai.deepseek.chat的属性都可以在运行时通过向 Prompt 调用添加请求特定的运行时选项来覆盖。运行时选项DeepSeekChatOptions.java提供了模型配置例如要使用的模型、温度、频率惩罚等。启动时可以使用DeepSeekChatModel(api, options)构造函数或spring.ai.deepseek.chat.*属性配置默认选项。在运行时您可以通过向 Prompt 调用添加新的、请求特定的选项来覆盖默认选项。例如要为特定请求覆盖默认模型和温度ChatResponseresponsechatModel.call(newPrompt(生成 5 位著名海盗的名字。请提供 JSON 响应不要包含任何代码块标记如 json。,DeepSeekChatOptions.builder().withModel(DeepSeekApi.ChatModel.DEEPSEEK_V4_PRO.getValue()).withTemperature(0.8f).build()));除了模型特定的 DeepSeekChatOptions 之外您还可以使用通过ChatOptions#builder()创建的可移植 ChatOptions 实例。示例控制器自动配置创建一个新的 Spring Boot 项目并将spring-ai-starter-model-deepseek添加到您的 pom或 gradle依赖项中。在src/main/resources目录下添加一个application.properties文件以启用和配置 DeepSeek 聊天模型spring.ai.deepseek.api-key您的_API_密钥 spring.ai.deepseek.chat.modeldeepseek-v4-pro spring.ai.deepseek.chat.temperature0.8将 api-key 替换为您的 DeepSeek 凭证。这将创建一个DeepSeekChatModel实现您可以将其注入到您的类中。以下是一个简单的Controller类示例它使用聊天模型进行文本生成。RestControllerpublicclassChatController{privatefinalDeepSeekChatModelchatModel;AutowiredpublicChatController(DeepSeekChatModelchatModel){this.chatModelchatModel;}GetMapping(/ai/generate)publicMapgenerate(RequestParam(valuemessage,defaultValue讲个笑话给我听)Stringmessage){returnMap.of(generation,chatModel.call(message));}GetMapping(/ai/generateStream)publicFluxChatResponsegenerateStream(RequestParam(valuemessage,defaultValue讲个笑话给我听)Stringmessage){varpromptnewPrompt(newUserMessage(message));returnchatModel.stream(prompt);}}工具调用您可以向DeepSeekChatModel注册自定义 Java 函数并让 DeepSeek 模型智能地选择输出一个包含参数的 JSON 对象以调用一个或多个已注册的函数。这是一种将 LLM 功能与外部工具和 API 连接起来的强大技术。了解更多关于工具调用的信息。DeepSeekChatModel不在内部执行工具调用。工具执行必须使用以下两种受支持的方法之一在外部处理带有 ToolCallingAdvisor 的 ChatClient— 这是大多数用例推荐的方法。当存在工具时ToolCallingAdvisor会自动注册并透明地管理工具调用循环。用户控制的工具执行— 当您需要对循环进行完全控制时例如在将工具调用与直接 ChatModel 访问结合时直接使用DefaultToolCallingManager。通过 ChatClient 进行工具调用推荐使用 ChatClient 进行同步和流式工具执行。当存在工具时ToolCallingAdvisor会自动注册因此无需显式配置顾问。ToolCallbackweatherCallbackFunctionToolCallback.builder(getCurrentWeather,newWeatherService()).description(获取某个地点的天气).inputType(WeatherService.Request.class).build();// 同步StringresponseChatClient.create(chatModel).prompt().user(巴黎、东京和纽约的天气怎么样).tools(weatherCallback).call().content();// 流式FluxStringstreamChatClient.create(chatModel).prompt().user(巴黎、东京和纽约的天气怎么样).tools(weatherCallback).stream().content();用户控制的工具执行当您需要直接访问 ChatModel API 并希望对工具调用循环进行完全控制时请使用此模式。直接调用 ChatModel不使用 ToolCallingAdvisor自行检查工具调用并使用 ToolCallingManager 驱动循环。ToolCallingManagertoolCallingManagerToolCallingManager.builder().build();DeepSeekChatOptionsoptionsDeepSeekChatOptions.builder().toolCallbacks(ToolCallbacks.from(newWeatherService())).build();PromptpromptnewPrompt(巴黎、东京和纽约的天气怎么样,options);ChatResponseresponsechatModel.call(prompt);while(response.hasToolCalls()){ToolExecutionResultresulttoolCallingManager.executeToolCalls(prompt,response);promptnewPrompt(result.conversationHistory(),options);responsechatModel.call(prompt);}对于流式使用MessageAggregator聚合每个流式响应以检测跨数据块的工具调用AtomicReferenceChatResponseaggregatedRefnewAtomicReference();newMessageAggregator().aggregate(chatModel.stream(prompt),aggregatedRef::set).collectList().block();while(aggregatedRef.get().hasToolCalls()){ToolExecutionResultresulttoolCallingManager.executeToolCalls(prompt,aggregatedRef.get());promptnewPrompt(result.conversationHistory(),options);aggregatedRef.set(null);newMessageAggregator().aggregate(chatModel.stream(prompt),aggregatedRef::set).collectList().block();}StringcontentaggregatedRef.get().getResult().getOutput().getText();聊天前缀补全聊天前缀补全遵循聊天补全 API用户提供助手的消息前缀让模型完成消息的其余部分。使用前缀补全时用户必须确保消息列表中的最后一条消息是DeepSeekAssistantMessage。下面是一个完整的 Java 代码示例用于聊天前缀补全。在此示例中我们将助手的前缀消息设置为 “python\n”以强制模型输出 Python 代码并将 stop 参数设置为 [‘’]以防止模型输出额外的解释。RestControllerpublicclassCodeGenerateController{privatefinalDeepSeekChatModelchatModel;AutowiredpublicChatController(DeepSeekChatModelchatModel){this.chatModelchatModel;}GetMapping(/ai/generatePythonCode)publicStringgenerate(RequestParam(valuemessage,defaultValue请写一个快速排序代码)Stringmessage){UserMessageuserMessagenewUserMessage(message);MessageassistantMessageDeepSeekAssistantMessage.builder().content(python\\n).prefix(true).build();PromptpromptnewPrompt(List.of(userMessage,assistantMessage),ChatOptions.builder().stopSequences(List.of()).build());ChatResponseresponsechatModel.call(prompt);returnresponse.getResult().getOutput().getText();}}推理支持您可以使用DeepSeekAssistantMessage获取支持此功能的模型生成的 CoT 内容。publicvoiddeepSeekReasoningExample(){DeepSeekChatOptionspromptOptionsDeepSeekChatOptions.builder().build();PromptpromptnewPrompt(9.11 和 9.8哪个更大,promptOptions);ChatResponseresponsechatModel.call(prompt);// 获取模型生成的 CoT 内容DeepSeekAssistantMessagedeepSeekAssistantMessage(DeepSeekAssistantMessage)response.getResult().getOutput();StringreasoningContentdeepSeekAssistantMessage.getReasoningContent();StringtextdeepSeekAssistantMessage.getText();}推理模型多轮对话在每一轮对话中模型输出 CoTreasoning_content和最终答案content。在下一轮对话中前几轮的 CoT 不会拼接到上下文中如下图所示此处应有图例多模态测试图像手动配置DeepSeekChatModel实现了ChatModel和StreamingChatModel并使用低级别的DeepSeekApi客户端连接到 DeepSeek 服务。将spring-ai-deepseek依赖项添加到您项目的 Mavenpom.xml文件中dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-deepseek/artifactId/dependency或添加到您的 Gradlebuild.gradle文件中dependencies { implementation org.springframework.ai:spring-ai-deepseek }请参阅依赖管理部分将 Spring AI BOM 添加到您的构建文件中。接下来创建一个DeepSeekChatModel并将其用于文本生成DeepSeekApideepSeekApiDeepSeekApi.builder().apiKey(System.getenv(DEEPSEEK_API_KEY)).build();DeepSeekChatOptionsoptionsDeepSeekChatOptions.builder().model(DeepSeekApi.ChatModel.DEEPSEEK_V4_PRO.getValue()).temperature(0.4).maxTokens(200).build();DeepSeekChatModelchatModelDeepSeekChatModel.builder().deepSeekApi(deepSeekApi).options(options).build();ChatResponseresponsechatModel.call(newPrompt(生成 5 位著名海盗的名字。));// 或者使用流式响应FluxChatResponsestreamResponsechatModel.stream(newPrompt(生成 5 位著名海盗的名字。));DeepSeekChatOptions提供了聊天请求的配置信息。DeepSeekChatOptions.Builder是一个流畅的选项构建器。低级 DeepSeekApi 客户端DeepSeekApi是一个用于 DeepSeek API 的轻量级 Java 客户端。以下是一个简单的代码片段展示如何以编程方式使用该 APIDeepSeekApideepSeekApinewDeepSeekApi(System.getenv(DEEPSEEK_API_KEY));ChatCompletionMessagechatCompletionMessagenewChatCompletionMessage(Hello world,Role.USER);// 同步请求ResponseEntityChatCompletionresponsedeepSeekApi.chatCompletionEntity(newChatCompletionRequest(List.of(chatCompletionMessage),DeepSeekApi.ChatModel.DEEPSEEK_V4_FLASH.getValue(),0.7,false));// 流式请求FluxChatCompletionChunkstreamResponsedeepSeekApi.chatCompletionStream(newChatCompletionRequest(List.of(chatCompletionMessage),DeepSeekApi.ChatModel.DEEPSEEK_V4_FLASH.getValue(),0.7,true));有关更多信息请遵循DeepSeekApi.java的 JavaDoc。DeepSeekApi 示例DeepSeekApiIT.java测试提供了关于如何使用这个轻量级库的一些常规示例。