最近在給團(tuán)隊(duì)內(nèi)部工具加智能問答能力翻遍Java生態(tài)發(fā)現(xiàn)LangChain4j是接入大模型最順手的一個框架搭配Qwen問答場景5分鐘就能跑通一個最小demo。這篇文章就是那5分鐘的完整記錄——從開通模型服務(wù)、配置Maven依賴到寫出第一行可運(yùn)行的問答代碼再把過程中遇到的環(huán)境變量、超時、依賴沖突這些坑一并講清楚。如果你是Java開發(fā)者想在項(xiàng)目里接大模型但還沒動手這篇可以直接當(dāng)操作手冊用。就算你之前完全沒接觸過LangChain4j只要照著操作大概率也能一次跑通。1. 為什么在Java項(xiàng)目里選擇 LangChain4j Qwen1.1 LangChain4j填補(bǔ)了Java生態(tài)的“LLM應(yīng)用層”空缺Python圈子里搞LLM應(yīng)用開發(fā)隨手就是LangChain、LlamaIndex各種模型調(diào)用、鏈?zhǔn)骄幣?、工具調(diào)用、RAG組件一抓一大把。但Java圈長期處于一種非常原始的狀態(tài)想接大模型要么直接在業(yè)務(wù)代碼里拼HTTP請求要么去寫某家模型廠商SDK的方法調(diào)用。這么搞當(dāng)然也能跑但問題很快就來了。第一個問題是耦合。今天接的是A模型的SDK明天想換B模型業(yè)務(wù)代碼就要跟著改一大片。第二個問題是重復(fù)造輪子。多輪對話要自己維護(hù)歷史消息流式輸出要自己處理SSE事件流工具調(diào)用要自己做JSON參數(shù)解析和拼接模型名、溫度、最大token這些參數(shù)散落在各處。這些事跟業(yè)務(wù)邏輯一點(diǎn)關(guān)系都沒有但不做還不行。LangChain4j最核心的價值是它把這層臟活累活抽象掉了。它在模型層定義了ChatLanguageModel這樣一個統(tǒng)一接口你面向接口編程具體用哪家模型用哪個builder去構(gòu)造都只是啟動時的配置。這個設(shè)計(jì)跟JDBC的思路很像應(yīng)用層寫SQL至于背后是MySQL還是PostgreSQL只要換一個驅(qū)動就行。我項(xiàng)目里最開始用的是Qwen后面如果要切到其他兼容OpenAI協(xié)議的服務(wù)Core代碼幾乎不用動換個BaseUrl和模型名就完事了。除了模型抽象LangChain4j還提供了提示詞模板、聊天記憶ChatMemory、工具調(diào)用Tool、向量檢索Embedding這一整套東西。對于要做知識庫問答、企業(yè)內(nèi)部助手這類場景這些能力不是錦上添花而是剛需。1.2 問答場景選Qwen本質(zhì)選的是“省心”模型服務(wù)這塊我最初在幾個主流選項(xiàng)之間猶豫過最后選了Qwen核心原因是三件事中文效果、成本、訪問路徑。先說中文效果。問答類場景對中文理解和生成質(zhì)量要求很高Qwen系模型在中文語料上的表現(xiàn)是有明顯優(yōu)勢的。團(tuán)隊(duì)內(nèi)部工具里問的都是帶業(yè)務(wù)語境的中文問題拿qwen-plus實(shí)測下來的回答質(zhì)量放在大多數(shù)業(yè)務(wù)問答場景里都夠用。再說成本。DashScope平臺對新用戶有免費(fèi)額度個人學(xué)習(xí)、寫demo階段幾乎不花錢。到了生產(chǎn)環(huán)境qwen-turbo價格非常低qwen-plus也遠(yuǎn)低于一些國際模型。對于想快速驗(yàn)證“大模型問答能不能解決業(yè)務(wù)問題”的團(tuán)隊(duì)來說這個試錯成本非常友好。最后是訪問路徑。Qwen通過DashScope的OpenAI兼容模式對外開放使用的正是LangChain4j里langchain4j-open-ai模塊所實(shí)現(xiàn)的那套協(xié)議。不需要單獨(dú)找適配器不需要寫專用客戶端一個OpenAiChatModel就把模型服務(wù)拉起來了。這一點(diǎn)很重要如果團(tuán)隊(duì)后續(xù)自己在內(nèi)網(wǎng)用vLLM部署了一個開源模型只要那個服務(wù)也暴露了OpenAI兼容接口同一套LangChain4j代碼可以直接切過去。模型層做了完全隔離這才是靠譜的架構(gòu)。2. 跑通前的準(zhǔn)備開通DashScope與項(xiàng)目搭建2.1 開通DashScope并創(chuàng)建API Key第一步是去模型服務(wù)平臺創(chuàng)建API Key。這里直接說步驟任何人都能照做打開DashScope控制臺用賬號登錄。新賬號需要完成實(shí)名認(rèn)證不做完這一步后面沒法開通模型服務(wù)。在控制臺首頁找到“模型服務(wù)”相關(guān)入口進(jìn)入后開通服務(wù)。Qwen系列默認(rèn)就能用不需要單獨(dú)申請白名單。進(jìn)入API-KEY管理頁面點(diǎn)擊創(chuàng)建API Key。創(chuàng)建的時候會生成一串以sk-開頭的密鑰。這里有個細(xì)節(jié)Key創(chuàng)建完成后列表里只會顯示一次完整值之后只能看到掩碼。所以建議創(chuàng)建完立刻復(fù)制到本地密碼管理器里保存。拿到Key之后先別急著寫代碼。我的建議是立刻把它配成環(huán)境變量而不是直接貼在代碼里。命令行執(zhí)行export DASHSCOPE_API_KEYsk-xxx如果你用的是IDEA這類IDE直接運(yùn)行的話環(huán)境變量還需要在Run Configuration里配?？梢栽贓nvironment variables一欄追加DASHSCOPE_API_KEYsk-xxx。這個細(xì)節(jié)很多人會踩坑明明在終端里export了一從IDE跑就報401查半天才發(fā)現(xiàn)是IDE拿到的環(huán)境變量是空的。Key到手之后記得兩件事第一永遠(yuǎn)不要提交到Git倉庫哪怕只是demo也建議用環(huán)境變量或本地配置文件的忽略機(jī)制第二別把Key貼到任何公開群聊里。這類密鑰泄露以后很麻煩輕則被薅額度重則賬戶欠費(fèi)。2.2 用一個Maven項(xiàng)目把依賴?yán)饋?分鐘跑通不需要Spring Boot不需要復(fù)雜工程結(jié)構(gòu)一個純Maven項(xiàng)目就夠。JDK版本建議用17或者更高寫records、var、switch表達(dá)式都方便而且LangChain4j對Java 17的支持非常穩(wěn)。pom.xml里加這些依賴properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target langchain4j.version0.35.0/langchain4j.version /properties dependencies dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version${langchain4j.version}/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version${langchain4j.version}/version /dependency dependency groupIdorg.slf4j/groupId artifactIdslf4j-simple/artifactId version2.0.13/version /dependency /dependencies三個依賴分別干什么說清楚langchain4j是核心庫包含ChatLanguageModel接口、ChatRequest、ChatResponse這些核心抽象以及AiServices、ChatMemory等高級封裝。langchain4j-open-ai是OpenAI協(xié)議模型的適配實(shí)現(xiàn)OpenAiChatModel就在這里。Qwen走DashScope兼容模式用的就是這一層。slf4j-simple是一個日志實(shí)現(xiàn)不加它的話跑起來控制臺會刷一行SLF4J: Failed to load class org.slf4j.impl.StaticLoggerBinder的警告。加上之后日志信息會正常打印排查問題會舒服很多。版本號0.35.0是我在寫這篇時驗(yàn)證過的版本。LangChain4j迭代速度很快建議你在實(shí)際使用時去官方倉庫看一眼最新穩(wěn)定版版本號直接用最新即可。另外如果后續(xù)項(xiàng)目里要集成Spring Bootlangchain4j-spring-boot-starter會提供自動配置但5分鐘跑通這個階段完全用不上加了反而多一層配置干擾。首次執(zhí)行mvn compile會拉取依賴網(wǎng)絡(luò)好的話一兩分鐘就完成了。如果你用的是Gradle依賴坐標(biāo)可以等價替換。3. 最小可運(yùn)行代碼用OpenAI兼容協(xié)議調(diào)通Qwen3.1 核心調(diào)用代碼就這么幾行寫一個QwenQuickstart類主方法里構(gòu)造模型對象然后調(diào)一次問答import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; public class QwenQuickstart { public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(DASHSCOPE_API_KEY)) .baseUrl(https://dashscope.aliyuncs.com/compatible-mode/v1) .modelName(qwen-plus) .build(); String answer model.generate(請用一句話介紹Java編程語言); System.out.println(answer); } }第一次看到OpenAiChatModel這個名字很多人會問我要接的是Qwen為什么用的是OpenAI的類其實(shí)這里的OpenAi指的是協(xié)議而不是具體廠商。DashScope給Qwen模型開放了一個OpenAI兼容端點(diǎn)也就是說它把Qwen模型的服務(wù)包裝成了標(biāo)準(zhǔn)的OpenAI風(fēng)格API。所以LangChain4j里凡是實(shí)現(xiàn)了OpenAI協(xié)議適配的類都能直接對接。這也意味著如果哪天你想換成其他也支持這種協(xié)議的服務(wù)這個類不需要換。代碼里baseUrl指向https://dashscope.aliyuncs.com/compatible-mode/v1這個路徑是固定的/compatible-mode/v1一個字符都不能少。modelName填的是模型名這里用的是qwen-plus想換qwen-turbo或者qwen-max直接把字符串改掉就行。model.generate(...)是最簡單的一次性問答方法傳入字符串返回模型的回答字符串。很適合快速驗(yàn)證鏈路是否通。跑起來之后控制臺如果打印出一句關(guān)于Java的語言介紹說明你已經(jīng)成功走完了整個鏈路Java代碼 - LangChain4j - DashScope兼容端點(diǎn) - Qwen模型 - 返回回答。3.2 常用參數(shù)與第一次調(diào)優(yōu)generate雖然簡單但真實(shí)場景里經(jīng)常要指定系統(tǒng)提示詞、控制回復(fù)長度、調(diào)整超時時間。先用這張表把最常用的幾個參數(shù)說清楚參數(shù)作用推薦值temperature控制回復(fù)隨機(jī)性范圍0~2。值越高回答越發(fā)散問答場景0.2~0.5maxTokens限制回復(fù)的最大token數(shù)默認(rèn)值即可長文輸出場景按需調(diào)大timeout每次請求的超時時間30秒maxRetries請求失敗后的自動重試次數(shù)3temperature是第一個值得反復(fù)實(shí)驗(yàn)的參數(shù)。在問答場景用戶要的是準(zhǔn)確、穩(wěn)定的事實(shí)性回答所以建議調(diào)低處在0.2~0.5之間比較合適。如果是做創(chuàng)意文案、頭腦風(fēng)暴才需要拉高到0.7以上。除了直接generate還有一種更常用的寫法就是構(gòu)建一個ChatRequest傳入完整的消息列表import dev.langchain4j.data.message.ChatMessage; import dev.langchain4j.data.message.SystemMessage; import dev.langchain4j.data.message.UserMessage; import dev.langchain4j.model.chat.ChatLanguageModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.output.Response; import java.util.ArrayList; import java.util.List; public class QwenWithSystemPrompt { public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(DASHSCOPE_API_KEY)) .baseUrl(https://dashscope.aliyuncs.com/compatible-mode/v1) .modelName(qwen-plus) .temperature(0.3) .build(); ListChatMessage messages new ArrayList(); messages.add(SystemMessage.from(你是一位資深的Java技術(shù)顧問回答問題要簡潔、準(zhǔn)確不要輸出與問題無關(guān)的內(nèi)容。)); messages.add(UserMessage.from(LangChain4j是什么)); Responsedev.langchain4j.data.message.AiMessage response model.chat(dev.langchain4j.model.chat.request.ChatRequest.builder() .messages(messages) .build()); System.out.println(response.content().text()); } }這段代碼里SystemMessage用來設(shè)定角色和行為邊界。比如我要求“簡潔、準(zhǔn)確”模型就會明顯比不加約束的時候收斂很多。UserMessage是用戶輸入。多輪對話場景下往這個messages列表里繼續(xù)追加歷史消息即可。這里要說明一下generate和chat的區(qū)別generate只接收一個字符串適合快速驗(yàn)證鏈路chat接收完整的消息列表是真正寫業(yè)務(wù)時該用的入口。4. 實(shí)際跑通過的幾個坑與排查心得4.1 401 UnauthorizedAPI Key的問題最常見也最容易排查。現(xiàn)象是請求發(fā)出后服務(wù)端返回401日志里能看到AuthenticationError或者401狀態(tài)碼。原因一般就這幾類第一環(huán)境變量沒有傳到運(yùn)行進(jìn)程里。剛才說過IDE里跑代碼需要額外配置環(huán)境變量尤其是從IDEA啟動時終端里export的變量默認(rèn)是拿不到的。先在代碼里加一行System.out.println(System.getenv(DASHSCOPE_API_KEY))看打印出來的值是不是空這個動作能幫你快速定位問題。第二Key過期或者賬戶欠費(fèi)。DashScope的Key有過期策略如果之前創(chuàng)建的Key過期了去控制臺重新生成一個就好。第三復(fù)制的時候把空格也帶進(jìn)去了。粘貼到IDE配置框里的時候首尾多一個空格就會導(dǎo)致鑒權(quán)失敗而且肉眼很難看出來。遇到401先檢查Key兩邊是不是有不可見字符。4.2 404 / Invalid URLbaseUrl寫錯了如果你把baseUrl寫成了https://dashscope.aliyuncs.com或者漏掉了/compatible-mode/v1服務(wù)端很可能返回404。這類錯誤在日志里通常能看到明確的HTTP狀態(tài)碼但有個坑是LangChain4j在發(fā)請求前可能會把URL規(guī)范化導(dǎo)致錯誤路徑被合并表現(xiàn)變成讓人摸不著頭腦的Invalid URL。我的排查建議是如果報錯涉及URL先回看一遍baseUrl的完整字符串和官方文檔逐字符對照。注意末尾不要有斜杠也不要有多余的空格。4.3 SLF4J警告和依賴沖突剛搭建項(xiàng)目的時候如果沒加日志實(shí)現(xiàn)依賴控制臺會看到一行黃色的SLF4J: Failed to load class警告。這不影響功能但會讓新手誤以為哪里掛了。解決辦法就是pom里加一個slf4j-simple或者如果你項(xiàng)目已經(jīng)有l(wèi)ogback了直接什么都不用加日志框架會自動綁定。如果是一個已有的大型項(xiàng)目引入LangChain4j后可能會出現(xiàn)NoSuchMethodError或者奇怪的Jackson反序列化異常。這種大概率是項(xiàng)目里已有的gson、guava、okhttp跟langchain4j-open-ai傳遞依賴的版本沖突了。遇到這種情況用mvn dependency:tree -Dincludesdev.langchain4j看一下依賴樹把沖突的版本調(diào)整一致。4.4 超時、限流和重試策略調(diào)用qwen-plus時我遇到過一次SocketTimeoutException。原因是問題比較復(fù)雜模型生成的回答較長而我把timeout設(shè)置得比較短。解決辦法是在builder里顯式設(shè)置超時時間OpenAiChatModel.builder() .timeout(java.time.Duration.ofSeconds(30)) ...另外如果請求過于頻繁服務(wù)端會返回429 Too Many Requests。這時候靠maxRetries重試自動處理即可OpenAiChatModel.builder() .maxRetries(3) ...重試雖然方便但生產(chǎn)環(huán)境建議自己實(shí)現(xiàn)帶指數(shù)退避的重試不要完全依賴框架默認(rèn)策略否則限流時可能出現(xiàn)重試風(fēng)暴。4.5 回答質(zhì)量不穩(wěn)定怎么“教育”模型有時候同一道題模型兩次回答方向不一樣或者輸出了一段跟業(yè)務(wù)無關(guān)的內(nèi)容。這種問題不屬于bug而是模型參數(shù)和提示詞的問題。我的處理思路是三步第一加SystemMessage明確角色和回答邊界第二把temperature降到0.2甚至更低第三對關(guān)鍵答案做程序化校驗(yàn)做一個簡單的關(guān)鍵字?jǐn)嘌员ＷC輸出格式符合預(yù)期。如果試了這三步還不穩(wěn)定那就考慮換更強(qiáng)的qwen-max或者把問題拆得更細(xì)。5. 從Demo到工程落地三個進(jìn)階能力5.1 流式輸出讓回答變成“打字機(jī)”跑通同步接口只是第一步。你要真是給用戶做一個問答機(jī)器人沒人愿意盯著屏幕等一個3秒后才一次性出來的長回答。流式輸出能把耗時從“等待”變成“持續(xù)輸出”用戶第一反應(yīng)就會覺得系統(tǒng)“活”了。LangChain4j里有專門的StreamingChatLanguageModel接口同樣屬于langchain4j-open-ai模塊。構(gòu)造方式類似import dev.langchain4j.model.chat.StreamingChatLanguageModel; import dev.langchain4j.model.openai.OpenAiStreamingChatModel; import dev.langchain4j.model.output.Response; import dev.langchain4j.data.message.AiMessage; StreamingChatLanguageModel model OpenAiStreamingChatModel.builder() .apiKey(System.getenv(DASHSCOPE_API_KEY)) .baseUrl(https://dashscope.aliyuncs.com/compatible-mode/v1) .modelName(qwen-plus) .build(); model.generate(請解釋微服務(wù)架構(gòu), new StreamingResponseHandlerAiMessage() { Override public void onNext(String token) { System.out.print(token); } Override public void onComplete(ResponseAiMessage response) { System.out.println(); } Override public void onError(Throwable error) { error.printStackTrace(); } });onNext回調(diào)里拿到的token就是模型每次返回的增量片段把它們拼起來就是完整回答。前端接SSE或者WebSocket把這些增量實(shí)時推給瀏覽器打字機(jī)效果就出來了。這里注意流式接口的語義是邊生成邊返回所以你的業(yè)務(wù)代碼如果需要等完整結(jié)果再處理就別用流式或者把流式結(jié)果先聚合到內(nèi)存里再統(tǒng)一處理。5.2 多輪對話記憶別再手動拼歷史消息了用chat接口做多輪對話你得自己維護(hù)一個messages列表每輪追加用戶消息和AI消息token數(shù)還要自己算。這種手寫方案很容易在消息列表無限增長時把上下文撐爆。LangChain4j提供了ChatMemory來管理對話記憶最常用的實(shí)現(xiàn)是MessageWindowChatMemory它只保留最近N條消息超出窗口的舊消息會被自動丟棄。然后借助AiServices你只需要定義一個接口框架自動把“帶記憶的對話”變成一個普通Java方法調(diào)用import dev.langchain4j.memory.ChatMemory; import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.service.AiServices; interface Assistant { String chat(String userMessage); } ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(DASHSCOPE_API_KEY)) .baseUrl(https://dashscope.aliyuncs.com/compatible-mode/v1) .modelName(qwen-plus) .build(); ChatMemory chatMemory MessageWindowChatMemory.withMaxMessages(10); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(chatMemory) .build(); String answer1 assistant.chat(你好我叫小張); String answer2 assistant.chat(我叫什么名字);第二次調(diào)用時模型能記得用戶叫小張這就是記憶窗口在起作用。MessageWindowChatMemory.withMaxMessages(10)表示最多保留10條消息超過之后自動淘汰最舊的消息。窗口越大模型可參考的上下文越多但每次請求的token成本也會隨之上升這個需要根據(jù)業(yè)務(wù)按需調(diào)整。5.3 工具調(diào)用問答助手變“數(shù)字化員工”只做問答不夠問答只是入口真正的價值在于模型能幫你做事。LangChain4j支持把Java方法注冊成工具模型在回答過程中如果發(fā)現(xiàn)需要調(diào)用某個工具會主動發(fā)起調(diào)用并把返回值整合進(jìn)最終回答。舉個例子給Assistant接口之外定義一個工具類import dev.langchain4j.agent.tool.Tool; class OrderTool { Tool(根據(jù)訂單號查詢訂單狀態(tài)) public String queryOrderStatus(String orderNo) { // 這里查數(shù)據(jù)庫、調(diào)內(nèi)部接口都行 return 訂單 orderNo 當(dāng)前狀態(tài)為已發(fā)貨; } }然后在構(gòu)建AiServices時把這個工具注冊進(jìn)去Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(chatMemory) .tools(new OrderTool()) .build(); String answer assistant.chat(幫我查一下訂單2024001的狀態(tài));當(dāng)模型發(fā)現(xiàn)你的問題涉及訂單查詢它會根據(jù)Tool里的描述生成調(diào)用參數(shù)框架自動反序列化并執(zhí)行你的queryOrderStatus方法再把結(jié)果回傳給模型模型組織成自然語言回答。這就是工具調(diào)用的完整鏈路。這個能力一下子把“問答”升級成了“能執(zhí)行任務(wù)的助手”。查庫存、生成工單、拉報表、提單審批只要把方法暴露成Tool模型就能“指揮”代碼干活。對Java后端來說這是我覺得LangChain4j最有價值的一塊能力遠(yuǎn)比單純把大模型接入聊天窗有價值。這里再說一個實(shí)際體驗(yàn)跑通demo本身不難難的是從demo到生產(chǎn)之間那段路。我自己的體會是API Key一定要盡早納入配置中心統(tǒng)一管理不要散落在各個環(huán)境變量里每次調(diào)用最好記錄一下模型名、token數(shù)、耗時方便后續(xù)對賬和成本優(yōu)化如果業(yè)務(wù)存在高頻調(diào)用限流和重試策略要提前設(shè)計(jì)別讓模型供應(yīng)商的429限制突然打崩你的接口。最后再分享一個小技巧剛開始調(diào)試LangChain4j時把日志級別開到DEBUG看LangChain4j實(shí)際發(fā)出的HTTP請求體。你會發(fā)現(xiàn)它把messages列表、temperature、maxTokens這些參數(shù)完整地拼進(jìn)了請求。看到這個真實(shí)的請求結(jié)構(gòu)之后你對這套框架的理解會立刻深一層——原來它不過是個幫你把模型調(diào)用封裝成普通Java接口的“翻譯官”。想清楚這一點(diǎn)后面無論換模型還是排查問題你心里都會更有底。