1. 手写大模型接口这件事到底浪费在哪里先说一个我观察到的现象身边不少 Java 后端同学接到给系统加个 AI 问答的需求后第一反应是打开 HTTP 客户端手动拼 JSON调一个对话补全接口然后自己写重试、自己拼上下文、自己处理流式返回。代码写完三四百行跑起来还经常出问题——上下文超长被截断、流式响应乱码、多轮对话记不住前文。这套流程走下来快则两三天慢则一周最后交付的还只是一个能聊天的壳子。问题不在于这些同学能力不行而在于他们把一个已经被工程化解决的问题当成了从零开始的问题。大模型接口调用这件事本质上和十年前我们手写 JDBC 是一样的处境早期大家确实手写Connection、Statement、ResultSet后来有了 MyBatis、JPA谁还手写现在的大模型接入正处在该上框架了的阶段。LangChain4j 就是 Java 生态里干这件事的框架。它把模型调用、提示词模板、对话记忆、文档检索、流式输出这些重复劳动全部封装掉让你专注在业务逻辑上。再配上通义千问这类国内可直接调用的模型服务以及 RAG检索增强生成这套让模型基于你的私有资料回答的模式一个完整的智能问答系统核心代码可以压缩到百来行。这篇文章要讲清楚三件事为什么 Java 开发者不该再手写大模型接口、LangChain4j 到底帮你省掉了哪些活、怎么用 LangChain4j 通义千问搭一套带流式输出的 RAG 问答。适合有 Java 基础、想快速把 AI 能力接进现有系统的后端同学也适合被AI 集成需求追着跑、想找一条靠谱落地路径的技术负责人。全文的代码和配置都可以直接抄我会把每个选择背后的理由讲透而不是甩一堆 API 让你自己猜。2. 手写接口 vs 框架封装一笔算得清的账2.1 手写方案里那些看不见的成本很多人觉得手写接口简单可控但真正做过一轮的人会发现可控是假象。我拿一个最朴素的多轮对话 流式输出需求来拆手写方案至少要处理这些事HTTP 层选 HttpClient 还是 OkHttp连接池怎么配超时设多少流式响应的InputStream怎么按行读、怎么处理 SSE 的data:前缀和[DONE]结束标记协议层请求体里messages数组怎么组织system、user、assistant三种角色怎么区分多轮对话时历史消息怎么拼、拼多少条、超了 token 上限怎么截异常层限流返回 429 怎么办网络抖动重试几次重试时流式已经吐了一半的内容怎么处理业务层提示词模板怎么管理不同场景用不同模板怎么切换模型返回的 Markdown 怎么渲染这些事单拎出来都不难但叠在一起就是几百行胶水代码而且每一行都是你自己维护的负债。模型服务商改个字段名、加个新参数你就得跟着改。更别提换模型——从通义千问换到另一个服务请求格式、鉴权方式、流式协议可能全不一样手写方案基本等于重写。2.2 LangChain4j 把哪些活接走了LangChain4j 的设计思路很清晰用统一的抽象屏蔽模型差异用声明式接口替代命令式调用。它主要帮你接管了四块能力手写方案LangChain4j模型调用自己拼 JSON、发 HTTP一行model.generate()对话记忆自己维护消息列表MessageWindowChatMemory自动管理提示词模板字符串拼接SystemMessage/UserMessage注解流式输出自己解析 SSEStreamingChatLanguageModel回调文档检索自己接向量库EmbeddingStoreContentRetriever接口定义手写 Service声明式interface 动态代理最舒服的是最后一条。你可以像写 MyBatis 的 Mapper 一样定义一个接口加几个注解LangChain4j 用动态代理帮你生成实现。比如interface Assistant { SystemMessage(你是一个严谨的技术助手只基于提供的资料回答) String chat(UserMessage String question); }就这么几行背后已经包含了模型调用、提示词注入、消息封装。这种声明式的体验是手写方案给不了的。2.3 什么时候手写反而更合适我不是说手写一无是处。有两种情况手写更划算一是你只需要调一次接口、做一次性验证引入框架反而重二是你要对接的模型服务极其特殊框架还没适配那只能自己来。但只要你的需求涉及多轮对话、流式输出、RAG 检索、多模型切换中的任意两项框架的收益就远超学习成本。判断标准很简单如果你写的胶水代码超过 100 行就该考虑框架了。3. 通义千问接入前的环境与依赖准备3.1 为什么选通义千问作为模型底座选模型这件事国内开发者绕不开几个现实约束网络可达性、计费方式、中文能力、API 稳定性。通义千问在这几点上比较均衡——国内直连、按 token 计费、中文语料充足、有兼容 OpenAI 格式的接口。LangChain4j 对它的支持也比较成熟有专门的langchain4j-community-dashscope模块。这里要提醒一句模型选型不要一上来就追求最强。RAG 场景下模型主要负责基于检索到的资料组织语言对模型本身的推理能力要求没那么高。用中等规格的模型先把链路跑通等效果不达标再升级比一上来就用最贵的模型试错要省钱得多。3.2 Maven 依赖怎么配核心依赖分三块LangChain4j 核心、通义千问适配、向量存储。我用的版本组合如下你可以直接抄properties langchain4j.version0.35.0/langchain4j.version /properties dependencies !-- LangChain4j 核心 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency !-- 通义千问适配社区模块 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-community-dashscope/artifactId version${langchain4j.version}/version /dependency !-- 内存向量库用于 RAG 检索 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-embeddings-all-minilm-l6-v2/artifactId version${langchain4j.version}/version /dependency !-- 文档解析支持 PDF、Word 等 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-document-parser-apache-tika/artifactId version${langchain4j.version}/version /dependency /dependencies注意LangChain4j 版本迭代较快社区模块的 artifactId 偶有调整。如果拉不到依赖去 Maven 中央仓库搜langchain4j-community-dashscope确认最新坐标别硬套我这里的版本号。3.3 密钥与配置的安全处理API Key 绝对不能硬编码进代码也不建议直接写死在application.yml里提交到仓库。我的做法是走环境变量 配置类读取Configuration public class ModelConfig { Value(${dashscope.api-key}) private String apiKey; Bean public ChatLanguageModel chatModel() { return DashScopeChatModel.builder() .apiKey(apiKey) .modelName(qwen-plus) .temperature(0.3) .build(); } }application.yml里这样写dashscope: api-key: ${DASHSCOPE_API_KEY}启动时通过环境变量注入。temperature设 0.3 是有讲究的——RAG 场景要的是忠实于资料不是发挥创意温度调低能让模型更保守地复述检索内容减少胡编。这个参数我踩过坑一开始用默认值 0.7模型经常在资料没覆盖的地方自由发挥调低之后幻觉明显减少。4. 从零搭一套 RAG文档入库到检索的完整链路4.1 RAG 到底解决了什么问题先讲清楚 RAG 的价值不然容易做成为了 RAG 而 RAG。大模型有两个硬伤知识有截止日期、不知道你的私有资料。你问它我们公司上季度的报销政策是什么它要么说不知道要么一本正经地编。RAG 的思路是在提问之前先去你的资料库里检索相关内容把检索结果塞进提示词让模型基于这些内容回答。打个比方模型是个博学但没看过你公司文件的顾问RAG 就是每次提问前先让助理把相关文件找出来递给顾问顾问看着文件回答。这样既用上了模型的表达能力又保证了答案有据可依。4.2 文档加载与切分切得好不好直接决定检索质量RAG 效果差八成问题出在切分上。文档切得太粗检索出来的段落包含大量无关信息模型被干扰切得太细一个完整意思被拆散检索到的片段缺头少尾。我的经验值是中文技术文档按 500 到 800 字符切重叠 100 字符左右。DocumentSplitter splitter DocumentSplitters.recursive(600, 100); DocumentParser parser new ApacheTikaDocumentParser(); Document document parser.parse(new File(docs/manual.pdf)); ListTextSegment segments splitter.split(document);recursive切分器会优先按段落、句子这些自然边界切而不是硬按字符数截断这样切出来的片段语义更完整。重叠部分是为了防止关键信息正好卡在切口上——比如一个定义跨了两个片段重叠能保证至少有一个片段包含完整定义。提示如果你的资料里有大量表格Tika 解析出来的表格结构会乱。这种情况建议先把表格转成 Markdown 再入库或者针对表格单独做处理别指望通用解析器能完美还原。4.3 向量化与存储让语义相似可计算切分完的文本要转成向量才能做语义检索。向量化的本质是把一段文字映射成一串数字语义相近的文字向量距离也近。这样用户问怎么报销即使资料里写的是费用申请流程也能被检索到——因为它们语义相近向量距离近。EmbeddingModel embeddingModel new AllMiniLmL6V2EmbeddingModel(); EmbeddingStoreTextSegment embeddingStore new InMemoryEmbeddingStore(); EmbeddingStoreIngestor ingestor EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(embeddingStore) .build(); ingestor.ingest(document);这里用的是内存向量库适合验证和小规模场景。生产环境数据量大、要持久化得换成专门的向量库。选型上数据量在百万级以内、团队不想额外运维可以考虑基于本地文件的方案数据量再大或者要分布式就得上独立的向量数据库。别一上来就上重型向量库先用内存版把链路跑通确认效果后再迁移迁移成本其实不高因为 LangChain4j 的EmbeddingStore接口是统一的。4.4 检索器配置召回数量不是越多越好检索器负责在提问时找出最相关的片段。核心参数是召回数量maxResultsContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.6) .build();maxResults设 5 是我反复调出来的经验值。设 3有时候关键信息没被召回设 10塞进提示词的无关内容太多模型反而抓不住重点还浪费 token。minScore是相似度阈值低于这个分数的片段直接丢弃避免矮子里拔将军把不相关的内容硬塞进去。这两个参数没有万能值得拿你的真实问题去测看召回的内容是否切题。5. 声明式接口 流式输出把问答体验做顺5.1 用接口定义替代手写调用LangChain4j 最优雅的地方是声明式接口。定义一个Assistant接口加注解框架自动生成实现interface Assistant { SystemMessage( 你是一个企业知识助手。请严格基于检索到的资料回答问题。 如果资料中没有相关信息直接说资料中未找到相关内容不要编造。 回答要简洁必要时分点说明。 ) String chat(UserMessage String question); }然后组装Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .contentRetriever(retriever) .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) .build();注意contentRetriever一挂上RAG 就自动生效了——框架会在每次提问前自动检索、自动把结果注入提示词。chatMemory负责多轮对话记忆withMaxMessages(10)表示保留最近 10 条消息。这个数字也要权衡留太少多轮对话会失忆留太多token 消耗大且早期无关内容会干扰当前回答。5.2 流式输出为什么必须做同步返回和流式返回用户体验差一个量级。同步模式下用户点发送后要盯着转圈等三五秒才看到整段答案蹦出来流式模式下第一个字几乎立刻出现然后逐字往外吐用户感觉它在思考、在回答等待焦虑大幅降低。这不是锦上添花是问答类产品的体验底线。LangChain4j 的流式接口用回调实现interface StreamingAssistant { SystemMessage(你是一个企业知识助手基于资料简洁回答) TokenStream chat(UserMessage String question); }TokenStream提供了几种消费方式最常用的是绑定到回调TokenStream tokenStream streamingAssistant.chat(报销流程是什么); tokenStream .onNext(token - { // 每收到一个 token 就推给前端 sseEmitter.send(token); }) .onComplete(response - { sseEmitter.complete(); }) .onError(error - { sseEmitter.completeWithError(error); }) .start();5.3 流式接口和 Spring MVC 怎么对接后端要把流式内容推给前端标准做法是 SSEServer-Sent Events。Spring MVC 提供了SseEmitterGetMapping(value /chat/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter streamChat(RequestParam String question) { SseEmitter emitter new SseEmitter(60_000L); streamingAssistant.chat(question) .onNext(emitter::send) .onComplete(r - emitter.complete()) .onError(emitter::completeWithError) .start(); return emitter; }前端用EventSource接收即可。这里有个坑我踩过SseEmitter的超时时间一定要设默认值在某些容器下很短长回答还没吐完连接就断了。我设的 60 秒你可以根据最长回答时长调整。另外onNext里如果直接send原始 token遇到换行符可能破坏 SSE 格式稳妥做法是把 token 里的换行转义或者用 JSON 包一层再发。5.4 多轮对话的记忆管理细节MessageWindowChatMemory是滑动窗口只保留最近 N 条消息。但有个细节要注意它按消息条数算不按 token 算。如果某条消息特别长10 条消息可能就撑爆上下文了。更精细的做法是用TokenWindowChatMemory按 token 数控制窗口ChatMemory memory TokenWindowChatMemory.withMaxTokens(2000, new OpenAiTokenizer());这样无论消息长短总 token 数都可控。代价是需要一个 tokenizer 来估算 token 数稍微重一点。我的建议是对话轮次少、消息短的场景用MessageWindowChatMemory就够如果用户可能粘贴大段文本提问果断上TokenWindowChatMemory。6. 实测中那些文档不会写的坑6.1 检索到了但模型不用提示词的锅链路跑通后我遇到一个诡异现象检索器明明召回了正确片段模型却答非所问。排查半天发现是提示词的问题。原来的 system message 写得太客气你可以参考以下资料模型就真的只是参考该编还是编。改成强约束后就好了请严格基于以下检索到的资料回答问题。 资料中没有的内容一律回答资料中未找到相关内容。 禁止使用资料之外的知识作答。提示词的约束力直接决定 RAG 的可靠性。别指望模型自觉要把规则写死、写明确。这是我从多次调试里总结出的最值钱的一条经验。6.2 中文分词的隐性影响用英文 embedding 模型处理中文效果会打折扣。我一开始用默认的英文模型发现中文语义检索经常不准。换成对中文更友好的 embedding 模型后召回质量明显提升。选 embedding 模型时一定要确认它对中文的支持程度别默认所有模型都中英文通吃。这个点很容易被忽略但影响很大。6.3 流式输出的乱码与断连流式场景下我遇到过两类问题。一是中文乱码token 按字节流返回时一个中文字符可能被拆到两个 token 里直接拼接会出乱码。解决办法是在服务端按字符边界处理或者确保编码统一为 UTF-8。二是连接中断用户网络抖动或主动关闭页面时后端还在往一个已断开的连接推数据会抛异常。要在onError里做好兜底别让异常冒到顶层。6.4 首次请求慢模型冷启动第一次调用模型接口时响应明显比后续慢这是模型服务的冷启动。对用户体验有影响的话可以在应用启动后发一个预热请求把连接和模型都叫醒。这个技巧在延迟敏感的场景里很实用成本几乎为零。7. 几个能直接抄的优化方向链路跑通只是起点真正拉开差距的是细节优化。分享几个我实践下来收益明显的方向。检索结果重排序。初步召回 5 条后用一个更精细的模型对这 5 条重新打分排序把最相关的放前面。LangChain4j 支持接入重排序模型对提升答案准确率帮助很大尤其是资料库内容庞杂的时候。查询改写。用户的问题往往口语化、有指代直接拿去检索效果差。可以在检索前先用模型把问题改写成更适合检索的形式。比如用户问那个报销的事咋弄改写成费用报销流程和所需材料检索命中率立刻不一样。分场景配置。不同业务用不同的提示词、不同的召回策略。技术文档问答和客服问答对忠实度和语气的要求完全不同别用一套配置打天下。LangChain4j 支持定义多个Assistant接口按场景注入不同配置切换很灵活。加一层缓存。高频重复问题比如怎么重置密码没必要每次都走完整链路。在检索层或答案层加缓存能显著降低响应时间和调用成本。缓存 key 用问题的向量表示语义相同的问题也能命中。监控与反馈闭环。记录每次问答的检索片段、模型回答、用户反馈。这些数据是后续优化的金矿——哪些问题召回不准、哪些回答被用户点了没用一目了然。没有这个闭环优化就是盲人摸象。最后说个心态上的体会RAG 不是配好就一劳永逸的东西它更像一个需要持续调优的系统。检索质量、提示词、模型参数每一环都有优化空间。但好消息是用 LangChain4j 把骨架搭起来之后后续的优化都是在这个骨架上做增量而不是推倒重来。这比手写一堆胶水代码、每次改动都牵一发动全身要舒服太多了。先把最小可用链路跑通再拿真实问题去喂、去调这条路我走过是通的。
