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