最近这两年被问到最多的问题就是“你们Java后端到底怎么接大语言模型” 很多团队的前端已经在用各种AI能力做功能但后端Java服务反而还停留在“听说过、没碰过”的阶段。我把手头一个智能巡检助手接入大模型的全过程整理了一遍从方案选型、工程准备、代码落地到生产环境优化每一步都附上实操细节和踩坑记录。这篇文章适合正在评估或准备动手接入的Java后端开发者无论你是用Spring Boot还是纯Servlet项目只要理解了核心链路迁移到任何框架都一样。1. 先定方案三种接入路径怎么选接入大语言模型不是只有一种方式我见过不少团队一上来就找“Java SDK”结果要么被SDK版本坑死要么被厂商绑定。这里先花300字把方案定清楚后面编码才不会走回头路。1.1 三种主流接入方式对比直接HTTP调用是最通用、最省心的方式。不管你是接国内大模型厂商的OpenAI兼容接口还是自建一套基于vLLM、FastChat的本地模型服务底层都是HTTP POST JSON。只要模型服务暴露的是标准接口Java这边用HttpClient、RestTemplate、WebClient、OkHttp都可以完全不依赖任何厂商SDK。我最终就是选了这个方案理由很简单SDK最容易在版本升级时出幺蛾子HTTP调用出了问题我能直接看报文排查。官方SDK封装适合“不想写HTTP代码、只想快速出活”的场景。比如OpenAI官方Java SDK、阿里云的DashScope SDK都会帮你封装好鉴权、超时、序列化这些细节代码量确实少不少。但这玩意儿有个隐患——SDK的版本迭代经常跟后端框架冲突Maven依赖树里时不时冒出个老版本Netty或Jackson跟你的Spring Boot版本打架。如果你是在维护一个大型老项目引入SDK前先检查依赖冲突否则上线时哭都来不及。中间网关方案适合中大型团队。架构上在业务服务和模型服务之间加一层统一的AI网关比如自研的Spring Cloud Gateway路由或者商用的模型管理平台业务方只对接网关不直接碰模型厂商。好处是多模型切换比如OpenAI换国产模型只改网关业务代码零改动统一鉴权、限流、审计也好做。坏处是多了一层要维护的组件团队得有额外的运维精力。1.2 选模型还是选服务除了接入方式更关键的决策是选模型。我按两个维度拆分成本敏感、数据敏感、能接受一定延迟优先本地部署开源模型。7B~14B级别的量化模型比如Qwen系列、GLM系列用一张A100甚至一张4090就能跑起来单次调用成本几乎为0数据不出内网金融、医疗类项目尤其适合。缺点是前期有部署成本而且效果跟商业大模型还是有差距。追求效果、快速验证直接用商业API。通义千问、文心一言、DeepSeek这些厂商都提供兼容OpenAI格式的接口充值即用模型迭代也不用你操心。缺点是按Token计费高频调用时账单会肉疼。先说结论中小型项目、起步阶段直接选HTTP调用 商业API是最务实的组合。等业务量上来了再考虑把底层模型替换成本地部署的那时因为代码里走的是标准HTTP协议切换成本几乎为零。2. 动手前的工程准备方案定了接着就是把工程环境收拾利索。这一步看着基础但很多人就是在这里被绊住——不是缺依赖就是密钥泄露等上线了才发现隐患。2.1 Spring Boot版本与依赖选择我这次用的是Spring Boot 3.2.xJDK 17。选这个组合的原因很简单Spring Boot 3.2之后RestClient正式成为一等公民它比RestTemplate更现代API更贴合直觉用来调大模型接口非常顺手。如果你还在用Spring Boot 2.x那也别慌——用RestTemplate或者直接上OkHttp也是一样的核心代码差异不大。依赖上只需要两个东西dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-webflux/artifactId /dependency这里有个小坑如果你只是想要RestClient其实不需要引入webfluxSpring Boot 3.2的spring-web本身就带了RestClient。我之所以引入webflux是因为后面做流式输出时要用SseEmitter的替代方案见3.2节。如果你只要同步调用把webflux这行去掉能少一堆依赖。2.2 密钥管理与安全配置大模型API的Key就像数据库密码绝不能硬编码在代码里。我见过有人把sk-xxx直接写到application.yml提交到Git仓库第二天账单就被刷爆了。标准做法是环境变量export LLM_API_KEYyour-api-key export LLM_BASE_URLhttps://api.example.com/v1 export LLM_MODELqwen-plus然后通过配置类注入Configuration ConfigurationProperties(prefix llm) public class LLMProperties { private String apiKey; private String baseUrl; private String model; private Integer maxTokens 2048; private Double temperature 0.7; public String getApiKey() { return apiKey; } public void setApiKey(String apiKey) { this.apiKey apiKey; } // 其他getter/setter略 }ConfigurationProperties会自动绑定llm.api-key这样的配置项不用一个个Value注解。至于Spring的Value(${llm.api-key})和ConfigurationProperties选哪个我建议后者类型安全、集中管理。特别注意如果你用ConfigurationProperties记得在Spring Boot启动类上加EnableConfigurationProperties或者用Component标注配置类否则绑定不会生效。这个坑我踩过一次当时控制台一直提示“LLMProperties无法注入”排查了半天才发现是少了注解。2.3 定义模型交互的公共数据结构大模型接口交互的报文是JSONJava这边得有一一对应的数据类。以OpenAI兼容格式为例定义三个核心类public record ChatMessage(String role, String content) { public static ChatMessage system(String content) { return new ChatMessage(system, content); } public static ChatMessage user(String content) { return new ChatMessage(user, content); } } public record ChatRequest( String model, ListChatMessage messages, Double temperature, Integer maxTokens, Boolean stream ) { public ChatRequest { // 默认值兜底防止构造时漏传 if (temperature null) temperature 0.7; if (maxTokens null) maxTokens 2048; if (stream null) stream false; } } public record ChatResponse( String id, String object, Long created, String model, ListChoice choices, Usage usage ) { public record Choice(Integer index, ChatMessage message, String finishReason) {} public record Usage(Integer promptTokens, Integer completionTokens, Integer totalTokens) {} }注意我用了Java 16的record而不是传统POJO——代码量瞬间少一半而且天然适合做不可变DTO。如果你还在用Java 8那只能回归Lombok或手写getter/setter了不过从2024年的视角看一个Java后端新项目还在用Java 8建议赶紧升级。3. 核心链路Java调用LLM的完整实现工程准备好了下面进入重头戏。我把调用大模型抽象成三个动作建立连接 - 发送请求 - 解析响应。同步调用和流式调用在建立连接和发送请求上几乎一样区别主要在“解析响应”这一步。3.1 同步调用五步走完一次对话同步调用适合“你给我最终答案”的场景比如文本分类、摘要生成、知识库问答。完整代码如下Service public class LLMService { private final LLMProperties props; private final RestClient restClient; public LLMService(LLMProperties props, RestClient.Builder restClientBuilder) { this.props props; this.restClient restClientBuilder .baseUrl(props.getBaseUrl()) .defaultHeader(HttpHeaders.AUTHORIZATION, Bearer props.getApiKey()) .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE) .build(); } public String chat(ListChatMessage messages) { ChatRequest request new ChatRequest( props.getModel(), messages, props.getTemperature(), props.getMaxTokens(), false ); try { ChatResponse response restClient.post() .uri(/chat/completions) .body(request) .retrieve() .body(ChatResponse.class); if (response ! null response.choices() ! null !response.choices().isEmpty()) { return response.choices().get(0).message().content(); } throw new IllegalStateException(模型返回为空); } catch (RestClientResponseException e) { // 这里可以拿到HTTP状态码和响应体做更精细的异常处理 throw new LLMException(模型调用失败, status e.getStatusCode().value() , body e.getResponseBodyAsString(), e); } } }这段代码有三个值得展开的细节RestClient.Builder通过构造器注入。Spring Boot自动配置了一个RestClient.Builder默认带了连接池和超时配置你不需要自己new。如果你自己new就失去了框架的默认调优。鉴权头在构造时统一设置。这样所有调用都不用重复写Authorization后面切换Key也方便。RestClientResponseException只捕获HTTP层面的异常像网络不通、连接超时这类ResourceAccessException要先捕获再catch它。我在生产代码里通常是两个catch块分开处理。3.2 流式响应SSE逐字输出的后端实现流式输出是大模型应用体验的关键用户不喜欢干等两秒然后“啪”一下全出来他们要的是打字机效果。SSEServer-Sent Events就是干这个的服务器不断往客户端推送数据直到整个响应结束。OpenAI兼容接口的流式响应格式长这样data: {id:chatcmpl-xxx,object:chat.completion.chunk,choices:[{delta:{content:你},index:0}]} data: {id:chatcmpl-xxx,object:chat.completion.chunk,choices:[{delta:{content:好},index:0}]} data: [DONE]Java后端要做的事就是收到大模型的SSE流后逐段解析再通过SseEmitter转发给前端。代码如下RestController RequestMapping(/api/llm) public class ChatController { private final LLMService llmService; public ChatController(LLMService llmService) { this.llmService llmService; } PostMapping(/chat/stream) public SseEmitter streamChat(RequestBody ListChatMessage messages) { SseEmitter emitter new SseEmitter(180_000L); // 超时设置为3分钟 Executors.newSingleThreadExecutor().submit(() - { try { llmService.streamChat(messages, content - { try { emitter.send(SseEmitter.event().data(content)); } catch (IOException e) { emitter.completeWithError(e); } }); emitter.complete(); } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; } }对应地LLMService里增加一个流式方法public void streamChat(ListChatMessage messages, ConsumerString onContent) { ChatRequest request new ChatRequest( props.getModel(), messages, props.getTemperature(), props.getMaxTokens(), true ); restClient.post() .uri(/chat/completions) .body(request) .exchange((clientRequest, clientResponse) - { BufferedReader reader new BufferedReader( new InputStreamReader(clientResponse.getBody(), StandardCharsets.UTF_8) ); String line; while ((line reader.readLine()) ! null) { if (line.isBlank()) continue; if (line.startsWith(data:)) { String data line.substring(5).trim(); if ([DONE].equals(data)) break; ChatChunk chunk JsonUtils.parse(data, ChatChunk.class); if (chunk.choices() ! null !chunk.choices().isEmpty() chunk.choices().get(0).delta() ! null) { String delta chunk.choices().get(0).delta().content(); if (delta ! null !delta.isEmpty()) { onContent.accept(delta); } } } } return null; }); }这里有个非常重要的技术细节别用restClient.post().retrieve().body来做流式retrieve()会把整个响应体读完再返回根本没法做增量解析。必须用.exchange()这种底层API它让你拿到原始的ClientHttpResponse然后你把InputStream交给BufferedReader逐行读。还要注意线程模型的问题。上面我用了Executors.newSingleThreadExecutor()这是因为SseEmitter的send是阻塞的如果在Tomcat的worker线程里做会占用请求线程并发一高线程就耗尽了。但直接这样写也有隐患——每个请求都新建一个线程池这这相当于活动线程不受控。更稳的做法是用Spring的Async配一个带边界的线程池或者用WebFlux的Flux做面向响应式的实现后面翻到第4.3节我再展开说。3.3 参数调优那些你不调就亏的参数大模型接口暴露了一堆参数常用的几个必须搞清楚参数作用我的建议temperature随机性越高越自由创造性任务用0.8~0.9事实性任务用0.1~0.3maxTokens限制生成的token数默认2048长文档任务调到4000topP核采样影响词的概率分布一般不需要调Temperature够用了frequencyPenalty惩罚重复词文本生成长文时调到0.5左右避免车轱辘话presencePenalty鼓励讨论新话题创意写作时设1.0这几个参数不是越大越好。temperature调到2.0模型基本在胡编乱造maxTokens设太高响应时间会拉长费用也直线上升。我一般的原则是业务场景先想清楚再定参数而不是随手抄一个默认值。4. 生产化改造从“能跑”到“稳”能调通接口只是第一步真正上线到生产环境还得解决超时、重试、并发、上下文管理这些问题。这块儿没做好的话模型调用就像拆盲盒随时可能把线上服务拖垮。4.1 超时设置与重试策略大模型响应速度跟网络状况、模型负载、输入长度强相关。如果不设超时请求卡那里会把线程池占满其他接口跟着遭殃。RestClient配置超时有两种方式// 方式一在application.yml中加配置 spring: rest-client: connect-timeout: 5000 read-timeout: 60000// 方式二手动构建时设置 Bean public RestClient restClient(LLMProperties props) { SimpleClientHttpRequestFactory factory new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(5000); factory.setReadTimeout(60000); return RestClient.builder() .baseUrl(props.getBaseUrl()) .requestFactory(factory) .build(); }注意一个细节connectTimeout建立连接不是越长越好5秒足够了readTimeout读取数据是主要瓶颈因为大模型生成长文本确实慢我一般放到60秒流式场景更长。另外重试策略只对幂等请求生效——大模型请求是幂等的同一个prompt可以重复请求所以可以放心加重试但重试次数控制在2~3次太多会造成资源浪费。如果用Spring的Retryable记得加上maxAttempts3和backoff不然默认会立刻重试网络一抖照样挂。4.2 限流与并发控制商业模型API都有QPS每秒请求数和并发数限制超过会返回429。高并发场景下你的服务也要做自我保护。我之前做的一个问答系统曾经过来十几个并发请求直接把上游服务打爆了报了一串429。解决办法是在Java层加信号量Component public class LLMFlowController { private final Semaphore semaphore new Semaphore(20); // 最大20个并发 public void acquire() { if (!semaphore.tryAcquire(3, TimeUnit.SECONDS)) { throw new RateLimitException(系统繁忙请稍后重试); } } public void release() { semaphore.release(); } }调用时包裹成模板方法public String chatWithLimit(ListChatMessage messages) { flowController.acquire(); try { return chat(messages); } finally { flowController.release(); } }这里用tryAcquire带超时而不是acquire是因为如果拿不到信号量说明系统已经过载再排队等下去只会拖垮整体响应速度不如直接快速失败返回友好的提示。别傻等用户体验反而更好。4.3 上下文管理与Token预算聊过天的都懂大模型的上下文窗口是有限的而且输入越长费用越高。我遇到过用户连续聊了30轮把上下文全塞进请求里结果模型返回质量下降、费用翻倍。解决方案是做一个简单的“记忆窗口”保留System Prompt只保留最近6轮对话超出窗口的部分做摘要压缩具体做法public ListChatMessage trimConversation(ListChatMessage messages, int maxRounds) { if (messages.size() maxRounds * 2 1) { return messages; // 包含system prompt所以是 2N1 } // 第一条保留通常是system从最后取maxRounds*2条 ListChatMessage systemAndRecent new ArrayList(); systemAndRecent.add(messages.get(0)); systemAndRecent.addAll(messages.subList(messages.size() - maxRounds * 2, messages.size())); return systemAndRecent; }再往上层的方案是用向量数据库把历史对话存起来每次请求时检索跟当前问题相关的历史片段拼进去这属于RAG检索增强生成的范畴了。这里不展开但思路是别把什么都往Prompt里塞让模型只看它该看的。4.4 故障降级与体验兜底线上接入大模型必须假设它随时会挂。我见过几种典型故障模型服务商停电、API额度用完、网络抖动、输出格式错误。降级方案要从简单到复杂分几层第一层错误响应重试。就是前面说的重试2~3次。第二层缓存兜底。对相同输入的结果做缓存特别是摘要、分类这类幂等场景缓存命中率往往不低。我用Caffeine做了本地缓存TTL设置10分钟。第三层备用模型。主模型挂了切副模型比如通义千问挂了切DeepSeek。由于代码层已经统一成了HTTP调用切换只需改配置或做一个动态路由。第四层人工兜底。给前端返回“AI服务暂不可用请稍后再试”同时把失败请求打到数据库后续手动补偿。这四层不需要全都做但至少前两层必须有否则用户一旦遇到故障就是裸奔。5. 常见问题与排查技巧实录最后这部分是我最想写的——代码怎么写是“术”怎么排查问题才是“道”。下面记录了几个我在实际项目中踩过的坑和排查思路。5.1 连接超时与响应慢的排查症状接口偶尔报Read timed out或者整体响应要10秒以上。排查步骤先区分是连接慢还是读取慢。连接超时通常是网络或防火墙问题可以用curl先测一下curl -m 10 -v https://api.example.com/v1/chat/completions再确认是不是被限流了。看响应头里的Retry-After字段。如果上游一直在返回429说明你的并发超限了得加流量控制。检查Keep-Alive连接池。Spring的RestClient默认连接池大小是有限制的如果复用不够每次请求都重新建立TCP延迟会明显增加。可以在构造时指定HttpComponentsClientHttpRequestFactory factory new HttpComponentsClientHttpRequestFactory(); factory.setConnectTimeout(5000); factory.setReadTimeout(60000);然后设置连接池的maxTotal和defaultMaxPerRoute。经验之谈大模型调用慢80%的情况都不是你代码的问题而是上游推理本身就需要时间——特别在使用长文本生成或复杂推理时。遇到慢响应先看看用户的Prompt是不是太长了让模型思考的内容太多它自然需要更长的时间。5.2 JSON解析失败的典型场景症状返回报文能看懂但Jackson解析时抛JsonProcessingException或者某个字段值是null。我遇到过三种情况字段驼峰命名不一致。有的模型API返回finish_reason下划线Java类里写的finishReason驼峰Jackson默认不匹配。解决办法是在数据类上加JsonProperty(finish_reason)或者临时在ObjectMapper上配置PropertyNamingStrategies.SNAKE_CASE。extra字段干扰。模型新版本可能会加一些额外字段比如prompt_tokens_detailsJava类里没有定义。Jackson默认遇到未知字段会直接忽略但如果全局配置了FAIL_ON_UNKNOWN_PROPERTIEStrue就会炸。建议在ObjectMapper里显式关掉这个开关。响应被截断。尤其是非流式请求但网络不稳定时JSON少了结尾的}解析自然失败。这种情况建议把原始响应体打日志方便排查。5.3 输出内容不稳定的处理症状同样的问题两次回答完全不一样或者一个回答出现明显的事实错误幻觉。大模型的随机性是正常的但要降低业务风险可以做几件事把temperature调低。事实性问题调到0.1~0.2基本能做到稳定输出。强化System Prompt。明确告诉模型“你是XX领域的专家只回答XX相关的内容不确定时说不知道”。我在智能巡检助手里就是这样要求模型效果提升不是一点半点。加few-shot示例。某些任务格式要求严格比如输出JSON给模型看几个标准示例比你写一万字规则都管用。上游加一层校验。如果需求是“抽取结构化信息”可以对模型输出做正则或规则校验不合法就重试一次或者调用一次“修正模型”来规范化输出。这个“修正模型”的做法挺实用第一次让模型做任务输出格式可能不太规范第二次把输出内容和格式要求一起丢回给模型让模型自己重写很多时候一次就修好。代价是多一次API调用但在关键场景是值得的。5.4 鉴权失效与密钥过期症状401 Unauthorized但代码看起来没问题。常见的坑是环境变量没生效。有一次我把LLM_API_KEY配在.env文件里但生产服务是systemd部署的systemd默认不读.env。后来统一改成了在部署脚本里用export设置并在配置类里启动时校验一下apiKey是否为空提前发现问题。另一个坑是Bearer前缀写错。HTTP头要求是Authorization: Bearer key逗号、空格漏了都会导致401。这个查起来特别隐蔽因为日志里会打Bearer ********看不到完整内容。我后来加了一个开关只有在dev环境才打印完整Key不然校验失败时两眼一抹黑。Bearer sk-xxxx // 正确 Bearer sk-xxxx // 多了个空格 Bearer sk-xxxx // Bearer后面没空格第六节经验收尾最后说两句我心里话。接入大语言模型这件事技术上真的不算难不就是HTTP JSON吗真正的难点在于你怎么理解模型的行为特性怎么在工程上做好兜底和优化。我见过不少团队在“接入”这一步卡了半个月不是因为代码写不出来而是因为没想清楚选型、没做超时控制、没处理流式响应最后把简单的事情搞复杂了。如果你正在做类似的事情我的建议是先拿一个最小的业务场景跑通全链路从同步调用开始再上流式最后逐步加限流、缓存、降级这些生产必备能力。别一上来就追求“完美架构”AI这块变化太快稳定跑起来比什么都重要。等你的系统跑顺了再回头看看就会发现这些经验就是下一个项目最宝贵的起点。