DeepSeek Chat

You will need to create an API key with DeepSeek to access DeepSeek language models.

Create an account at DeepSeek registration page and generate a token on the API Keys page.

The Spring AI project defines a configuration property named spring.ai.deepseek.api-key that you should set to the value of the API Key obtained from the API Keys page.

You can set this configuration property in your application.properties file:

For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable:

You can also set this configuration programmatically in your application code:

Spring AI provides Spring Boot auto-configuration for the DeepSeek Chat Model. To enable it, add the following dependency to your project’s Maven pom.xml file:

or to your Gradle build.gradle file.

The DeepSeekChatOptions.java provides model configurations, such as the model to use, the temperature, the frequency penalty, etc.

On startup, the default options can be configured with the DeepSeekChatModel(api, options) constructor or the spring.ai.deepseek.chat.* properties.

At runtime, you can override the default options by adding new, request-specific options to the Prompt call. For example, to override the default model and temperature for a specific request:

Create a new Spring Boot project and add the spring-ai-starter-model-deepseek to your pom (or gradle) dependencies.

Add an application.properties file under the src/main/resources directory to enable and configure the DeepSeek Chat model:

This will create a DeepSeekChatModel implementation that you can inject into your class. Here is an example of a simple @Controller class that uses the chat model for text generation.

DeepSeekChatModel supports tool calling. The model can request tool execution but does not run tools itself — Spring AI handles execution.

For most applications, use ChatClient with the auto-registered ToolCallingAdvisor — see Tool Calling. For low-level control where you drive the loop yourself, see ChatModel Tool Calling.

The chat prefix completion follows the Chat Completion API, where users provide an assistant’s prefix message for the model to complete the rest of the message.

When using prefix completion, the user must ensure that the last message in the messages list is an AssistantMessage flagged as a prefix, by setting the DeepSeekChatModel.PREFIX_METADATA_KEY (deepseek.prefix) metadata entry to true.

Below is a complete Java code example for chat prefix completion. In this example, we set the prefix message of the assistant to "```python\n" to force the model to output Python code, and set the stop parameter to [‘`’] to prevent additional explanations from the model.

Models supporting that feature return their CoT content as a ReasoningPart of the AssistantMessage, available through getReasoning() (see Message Parts).

In each round of the conversation, the model outputs the CoT (reasoning_content) and the final answer (content). In the next round of the conversation, the CoT from previous rounds is not concatenated into the context, as illustrated in the following diagram:

Spring AI sends the reasoning of earlier assistant messages back as reasoning_content, which the API ignores when the request carries no tools.

A request that carries tools is different in thinking mode: according to the DeepSeek documentation, every assistant message of the conversation must carry its reasoning_content, and the API may reject the request otherwise. Spring AI replays the reasoning parts of each assistant message as its reasoning_content (see Message Parts), so a tool calling loop driven by ChatClient or by the ToolCallingManager keeps working, streamed or not. A conversation that holds reasoning signed by another provider, for example Anthropic thinking, cannot be continued that way, because such reasoning is not replayed. NOTE: Only the in-memory chat memory repository keeps the message parts. A conversation restored from any other repository has lost its reasoning, so a follow-up request that carries tools in thinking mode does not meet that requirement.

Each choice of a response is a Generation whose AssistantMessage holds the choice as ordered message parts:

The parts follow that order: reasoning, text, tool calls, which is the only order DeepSeek produces them in. A DeepSeek message has one field per kind of content rather than a list of content blocks, and the reasoning that is interleaved with tool calls in thinking mode spans several assistant messages, one per tool call round. A choice whose content is empty has no TextPart, unless it has no other part either, and getText() returns an empty string in both cases.

When an assistant message is sent back, its parts are folded into a single DeepSeek message:

When streaming, the reasoning and text deltas of each chunk are partial parts stamped with a synthesized index, so that MessageAggregator rebuilds one ReasoningPart and one TextPart. While a tool call streams, each of its argument deltas arrives right away as a partial ToolCallPart, which is only fit for display purposes and is not a tool call (see Streaming Tool Call Arguments). Once the model has finished its tool calls, one more chunk carries them as complete ToolCallPart`s, at the same index as their deltas, and only those are returned by `getToolCalls().

The DeepSeekChatModel implements the ChatModel and StreamingChatModel and uses the Low-level DeepSeekApi Client to connect to the DeepSeek service.

Add the spring-ai-deepseek dependency to your project’s Maven pom.xml file:

or to your Gradle build.gradle file.

Next, create a DeepSeekChatModel and use it for text generation:

The DeepSeekChatOptions provides the configuration information for the chat requests. The DeepSeekChatOptions.Builder is a fluent options builder.