此版本仍在开发中,尚未被视为稳定版。如需最新的快照版本,请使用 Spring AI 1.1.3spring-doc.cadn.net.cn

深思聊天

Spring AI 支持来自 DeepSeek 的各种 AI 语言模型。您可以与 DeepSeek 语言模型进行交互,并基于 DeepSeek 模型创建一个多语言对话助手。spring-doc.cadn.net.cn

前置条件

您需要在DeepSeek创建一个API密钥以访问DeepSeek语言模型。spring-doc.cadn.net.cn

DeepSeek 注册页面创建账号,并在API密钥页面生成一个Tokens。spring-doc.cadn.net.cn

The Spring AI 项目定义了一个配置属性名为spring.ai.deepseek.api-key,你应该将其设置为从API密钥页面获得的API Key的值。spring-doc.cadn.net.cn

您可以在您的application.properties文件中设置此配置属性:spring-doc.cadn.net.cn

spring.ai.deepseek.api-key=<your-deepseek-api-key>

处理敏感信息(如API密钥)时,为了增强安全性,您可以使用Spring表达式语言(SpEL)引用自定义环境变量:spring-doc.cadn.net.cn

# 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>

您也可以在应用程序代码中通过编程方式设置此配置:spring-doc.cadn.net.cn

// Retrieve API key from a secure source or environment variable
String apiKey = System.getenv("DEEPSEEK_API_KEY");

添加仓库和BOM

Spring AI 工件发布在 Spring 预发行版和快照仓库中。 请参阅 工件仓库 部分,将这些仓库添加到您的构建系统中。spring-doc.cadn.net.cn

为了帮助进行依赖管理,Spring AI 提供了一个 BOM(物料清单),以确保在整个项目中使用一致的 Spring AI 版本。请参阅 依赖管理 部分,在构建系统中添加 Spring AI BOM。spring-doc.cadn.net.cn

Auto-configuration

Spring AI 提供了对 DeepSeek 聊天模型的 Spring Boot 自动配置。 要启用此功能,请将以下依赖项添加到项目中的 Maven pom.xml 文件中:spring-doc.cadn.net.cn

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

请将内容添加到您的Gradle build.gradle 文件中。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-deepseek'
}
请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。

聊天属性

重试属性

spring.ai.retry 前缀用于配置 DeepSeek 聊天模型的重试机制。spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.retry.max-attemptsspring-doc.cadn.net.cn

最大重试尝试次数。spring-doc.cadn.net.cn

10spring-doc.cadn.net.cn

spring.ai.retry.backoff.initial-intervalspring-doc.cadn.net.cn

指数退避策略的初始睡眠时长。spring-doc.cadn.net.cn

2 秒。spring-doc.cadn.net.cn

spring.ai.retry.backoff.multiplierspring-doc.cadn.net.cn

重试间隔倍数。spring-doc.cadn.net.cn

5spring-doc.cadn.net.cn

spring.ai.retry.backoff.max-intervalspring-doc.cadn.net.cn

最大退避持续时间。spring-doc.cadn.net.cn

3 min.spring-doc.cadn.net.cn

spring.ai.retry.on-client-errorsspring-doc.cadn.net.cn

如果为false,则抛出一个NonTransientAiException,并且不会重试4xx客户端错误代码spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.retry.exclude-on-http-codesspring-doc.cadn.net.cn

不应当触发重试的HTTP状态码列表(例如,抛出NonTransientAiException)。spring-doc.cadn.net.cn

<p>空内容</p>spring-doc.cadn.net.cn

spring.ai.retry.on-http-codesspring-doc.cadn.net.cn

应触发重试的HTTP状态码列表(例如,抛出TransientAiException)。spring-doc.cadn.net.cn

<p>空内容</p>spring-doc.cadn.net.cn

连接属性

spring.ai.deepseek 前缀用作属性前缀,可以让您连接到 DeepSeek。spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.deepseek.base-urlspring-doc.cadn.net.cn

连接的URLspring-doc.cadn.net.cn

https://api.deepseek.comspring-doc.cadn.net.cn

spring.ai.deepseek.api-keyspring-doc.cadn.net.cn

API密钥spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

配置属性

spring.ai.deepseek.chat 前缀是属性前缀,用于配置 DeepSeek 的聊天模型实现。spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认

spring.ai.deepseek.chat.enabledspring-doc.cadn.net.cn

启用DeepSeek聊天模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.deepseek.chat.base-urlspring-doc.cadn.net.cn

可选地覆盖spring.ai.deepseek.base-url以提供一个特定于聊天的URLspring-doc.cadn.net.cn

https://api.deepseek.com/spring-doc.cadn.net.cn

spring.ai.deepseek.chat.api-keyspring-doc.cadn.net.cn

可选地重写spring.ai.deepseek.api-key以提供特定于聊天的API密钥spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.deepseek.chat.completions-pathspring-doc.cadn.net.cn

聊天补全端点的路径spring-doc.cadn.net.cn

/chat/completionsspring-doc.cadn.net.cn

spring.ai.deepseek.chat.beta-prefix-pathspring-doc.cadn.net.cn

beta 特性端点的前缀路径spring-doc.cadn.net.cn

/betaspring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.modelspring-doc.cadn.net.cn

使用的目标模型ID。您可以选择使用deepseek-reasoner或deepseek-chat。spring-doc.cadn.net.cn

deepseek-chatspring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.frequencyPenaltyspring-doc.cadn.net.cn

在-2.0到2.0之间的数字。正数值根据文本中现有内容中新词的频率对新词进行惩罚,从而降低模型逐字重复相同行的可能性。spring-doc.cadn.net.cn

0.0fspring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.maxTokensspring-doc.cadn.net.cn

生成聊天补全时的最大token数。输入token和生成token的总长度受限于模型的上下文长度。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.presencePenaltyspring-doc.cadn.net.cn

在-2.0到2.0之间的数字。正数值根据新词在整个文本中出现的频率来惩罚新的词汇,从而增加模型讨论新话题的可能性。spring-doc.cadn.net.cn

0.0fspring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.stopspring-doc.cadn.net.cn

API将在生成更多Tokens之前停止生成至多4个序列。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.temperaturespring-doc.cadn.net.cn

使用多少采样温度,介于0和2之间。较高的值如0.8会让输出更加随机,而较低的值如0.2会让输出更加集中和确定性更强。我们通常建议调整这个参数或top_p中的一个,但不要同时调整两者。spring-doc.cadn.net.cn

1.0Fspring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.topPspring-doc.cadn.net.cn

替代温度采样的一种方法是核采样(nucleus sampling),在这种方法中,模型考虑具有 top_p 概率质量的标记的结果。因此 0.1 表示仅考虑顶部 10% 的概率质量所包含的标记。我们通常建议更改此参数或温度值中的一个即可。spring-doc.cadn.net.cn

1.0Fspring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.logprobsspring-doc.cadn.net.cn

是否返回输出标记的概率值。如果为真,则返回消息内容中每个输出标记的对数概率。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.topLogprobsspring-doc.cadn.net.cn

指定每个标记位置返回的最有可能的标记数量(介于0和20之间),以及每个标记关联的对数概率。如果使用此参数,则必须将logprobs设置为true。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.tool-namesspring-doc.cadn.net.cn

使用名称标识的工具列表,以在单个提示请求中启用功能调用。具有这些名称的工具必须存在于ToolCallback注册表中。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.tool-callbacksspring-doc.cadn.net.cn

使用回调注册与ChatModel相关的工具。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.deepseek.chat.options.internal-tool-execution-enabledspring-doc.cadn.net.cn

如果为假,Spring AI 将不会内部处理工具调用,而是将它们代理给客户端。然后需要由客户端负责处理这些工具调用、将其分派到适当的函数,并返回结果。如果为真(默认值),Spring AI 将会内部处理这些函数调用。仅适用于支持功能调用的聊天模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

您可以通过覆盖公共的spring.ai.deepseek.base-urlspring.ai.deepseek.api-key来为ChatModel实现设置自定义值。如果设置了spring.ai.deepseek.chat.base-urlspring.ai.deepseek.chat.api-key属性,它们将优先于公共属性。 这在您希望为不同的模型使用不同的DeepSeek账户以及不同的模型端点时非常有用。
所有以spring.ai.deepseek.chat.options开头的属性可以在运行时通过向Prompt调用添加特定于请求的运行时选项来覆盖。

运行时选项

The DeepSeekChatOptions.java 提供了模型配置,例如要使用的模型、温度、频率惩罚等。spring-doc.cadn.net.cn

在启动时,可以通过DeepSeekChatModel(api, options)构造函数或spring.ai.deepseek.chat.options.*属性来配置默认选项。spring-doc.cadn.net.cn

在运行时,您可以通过向Prompt调用添加新的、针对请求的选项来覆盖默认选项。 例如,要为特定请求覆盖默认模型和温度设置:spring-doc.cadn.net.cn

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-deepseekspring-doc.cadn.net.cn

src/main/resources目录下添加一个application.properties文件以启用并配置DeepSeek Chat模型:spring-doc.cadn.net.cn

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类示例,该类使用聊天模型进行文本生成。spring-doc.cadn.net.cn

@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,用户提供助手的前缀消息供模型完成剩余的消息。spring-doc.cadn.net.cn

当使用前缀补全时,用户必须确保消息列表中的最后一条消息是DeepSeekAssistantMessage。spring-doc.cadn.net.cn

以下是一个完整的Java代码示例,用于聊天前缀完成。在这个例子中,我们将助手的前缀消息设置为“```python ”,以强制模型输出Python代码,并将停止参数设置为[‘`’],以防模型额外添加解释。spring-doc.cadn.net.cn

@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 内容,使他们能够查看、展示和提炼这些内容。spring-doc.cadn.net.cn

您可以使用DeepSeekAssistantMessage获取由deepseek-reasoner生成的CoT内容。spring-doc.cadn.net.cn

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连接到上下文中,如下图所示:spring-doc.cadn.net.cn

Multimodal Test Image

请确保在输入消息序列中不包含reasoning_content字段,否则API将会返回400错误。因此,在发送API请求之前,请从API响应中移除reasoning_content字段,如API示例所示。spring-doc.cadn.net.cn

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 实现了 ChatModelStreamingChatModel 并使用 低级 DeepSeekApi 客户端 连接到 DeepSeek 服务。spring-doc.cadn.net.cn

将如下的spring-ai-deepseek依赖添加到项目中Maven的pom.xml文件中:spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-deepseek</artifactId>
</dependency>

请将内容添加到您的Gradle build.gradle 文件中。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-deepseek'
}
请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。

接下来,创建一个DeepSeekChatModel并用于文本生成:spring-doc.cadn.net.cn

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 是一个流畅选项构建器。spring-doc.cadn.net.cn

低级 DeepSeekApi 客户端

The DeepSeekApi 是一个轻量级的 Java 客户端,用于访问 DeepSeek APIspring-doc.cadn.net.cn

这里是一个简单的示例,展示了如何通过编程方式使用API:spring-doc.cadn.net.cn

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以获取更多信息。spring-doc.cadn.net.cn

深寻API示例