应使用 spring-ai-openai-spring-boot-starter 通过 OpenAI 兼容模式对接 DeepSeek，因其稳定成熟且接口完全兼容；专用 starter 尚无稳定版，快照依赖易致构建失败。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
能直接用，但得选对依赖和配置方式——Spring AI 官方尚未在稳定版中发布 spring-ai-starter-deepseek，当前最稳、最通用的路径是走 OpenAI 兼容模式，用 spring-ai-openai-spring-boot-starter 对接 DeepSeek 的 API 端点。
为什么不用 deepseek 专用 starter？
截至 2026 年 5 月，spring-ai-starter-deepseek 仅存在于快照（snapshot）或预发布版本中，Maven Central 上无正式稳定版（如 1.0.0 或 0.8.1）。强行引入快照依赖会导致构建不稳定、IDE 报红、CI/CD 失败等实际问题。
-
spring-ai-openai-spring-boot-starter是成熟稳定的，已广泛用于生产环境 - DeepSeek 官方明确提供 OpenAI 兼容接口（
https://api.deepseek.com/v1），请求结构、响应格式与 OpenAI Chat Completion 完全一致 - 无需改代码逻辑，只换配置和依赖，迁移成本几乎为零
关键依赖与配置怎么写？
在 pom.xml 中添加：
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>0.8.1</version> </dependency>
在 application.yml 中配置：
立即学习“Java免费学习笔记（深入）”；
spring:
ai:
openai:
api-key: sk-xxx-your-deepseek-key-here
base-url: https://api.deepseek.com/v1
chat:
options:
model: deepseek-chat
temperature: 0.7
max-tokens: 2048
-
base-url必须带/v1，漏掉会返回 404 -
model值必须是 DeepSeek 官方支持的型号名，如deepseek-chat或deepseek-reasoner，不能写成deepseek-chat-7b（那是 Ollama 本地模型名） - 如果项目已启用 WebFlux，建议额外加
spring-boot-starter-webflux，否则流式响应（Flux<String>）会抛NoClassDefFoundError
调用时容易踩的坑有哪些？
直接注入 ChatClient 或 OpenAiChatModel 都可以，但行为差异明显：
- 用
ChatClient：自动处理系统提示词、消息历史、工具调用等高级能力，适合构建对话机器人 - 用
OpenAiChatModel：更轻量，call(prompt)返回纯文本，适合单次生成场景（如摘要、翻译） - 别在
@Bean中手动 newOpenAiChatModel——会绕过 Spring AI 的自动配置，导致base-url和api-key不生效 - 若需动态切换用户专属 API Key，
OpenAiChatModel不支持运行时覆盖；必须自己封装一个工厂类，按需构造新实例
示例（推荐用 ChatClient）：
@RestController
public class AiController {
private final ChatClient chatClient;
public AiController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
@GetMapping("/chat")
public String chat(@RequestParam String message) {
return chatClient.prompt().user(message).call().content();
}
}
流式响应怎么启用？
DeepSeek 的 OpenAI 兼容接口支持 stream=true，但默认不开启。必须显式调用 .stream() 方法，并确保返回类型是 Flux<String>：
@GetMapping(value = "/chat-stream", produces = "text/event-stream")
public Flux<String> stream(@RequestParam String message) {
return chatClient.prompt().user(message).stream().content();
}
- HTTP 响应头必须设为
text/event-stream，否则前端无法解析 SSE - Spring Boot 默认不启用响应式 Web 支持，若没加
spring-boot-starter-webflux，此接口会直接 500 - DeepSeek 流式响应的
delta.content可能为空字符串（尤其在开头或结尾），前端需忽略空片段，否则显示乱码
真正麻烦的从来不是“能不能调通”，而是密钥如何安全注入、超时与重试怎么配、错误码怎么分类处理、以及当 DeepSeek 服务临时不可用时，你的 fallback 逻辑是否真能兜住——这些细节不会出现在 starter 的 auto-configuration 里，得自己补。
