1. 為什么 Java 開(kāi)發(fā)者現(xiàn)在該認(rèn)真看看 LangChain4j這兩年大模型應(yīng)用開(kāi)發(fā)的熱度基本被 Python 生態(tài)吃掉了LangChain、LlamaIndex 這些框架一個(gè)比一個(gè)火搞得很多寫(xiě) Java 的同學(xué)心里發(fā)慌難道做 AI 應(yīng)用就得轉(zhuǎn)語(yǔ)言我一開(kāi)始也這么想直到實(shí)際在幾個(gè)后端項(xiàng)目里試了 LangChain4j才發(fā)現(xiàn)事情沒(méi)那么絕對(duì)。LangChain4j 這個(gè)庫(kù)的定位很明確就是把大模型調(diào)用、提示詞編排、對(duì)話記憶、工具調(diào)用、檢索增強(qiáng)這些能力用 Java 開(kāi)發(fā)者熟悉的方式封裝起來(lái)讓你在現(xiàn)有的 Spring Boot 項(xiàng)目里就能把 AI 功能接進(jìn)去不用另起一套 Python 服務(wù)再搞跨語(yǔ)言通信。它解決的核心問(wèn)題其實(shí)就一個(gè)讓 Java 后端工程師用自己熟悉的類(lèi)型系統(tǒng)、依賴(lài)管理和工程結(jié)構(gòu)去構(gòu)建基于大模型的應(yīng)用。你不需要懂 Python 的異步生態(tài)不需要折騰虛擬環(huán)境Maven 里加幾個(gè)依賴(lài)寫(xiě)幾個(gè)接口就能跑起來(lái)一個(gè)能對(duì)話、能查資料、能調(diào)用你現(xiàn)有業(yè)務(wù)方法的智能體。適合誰(shuí)看我覺(jué)得有三類(lèi)人最該上手一是手里有成熟 Java 后端系統(tǒng)、想加 AI 能力但不想重構(gòu)技術(shù)棧的工程師二是做企業(yè)級(jí)應(yīng)用、對(duì)穩(wěn)定性和可維護(hù)性要求高的團(tuán)隊(duì)三是想理解大模型應(yīng)用底層編排邏輯、不想只停留在調(diào) API 層面的開(kāi)發(fā)者。這篇文章我不打算寫(xiě)成官方文檔的翻譯而是按我自己踩坑的順序從環(huán)境搭建、核心概念、實(shí)操代碼到問(wèn)題排查把 LangChain4j 入門(mén)這條路上真正會(huì)卡住人的地方講清楚。你跟著走一遍基本能獨(dú)立搭出一個(gè)帶記憶、帶工具調(diào)用、帶知識(shí)庫(kù)檢索的小型 AI 服務(wù)。下面進(jìn)入正題。2. 動(dòng)手之前先把這幾個(gè)核心概念捋順2.1 LangChain4j 到底封裝了什么很多人第一次看 LangChain4j 的文檔會(huì)懵類(lèi)名一大堆不知道從哪下手。我的建議是先建立一張心智地圖這個(gè)庫(kù)本質(zhì)上在幫你做四件事——和大模型通信、管理對(duì)話狀態(tài)、編排多步驟流程、連接外部數(shù)據(jù)和工具。圍繞這四件事它提供了對(duì)應(yīng)的抽象接口。最核心的接口是ChatLanguageModel你可以把它理解成一個(gè)能對(duì)話的模型對(duì)象。它屏蔽了不同廠商 API 的差異OpenAI、通義千問(wèn)、本地部署的模型只要對(duì)應(yīng)的集成包引入了用法基本一致。再往上是AiServices這是我覺(jué)得 LangChain4j 最舒服的設(shè)計(jì)它允許你用聲明式接口的方式定義 AI 服務(wù)就像寫(xiě) MyBatis 的 Mapper 一樣定義一個(gè)接口加幾個(gè)注解框架幫你生成實(shí)現(xiàn)。這個(gè)設(shè)計(jì)對(duì) Java 開(kāi)發(fā)者極其友好后面實(shí)操會(huì)重點(diǎn)講。再往上是記憶Memory和檢索Retrieval。記憶解決的是模型記不住上一輪說(shuō)了什么的問(wèn)題檢索解決的是模型不知道你私有數(shù)據(jù)的問(wèn)題。這兩個(gè)是實(shí)際項(xiàng)目里繞不開(kāi)的光會(huì)調(diào) API 只能做玩具加上這兩個(gè)才能做產(chǎn)品。2.2 模型、提示詞、記憶三者的關(guān)系我用一個(gè)生活化的類(lèi)比幫你理清把大模型想象成一個(gè)知識(shí)淵博但記性極差的顧問(wèn)。你每次找他咨詢(xún)他都不記得你上次來(lái)過(guò)。提示詞Prompt就是你這次遞給他的問(wèn)題紙條記憶Memory就是你隨身帶的一個(gè)筆記本每次咨詢(xún)前把之前的對(duì)話記錄一起遞給他他看完才知道上下文。而 LangChain4j 就是你的助理幫你管理這個(gè)筆記本、幫你把紙條遞過(guò)去、幫你把顧問(wèn)的回答整理好。理解這個(gè)類(lèi)比你就能明白為什么記憶模塊那么重要也能明白為什么提示詞工程本質(zhì)上是在設(shè)計(jì)遞給顧問(wèn)的那張紙條。很多新手一上來(lái)就糾結(jié)模型選哪個(gè)其實(shí)在入門(mén)階段提示詞和記憶的設(shè)計(jì)對(duì)最終效果的影響往往比換個(gè)模型大得多。我見(jiàn)過(guò)太多人花時(shí)間對(duì)比模型跑分結(jié)果提示詞寫(xiě)得含糊不清效果自然差。2.3 版本選擇和依賴(lài)管理的關(guān)鍵決策LangChain4j 迭代很快不同版本 API 有差異這是新手最容易踩的坑。我的建議是入門(mén)階段鎖定一個(gè)穩(wěn)定版本不要追最新。截至我寫(xiě)這篇內(nèi)容時(shí)1.x 系列已經(jīng)比較成熟社區(qū)文檔也跟得上。你在pom.xml里明確寫(xiě)死版本號(hào)別用范圍依賴(lài)否則某天構(gòu)建突然失敗你會(huì)很懵。依賴(lài)拆分也是它的一大特點(diǎn)它把不同廠商的集成做成了獨(dú)立模塊。核心包是langchain4jOpenAI 集成是langchain4j-openai其他廠商各有各的包。這樣做的好處是按需引入不會(huì)把一堆用不到的 SDK 塞進(jìn)你的項(xiàng)目。壞處是新手容易漏引依賴(lài)報(bào)錯(cuò)時(shí)找不到類(lèi)。我的經(jīng)驗(yàn)是先把核心包和你要用的模型集成包引上跑通最小對(duì)話再逐步加記憶、檢索這些模塊一次全引上反而容易亂。3. 環(huán)境搭建與最小可運(yùn)行示例3.1 Maven 依賴(lài)配置實(shí)操先給一份我實(shí)測(cè)能跑通的最小依賴(lài)配置。這里以 OpenAI 兼容接口為例因?yàn)楹芏鄧?guó)內(nèi)廠商也提供兼容接口換 baseUrl 就能用靈活性高。properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target langchain4j.version1.0.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 /dependenciesJDK 版本我建議至少 17LangChain4j 用到了不少新特性用 8 會(huì)各種別扭。如果你項(xiàng)目還鎖在 8要么升級(jí)要么做好心理準(zhǔn)備處理兼容問(wèn)題。這一點(diǎn)沒(méi)有捷徑我試過(guò)在 JDK 8 上硬跑最后放棄升級(jí)了。3.2 第一個(gè)對(duì)話程序從零到跑通依賴(lài)配好后寫(xiě)一個(gè)最簡(jiǎn)單的對(duì)話程序。注意 API Key 千萬(wàn)別硬編碼在代碼里用環(huán)境變量或者配置中心這是基本的安全習(xí)慣。import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.chat.ChatLanguageModel; public class FirstChat { public static void main(String[] args) { ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(API_KEY)) .baseUrl(https://api.example.com/v1) .modelName(your-model-name) .temperature(0.7) .build(); String answer model.chat(用一句話解釋什么是依賴(lài)注入); System.out.println(answer); } }這段代碼里幾個(gè)參數(shù)值得說(shuō)清楚。baseUrl指向服務(wù)地址如果你用兼容接口換成對(duì)應(yīng)地址即可。modelName填你實(shí)際要用的模型標(biāo)識(shí)。temperature控制輸出的隨機(jī)性0 到 1 之間值越低越確定、越保守值越高越發(fā)散、越有創(chuàng)意。做事實(shí)性問(wèn)答建議 0.2 到 0.3做創(chuàng)意文案可以到 0.8 以上。這個(gè)參數(shù)我調(diào)過(guò)很多次新手最容易忽略它結(jié)果抱怨模型胡說(shuō)八道其實(shí)往往是溫度設(shè)太高了。3.3 用 AiServices 聲明式定義你的 AI 服務(wù)上面那種直接調(diào)model.chat()的方式適合測(cè)試但真實(shí)項(xiàng)目里更推薦用AiServices。它的寫(xiě)法像這樣interface Assistant { String chat(String userMessage); } Assistant assistant AiServices.create(Assistant.class, model); String reply assistant.chat(幫我寫(xiě)一個(gè) Java 單例模式的例子);看起來(lái)簡(jiǎn)單但威力在于你可以往接口里加注解、加記憶、加工具。比如加個(gè)系統(tǒng)提示詞interface Assistant { SystemMessage(你是一個(gè)嚴(yán)謹(jǐn)?shù)?Java 技術(shù)顧問(wèn)回答要簡(jiǎn)潔代碼要能直接運(yùn)行) String chat(String userMessage); }SystemMessage定義的是模型的人設(shè)和全局約束它比你在每條用戶(hù)消息里重復(fù)寫(xiě)要求要優(yōu)雅得多。我個(gè)人的經(jīng)驗(yàn)是把角色設(shè)定、輸出格式要求、禁止事項(xiàng)都放在系統(tǒng)消息里用戶(hù)消息只放具體任務(wù)這樣提示詞結(jié)構(gòu)清晰也方便統(tǒng)一維護(hù)。4. 對(duì)話記憶與多輪上下文實(shí)戰(zhàn)4.1 為什么裸模型記不住上下文大模型的 API 本質(zhì)上是無(wú)狀態(tài)的你每次調(diào)用都是一次獨(dú)立的請(qǐng)求模型不會(huì)自動(dòng)記住上一輪。這不是 LangChain4j 的問(wèn)題是所有大模型 API 的共性。所以記憶這件事必須由應(yīng)用層來(lái)做也就是每次請(qǐng)求時(shí)把歷史對(duì)話一起帶上。LangChain4j 提供了ChatMemory抽象最常用的是MessageWindowChatMemory它維護(hù)一個(gè)固定大小的消息窗口超出就丟棄最老的。為什么要有窗口因?yàn)槟Ｐ偷纳舷挛拈L(zhǎng)度有限而且歷史越長(zhǎng) token 消耗越大、成本越高、響應(yīng)越慢。窗口大小就是在這幾者之間做權(quán)衡。4.2 給 AI 服務(wù)加上記憶的完整代碼ChatMemory memory MessageWindowChatMemory.withMaxMessages(20); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .chatMemory(memory) .build(); assistant.chat(我叫小明正在學(xué) Java); assistant.chat(我叫什么名字); // 能正確回答小明withMaxMessages(20)表示保留最近 20 條消息。這個(gè)數(shù)字怎么定我的經(jīng)驗(yàn)是普通客服類(lèi)場(chǎng)景 10 到 20 條夠用長(zhǎng)文檔分析類(lèi)場(chǎng)景可能需要更大但要配合 token 預(yù)算來(lái)算。一條中文消息大概 1 到 2 個(gè) token 每字20 條消息如果每條平均 50 字大概 1000 到 2000 token加上系統(tǒng)提示詞和模型輸出單次請(qǐng)求 token 量可控。如果你設(shè)成 200 條成本會(huì)飆升而且模型對(duì)超長(zhǎng)上下文的注意力也會(huì)下降。4.3 記憶持久化別讓對(duì)話一重啟就丟MessageWindowChatMemory默認(rèn)存在內(nèi)存里服務(wù)一重啟就沒(méi)了。生產(chǎn)環(huán)境肯定不行用戶(hù)會(huì)罵人。LangChain4j 允許你自定義ChatMemoryStore把消息存到數(shù)據(jù)庫(kù)或 Redis。public class RedisChatMemoryStore implements ChatMemoryStore { Override public ListChatMessage getMessages(Object memoryId) { // 從 Redis 讀取并反序列化 } Override public void updateMessages(Object memoryId, ListChatMessage messages) { // 序列化寫(xiě)入 Redis } Override public void deleteMessages(Object memoryId) { // 刪除 } }這里有個(gè)坑我要提醒消息對(duì)象的序列化要處理好不同版本的消息類(lèi)結(jié)構(gòu)可能變。我建議用 JSON 存并且給存儲(chǔ)結(jié)構(gòu)加個(gè)版本字段將來(lái)升級(jí)時(shí)能做兼容。另外memoryId通常用用戶(hù) ID 或會(huì)話 ID一定要保證隔離別讓 A 用戶(hù)的對(duì)話串到 B 用戶(hù)那里這是嚴(yán)重的安全問(wèn)題。5. 工具調(diào)用與檢索增強(qiáng)的落地5.1 讓模型調(diào)用你的 Java 方法工具調(diào)用Tool Calling是讓 AI 從聊天變成干活的關(guān)鍵。原理是你把一些 Java 方法暴露給模型模型在需要時(shí)返回一個(gè)我要調(diào)用某方法、參數(shù)是什么的指令LangChain4j 幫你執(zhí)行方法并把結(jié)果回傳給模型模型再基于結(jié)果生成最終回答。class WeatherTools { Tool(查詢(xún)指定城市的天氣) String getWeather(P(城市名稱(chēng)) String city) { // 實(shí)際調(diào)用你的天氣服務(wù) return city 今天晴25度; } } Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new WeatherTools()) .build();Tool的說(shuō)明文字很關(guān)鍵模型靠它判斷什么時(shí)候該調(diào)用這個(gè)工具。說(shuō)明要寫(xiě)得像給同事解釋這個(gè)方法是干嘛的別寫(xiě)得太技術(shù)化。我見(jiàn)過(guò)有人寫(xiě)invoke weather api模型根本不知道啥時(shí)候用改成查詢(xún)指定城市的實(shí)時(shí)天氣情況就正常了。5.2 檢索增強(qiáng)讓模型讀懂你的私有文檔檢索增強(qiáng)RAG解決的是模型不知道你內(nèi)部資料的問(wèn)題。流程是把文檔切塊、向量化、存進(jìn)向量庫(kù)用戶(hù)提問(wèn)時(shí)先把問(wèn)題向量化檢索出最相關(guān)的幾塊拼進(jìn)提示詞一起發(fā)給模型。EmbeddingModel embeddingModel ...; EmbeddingStoreTextSegment store ...; // 入庫(kù) Document doc Document.from(你的文檔內(nèi)容); ListTextSegment segments new DocumentSplitter(500, 50).split(doc); store.addAll(embeddingModel.embedAll(segments).content(), segments); // 檢索 ContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(3) .build(); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .contentRetriever(retriever) .build();切塊大小 500、重疊 50 是我常用的起點(diǎn)。切太大檢索精度下降切太小語(yǔ)義不完整。重疊是為了避免關(guān)鍵信息正好被切在邊界上。這個(gè)參數(shù)沒(méi)有萬(wàn)能值要拿你的真實(shí)文檔測(cè)我一般會(huì)準(zhǔn)備十幾個(gè)典型問(wèn)題調(diào)參數(shù)時(shí)看召回的相關(guān)塊是否真的相關(guān)。6. 常見(jiàn)問(wèn)題排查與避坑經(jīng)驗(yàn)6.1 高頻報(bào)錯(cuò)速查表現(xiàn)象可能原因排查方向啟動(dòng)報(bào) ClassNotFound依賴(lài)漏引或版本沖突檢查是否引入對(duì)應(yīng)廠商集成包用 mvn dependency:tree 看沖突調(diào)用超時(shí)網(wǎng)絡(luò)或模型響應(yīng)慢設(shè)置合理的 timeout檢查 baseUrl 是否可達(dá)返回亂碼或截?cái)嗑幋a或 maxTokens 設(shè)置過(guò)小確認(rèn) UTF-8調(diào)大 maxTokens工具不被調(diào)用Tool 描述不清優(yōu)化描述文字確認(rèn)參數(shù)注解正確記憶串號(hào)memoryId 設(shè)計(jì)不當(dāng)檢查會(huì)話隔離邏輯6.2 幾個(gè)我踩過(guò)的坑第一個(gè)坑是流式輸出和記憶混用時(shí)的順序問(wèn)題。流式返回時(shí)如果你在流結(jié)束前就把消息寫(xiě)進(jìn)記憶可能寫(xiě)入不完整。正確做法是等流式響應(yīng)完全結(jié)束后再更新記憶。第二個(gè)坑是提示詞里塞了太多無(wú)關(guān)內(nèi)容。新手容易把一堆背景資料全塞進(jìn)系統(tǒng)提示詞結(jié)果模型注意力被稀釋回答質(zhì)量反而下降。我的做法是系統(tǒng)提示詞只放角色和規(guī)則具體資料通過(guò)檢索動(dòng)態(tài)注入。第三個(gè)坑是忽視 token 成本。上線前一定要估算單次請(qǐng)求平均 token 數(shù)乘以日調(diào)用量再乘以單價(jià)。我見(jiàn)過(guò)一個(gè)項(xiàng)目沒(méi)算這筆賬上線一周賬單嚇人?？刂剖侄伟▔嚎s歷史、精簡(jiǎn)提示詞、對(duì)簡(jiǎn)單問(wèn)題用小模型。6.3 性能與成本優(yōu)化的實(shí)操建議模型分級(jí)是個(gè)好策略簡(jiǎn)單意圖識(shí)別、分類(lèi)任務(wù)用便宜的小模型復(fù)雜推理用大模型。LangChain4j 支持配置多個(gè)模型實(shí)例按場(chǎng)景切換。另外對(duì)高頻且答案固定的問(wèn)題做緩存能省下大量調(diào)用。緩存 key 可以用問(wèn)題文本的哈希注意設(shè)置合理的過(guò)期時(shí)間避免答案過(guò)時(shí)。還有一點(diǎn)異步調(diào)用能顯著提升吞吐。LangChain4j 提供了異步的模型接口配合 Java 的 CompletableFuture 使用在 IO 等待期間不阻塞線程。但要注意線程池配置別把連接池打滿(mǎn)。7. 從入門(mén)到能用的進(jìn)階路線跑通上面這些你已經(jīng)能做出一個(gè)像樣的 AI 服務(wù)了。接下來(lái)往哪走我的建議是先別急著上多智能體、復(fù)雜工作流這些花哨的東西而是把可觀測(cè)性做好。記錄每次請(qǐng)求的輸入、輸出、token 消耗、耗時(shí)這些數(shù)據(jù)是你后續(xù)優(yōu)化的依據(jù)。沒(méi)有數(shù)據(jù)調(diào)優(yōu)就是瞎猜。然后是評(píng)測(cè)體系。準(zhǔn)備一批標(biāo)準(zhǔn)問(wèn)題和期望答案每次改提示詞或換模型都跑一遍看效果是變好還是變差。這個(gè)習(xí)慣能幫你避免感覺(jué)好像變好了這種主觀判斷帶來(lái)的反復(fù)橫跳。最后是錯(cuò)誤處理和降級(jí)。模型服務(wù)會(huì)抖動(dòng)會(huì)限流會(huì)超時(shí)。你的代碼要有重試、有超時(shí)、有降級(jí)方案比如模型不可用時(shí)返回兜底話術(shù)。這些工程細(xì)節(jié)才是把 demo 變成產(chǎn)品的分水嶺。我個(gè)人在實(shí)際項(xiàng)目里的體會(huì)是LangChain4j 最大的價(jià)值不是它封裝了多少功能而是它讓 Java 團(tuán)隊(duì)能用自己熟悉的工程方式去構(gòu)建 AI 應(yīng)用不用為了 AI 而割裂技術(shù)棧。入門(mén)門(mén)檻確實(shí)不高但要做好功夫還是在提示詞設(shè)計(jì)、數(shù)據(jù)質(zhì)量和工程細(xì)節(jié)上這些是任何框架都替不了的。