1. 手寫大模型接口這件事到底浪費(fèi)在哪里先說(shuō)一個(gè)我觀察到的現(xiàn)象身邊不少 Java 后端同學(xué)接到給系統(tǒng)加個(gè) AI 問(wèn)答的需求后第一反應(yīng)是打開 HTTP 客戶端手動(dòng)拼 JSON調(diào)一個(gè)對(duì)話補(bǔ)全接口然后自己寫重試、自己拼上下文、自己處理流式返回。代碼寫完三四百行跑起來(lái)還經(jīng)常出問(wèn)題——上下文超長(zhǎng)被截?cái)?、流式響?yīng)亂碼、多輪對(duì)話記不住前文。這套流程走下來(lái)快則兩三天慢則一周最后交付的還只是一個(gè)能聊天的殼子。問(wèn)題不在于這些同學(xué)能力不行而在于他們把一個(gè)已經(jīng)被工程化解決的問(wèn)題當(dāng)成了從零開始的問(wèn)題。大模型接口調(diào)用這件事本質(zhì)上和十年前我們手寫 JDBC 是一樣的處境早期大家確實(shí)手寫Connection、Statement、ResultSet后來(lái)有了 MyBatis、JPA誰(shuí)還手寫現(xiàn)在的大模型接入正處在該上框架了的階段。LangChain4j 就是 Java 生態(tài)里干這件事的框架。它把模型調(diào)用、提示詞模板、對(duì)話記憶、文檔檢索、流式輸出這些重復(fù)勞動(dòng)全部封裝掉讓你專注在業(yè)務(wù)邏輯上。再配上通義千問(wèn)這類國(guó)內(nèi)可直接調(diào)用的模型服務(wù)以及 RAG檢索增強(qiáng)生成這套讓模型基于你的私有資料回答的模式一個(gè)完整的智能問(wèn)答系統(tǒng)核心代碼可以壓縮到百來(lái)行。這篇文章要講清楚三件事為什么 Java 開發(fā)者不該再手寫大模型接口、LangChain4j 到底幫你省掉了哪些活、怎么用 LangChain4j 通義千問(wèn)搭一套帶流式輸出的 RAG 問(wèn)答。適合有 Java 基礎(chǔ)、想快速把 AI 能力接進(jìn)現(xiàn)有系統(tǒng)的后端同學(xué)也適合被AI 集成需求追著跑、想找一條靠譜落地路徑的技術(shù)負(fù)責(zé)人。全文的代碼和配置都可以直接抄我會(huì)把每個(gè)選擇背后的理由講透而不是甩一堆 API 讓你自己猜。2. 手寫接口 vs 框架封裝一筆算得清的賬2.1 手寫方案里那些看不見的成本很多人覺得手寫接口簡(jiǎn)單可控但真正做過(guò)一輪的人會(huì)發(fā)現(xiàn)可控是假象。我拿一個(gè)最樸素的多輪對(duì)話 流式輸出需求來(lái)拆手寫方案至少要處理這些事HTTP 層選 HttpClient 還是 OkHttp連接池怎么配超時(shí)設(shè)多少流式響應(yīng)的InputStream怎么按行讀、怎么處理 SSE 的data:前綴和[DONE]結(jié)束標(biāo)記協(xié)議層請(qǐng)求體里messages數(shù)組怎么組織system、user、assistant三種角色怎么區(qū)分多輪對(duì)話時(shí)歷史消息怎么拼、拼多少條、超了 token 上限怎么截異常層限流返回 429 怎么辦網(wǎng)絡(luò)抖動(dòng)重試幾次重試時(shí)流式已經(jīng)吐了一半的內(nèi)容怎么處理業(yè)務(wù)層提示詞模板怎么管理不同場(chǎng)景用不同模板怎么切換模型返回的 Markdown 怎么渲染這些事單拎出來(lái)都不難但疊在一起就是幾百行膠水代碼而且每一行都是你自己維護(hù)的負(fù)債。模型服務(wù)商改個(gè)字段名、加個(gè)新參數(shù)你就得跟著改。更別提換模型——從通義千問(wèn)換到另一個(gè)服務(wù)請(qǐng)求格式、鑒權(quán)方式、流式協(xié)議可能全不一樣手寫方案基本等于重寫。2.2 LangChain4j 把哪些活接走了LangChain4j 的設(shè)計(jì)思路很清晰用統(tǒng)一的抽象屏蔽模型差異用聲明式接口替代命令式調(diào)用。它主要幫你接管了四塊能力手寫方案LangChain4j模型調(diào)用自己拼 JSON、發(fā) HTTP一行model.generate()對(duì)話記憶自己維護(hù)消息列表MessageWindowChatMemory自動(dòng)管理提示詞模板字符串拼接SystemMessage/UserMessage注解流式輸出自己解析 SSEStreamingChatLanguageModel回調(diào)文檔檢索自己接向量庫(kù)EmbeddingStoreContentRetriever接口定義手寫 Service聲明式interface 動(dòng)態(tài)代理最舒服的是最后一條。你可以像寫 MyBatis 的 Mapper 一樣定義一個(gè)接口加幾個(gè)注解LangChain4j 用動(dòng)態(tài)代理幫你生成實(shí)現(xiàn)。比如interface Assistant { SystemMessage(你是一個(gè)嚴(yán)謹(jǐn)?shù)募夹g(shù)助手只基于提供的資料回答) String chat(UserMessage String question); }就這么幾行背后已經(jīng)包含了模型調(diào)用、提示詞注入、消息封裝。這種聲明式的體驗(yàn)是手寫方案給不了的。2.3 什么時(shí)候手寫反而更合適我不是說(shuō)手寫一無(wú)是處。有兩種情況手寫更劃算一是你只需要調(diào)一次接口、做一次性驗(yàn)證引入框架反而重二是你要對(duì)接的模型服務(wù)極其特殊框架還沒適配那只能自己來(lái)。但只要你的需求涉及多輪對(duì)話、流式輸出、RAG 檢索、多模型切換中的任意兩項(xiàng)框架的收益就遠(yuǎn)超學(xué)習(xí)成本。判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果你寫的膠水代碼超過(guò) 100 行就該考慮框架了。3. 通義千問(wèn)接入前的環(huán)境與依賴準(zhǔn)備3.1 為什么選通義千問(wèn)作為模型底座選模型這件事國(guó)內(nèi)開發(fā)者繞不開幾個(gè)現(xiàn)實(shí)約束網(wǎng)絡(luò)可達(dá)性、計(jì)費(fèi)方式、中文能力、API 穩(wěn)定性。通義千問(wèn)在這幾點(diǎn)上比較均衡——國(guó)內(nèi)直連、按 token 計(jì)費(fèi)、中文語(yǔ)料充足、有兼容 OpenAI 格式的接口。LangChain4j 對(duì)它的支持也比較成熟有專門的langchain4j-community-dashscope模塊。這里要提醒一句模型選型不要一上來(lái)就追求最強(qiáng)。RAG 場(chǎng)景下模型主要負(fù)責(zé)基于檢索到的資料組織語(yǔ)言對(duì)模型本身的推理能力要求沒那么高。用中等規(guī)格的模型先把鏈路跑通等效果不達(dá)標(biāo)再升級(jí)比一上來(lái)就用最貴的模型試錯(cuò)要省錢得多。3.2 Maven 依賴怎么配核心依賴分三塊LangChain4j 核心、通義千問(wèn)適配、向量存儲(chǔ)。我用的版本組合如下你可以直接抄properties langchain4j.version0.35.0/langchain4j.version /properties dependencies !-- LangChain4j 核心 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency !-- 通義千問(wèn)適配社區(qū)模塊 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-community-dashscope/artifactId version${langchain4j.version}/version /dependency !-- 內(nèi)存向量庫(kù)用于 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 版本迭代較快社區(qū)模塊的 artifactId 偶有調(diào)整。如果拉不到依賴去 Maven 中央倉(cāng)庫(kù)搜langchain4j-community-dashscope確認(rèn)最新坐標(biāo)別硬套我這里的版本號(hào)。3.3 密鑰與配置的安全處理API Key 絕對(duì)不能硬編碼進(jìn)代碼也不建議直接寫死在application.yml里提交到倉(cāng)庫(kù)。我的做法是走環(huán)境變量 配置類讀取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}啟動(dòng)時(shí)通過(guò)環(huán)境變量注入。temperature設(shè) 0.3 是有講究的——RAG 場(chǎng)景要的是忠實(shí)于資料不是發(fā)揮創(chuàng)意溫度調(diào)低能讓模型更保守地復(fù)述檢索內(nèi)容減少胡編。這個(gè)參數(shù)我踩過(guò)坑一開始用默認(rèn)值 0.7模型經(jīng)常在資料沒覆蓋的地方自由發(fā)揮調(diào)低之后幻覺明顯減少。4. 從零搭一套 RAG文檔入庫(kù)到檢索的完整鏈路4.1 RAG 到底解決了什么問(wèn)題先講清楚 RAG 的價(jià)值不然容易做成為了 RAG 而 RAG。大模型有兩個(gè)硬傷知識(shí)有截止日期、不知道你的私有資料。你問(wèn)它我們公司上季度的報(bào)銷政策是什么它要么說(shuō)不知道要么一本正經(jīng)地編。RAG 的思路是在提問(wèn)之前先去你的資料庫(kù)里檢索相關(guān)內(nèi)容把檢索結(jié)果塞進(jìn)提示詞讓模型基于這些內(nèi)容回答。打個(gè)比方模型是個(gè)博學(xué)但沒看過(guò)你公司文件的顧問(wèn)RAG 就是每次提問(wèn)前先讓助理把相關(guān)文件找出來(lái)遞給顧問(wèn)顧問(wèn)看著文件回答。這樣既用上了模型的表達(dá)能力又保證了答案有據(jù)可依。4.2 文檔加載與切分切得好不好直接決定檢索質(zhì)量RAG 效果差八成問(wèn)題出在切分上。文檔切得太粗檢索出來(lái)的段落包含大量無(wú)關(guān)信息模型被干擾切得太細(xì)一個(gè)完整意思被拆散檢索到的片段缺頭少尾。我的經(jīng)驗(yàn)值是中文技術(shù)文檔按 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切分器會(huì)優(yōu)先按段落、句子這些自然邊界切而不是硬按字符數(shù)截?cái)噙@樣切出來(lái)的片段語(yǔ)義更完整。重疊部分是為了防止關(guān)鍵信息正好卡在切口上——比如一個(gè)定義跨了兩個(gè)片段重疊能保證至少有一個(gè)片段包含完整定義。提示如果你的資料里有大量表格Tika 解析出來(lái)的表格結(jié)構(gòu)會(huì)亂。這種情況建議先把表格轉(zhuǎn)成 Markdown 再入庫(kù)或者針對(duì)表格單獨(dú)做處理別指望通用解析器能完美還原。4.3 向量化與存儲(chǔ)讓語(yǔ)義相似可計(jì)算切分完的文本要轉(zhuǎn)成向量才能做語(yǔ)義檢索。向量化的本質(zhì)是把一段文字映射成一串?dāng)?shù)字語(yǔ)義相近的文字向量距離也近。這樣用戶問(wèn)怎么報(bào)銷即使資料里寫的是費(fèi)用申請(qǐng)流程也能被檢索到——因?yàn)樗鼈冋Z(yǔ)義相近向量距離近。EmbeddingModel embeddingModel new AllMiniLmL6V2EmbeddingModel(); EmbeddingStoreTextSegment embeddingStore new InMemoryEmbeddingStore(); EmbeddingStoreIngestor ingestor EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(embeddingStore) .build(); ingestor.ingest(document);這里用的是內(nèi)存向量庫(kù)適合驗(yàn)證和小規(guī)模場(chǎng)景。生產(chǎn)環(huán)境數(shù)據(jù)量大、要持久化得換成專門的向量庫(kù)。選型上數(shù)據(jù)量在百萬(wàn)級(jí)以內(nèi)、團(tuán)隊(duì)不想額外運(yùn)維可以考慮基于本地文件的方案數(shù)據(jù)量再大或者要分布式就得上獨(dú)立的向量數(shù)據(jù)庫(kù)。別一上來(lái)就上重型向量庫(kù)先用內(nèi)存版把鏈路跑通確認(rèn)效果后再遷移遷移成本其實(shí)不高因?yàn)?LangChain4j 的EmbeddingStore接口是統(tǒng)一的。4.4 檢索器配置召回?cái)?shù)量不是越多越好檢索器負(fù)責(zé)在提問(wèn)時(shí)找出最相關(guān)的片段。核心參數(shù)是召回?cái)?shù)量maxResultsContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.6) .build();maxResults設(shè) 5 是我反復(fù)調(diào)出來(lái)的經(jīng)驗(yàn)值。設(shè) 3有時(shí)候關(guān)鍵信息沒被召回設(shè) 10塞進(jìn)提示詞的無(wú)關(guān)內(nèi)容太多模型反而抓不住重點(diǎn)還浪費(fèi) token。minScore是相似度閾值低于這個(gè)分?jǐn)?shù)的片段直接丟棄避免矮子里拔將軍把不相關(guān)的內(nèi)容硬塞進(jìn)去。這兩個(gè)參數(shù)沒有萬(wàn)能值得拿你的真實(shí)問(wèn)題去測(cè)看召回的內(nèi)容是否切題。5. 聲明式接口 流式輸出把問(wèn)答體驗(yàn)做順5.1 用接口定義替代手寫調(diào)用LangChain4j 最優(yōu)雅的地方是聲明式接口。定義一個(gè)Assistant接口加注解框架自動(dòng)生成實(shí)現(xiàn)interface Assistant { SystemMessage( 你是一個(gè)企業(yè)知識(shí)助手。請(qǐng)嚴(yán)格基于檢索到的資料回答問(wèn)題。 如果資料中沒有相關(guān)信息直接說(shuō)資料中未找到相關(guān)內(nèi)容不要編造。 回答要簡(jiǎn)潔必要時(shí)分點(diǎn)說(shuō)明。 ) String chat(UserMessage String question); }然后組裝Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(chatModel) .contentRetriever(retriever) .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) .build();注意contentRetriever一掛上RAG 就自動(dòng)生效了——框架會(huì)在每次提問(wèn)前自動(dòng)檢索、自動(dòng)把結(jié)果注入提示詞。chatMemory負(fù)責(zé)多輪對(duì)話記憶withMaxMessages(10)表示保留最近 10 條消息。這個(gè)數(shù)字也要權(quán)衡留太少多輪對(duì)話會(huì)失憶留太多token 消耗大且早期無(wú)關(guān)內(nèi)容會(huì)干擾當(dāng)前回答。5.2 流式輸出為什么必須做同步返回和流式返回用戶體驗(yàn)差一個(gè)量級(jí)。同步模式下用戶點(diǎn)發(fā)送后要盯著轉(zhuǎn)圈等三五秒才看到整段答案蹦出來(lái)流式模式下第一個(gè)字幾乎立刻出現(xiàn)然后逐字往外吐用戶感覺它在思考、在回答等待焦慮大幅降低。這不是錦上添花是問(wèn)答類產(chǎn)品的體驗(yàn)底線。LangChain4j 的流式接口用回調(diào)實(shí)現(xiàn)interface StreamingAssistant { SystemMessage(你是一個(gè)企業(yè)知識(shí)助手基于資料簡(jiǎn)潔回答) TokenStream chat(UserMessage String question); }TokenStream提供了幾種消費(fèi)方式最常用的是綁定到回調(diào)TokenStream tokenStream streamingAssistant.chat(報(bào)銷流程是什么); tokenStream .onNext(token - { // 每收到一個(gè) token 就推給前端 sseEmitter.send(token); }) .onComplete(response - { sseEmitter.complete(); }) .onError(error - { sseEmitter.completeWithError(error); }) .start();5.3 流式接口和 Spring MVC 怎么對(duì)接后端要把流式內(nèi)容推給前端標(biāo)準(zhǔn)做法是 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接收即可。這里有個(gè)坑我踩過(guò)SseEmitter的超時(shí)時(shí)間一定要設(shè)默認(rèn)值在某些容器下很短長(zhǎng)回答還沒吐完連接就斷了。我設(shè)的 60 秒你可以根據(jù)最長(zhǎng)回答時(shí)長(zhǎng)調(diào)整。另外onNext里如果直接send原始 token遇到換行符可能破壞 SSE 格式穩(wěn)妥做法是把 token 里的換行轉(zhuǎn)義或者用 JSON 包一層再發(fā)。5.4 多輪對(duì)話的記憶管理細(xì)節(jié)MessageWindowChatMemory是滑動(dòng)窗口只保留最近 N 條消息。但有個(gè)細(xì)節(jié)要注意它按消息條數(shù)算不按 token 算。如果某條消息特別長(zhǎng)10 條消息可能就撐爆上下文了。更精細(xì)的做法是用TokenWindowChatMemory按 token 數(shù)控制窗口ChatMemory memory TokenWindowChatMemory.withMaxTokens(2000, new OpenAiTokenizer());這樣無(wú)論消息長(zhǎng)短總 token 數(shù)都可控。代價(jià)是需要一個(gè) tokenizer 來(lái)估算 token 數(shù)稍微重一點(diǎn)。我的建議是對(duì)話輪次少、消息短的場(chǎng)景用MessageWindowChatMemory就夠如果用戶可能粘貼大段文本提問(wèn)果斷上TokenWindowChatMemory。6. 實(shí)測(cè)中那些文檔不會(huì)寫的坑6.1 檢索到了但模型不用提示詞的鍋鏈路跑通后我遇到一個(gè)詭異現(xiàn)象檢索器明明召回了正確片段模型卻答非所問(wèn)。排查半天發(fā)現(xiàn)是提示詞的問(wèn)題。原來(lái)的 system message 寫得太客氣你可以參考以下資料模型就真的只是參考該編還是編。改成強(qiáng)約束后就好了請(qǐng)嚴(yán)格基于以下檢索到的資料回答問(wèn)題。 資料中沒有的內(nèi)容一律回答資料中未找到相關(guān)內(nèi)容。 禁止使用資料之外的知識(shí)作答。提示詞的約束力直接決定 RAG 的可靠性。別指望模型自覺要把規(guī)則寫死、寫明確。這是我從多次調(diào)試?yán)锟偨Y(jié)出的最值錢的一條經(jīng)驗(yàn)。6.2 中文分詞的隱性影響用英文 embedding 模型處理中文效果會(huì)打折扣。我一開始用默認(rèn)的英文模型發(fā)現(xiàn)中文語(yǔ)義檢索經(jīng)常不準(zhǔn)。換成對(duì)中文更友好的 embedding 模型后召回質(zhì)量明顯提升。選 embedding 模型時(shí)一定要確認(rèn)它對(duì)中文的支持程度別默認(rèn)所有模型都中英文通吃。這個(gè)點(diǎn)很容易被忽略但影響很大。6.3 流式輸出的亂碼與斷連流式場(chǎng)景下我遇到過(guò)兩類問(wèn)題。一是中文亂碼token 按字節(jié)流返回時(shí)一個(gè)中文字符可能被拆到兩個(gè) token 里直接拼接會(huì)出亂碼。解決辦法是在服務(wù)端按字符邊界處理或者確保編碼統(tǒng)一為 UTF-8。二是連接中斷用戶網(wǎng)絡(luò)抖動(dòng)或主動(dòng)關(guān)閉頁(yè)面時(shí)后端還在往一個(gè)已斷開的連接推數(shù)據(jù)會(huì)拋異常。要在onError里做好兜底別讓異常冒到頂層。6.4 首次請(qǐng)求慢模型冷啟動(dòng)第一次調(diào)用模型接口時(shí)響應(yīng)明顯比后續(xù)慢這是模型服務(wù)的冷啟動(dòng)。對(duì)用戶體驗(yàn)有影響的話可以在應(yīng)用啟動(dòng)后發(fā)一個(gè)預(yù)熱請(qǐng)求把連接和模型都叫醒。這個(gè)技巧在延遲敏感的場(chǎng)景里很實(shí)用成本幾乎為零。7. 幾個(gè)能直接抄的優(yōu)化方向鏈路跑通只是起點(diǎn)真正拉開差距的是細(xì)節(jié)優(yōu)化。分享幾個(gè)我實(shí)踐下來(lái)收益明顯的方向。檢索結(jié)果重排序。初步召回 5 條后用一個(gè)更精細(xì)的模型對(duì)這 5 條重新打分排序把最相關(guān)的放前面。LangChain4j 支持接入重排序模型對(duì)提升答案準(zhǔn)確率幫助很大尤其是資料庫(kù)內(nèi)容龐雜的時(shí)候。查詢改寫。用戶的問(wèn)題往往口語(yǔ)化、有指代直接拿去檢索效果差?？梢栽跈z索前先用模型把問(wèn)題改寫成更適合檢索的形式。比如用戶問(wèn)那個(gè)報(bào)銷的事咋弄改寫成費(fèi)用報(bào)銷流程和所需材料檢索命中率立刻不一樣。分場(chǎng)景配置。不同業(yè)務(wù)用不同的提示詞、不同的召回策略。技術(shù)文檔問(wèn)答和客服問(wèn)答對(duì)忠實(shí)度和語(yǔ)氣的要求完全不同別用一套配置打天下。LangChain4j 支持定義多個(gè)Assistant接口按場(chǎng)景注入不同配置切換很靈活。加一層緩存。高頻重復(fù)問(wèn)題比如怎么重置密碼沒必要每次都走完整鏈路。在檢索層或答案層加緩存能顯著降低響應(yīng)時(shí)間和調(diào)用成本。緩存 key 用問(wèn)題的向量表示語(yǔ)義相同的問(wèn)題也能命中。監(jiān)控與反饋閉環(huán)。記錄每次問(wèn)答的檢索片段、模型回答、用戶反饋。這些數(shù)據(jù)是后續(xù)優(yōu)化的金礦——哪些問(wèn)題召回不準(zhǔn)、哪些回答被用戶點(diǎn)了沒用一目了然。沒有這個(gè)閉環(huán)優(yōu)化就是盲人摸象。最后說(shuō)個(gè)心態(tài)上的體會(huì)RAG 不是配好就一勞永逸的東西它更像一個(gè)需要持續(xù)調(diào)優(yōu)的系統(tǒng)。檢索質(zhì)量、提示詞、模型參數(shù)每一環(huán)都有優(yōu)化空間。但好消息是用 LangChain4j 把骨架搭起來(lái)之后后續(xù)的優(yōu)化都是在這個(gè)骨架上做增量而不是推倒重來(lái)。這比手寫一堆膠水代碼、每次改動(dòng)都牽一發(fā)動(dòng)全身要舒服太多了。先把最小可用鏈路跑通再拿真實(shí)問(wèn)題去喂、去調(diào)這條路我走過(guò)是通的。