|
此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3! |
深思聊天
Spring AI 支持来自 DeepSeek 的各种 AI 语言模型。您可以与 DeepSeek 语言模型进行交互,并基于 DeepSeek 模型创建一个多语言对话助手。
前置条件
您需要在DeepSeek创建一个API密钥以访问DeepSeek语言模型。
在DeepSeek 注册页面创建账号,并在API密钥页面生成一个Tokens。
The Spring AI 项目定义了一个配置属性名为spring.ai.deepseek.api-key,你应该将其设置为从API密钥页面获得的API Key的值。
您可以在您的application.properties文件中设置此配置属性:
spring.ai.deepseek.api-key=<your-deepseek-api-key>
处理敏感信息(如API密钥)时,为了增强安全性,您可以使用Spring表达式语言(SpEL)引用自定义环境变量:
# In application.yml
spring:
ai:
deepseek:
api-key: ${DEEPSEEK_API_KEY}
# In your environment or .env file
export DEEPSEEK_API_KEY=<your-deepseek-api-key>
您也可以在应用程序代码中通过编程方式设置此配置:
// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("DEEPSEEK_API_KEY");
Auto-configuration
Spring AI 提供了对 DeepSeek 聊天模型的 Spring Boot 自动配置。
要启用此功能,请将以下依赖项添加到项目中的 Maven pom.xml 文件中:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-deepseek</artifactId>
</dependency>
请将内容添加到您的Gradle build.gradle 文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-deepseek'
}
| 请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。 |
聊天属性
重试属性
spring.ai.retry 前缀用于配置 DeepSeek 聊天模型的重试机制。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
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 min. |
spring.ai.retry.on-client-errors |
如果为false,则抛出一个NonTransientAiException,并且不会重试 |
false |
spring.ai.retry.exclude-on-http-codes |
不应当触发重试的HTTP状态码列表(例如,抛出NonTransientAiException)。 |
<p>空内容</p> |
spring.ai.retry.on-http-codes |
应触发重试的HTTP状态码列表(例如,抛出TransientAiException)。 |
<p>空内容</p> |
连接属性
spring.ai.deepseek 前缀用作属性前缀,可以让您连接到 DeepSeek。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.deepseek.base-url |
连接的URL |
|
spring.ai.deepseek.api-key |
API密钥 |
- |
配置属性
spring.ai.deepseek.chat 前缀是属性前缀,用于配置 DeepSeek 的聊天模型实现。
| <property> </property> | <description> </description> | 默认 |
|---|---|---|
spring.ai.deepseek.chat.enabled |
启用DeepSeek聊天模型。 |
true |
spring.ai.deepseek.chat.base-url |
可选地覆盖spring.ai.deepseek.base-url以提供一个特定于聊天的URL |
|
spring.ai.deepseek.chat.api-key |
可选地重写spring.ai.deepseek.api-key以提供特定于聊天的API密钥 |
- |
spring.ai.deepseek.chat.completions-path |
聊天补全端点的路径 |
|
spring.ai.deepseek.chat.beta-prefix-path |
beta 特性端点的前缀路径 |
|
spring.ai.deepseek.chat.options.model |
使用的目标模型ID。您可以选择使用deepseek-reasoner或deepseek-chat。 |
deepseek-chat |
spring.ai.deepseek.chat.options.frequencyPenalty |
在-2.0到2.0之间的数字。正数值根据文本中现有内容中新词的频率对新词进行惩罚,从而降低模型逐字重复相同行的可能性。 |
0.0f |
spring.ai.deepseek.chat.options.maxTokens |
生成聊天补全时的最大token数。输入token和生成token的总长度受限于模型的上下文长度。 |
- |
spring.ai.deepseek.chat.options.presencePenalty |
在-2.0到2.0之间的数字。正数值根据新词在整个文本中出现的频率来惩罚新的词汇,从而增加模型讨论新话题的可能性。 |
0.0f |
spring.ai.deepseek.chat.options.stop |
API将在生成更多Tokens之前停止生成至多4个序列。 |
- |
spring.ai.deepseek.chat.options.temperature |
使用多少采样温度,介于0和2之间。较高的值如0.8会让输出更加随机,而较低的值如0.2会让输出更加集中和确定性更强。我们通常建议调整这个参数或top_p中的一个,但不要同时调整两者。 |
1.0F |
spring.ai.deepseek.chat.options.topP |
替代温度采样的一种方法是核采样(nucleus sampling),在这种方法中,模型考虑具有 top_p 概率质量的标记的结果。因此 0.1 表示仅考虑顶部 10% 的概率质量所包含的标记。我们通常建议更改此参数或温度值中的一个即可。 |
1.0F |
spring.ai.deepseek.chat.options.logprobs |
是否返回输出标记的概率值。如果为真,则返回消息内容中每个输出标记的对数概率。 |
- |
spring.ai.deepseek.chat.options.topLogprobs |
指定每个标记位置返回的最有可能的标记数量(介于0和20之间),以及每个标记关联的对数概率。如果使用此参数,则必须将logprobs设置为true。 |
- |
spring.ai.deepseek.chat.options.tool-names |
使用名称标识的工具列表,以在单个提示请求中启用功能调用。具有这些名称的工具必须存在于ToolCallback注册表中。 |
- |
spring.ai.deepseek.chat.options.tool-callbacks |
使用回调注册与ChatModel相关的工具。 |
- |
spring.ai.deepseek.chat.options.internal-tool-execution-enabled |
如果为假,Spring AI 将不会内部处理工具调用,而是将它们代理给客户端。然后需要由客户端负责处理这些工具调用、将其分派到适当的函数,并返回结果。如果为真(默认值),Spring AI 将会内部处理这些函数调用。仅适用于支持功能调用的聊天模型。 |
true |
您可以通过覆盖公共的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.options开头的属性可以在运行时通过向Prompt调用添加特定于请求的运行时选项来覆盖。 |
运行时选项
The DeepSeekChatOptions.java 提供了模型配置,例如要使用的模型、温度、频率惩罚等。
在启动时,可以通过DeepSeekChatModel(api, options)构造函数或spring.ai.deepseek.chat.options.*属性来配置默认选项。
在运行时,您可以通过向Prompt调用添加新的、针对请求的选项来覆盖默认选项。
例如,要为特定请求覆盖默认模型和温度设置:
ChatResponse response = chatModel.call(
new Prompt(
"Generate the names of 5 famous pirates. Please provide the JSON response without any code block markers such as ```json```.",
DeepSeekChatOptions.builder()
.withModel(DeepSeekApi.ChatModel.DEEPSEEK_CHAT.getValue())
.withTemperature(0.8f)
.build()
));
| 除了针对特定模型的DeepSeekChatOptions,你还可以使用一个通用的ChatOptions 实例,通过调用ChatOptions#builder() 创建。 |
样例控制器(自动配置)
创建一个新的Spring Boot项目,并在pom(或gradle)依赖中添加spring-ai-starter-model-deepseek。
在src/main/resources目录下添加一个application.properties文件以启用并配置DeepSeek Chat模型:
spring.ai.deepseek.api-key=YOUR_API_KEY
spring.ai.deepseek.chat.options.model=deepseek-chat
spring.ai.deepseek.chat.options.temperature=0.8
请将api-key替换为您的DeepSeek凭证。 |
这将创建一个DeepSeekChatModel实现,你可以在类中注入。
以下是一个简单的@Controller类示例,该类使用聊天模型进行文本生成。
@RestController
public class ChatController {
private final DeepSeekChatModel chatModel;
@Autowired
public ChatController(DeepSeekChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generate")
public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
return Map.of("generation", chatModel.call(message));
}
@GetMapping("/ai/generateStream")
public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
var prompt = new Prompt(new UserMessage(message));
return chatModel.stream(prompt);
}
}
聊天前缀完成
聊天前缀完成遵循Chat Completion API,用户提供助手的前缀消息供模型完成剩余的消息。
当使用前缀补全时,用户必须确保消息列表中的最后一条消息是DeepSeekAssistantMessage。
以下是一个完整的Java代码示例,用于聊天前缀完成。在这个例子中,我们将助手的前缀消息设置为“```python ”,以强制模型输出Python代码,并将停止参数设置为[‘`’],以防模型额外添加解释。
@RestController
public class CodeGenerateController {
private final DeepSeekChatModel chatModel;
@Autowired
public ChatController(DeepSeekChatModel chatModel) {
this.chatModel = chatModel;
}
@GetMapping("/ai/generatePythonCode")
public String generate(@RequestParam(value = "message", defaultValue = "Please write quick sort code") String message) {
UserMessage userMessage = new UserMessage(message);
Message assistantMessage = DeepSeekAssistantMessage.prefixAssistantMessage("```python\\n");
Prompt prompt = new Prompt(List.of(userMessage, assistantMessage), ChatOptions.builder().stopSequences(List.of("```")).build());
ChatResponse response = chatModel.call(prompt);
return response.getResult().getOutput().getText();
}
}
理论模型(deepseek-reasoner)
deepseek-reasoner 是由 DeepSeek 开发的推理模型。在提供最终答案之前,该模型首先生成一个思维链(Chain of Thought,CoT),以提高其回答的准确性。我们的 API 允许用户访问 deepseek-reasoner 生成的 CoT 内容,使他们能够查看、展示和提炼这些内容。
您可以使用DeepSeekAssistantMessage获取由deepseek-reasoner生成的CoT内容。
public void deepSeekReasonerExample() {
DeepSeekChatOptions promptOptions = DeepSeekChatOptions.builder()
.model(DeepSeekApi.ChatModel.DEEPSEEK_REASONER.getValue())
.build();
Prompt prompt = new Prompt("9.11 and 9.8, which is greater?", promptOptions);
ChatResponse response = chatModel.call(prompt);
// Get the CoT content generated by deepseek-reasoner, only available when using deepseek-reasoner model
DeepSeekAssistantMessage deepSeekAssistantMessage = (DeepSeekAssistantMessage) response.getResult().getOutput();
String reasoningContent = deepSeekAssistantMessage.getReasoningContent();
String text = deepSeekAssistantMessage.getText();
}
多轮对话推理模型
在每次对话轮次中,模型输出CoT(推理内容)和最终答案(内容)。在下一轮对话中,不会将之前轮次的CoT连接到上下文中,如下图所示:
请确保在输入消息序列中不包含reasoning_content字段,否则API将会返回400错误。因此,在发送API请求之前,请从API响应中移除reasoning_content字段,如API示例所示。
public String deepSeekReasonerMultiRoundExample() {
List<Message> messages = new ArrayList<>();
messages.add(new UserMessage("9.11 and 9.8, which is greater?"));
DeepSeekChatOptions promptOptions = DeepSeekChatOptions.builder()
.model(DeepSeekApi.ChatModel.DEEPSEEK_REASONER.getValue())
.build();
Prompt prompt = new Prompt(messages, promptOptions);
ChatResponse response = chatModel.call(prompt);
DeepSeekAssistantMessage deepSeekAssistantMessage = (DeepSeekAssistantMessage) response.getResult().getOutput();
String reasoningContent = deepSeekAssistantMessage.getReasoningContent();
String text = deepSeekAssistantMessage.getText();
messages.add(AssistantMessage.builder().content(Objects.requireNonNull(text)).build());
messages.add(new UserMessage("How many Rs are there in the word 'strawberry'?"));
Prompt prompt2 = new Prompt(messages, promptOptions);
ChatResponse response2 = chatModel.call(prompt2);
DeepSeekAssistantMessage deepSeekAssistantMessage2 = (DeepSeekAssistantMessage) response2.getResult().getOutput();
String reasoningContent2 = deepSeekAssistantMessage2.getReasoningContent();
return deepSeekAssistantMessage2.getText();
}
手动配置
The DeepSeekChatModel 实现了 ChatModel 和 StreamingChatModel 并使用 低级 DeepSeekApi 客户端 连接到 DeepSeek 服务。
将如下的spring-ai-deepseek依赖添加到项目中Maven的pom.xml文件中:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-deepseek</artifactId>
</dependency>
请将内容添加到您的Gradle build.gradle 文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-deepseek'
}
| 请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。 |
接下来,创建一个DeepSeekChatModel并用于文本生成:
DeepSeekApi deepSeekApi = DeepSeekApi.builder()
.apiKey(System.getenv("DEEPSEEK_API_KEY"))
.build();
DeepSeekChatOptions options = DeepSeekChatOptions.builder()
.model(DeepSeekApi.ChatModel.DEEPSEEK_CHAT.getValue())
.temperature(0.4)
.maxTokens(200)
.build();
DeepSeekChatModel chatModel = DeepSeekChatModel.builder()
.deepSeekApi(deepSeekApi)
.defaultOptions(options)
.build();
ChatResponse response = chatModel.call(
new Prompt("Generate the names of 5 famous pirates."));
// Or with streaming responses
Flux<ChatResponse> streamResponse = chatModel.stream(
new Prompt("Generate the names of 5 famous pirates."));
DeepSeekChatOptions 提供了聊天请求的配置信息。
DeepSeekChatOptions.Builder 是一个流畅选项构建器。
低级 DeepSeekApi 客户端
The DeepSeekApi 是一个轻量级的 Java 客户端,用于访问 DeepSeek API。
这里是一个简单的示例,展示了如何通过编程方式使用API:
DeepSeekApi deepSeekApi =
new DeepSeekApi(System.getenv("DEEPSEEK_API_KEY"));
ChatCompletionMessage chatCompletionMessage =
new ChatCompletionMessage("Hello world", Role.USER);
// Sync request
ResponseEntity<ChatCompletion> response = deepSeekApi.chatCompletionEntity(
new ChatCompletionRequest(List.of(chatCompletionMessage), DeepSeekApi.ChatModel.DEEPSEEK_CHAT.getValue(), 0.7, false));
// Streaming request
Flux<ChatCompletionChunk> streamResponse = deepSeekApi.chatCompletionStream(
new ChatCompletionRequest(List.of(chatCompletionMessage), DeepSeekApi.ChatModel.DEEPSEEK_CHAT.getValue(), 0.7, true));
跟随DeepSeekApi.java的JavaDoc以获取更多信息。
深寻API示例
-
The DeepSeekApiIT.java 测试提供了一些如何使用轻量级库的一般示例。