上周把DeepSeek API接进我们Spring Boot项目时,群里一个同事贴了张报错截图:api_key_required。Key明明配了,文档也翻了,怎么还是401?这个场景几乎每个团队第一次接大模型接口都会遇到。模型本身不难,难的是在工程体系里把一次HTTP调用安排得明明白白。这篇文章我会把在Spring Boot里对接DeepSeek API的完整过程,从选型、鉴权、请求封装、流式输出到生产环境踩坑,一层层拆开讲。适合后端Java工程师,也适合想自己搭一个AI功能Demo的爱好者参考。
1. 为什么在Spring Boot里接DeepSeek API:先想清楚再动手
1.1 这不止是一次HTTP调用
很多人以为接大模型API就是“发一个POST请求,拿到返回字符串”,真正做起来你会发现,这只是冰山一角。DeepSeek API本身是一个HTTP接口,但你的业务系统需要处理的问题远远超出“能调通”这个层面:HTTP连接超时和读超时怎么设置、Token用量怎么统计、模型返回格式错误怎么兜底、用户上下文怎么保持、并发上来之后线程池怎么不被打满。
这些问题单靠一个HttpClient随手调一调是扛不住的。Spring Boot的好处在于,它有成熟的依赖注入、配置体系、AOP、线程池管理和监控埋点,很适合把一个“裸的HTTP调用”包装成公司内部可复用、可观测、可治理的AI能力组件。我们最终选择用Spring Boot做这件事,不是因为它有多花哨,而是因为团队所有人都在这个技术栈里,维护成本最低。
1.2 先决定API调用放在哪一层
动手之前,先把DeepSeek API调用放在什么位置想清楚。我当时给团队提的建议是:不要把API Key散落在各个业务服务里,而是单独做一个llm-gateway模块,所有业务方(搜索助手、内容总结、客服问答)都通过这个模块访问大模型。这样API Key只存在一个地方,审计日志只在一个地方,限流和降级也只在一个地方。
如果只是写一个简单Demo,那随意,Controller里直接注入一个Service即可。但如果你预判这个能力会扩展到多个业务场景,从第一天就做一层隔离,后面会轻松很多。Spring Boot的包结构天然适合这种方式:configuration放请求客户端配置,client放HTTP封装,dto放请求响应模型,service放业务编排。
1.3 官方SDK和自封装,我为什么选后者
DeepSeek的API兼容OpenAI协议,所以社区里很多OpenAI的Java SDK也能直接用,另外Spring官方生态里也有Spring AI,它已经把OpenAI、DeepSeek等模型商接入做了统一抽象。那为什么我还要手写一个REST客户端?
原因有三:第一,很多SDK为了兼容所有模型商,抽象层特别厚,出了问题排查链路很长;第二,我们需要的自定义逻辑,比如按业务线拆分token配额、把错误码映射成内部异常、在请求日志里记录消息摘要,SDK不一定支持得那么顺手;第三,DeepSeek的API本身很简单,一个POST /chat/completions就搞定了,自己封装几十行代码就够,没必要引入一整个依赖树。
当然,如果你们团队已经用了Spring AI,那也没有必要推翻重来,接着用就好。我这里讲的实现方式,是“不依赖额外大模型SDK、用Spring Boot原生能力也能跑得很好”的路线。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 接入前必做的基础准备:Key、模型和请求格式
2.1 获取API Key,并选对模型
去DeepSeek开放平台注册账号、创建API Key,这些操作按文档走就行。需要注意几点:
- API Key要保存好,一旦泄露就要立即吊销,它等同于你账户的资金凭证;
- 生产环境不要硬编码在代码里,放在环境变量或者配置中心;
- 根据场景选模型,
deepseek-chat和deepseek-reasoner是两个不同方向。
| 模型 | 适用场景 | 特点 |
|---|---|---|
| deepseek-chat | 通用对话、文本生成、内容总结 | 响应快,成本较低,上下文最长支持1M tokens |
| deepseek-reasoner | 数学推理、代码逻辑、复杂分析 | 带思维链推理过程,耗时更长,消耗token更多 |
我们大部分业务用的都是deepseek-chat,只有需要深度推理的内部工具用了deepseek-reasoner。选模型这件事,不要一个配置走天下,建议在请求DTO里把model字段设计成可配置项。
2.2 OpenAI兼容格式:把请求体写对
DeepSeek API的接口路径是https://api.deepseek.com/chat/completions,请求结构跟OpenAI几乎一样。最精简的请求体长这样:
json复制{
"model": "deepseek-chat",
"messages": [
{"role": "system", "content": "你是一个智能助手"},
{"role": "user", "content": "用一句话介绍Spring Boot"}
],
"stream": false
}
messages数组是整个对话的核心,数组里每个元素代表一条消息,role有system、user、assistant三种,content是消息正文。系统提示词、历史对话、新问题都通过这个数组传给模型。不需要像老式接口那样拼字符串,模型会把数组里的所有内容当成完整的对话上下文。
2.3 鉴权头:Authorization里最常见的401
鉴权方式是在HTTP头里加Authorization: Bearer <你的API Key>。我见过最多的错误,就是代码里漏了Bearer这个前缀,或者把Key填进Header的参数名错了,服务端返回的一律是api_key_required之类错误。
一个完整的调通验证,用curl直接在命令行测最快:
bash复制curl https://api.deepseek.com/chat/completions \
-H "Authorization: Be
