1. 为什么在Spring Boot里接DeepSeek先得搞懂它的API风格过去一年里我接过大大小小七八个模型接口从各家私有化部署到云端API都有。坦白讲Spring Boot开发者第一次接触DeepSeek深度求索时最容易踩的坑不是代码写不出来而是用错了API调用姿势。DeepSeek的接口风格和OpenAI高度兼容但细节上有不少差异比如模型名称的语义、上下文的处理方式、超时行为的差异这些直接影响到你在Java代码里怎么写HTTP请求、怎么处理流式响应。先回答一个很多人关新的问题Spring Boot接入DeepSeek到底要准备什么核心就三件事一个DeepSeek开放平台的API Key一个能跑Spring Boot的JDK环境以及一个HTTP客户端。不需要引入任何DeepSeek专属SDK因为官方本身也没有提供Java版SDK但它的接口直接兼容OpenAI的调用协议所以你可以拿OpenAI的SDK来对接也可以自己用RestTemplate、WebClient或者原生的HttpURLConnection写。这点和很多国内模型服务不一样。那为什么我建议优先走OpenAI兼容协议而不是自己封装因为Spring Boot生态里已经有了大量针对OpenAI接口的封装比如spring-ai这个库它内部已经处理了请求构建、响应解析、Token用量统计这些琐碎事情。DeepSeek的接口在/chat/completions端点上保持了兼容所以spring-ai的OpenAI实现几乎不需要改就能对接DeepSeek。当然如果你不想引入额外依赖自己用HttpClient写也完全可行代码量在100行以内这个后面我详细展开。还有一个关键点必须提前说DeepSeek的模型分两个大方向——推理模型DeepSeek-R1系列和通用对话模型DeepSeek-V3系列。这两类模型在调用上有个细微差异R1系列会输出reasoning_content字段里面是模型的思维链内容V3系列则没有。如果你在Java里用统一的实体类去接收响应得把这个字段单独拎出来处理否则要么序列化报错要么拿到一堆无用的推理内容。这个属于光看文档发现不了、一跑就炸的经典问题后面我会专门讲。下面我从零开始按实际开发顺序把完整接入过程拆开讲。代码示例用Spring Boot 2.7.x JDK 17组合这两个版本目前是生产环境里最稳的搭配。2. 依赖选型OpenAI SDK、spring-ai、还是手写HttpClient2.1 三种方案的核心取舍先说结论如果你是一个跑生产服务的项目我推荐用OpenAI官方的Java SDKopenai-java或者spring-ai如果你是写工具类、内部小平台、快速验证Demo手写HttpClient最省事没有额外依赖出问题也容易排查。方案依赖量学习成本流式支持适合场景openai-java官方SDK中等低好内置SSE解析生产项目团队熟悉OpenAI协议spring-ai大中好封装流式回调深度使用Spring生态需要ChatMemory等功能手写HttpClient无额外依赖低需自己解析SSE格式小型工具、学习原理、排查问题这里要插一句spring-ai虽然名字里带Spring但它对不同模型厂商的适配深度不一样。它把OpenAI实现作为默认的基础实现DeepSeek因为兼容OpenAI协议所以理论上可以拿来直接用但我在实际项目中遇到过spring-ai的自动配置会按OpenAI的模型列表去做一些预校验导致DeepSeek的模型名传进去报404的问题。这个后面在避坑章节详细说如果你想省心openai-java会稳一些。2.2 手写HttpClient的最小代码骨架如果你不想引入任何额外依赖下面这套代码就是我实际在项目里用的最小骨架。用java.net.http.HttpClientJDK 11以后就有不需要引第三方库。import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; import com.fasterxml.jackson.databind.ObjectMapper; public class DeepSeekClient { private static final String API_URL https://api.deepseek.com/chat/completions; private final HttpClient client HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(30)) .build(); private final ObjectMapper mapper new ObjectMapper(); private final String apiKey; public DeepSeekClient(String apiKey) { this.apiKey apiKey; } public String chat(String userMessage) throws Exception { // 构造请求体这里用Map是为了让你看清结构实际开发建议定义专门的DTO var body mapper.writeValueAsString(Map.of( model, deepseek-chat, messages, new Object[]{ Map.of(role, user, content, userMessage) }, temperature, 0.7, stream, false )); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(API_URL)) .timeout(Duration.ofSeconds(60)) .header(Content-Type, application/json) .header(Authorization, Bearer apiKey) .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() ! 200) { throw new RuntimeException(DeepSeek API error: response.statusCode() response.body()); } return response.body(); } }这段代码的逻辑很直白把用户消息封装成JSON带上鉴权头发POST请求拿到响应后原样返回字符串。注意点有两个第一api.deepseek.com是官方标准端点也有人用api.deepseek.com/v1实际上两者都能通因为官方在网关层做了兼容跳转第二Authorization头的格式必须带Bearer前缀大小写都别错这个错了会直接返回401且错误信息有一定迷惑性。2.3 走OpenAI官方Java SDK的接入方式如果你倾向用SDK以openai-java为例在pom.xml里加dependency groupIdcom.openai/groupId artifactIdopenai-java/artifactId version0.12.0/version /dependency需要注意这个SDK不同版本之间的API变化比较大早期版本0.4.x和后续版本的包名、方法名都不同。我用的是0.12.0这个较新的版本调用方式如下import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatCompletionCreateParams; import com.openai.models.ChatCompletion; import com.openai.models.ChatModel; public class DeepSeekSdkDemo { public static void main(String[] args) { OpenAIClient client OpenAIOkHttpClient.builder() .apiKey(sk-xxxx) .baseUrl(https://api.deepseek.com) .build(); ChatCompletionCreateParams params ChatCompletionCreateParams.builder() .model(ChatModel.of(deepseek-chat)) .addUserMessage(用Java写一个快速排序) .build(); ChatCompletion completion client.chat().completions().create(params); String content completion.choices().get(0).message().content().orElse(); System.out.println(content); } }这里有个关键点baseUrl要设成https://api.deepseek.com而不是OpenAI的默认地址否则SDK会把请求打到OpenAI那边去。另外ChatModel.of(deepseek-chat)是绕过SDK内置的模型枚举直接传字符串如果你用SDK自带的ChatModel.GPT_4O_MINI这种枚举DeepSeek网关大概率会返回模型不存在。SDK的好处是它能自动处理JSON响应到Java对象的映射包括choices数组、message.content是Optional类型这些细节代码读起来干净很多。缺点是SDK依赖的底层HTTP库是OkHttp会额外引入一些传递依赖如果你项目里已经用了别的HTTP客户端要注意依赖冲突。3. 核心调用链路的代码设计从配置文件到响应解析3.1 标准的三层结构设计手写HttpClient的写法适合Demo但进了正式项目我一般会把DeepSeek的调用拆成三层配置层Configuration、服务层Service、接口层Controller。这样做的原因很实际第一API Key不能散落在代码各个角落要用配置中心和本地配置统一管理第二模型调用要预留重试、限流、日志审计的扩展点第三接口层需要面向业务设计返回结构而不是把DeepSeek的原始响应直接抛给前端。配置层示例在application.yml里deepseek: api-key: ${DEEPSEEK_API_KEY} base-url: https://api.deepseek.com model: deepseek-chat temperature: 0.7 max-tokens: 2048 timeout-seconds: 60对应一个配置类import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; Component ConfigurationProperties(prefix deepseek) public class DeepSeekProperties { private String apiKey; private String baseUrl https://api.deepseek.com; private String model deepseek-chat; private double temperature 0.7; private Integer maxTokens 2048; private int timeoutSeconds 60; // getter/setter省略 }api-key从环境变量DEEPSEEK_API_KEY读取而不是硬编码在配置文件里这个习惯能避免Key泄露到Git仓库。3.2 Service层请求构造与响应解析Service层是核心。我建议把请求体、响应体都定义成Java记录Record或者普通POJO别用Map满天飞因为temperature、max_tokens这些字段名的下划线风格和Java的驼峰风格有差异Jackson默认不会自动转换需要JsonProperty注解逐一映射。import com.fasterxml.jackson.annotation.JsonProperty; import java.util.List; public record DeepSeekRequest( String model, ListMessage messages, double temperature, JsonProperty(max_tokens) Integer maxTokens, boolean stream ) { public record Message(String role, String content) {} }DeepSeek对max_tokens有一个限制V3和R1模型的上限是8192这是文档上写的最大值实际请求里不会超过这个值也不会低于某个下限。如果你传了超过8192的值API会直接报参数错误而不是帮你截断所以配置里给个保守的2048比较安全。响应体解析时我一般只提取三个东西choices[0].message.content最终回答内容、usage.prompt_tokens输入Token数、usage.completion_tokens输出Token数。R1系列模型还会多一个choices[0].message.reasoning_content字段里面是模型的思考过程这个字段在V3里不存在所以如果用统一实体接收需要把这个字段声明为可选public record DeepSeekResponse( ListChoice choices, Usage usage ) { public record Choice(Message message) {} public record Message(String role, String content, String reasoning_content) {} public record Usage( JsonProperty(prompt_tokens) int promptTokens, JsonProperty(completion_tokens) int completionTokens, JsonProperty(total_tokens) int totalTokens ) {} }注意reasoning_content这个字段如果你用严格的Jackson配置比如禁用了FAIL_ON_UNKNOWN_PROPERTIES反而不设置JsonIgnoreProperties(ignoreUnknown true)V3模型的响应里没有这个字段就会报反序列化错误。所以建议在你的ObjectMapper配置里加上这一句ObjectMapper mapper new ObjectMapper() .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);我见过有同事因为这个小地方排查了半天最后发现不是接口问题是Jackson默认的严格模式把未知字段直接抛异常了。3.3 抽象出一个统一的聊天Service接口为了让Controller层不要关心底层是DeepSeek还是别的模型我会抽一个简单的接口public interface ChatService { String chat(String userMessage); ListString chatStream(String userMessage); } Service public class DeepSeekChatService implements ChatService { private final HttpRequestHelper requestHelper; private final DeepSeekProperties properties; public DeepSeekChatService(HttpRequestHelper requestHelper, DeepSeekProperties properties) { this.requestHelper requestHelper; this.properties properties; } Override public String chat(String userMessage) { try { String responseBody requestHelper.post(properties.getBaseUrl() /chat/completions, buildRequestBody(userMessage, false)); DeepSeekResponse response parseResponse(responseBody); return response.choices().get(0).message().content(); } catch (Exception e) { throw new ChatException(DeepSeek调用失败, e); } } }这样的好处是后面如果要从deepseek-chat切到deepseek-reasoner或者换成别的兼容OpenAI协议的模型服务只需要改配置和Service内部实现Controller层完全不用动。4. 实测踩坑请求超时、上下文管理、Token计费与流式输出4.1 请求超时和重试策略的坑接DeepSeek的第一个实际问题就是慢。R1推理模型在思考复杂问题时耗时可能达到30秒甚至60秒如果你们公司的网关Nginx默认超时是30秒那请求基本必挂。我自己在开发环境就遇到过用postman直连API没问题但一上Spring Boot接口报504网关超时排查方向一开始以为是代码问题后来才发现是Nginx的proxy_read_timeout设成了30秒。所以要分三层设置超时代码层HttpClient超时时间不要低于60秒最好设到120秒。网关层如果你有Nginx或Spring Cloud Gateway把读超时和连接超时都设成匹配值。前端层如果请求是浏览器发起的fetch默认超时不受服务端控制但连接池会被长时间占用的连接拖垮注意并发量控制。重试策略上DeepSeek的限流响应是429状态码偶尔也会返回503。我建议只在429和503时重试且最多重试两次每次间隔指数退避1秒、2秒。不要对4xx错误重试比如401鉴权错误重试一百次也没用。实际项目里我封装了一个简单的重试工具用Spring Retry最省事Bean public RetryTemplate retryTemplate() { return RetryTemplate.builder() .maxAttempts(3) .exponentialBackoff(1000, 2, 5000) .retryOn(TooManyRequestsException.class) .build(); }注意不要把业务异常也放进去重试否则一个因为参数错误导致的4xx会白白拖慢接口响应。4.2 上下文管理别把用户所有聊天记录都塞进去DeepSeek的API本身不做历史消息存储它只是一个无状态的处理服务。你每次调用都得把历史对话拼在messages数组里传递过去它才能有记忆。但这里有个隐患对话越长Token费用越高同时模型响应速度也会变慢。我实测过一组数据用deepseek-chat模型上下文长度和响应时间的关系大致如下上下文Token数单次响应耗时非流式约等效中文长度2K1-3秒约1500字对白8K5-10秒约6000字对白32K15-30秒约24000字对白所以生产环境不要无脑拼历史消息要做上下文窗口裁剪。常见的做法是保留系统提示词system 最近N轮对话超出部分截断丢弃。我在项目里设置的是保留最近10轮对话大约能覆盖用户半个小时内的问题范围。如果是一个知识库问答类应用更务实的做法是先用向量检索召回相关片段再把这些片段组装到messages里而不是把用户所有历史问题都带上。4.3 Token计费怎么在代码里统计和预警DeepSeek的计费是按Token来的不同模型单价不一样。我建议在Service层解析usage字段后把每次调用的Token消耗写入日志或数据库这样月底算成本有据可查。日志格式可以简单点log.info(DeepSeek调用完成, promptTokens{}, completionTokens{}, totalTokens{}, model{}, response.usage().promptTokens(), response.usage().completionTokens(), response.usage().totalTokens(), properties.getModel());如果你想在调用之前就算出大概花多少钱需要估算Token数。中文字符和Token的比例实测下来大概是1个汉字对应1到1.5个Token英文则是1个单词约等于1.3个Token。当然这是经验值实际以API返回的usage为准。我的经验是与其花时间做精细预估不如在代码里做一个简单的阈值告警单日累计消耗超过预设金额就发企业微信或钉钉消息这样成本可控又不费力。4.4 流式输出SSE解析的细节聊天应用如果不用流式输出用户等8秒才看到第一句话体验很差。DeepSeek的流式接口和OpenAI一样返回text/event-stream格式每行形如data: {...}。用Spring Boot实现流式最直接的方式是使用Spring的StreamingResponseBody或SseEmitter。我实际项目里用SseEmitter比较多因为它对浏览器EventSource友好。核心代码如下GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter chatStream(RequestParam String message) { SseEmitter emitter new SseEmitter(120_000L); executorService.execute(() - { try { // 发起DeepSeek流式请求逐块解析SSE事件 deepSeekClient.streamChat(message, chunk - { try { emitter.send(SseEmitter.event().data(chunk)); } catch (IOException e) { emitter.completeWithError(e); } }); emitter.complete(); } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; }注意这里的SseEmitter(120_000L)设置了超时时间意思是120秒内没有数据推送就自动断开。很多人的坑在于忘记设置这个超时时间默认的SseEmitter行为可能导致连接长时间挂起占用Tomcat线程池。流式解析时要注意SSE格式的边界每个事件块以data:开头内容是一段JSON。要处理[DONE]这个结束标志某些兼容实现会发这个以及保持连接的心跳注释行: heartbeat。如果你用OKhttp的ResponseBody逐行读取记得设置字符集UTF-8否则中文内容会乱码。5. 在Controller层暴露接口普通返回与流式输出怎么选5.1 面向业务的统一响应结构不管前端是什么框架我给后端接口定了一个统一响应格式避免每个接口各自返回不同的JSON结构。实际项目里我用的就是这个标准结构{ code: 0, message: success, data: { content: 这是DeepSeek返回的内容, promptTokens: 128, completionTokens: 256 } }对应的Java类public record ApiResponseT(int code, String message, T data) { public static T ApiResponseT ok(T data) { return new ApiResponse(0, success, data); } }Controller层面向业务时不要直接把DeepSeekResponse整个抛出去因为里面的reasoning_content字段、choices数组结构、usage里的原始计费数据前端根本用不上而且暴露模型内部结构会让接口变得难维护。我一般把content和usage提取成一个轻量的ChatResult对象。5.2 普通接口的完整示例如下RestController RequestMapping(/api/chat) public class ChatController { private final ChatService chatService; public ChatController(ChatService chatService) { this.chatService chatService; } PostMapping public ApiResponseChatResult chat(RequestBody ChatRequest request) { String result chatService.chat(request.message()); ChatResult data new ChatResult(result, null, null); return ApiResponse.ok(data); } public record ChatRequest(String message) {} public record ChatResult(String content, Integer promptTokens, Integer completionTokens) {} }如果只是给内部管理系统做个简单问答助手这个接口就够用了。但如果是给C端用户做的客服、AI助手那流式接口几乎是必须的。流式接口的设计上我建议让前端传一个stream字段来切换模式这样同一个接口既能支持普通轮询又能支持SSE流式前端代码不用写两套。5.3 流式接口的取舍提醒流式接口虽然体验好但有一个实际麻烦后端日志里很难看到完整的返回内容因为内容是一块一块发出去的。所以我在生产环境里保存的是完整的completion_tokens和首尾各截断一部分的内容摘要而不是全部输出。这也意味着如果你要做对话质检、内容审核得在Service层拿到全量内容后再统一处理不能等流式推给用户了才想起来做。6. 再说DeepSeek部署和模型选择的几个实际问题6.1 云端API和本地部署的分界线很多人被DeepSeek本地部署这个词吸引想在服务器或者Jetson Orin这类设备上跑一个自己的模型服务彻底摆脱API的Token费用和限流。这个思路没问题但我要泼一盆冷水DeepSeek官方开源的模型权重完整版的R1需要相当的硬件配置家用显卡跑的是量化版本效果和云端API有差距。本地部署更适合对数据私密性要求极高的场景比如企业内部文档分析、医疗数据处理等这些场景压根不允许把数据发到外部API。如果你的团队确实有本地部署的需求在Java里接入的方式反而更简单本地部署的模型服务一般会提供一个兼容OpenAI格式的HTTP端点比如http://localhost:11434/v1。你只要把Spring Boot配置里的base-url改成这个地址代码完全不用动。从这个角度看前面把API调用封装成独立Service层的设计就体现出价值了。6.2 模型选择deepseek-chat和deepseek-reasoner使用时机上的区别DeepSeek开放平台上主要有两个模型标识deepseek-chat对应V3系列和deepseek-reasoner对应R1系列。很多人拿到API Key后习惯性用deepseek-chat这个在大多数场景是对的因为响应快费用低。但如果是做数学题、复杂逻辑推理、代码调试这类需要深度思考的任务deepseek-reasoner的效果会明显好一截。我在项目里的做法是让用户自己选模式普通问答走deepseek-chat点击深度思考按钮时切换成deepseek-reasoner。配置上就一行区别deepseek: model: deepseek-chat # 默认 reasoning-model: deepseek-reasoner # 深度思考时切换需要注意的是deepseek-reasoner的价格约为deepseek-chat的几倍具体数字会调整但量级差异一直都在上线前务必在页面上做提示避免用户误操作产生高额账单。6.3 实测数据一个Spring Boot接口的最简性能参考最后给一个我自己压测的参考数据帮助你对容量有个直观感受。环境8核16G服务器Spring Boot 2.7Tomcat默认配置并发压测非流式接口deepseek-chat模型单请求平均耗时约4秒。并发数成功率平均响应时间备注5100%4.2秒正常2098%6.5秒偶尔超时5085%9.8秒大量超时触发重试结论是这种AI接口绝不能像普通数据库接口那样扛高并发因为你的瓶颈在模型服务端不在Spring Boot本身。如果业务上有高并发诉求必须在Spring Boot前面加一层请求队列或缓存把相同的问题缓存起来而不是每次都打到模型服务去。7. 接入后的第一轮优化缓存、并发控制与成本治理7.1 缓存命中策略AI接口的费用大头在重复问答上。我在一个内部知识问答系统里实测过用户提问的重合率接近15%也就是每7个问题里就有一个是以前问过的。针对这种场景可以做一个简单的缓存以问题文本的哈希值作为Key把答案缓存到本地Caffeine或Redis里命中就直接返回。Bean public CacheString, String chatCache() { return Caffeine.newBuilder() .maximumSize(1000) .expireAfterWrite(Duration.ofHours(24)) .build(); }需要注意的是缓存不能缓存流式接口因为流式接口的输出本身是逐步产生的缓存命中后只能一次性返回表现上会和流式不一致。我的做法是普通接口加缓存流式接口不加或者只在面板上提供重新生成的入口让用户主动绕过缓存。7.2 并发控制给调用链路加信号量模型服务的并发能力是有限的如果怕突发流量打爆套餐或触发限流可以在Service层加一个简单的Semaphoreprivate final Semaphore semaphore new Semaphore(10); // 最大10个并发请求 public String chat(String message) { if (!semaphore.tryAcquire(3, TimeUnit.SECONDS)) { throw new TooManyRequestsException(当前AI服务繁忙请稍后再试); } try { return doChat(message); } finally { semaphore.release(); } }这个做法的意义有两层第一保护你的API配额避免瞬间并发导致账号被限流第二保护你的后端线程池避免大量长时间挂起的AI请求把Tomcat线程池占满导致普通接口也无法响应。信号量的值可以参考你对模型服务的压测结果我一般先设10根据线上监控再调。7.3 成本治理日志里算明白每一笔账接入AI能力后成本治理容易被人忽略直到月底账单吓一跳。我习惯在日志里输出结构化的Token消耗配合Elasticsearch或简单日志分析脚本就能算出每个业务线的花费。如果公司内部有多套应用一起接入我建议在请求体里加一个user字段或者metadata字段标注这次请求来自哪个应用、哪个业务线方便做成本分摊。DeepSeek的接口调用本身不复杂真正有价值的是在接入之前考虑清楚模型怎么选、上下文怎么管理、成本怎么控制、并发怎么保护。把这些都想明白了Spring Boot接入DeepSeek就是几个小时的事情反之代码写完了也容易在性能和费用上翻车。根据我个人的经验第一次接入时建议把日志打得完整一点记录请求体脱敏、响应体、Token消耗和耗时这样出问题时有据可查后面优化也有基准数据可用。
Spring Boot接入DeepSeek实战：从API调用到流式输出与成本治理
1. 为什么在Spring Boot里接DeepSeek先得搞懂它的API风格过去一年里我接过大大小小七八个模型接口从各家私有化部署到云端API都有。坦白讲Spring Boot开发者第一次接触DeepSeek深度求索时最容易踩的坑不是代码写不出来而是用错了API调用姿势。DeepSeek的接口风格和OpenAI高度兼容但细节上有不少差异比如模型名称的语义、上下文的处理方式、超时行为的差异这些直接影响到你在Java代码里怎么写HTTP请求、怎么处理流式响应。先回答一个很多人关新的问题Spring Boot接入DeepSeek到底要准备什么核心就三件事一个DeepSeek开放平台的API Key一个能跑Spring Boot的JDK环境以及一个HTTP客户端。不需要引入任何DeepSeek专属SDK因为官方本身也没有提供Java版SDK但它的接口直接兼容OpenAI的调用协议所以你可以拿OpenAI的SDK来对接也可以自己用RestTemplate、WebClient或者原生的HttpURLConnection写。这点和很多国内模型服务不一样。那为什么我建议优先走OpenAI兼容协议而不是自己封装因为Spring Boot生态里已经有了大量针对OpenAI接口的封装比如spring-ai这个库它内部已经处理了请求构建、响应解析、Token用量统计这些琐碎事情。DeepSeek的接口在/chat/completions端点上保持了兼容所以spring-ai的OpenAI实现几乎不需要改就能对接DeepSeek。当然如果你不想引入额外依赖自己用HttpClient写也完全可行代码量在100行以内这个后面我详细展开。还有一个关键点必须提前说DeepSeek的模型分两个大方向——推理模型DeepSeek-R1系列和通用对话模型DeepSeek-V3系列。这两类模型在调用上有个细微差异R1系列会输出reasoning_content字段里面是模型的思维链内容V3系列则没有。如果你在Java里用统一的实体类去接收响应得把这个字段单独拎出来处理否则要么序列化报错要么拿到一堆无用的推理内容。这个属于光看文档发现不了、一跑就炸的经典问题后面我会专门讲。下面我从零开始按实际开发顺序把完整接入过程拆开讲。代码示例用Spring Boot 2.7.x JDK 17组合这两个版本目前是生产环境里最稳的搭配。2. 依赖选型OpenAI SDK、spring-ai、还是手写HttpClient2.1 三种方案的核心取舍先说结论如果你是一个跑生产服务的项目我推荐用OpenAI官方的Java SDKopenai-java或者spring-ai如果你是写工具类、内部小平台、快速验证Demo手写HttpClient最省事没有额外依赖出问题也容易排查。方案依赖量学习成本流式支持适合场景openai-java官方SDK中等低好内置SSE解析生产项目团队熟悉OpenAI协议spring-ai大中好封装流式回调深度使用Spring生态需要ChatMemory等功能手写HttpClient无额外依赖低需自己解析SSE格式小型工具、学习原理、排查问题这里要插一句spring-ai虽然名字里带Spring但它对不同模型厂商的适配深度不一样。它把OpenAI实现作为默认的基础实现DeepSeek因为兼容OpenAI协议所以理论上可以拿来直接用但我在实际项目中遇到过spring-ai的自动配置会按OpenAI的模型列表去做一些预校验导致DeepSeek的模型名传进去报404的问题。这个后面在避坑章节详细说如果你想省心openai-java会稳一些。2.2 手写HttpClient的最小代码骨架如果你不想引入任何额外依赖下面这套代码就是我实际在项目里用的最小骨架。用java.net.http.HttpClientJDK 11以后就有不需要引第三方库。import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; import com.fasterxml.jackson.databind.ObjectMapper; public class DeepSeekClient { private static final String API_URL https://api.deepseek.com/chat/completions; private final HttpClient client HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(30)) .build(); private final ObjectMapper mapper new ObjectMapper(); private final String apiKey; public DeepSeekClient(String apiKey) { this.apiKey apiKey; } public String chat(String userMessage) throws Exception { // 构造请求体这里用Map是为了让你看清结构实际开发建议定义专门的DTO var body mapper.writeValueAsString(Map.of( model, deepseek-chat, messages, new Object[]{ Map.of(role, user, content, userMessage) }, temperature, 0.7, stream, false )); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(API_URL)) .timeout(Duration.ofSeconds(60)) .header(Content-Type, application/json) .header(Authorization, Bearer apiKey) .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() ! 200) { throw new RuntimeException(DeepSeek API error: response.statusCode() response.body()); } return response.body(); } }这段代码的逻辑很直白把用户消息封装成JSON带上鉴权头发POST请求拿到响应后原样返回字符串。注意点有两个第一api.deepseek.com是官方标准端点也有人用api.deepseek.com/v1实际上两者都能通因为官方在网关层做了兼容跳转第二Authorization头的格式必须带Bearer前缀大小写都别错这个错了会直接返回401且错误信息有一定迷惑性。2.3 走OpenAI官方Java SDK的接入方式如果你倾向用SDK以openai-java为例在pom.xml里加dependency groupIdcom.openai/groupId artifactIdopenai-java/artifactId version0.12.0/version /dependency需要注意这个SDK不同版本之间的API变化比较大早期版本0.4.x和后续版本的包名、方法名都不同。我用的是0.12.0这个较新的版本调用方式如下import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatCompletionCreateParams; import com.openai.models.ChatCompletion; import com.openai.models.ChatModel; public class DeepSeekSdkDemo { public static void main(String[] args) { OpenAIClient client OpenAIOkHttpClient.builder() .apiKey(sk-xxxx) .baseUrl(https://api.deepseek.com) .build(); ChatCompletionCreateParams params ChatCompletionCreateParams.builder() .model(ChatModel.of(deepseek-chat)) .addUserMessage(用Java写一个快速排序) .build(); ChatCompletion completion client.chat().completions().create(params); String content completion.choices().get(0).message().content().orElse(); System.out.println(content); } }这里有个关键点baseUrl要设成https://api.deepseek.com而不是OpenAI的默认地址否则SDK会把请求打到OpenAI那边去。另外ChatModel.of(deepseek-chat)是绕过SDK内置的模型枚举直接传字符串如果你用SDK自带的ChatModel.GPT_4O_MINI这种枚举DeepSeek网关大概率会返回模型不存在。SDK的好处是它能自动处理JSON响应到Java对象的映射包括choices数组、message.content是Optional类型这些细节代码读起来干净很多。缺点是SDK依赖的底层HTTP库是OkHttp会额外引入一些传递依赖如果你项目里已经用了别的HTTP客户端要注意依赖冲突。3. 核心调用链路的代码设计从配置文件到响应解析3.1 标准的三层结构设计手写HttpClient的写法适合Demo但进了正式项目我一般会把DeepSeek的调用拆成三层配置层Configuration、服务层Service、接口层Controller。这样做的原因很实际第一API Key不能散落在代码各个角落要用配置中心和本地配置统一管理第二模型调用要预留重试、限流、日志审计的扩展点第三接口层需要面向业务设计返回结构而不是把DeepSeek的原始响应直接抛给前端。配置层示例在application.yml里deepseek: api-key: ${DEEPSEEK_API_KEY} base-url: https://api.deepseek.com model: deepseek-chat temperature: 0.7 max-tokens: 2048 timeout-seconds: 60对应一个配置类import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; Component ConfigurationProperties(prefix deepseek) public class DeepSeekProperties { private String apiKey; private String baseUrl https://api.deepseek.com; private String model deepseek-chat; private double temperature 0.7; private Integer maxTokens 2048; private int timeoutSeconds 60; // getter/setter省略 }api-key从环境变量DEEPSEEK_API_KEY读取而不是硬编码在配置文件里这个习惯能避免Key泄露到Git仓库。3.2 Service层请求构造与响应解析Service层是核心。我建议把请求体、响应体都定义成Java记录Record或者普通POJO别用Map满天飞因为temperature、max_tokens这些字段名的下划线风格和Java的驼峰风格有差异Jackson默认不会自动转换需要JsonProperty注解逐一映射。import com.fasterxml.jackson.annotation.JsonProperty; import java.util.List; public record DeepSeekRequest( String model, ListMessage messages, double temperature, JsonProperty(max_tokens) Integer maxTokens, boolean stream ) { public record Message(String role, String content) {} }DeepSeek对max_tokens有一个限制V3和R1模型的上限是8192这是文档上写的最大值实际请求里不会超过这个值也不会低于某个下限。如果你传了超过8192的值API会直接报参数错误而不是帮你截断所以配置里给个保守的2048比较安全。响应体解析时我一般只提取三个东西choices[0].message.content最终回答内容、usage.prompt_tokens输入Token数、usage.completion_tokens输出Token数。R1系列模型还会多一个choices[0].message.reasoning_content字段里面是模型的思考过程这个字段在V3里不存在所以如果用统一实体接收需要把这个字段声明为可选public record DeepSeekResponse( ListChoice choices, Usage usage ) { public record Choice(Message message) {} public record Message(String role, String content, String reasoning_content) {} public record Usage( JsonProperty(prompt_tokens) int promptTokens, JsonProperty(completion_tokens) int completionTokens, JsonProperty(total_tokens) int totalTokens ) {} }注意reasoning_content这个字段如果你用严格的Jackson配置比如禁用了FAIL_ON_UNKNOWN_PROPERTIES反而不设置JsonIgnoreProperties(ignoreUnknown true)V3模型的响应里没有这个字段就会报反序列化错误。所以建议在你的ObjectMapper配置里加上这一句ObjectMapper mapper new ObjectMapper() .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);我见过有同事因为这个小地方排查了半天最后发现不是接口问题是Jackson默认的严格模式把未知字段直接抛异常了。3.3 抽象出一个统一的聊天Service接口为了让Controller层不要关心底层是DeepSeek还是别的模型我会抽一个简单的接口public interface ChatService { String chat(String userMessage); ListString chatStream(String userMessage); } Service public class DeepSeekChatService implements ChatService { private final HttpRequestHelper requestHelper; private final DeepSeekProperties properties; public DeepSeekChatService(HttpRequestHelper requestHelper, DeepSeekProperties properties) { this.requestHelper requestHelper; this.properties properties; } Override public String chat(String userMessage) { try { String responseBody requestHelper.post(properties.getBaseUrl() /chat/completions, buildRequestBody(userMessage, false)); DeepSeekResponse response parseResponse(responseBody); return response.choices().get(0).message().content(); } catch (Exception e) { throw new ChatException(DeepSeek调用失败, e); } } }这样的好处是后面如果要从deepseek-chat切到deepseek-reasoner或者换成别的兼容OpenAI协议的模型服务只需要改配置和Service内部实现Controller层完全不用动。4. 实测踩坑请求超时、上下文管理、Token计费与流式输出4.1 请求超时和重试策略的坑接DeepSeek的第一个实际问题就是慢。R1推理模型在思考复杂问题时耗时可能达到30秒甚至60秒如果你们公司的网关Nginx默认超时是30秒那请求基本必挂。我自己在开发环境就遇到过用postman直连API没问题但一上Spring Boot接口报504网关超时排查方向一开始以为是代码问题后来才发现是Nginx的proxy_read_timeout设成了30秒。所以要分三层设置超时代码层HttpClient超时时间不要低于60秒最好设到120秒。网关层如果你有Nginx或Spring Cloud Gateway把读超时和连接超时都设成匹配值。前端层如果请求是浏览器发起的fetch默认超时不受服务端控制但连接池会被长时间占用的连接拖垮注意并发量控制。重试策略上DeepSeek的限流响应是429状态码偶尔也会返回503。我建议只在429和503时重试且最多重试两次每次间隔指数退避1秒、2秒。不要对4xx错误重试比如401鉴权错误重试一百次也没用。实际项目里我封装了一个简单的重试工具用Spring Retry最省事Bean public RetryTemplate retryTemplate() { return RetryTemplate.builder() .maxAttempts(3) .exponentialBackoff(1000, 2, 5000) .retryOn(TooManyRequestsException.class) .build(); }注意不要把业务异常也放进去重试否则一个因为参数错误导致的4xx会白白拖慢接口响应。4.2 上下文管理别把用户所有聊天记录都塞进去DeepSeek的API本身不做历史消息存储它只是一个无状态的处理服务。你每次调用都得把历史对话拼在messages数组里传递过去它才能有记忆。但这里有个隐患对话越长Token费用越高同时模型响应速度也会变慢。我实测过一组数据用deepseek-chat模型上下文长度和响应时间的关系大致如下上下文Token数单次响应耗时非流式约等效中文长度2K1-3秒约1500字对白8K5-10秒约6000字对白32K15-30秒约24000字对白所以生产环境不要无脑拼历史消息要做上下文窗口裁剪。常见的做法是保留系统提示词system 最近N轮对话超出部分截断丢弃。我在项目里设置的是保留最近10轮对话大约能覆盖用户半个小时内的问题范围。如果是一个知识库问答类应用更务实的做法是先用向量检索召回相关片段再把这些片段组装到messages里而不是把用户所有历史问题都带上。4.3 Token计费怎么在代码里统计和预警DeepSeek的计费是按Token来的不同模型单价不一样。我建议在Service层解析usage字段后把每次调用的Token消耗写入日志或数据库这样月底算成本有据可查。日志格式可以简单点log.info(DeepSeek调用完成, promptTokens{}, completionTokens{}, totalTokens{}, model{}, response.usage().promptTokens(), response.usage().completionTokens(), response.usage().totalTokens(), properties.getModel());如果你想在调用之前就算出大概花多少钱需要估算Token数。中文字符和Token的比例实测下来大概是1个汉字对应1到1.5个Token英文则是1个单词约等于1.3个Token。当然这是经验值实际以API返回的usage为准。我的经验是与其花时间做精细预估不如在代码里做一个简单的阈值告警单日累计消耗超过预设金额就发企业微信或钉钉消息这样成本可控又不费力。4.4 流式输出SSE解析的细节聊天应用如果不用流式输出用户等8秒才看到第一句话体验很差。DeepSeek的流式接口和OpenAI一样返回text/event-stream格式每行形如data: {...}。用Spring Boot实现流式最直接的方式是使用Spring的StreamingResponseBody或SseEmitter。我实际项目里用SseEmitter比较多因为它对浏览器EventSource友好。核心代码如下GetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter chatStream(RequestParam String message) { SseEmitter emitter new SseEmitter(120_000L); executorService.execute(() - { try { // 发起DeepSeek流式请求逐块解析SSE事件 deepSeekClient.streamChat(message, chunk - { try { emitter.send(SseEmitter.event().data(chunk)); } catch (IOException e) { emitter.completeWithError(e); } }); emitter.complete(); } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; }注意这里的SseEmitter(120_000L)设置了超时时间意思是120秒内没有数据推送就自动断开。很多人的坑在于忘记设置这个超时时间默认的SseEmitter行为可能导致连接长时间挂起占用Tomcat线程池。流式解析时要注意SSE格式的边界每个事件块以data:开头内容是一段JSON。要处理[DONE]这个结束标志某些兼容实现会发这个以及保持连接的心跳注释行: heartbeat。如果你用OKhttp的ResponseBody逐行读取记得设置字符集UTF-8否则中文内容会乱码。5. 在Controller层暴露接口普通返回与流式输出怎么选5.1 面向业务的统一响应结构不管前端是什么框架我给后端接口定了一个统一响应格式避免每个接口各自返回不同的JSON结构。实际项目里我用的就是这个标准结构{ code: 0, message: success, data: { content: 这是DeepSeek返回的内容, promptTokens: 128, completionTokens: 256 } }对应的Java类public record ApiResponseT(int code, String message, T data) { public static T ApiResponseT ok(T data) { return new ApiResponse(0, success, data); } }Controller层面向业务时不要直接把DeepSeekResponse整个抛出去因为里面的reasoning_content字段、choices数组结构、usage里的原始计费数据前端根本用不上而且暴露模型内部结构会让接口变得难维护。我一般把content和usage提取成一个轻量的ChatResult对象。5.2 普通接口的完整示例如下RestController RequestMapping(/api/chat) public class ChatController { private final ChatService chatService; public ChatController(ChatService chatService) { this.chatService chatService; } PostMapping public ApiResponseChatResult chat(RequestBody ChatRequest request) { String result chatService.chat(request.message()); ChatResult data new ChatResult(result, null, null); return ApiResponse.ok(data); } public record ChatRequest(String message) {} public record ChatResult(String content, Integer promptTokens, Integer completionTokens) {} }如果只是给内部管理系统做个简单问答助手这个接口就够用了。但如果是给C端用户做的客服、AI助手那流式接口几乎是必须的。流式接口的设计上我建议让前端传一个stream字段来切换模式这样同一个接口既能支持普通轮询又能支持SSE流式前端代码不用写两套。5.3 流式接口的取舍提醒流式接口虽然体验好但有一个实际麻烦后端日志里很难看到完整的返回内容因为内容是一块一块发出去的。所以我在生产环境里保存的是完整的completion_tokens和首尾各截断一部分的内容摘要而不是全部输出。这也意味着如果你要做对话质检、内容审核得在Service层拿到全量内容后再统一处理不能等流式推给用户了才想起来做。6. 再说DeepSeek部署和模型选择的几个实际问题6.1 云端API和本地部署的分界线很多人被DeepSeek本地部署这个词吸引想在服务器或者Jetson Orin这类设备上跑一个自己的模型服务彻底摆脱API的Token费用和限流。这个思路没问题但我要泼一盆冷水DeepSeek官方开源的模型权重完整版的R1需要相当的硬件配置家用显卡跑的是量化版本效果和云端API有差距。本地部署更适合对数据私密性要求极高的场景比如企业内部文档分析、医疗数据处理等这些场景压根不允许把数据发到外部API。如果你的团队确实有本地部署的需求在Java里接入的方式反而更简单本地部署的模型服务一般会提供一个兼容OpenAI格式的HTTP端点比如http://localhost:11434/v1。你只要把Spring Boot配置里的base-url改成这个地址代码完全不用动。从这个角度看前面把API调用封装成独立Service层的设计就体现出价值了。6.2 模型选择deepseek-chat和deepseek-reasoner使用时机上的区别DeepSeek开放平台上主要有两个模型标识deepseek-chat对应V3系列和deepseek-reasoner对应R1系列。很多人拿到API Key后习惯性用deepseek-chat这个在大多数场景是对的因为响应快费用低。但如果是做数学题、复杂逻辑推理、代码调试这类需要深度思考的任务deepseek-reasoner的效果会明显好一截。我在项目里的做法是让用户自己选模式普通问答走deepseek-chat点击深度思考按钮时切换成deepseek-reasoner。配置上就一行区别deepseek: model: deepseek-chat # 默认 reasoning-model: deepseek-reasoner # 深度思考时切换需要注意的是deepseek-reasoner的价格约为deepseek-chat的几倍具体数字会调整但量级差异一直都在上线前务必在页面上做提示避免用户误操作产生高额账单。6.3 实测数据一个Spring Boot接口的最简性能参考最后给一个我自己压测的参考数据帮助你对容量有个直观感受。环境8核16G服务器Spring Boot 2.7Tomcat默认配置并发压测非流式接口deepseek-chat模型单请求平均耗时约4秒。并发数成功率平均响应时间备注5100%4.2秒正常2098%6.5秒偶尔超时5085%9.8秒大量超时触发重试结论是这种AI接口绝不能像普通数据库接口那样扛高并发因为你的瓶颈在模型服务端不在Spring Boot本身。如果业务上有高并发诉求必须在Spring Boot前面加一层请求队列或缓存把相同的问题缓存起来而不是每次都打到模型服务去。7. 接入后的第一轮优化缓存、并发控制与成本治理7.1 缓存命中策略AI接口的费用大头在重复问答上。我在一个内部知识问答系统里实测过用户提问的重合率接近15%也就是每7个问题里就有一个是以前问过的。针对这种场景可以做一个简单的缓存以问题文本的哈希值作为Key把答案缓存到本地Caffeine或Redis里命中就直接返回。Bean public CacheString, String chatCache() { return Caffeine.newBuilder() .maximumSize(1000) .expireAfterWrite(Duration.ofHours(24)) .build(); }需要注意的是缓存不能缓存流式接口因为流式接口的输出本身是逐步产生的缓存命中后只能一次性返回表现上会和流式不一致。我的做法是普通接口加缓存流式接口不加或者只在面板上提供重新生成的入口让用户主动绕过缓存。7.2 并发控制给调用链路加信号量模型服务的并发能力是有限的如果怕突发流量打爆套餐或触发限流可以在Service层加一个简单的Semaphoreprivate final Semaphore semaphore new Semaphore(10); // 最大10个并发请求 public String chat(String message) { if (!semaphore.tryAcquire(3, TimeUnit.SECONDS)) { throw new TooManyRequestsException(当前AI服务繁忙请稍后再试); } try { return doChat(message); } finally { semaphore.release(); } }这个做法的意义有两层第一保护你的API配额避免瞬间并发导致账号被限流第二保护你的后端线程池避免大量长时间挂起的AI请求把Tomcat线程池占满导致普通接口也无法响应。信号量的值可以参考你对模型服务的压测结果我一般先设10根据线上监控再调。7.3 成本治理日志里算明白每一笔账接入AI能力后成本治理容易被人忽略直到月底账单吓一跳。我习惯在日志里输出结构化的Token消耗配合Elasticsearch或简单日志分析脚本就能算出每个业务线的花费。如果公司内部有多套应用一起接入我建议在请求体里加一个user字段或者metadata字段标注这次请求来自哪个应用、哪个业务线方便做成本分摊。DeepSeek的接口调用本身不复杂真正有价值的是在接入之前考虑清楚模型怎么选、上下文怎么管理、成本怎么控制、并发怎么保护。把这些都想明白了Spring Boot接入DeepSeek就是几个小时的事情反之代码写完了也容易在性能和费用上翻车。根据我个人的经验第一次接入时建议把日志打得完整一点记录请求体脱敏、响应体、Token消耗和耗时这样出问题时有据可查后面优化也有基准数据可用。