Spring AI 官方不提供 DeepSeek 的开箱即用 starter，需手动实现 ChatModel 接口并用 WebClient 对接其 OpenAI 兼容 API；配置须避免使用无效的 spring.ai.providers.deepseek 前缀，而应通过环境变量或自定义配置注入 API Key。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Spring AI 官方目前不提供 deepseek-spring-adapter 或 spring-ai-deepseek 这类开箱即用的 starter 模块。所有声称“Spring AI 原生支持 DeepSeek”的教程，实际都依赖手动适配或第三方非官方封装——这点必须先说清，否则后续踩坑全是配置失效、Bean 注入失败、AiClient 调不通。
为什么 Spring AI 的 AiClient 不能直接调用 DeepSeek API
Spring AI 的标准流程是：通过 Provider 抽象层 + ChatModel 实现类完成模型调用。但截至 2026 年 5 月，org.springframework.ai 官方 Maven 仓库中仍无 deepseek 相关 artifact（查证坐标 org.springframework.ai:spring-ai-deepseek 返回 404）。它只原生支持 OpenAI、Azure OpenAI、Ollama、Google Gemini 等少数几家。
这意味着你无法靠加一个 dependency 就自动注册 DeepSeekChatModel Bean；也不能用 @Autowired private ChatModel chatModel; 直接拿到能跑 deepseek-chat-7b 的实例。
常见错误现象：
Caused by: org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type 'org.springframework.ai.chat.ChatModel' available- 配置了
spring.ai.providers.deepseek.api-key，但启动时完全无日志、无报错、也无对应 Bean 初始化 - 强行写
new DeepSeekChatModel(...)却发现类根本不存在（IDE 提示 unresolved reference）
用 RestTemplate 或 WebClient 手动对接 DeepSeek API 是最稳路径
DeepSeek 官方 API（https://api.deepseek.com/v1/chat/completions）完全兼容 OpenAI 格式，这是关键突破口。你可以复用 Spring AI 中已有的 OpenAiChatModel 结构逻辑，但底层换掉 HTTP 客户端目标地址和认证头。
实操建议：
- 不要试图魔改
spring-ai-openai的源码去“硬塞” DeepSeek；它绑定了openai.*配置前缀和特定的 error 解析逻辑，改起来成本高且易崩 - 新建一个
DeepSeekChatModel类，实现ChatModel接口，内部用WebClient发起 POST 请求 - 请求头必须带
Authorization: Bearer ${DEEPSEEK_API_KEY}，不是Api-Key也不是其他变体 - 请求体 JSON 结构与 OpenAI 兼容，但
model字段必须填deepseek-chat-7b或deepseek-v3.2-think（注意大小写和连字符） - 响应体中
choices[0].message.content是你要提取的文本，别漏掉[0]下标
示例片段（简化版）：
public class DeepSeekChatModel implements ChatModel {
private final WebClient webClient;
private final String apiKey;
private final String model;
<pre class="brush:php;toolbar:false;">public DeepSeekChatModel(WebClient.Builder builder, String apiKey, String model) {
this.webClient = builder.baseUrl("https://api.deepseek.com/v1").build();
this.apiKey = apiKey;
this.model = model;
}
@Override
public ChatResponse call(ChatRequest request) {
var body = Map.of(
"model", model,
"messages", request.getMessages().stream()
.map(m -> Map.of("role", m.getRole().toString(), "content", m.getContent()))
.toList()
);
return webClient.post()
.uri("/chat/completions")
.header("Authorization", "Bearer " + apiKey)
.bodyValue(body)
.retrieve()
.bodyToMono(JsonNode.class)
.blockOptional()
.map(this::parseResponse)
.orElseThrow(() -> new RuntimeException("DeepSeek API returned no response"));
}}
使用AIsa生成图像与视频。仅需一个API密钥即可调用Gemini 3 Pro Image（图像）和Qwen Wan 2.6（视频）。
application.yml 里哪些配置项真有用，哪些是摆设
Spring Boot 启动时会加载所有 spring.* 开头的配置，但 Spring AI 不识别 deepseek.* 自定义前缀。所以以下写法无效：
deepseek: api-key: sk-xxx endpoint: https://api.deepseek.com/v1
真正该做的只有两件事：
- 把
DEEPSEEK_API_KEY设为环境变量（推荐），或在application.yml顶层写deepseek-api-key: ${DEEPSEEK_API_KEY:default_key} - 在
@Configuration类中用@Value("${deepseek-api-key}")注入，再传给你的DeepSeekChatModel构造器 -
timeout和retry需自己在WebClient构建时配，例如.codecs(c -> c.defaultCodecs().maxInMemorySize(10 * 1024 * 1024))防大响应体 OOM
别在 spring.ai.providers 下硬凑 deepseek 块——它不会被扫描，也不会触发任何自动配置。
本地部署 deepseek-r1 时，device 和 precision 参数怎么选
如果你走的是本地加载模型路线（比如用 transformers + llama.cpp 封装的 HTTP 服务），那 Spring AI 更是完全不感知。此时你面对的只是一个普通 REST 接口。
关键点在于硬件适配：
- 显卡显存 ≥ 12GB：可设
device="cuda:0"+precision="bf16"，吞吐最优 - 显存 6–8GB：必须量化到
q4_k_m或更低，且device="cuda:0"+precision="fp16"，否则 OOM - 仅 CPU：用
device="cpu"，但deepseek-r17B 推理延迟常超 10s/词，生产慎用 - 无论哪种，都要在启动脚本里显式 export
HF_HOME=/path/to/hf/cache，避免每次拉取模型权重
Spring AI 的 ModelOptions 在这种场景下毫无意义——它只对内置 provider 生效。你得自己控制请求体里的 temperature、max_tokens 字段。
真正的难点从来不在“怎么写通”，而在于“怎么让 retry 不重复扣 quota”、“怎么把 streaming 响应正确转成 SSE 给前端”、“怎么在 ChatResponse 中保留原始 usage 字段供计费”。这些 Spring AI 不管，但业务系统绕不开。
