1. 為什么我最終把整套 AI 應(yīng)用都?jí)涸诹?LangChain4j 上先說結(jié)論如果你是一個(gè) Java 后端想在不換語言棧的前提下把大模型能力接進(jìn)現(xiàn)有系統(tǒng)LangChain4j 目前是我用過最順手的方案。我從最早寫裸 HTTP 調(diào)接口到后來自己封裝 Prompt 模板、自己拼上下文再到現(xiàn)在用Tool注解加 Agent 流水線把一整套業(yè)務(wù)流程串起來中間踩的坑足夠?qū)懸槐拘?cè)子。這篇就按我實(shí)際項(xiàng)目的演進(jìn)路徑把從單個(gè)工具方法到完整 Agent 流水線的過程拆開講順帶把 RAG、多路召回、并發(fā)這些繞不開的話題一起聊透。標(biāo)題里說的“一個(gè)庫(kù)打全套”不是夸張。LangChain4j 把模型接入、Prompt 管理、工具調(diào)用、記憶、檢索增強(qiáng)、Agent 編排這幾層都覆蓋了你不需要在 Spring 項(xiàng)目里再塞三四個(gè)框架互相打架。適合誰看有 Java 基礎(chǔ)、想把 AI 能力落地到真實(shí)業(yè)務(wù)里的后端開發(fā)以及正在評(píng)估 Agent 框架選型的技術(shù)負(fù)責(zé)人?？赐昴阒辽倌芘袛嗄男﹫?chǎng)景該用Tool哪些該上 AgentRAG 的知識(shí)庫(kù)到底該怎么切、怎么召回、怎么扛住并發(fā)。我下面講的所有內(nèi)容都基于一個(gè)假設(shè)你手上已經(jīng)有一個(gè)能跑起來的 Java 服務(wù)可能是 Spring Boot也可能是別的。至于模型本地 Ollama 和云端 API 我都試過代碼層面切換成本很低重點(diǎn)在于編排邏輯而不是模型本身。2. 從一次接口調(diào)用到 Tool先把“能調(diào)”變成“會(huì)調(diào)”2.1 裸調(diào)模型的三個(gè)致命問題最早我的做法很樸素HTTP 客戶端發(fā)一個(gè)請(qǐng)求把用戶問題拼進(jìn) Prompt拿回文本返回給前端。能跑但很快就出問題。第一個(gè)問題是上下文管理失控。多輪對(duì)話時(shí)我得自己維護(hù)一個(gè) List手動(dòng)截?cái)嗍謩?dòng)拼角色。稍微復(fù)雜一點(diǎn)的多輪場(chǎng)景代碼里全是字符串拼接改一個(gè)標(biāo)點(diǎn)都要重新測(cè)。第二個(gè)問題是模型不知道你的業(yè)務(wù)。你問它“幫我查一下訂單 12345 的狀態(tài)”它只會(huì)編一個(gè)看起來合理的答案。要讓它真的去查庫(kù)你得在 Prompt 里寫死“如果用戶問訂單就輸出一個(gè)特定格式的 JSON”然后自己解析。這個(gè)方案在 demo 階段能用上線就是災(zāi)難因?yàn)槟Ｐ洼敵龈袷讲环€(wěn)定解析失敗率極高。第三個(gè)問題是沒有工具的概念。模型只能“說”不能“做”。而真實(shí)業(yè)務(wù)里查訂單、發(fā)通知、算價(jià)格全是“做”的動(dòng)作。2.2 Tool 注解到底解決了什么LangChain4j 的Tool注解本質(zhì)上是把 Java 方法暴露成模型可以調(diào)用的“函數(shù)”。你寫一個(gè)普通方法加個(gè)注解描述清楚它是干什么的、參數(shù)是什么框架會(huì)自動(dòng)把這個(gè)方法的元信息塞進(jìn)給模型的請(qǐng)求里。模型判斷需要調(diào)用時(shí)會(huì)返回一個(gè)結(jié)構(gòu)化的調(diào)用請(qǐng)求框架再反射執(zhí)行你的方法把結(jié)果回填給模型模型基于結(jié)果生成最終回答。這個(gè)過程聽起來簡(jiǎn)單但它把前面說的三個(gè)問題一次性解決了。上下文由框架的ChatMemory管理工具調(diào)用由框架解析和路由你只需要專注寫業(yè)務(wù)方法。我舉個(gè)實(shí)際例子。假設(shè)有一個(gè)訂單服務(wù)public class OrderTool { Tool(根據(jù)訂單號(hào)查詢訂單狀態(tài)返回狀態(tài)描述和預(yù)計(jì)送達(dá)時(shí)間) public String queryOrderStatus(P(訂單號(hào)純數(shù)字) String orderId) { // 實(shí)際查庫(kù)邏輯 Order order orderRepository.findById(orderId); return 訂單狀態(tài) order.getStatus() 預(yù)計(jì)送達(dá) order.getEta(); } }注意P注解它用來描述參數(shù)。這個(gè)描述非常重要模型就是靠它來判斷該傳什么值。我見過太多人只寫方法描述不寫參數(shù)描述結(jié)果模型傳參亂七八糟。2.3 工具方法設(shè)計(jì)的四條鐵律用了幾個(gè)月Tool之后我總結(jié)了幾條設(shè)計(jì)原則每一條都是踩坑換來的。第一方法粒度要適中。一個(gè)工具方法只做一件事。我一開始寫了一個(gè)handleOrder方法里面根據(jù)參數(shù)不同走查詢、取消、修改三條分支。結(jié)果模型經(jīng)常傳錯(cuò)參數(shù)因?yàn)樗植磺暹@個(gè)工具到底該在什么時(shí)候用。拆成queryOrder、cancelOrder、modifyOrder三個(gè)方法后調(diào)用準(zhǔn)確率明顯上升。第二返回值要結(jié)構(gòu)化且簡(jiǎn)短。模型不是數(shù)據(jù)庫(kù)你返回一個(gè)巨大的 JSON它反而抓不住重點(diǎn)。我現(xiàn)在的做法是返回一個(gè)精簡(jiǎn)的字符串關(guān)鍵字段用固定格式比如狀態(tài):已發(fā)貨|預(yù)計(jì):明天下午。這樣模型解析起來穩(wěn)定后續(xù)如果要程序化處理也方便。第三工具描述要寫“什么時(shí)候用”而不只是“是什么”。比如“查詢訂單狀態(tài)”就不如“當(dāng)用戶詢問訂單進(jìn)度、物流信息、預(yù)計(jì)送達(dá)時(shí)間時(shí)使用”。模型是靠描述做路由的描述里帶上觸發(fā)場(chǎng)景準(zhǔn)確率會(huì)高很多。第四異常要吞掉返回可讀的錯(cuò)誤信息。工具方法里拋異?？蚣芴幚砥饋砗軇e扭模型也看不懂堆棧。我現(xiàn)在的做法是 try-catch 包住返回“查詢失敗訂單號(hào)不存在”這樣的字符串模型會(huì)把這個(gè)信息自然地轉(zhuǎn)述給用戶。提示Tool方法所在的類需要被注冊(cè)到AiServices里別寫完注解就以為萬事大吉注冊(cè)這一步漏了模型永遠(yuǎn)看不到你的工具。3. RAG 接入知識(shí)庫(kù)不是“塞進(jìn)去就行”3.1 為什么單純加長(zhǎng)上下文解決不了知識(shí)問題很多人第一反應(yīng)是我把文檔全拼進(jìn) Prompt 不就行了我試過兩個(gè)問題。一是成本每次請(qǐng)求都帶上幾萬字token 費(fèi)用扛不住。二是效果模型在超長(zhǎng)上下文里會(huì)“迷失”你問它文檔第 37 頁(yè)的一個(gè)細(xì)節(jié)它可能給你編一個(gè)。RAG 的思路是先檢索只把最相關(guān)的片段塞進(jìn)去既省 token 又準(zhǔn)。LangChain4j 的 RAG 鏈路很清晰文檔加載、切分、向量化、存儲(chǔ)、檢索、注入。每一步都有坑我逐個(gè)說。3.2 文檔切分切錯(cuò)了后面全白搭切分是 RAG 里最容易被忽視、但影響最大的一步。我一開始按固定字?jǐn)?shù)切每 500 字一刀。結(jié)果一個(gè)完整的表格被切成兩半檢索出來的片段前言不搭后語模型回答自然離譜。后來我改成按語義切分優(yōu)先在段落、標(biāo)題、列表項(xiàng)這些自然邊界處斷開。LangChain4j 提供了DocumentSplitter可以配置最大片段大小和重疊長(zhǎng)度。我的經(jīng)驗(yàn)值是片段大小 300 到 500 字重疊 50 到 80 字。重疊是為了防止關(guān)鍵信息剛好落在切口上被切沒了。還有一個(gè)細(xì)節(jié)元數(shù)據(jù)要保留。每個(gè)片段最好帶上來源文件名、章節(jié)標(biāo)題、頁(yè)碼。這樣檢索出來之后你可以把來源一起給模型讓它回答時(shí)能引用出處用戶也更信任。3.3 多路召回單路檢索的天花板很低熱詞里有個(gè)“l(fā)angchain4j 多路召回”這個(gè)我深有體會(huì)。單一向量檢索有個(gè)天然缺陷它擅長(zhǎng)語義相似但不擅長(zhǎng)精確匹配。用戶問“錯(cuò)誤碼 E1024 怎么解決”向量檢索可能給你返回一堆“錯(cuò)誤處理”的通用文檔就是找不到那個(gè)具體的碼。我的做法是混合檢索向量檢索一路關(guān)鍵詞檢索一路兩路結(jié)果合并去重再按分?jǐn)?shù)排序。LangChain4j 里可以自己實(shí)現(xiàn)ContentRetriever接口把兩路結(jié)果融合。關(guān)鍵詞那一路我用的是簡(jiǎn)單的倒排索引對(duì)錯(cuò)誤碼、產(chǎn)品型號(hào)、人名這類精確詞效果很好。還有一個(gè)進(jìn)階玩法是查詢改寫。用戶的問題往往口語化直接拿去檢索效果差。我加了一個(gè)前置步驟讓模型把用戶問題改寫成兩三個(gè)更適合檢索的查詢分別去檢索結(jié)果合并。這一步對(duì)召回率的提升非常明顯代價(jià)是多一次模型調(diào)用延遲增加幾百毫秒看你能不能接受。3.4 知識(shí)庫(kù)到底能不能存圖片熱詞里有人問“rag知識(shí)庫(kù)能存儲(chǔ)圖片嘛”答案是能但要看你怎么用。純文本 RAG 存不了圖片的語義但你可以做多模態(tài) RAG圖片先用多模態(tài)模型生成描述文本把描述文本向量化存進(jìn)去檢索時(shí)命中描述再把原圖一起返回。LangChain4j 對(duì)多模態(tài)的支持在逐步完善但這條路我目前只在實(shí)驗(yàn)環(huán)境跑過生產(chǎn)環(huán)境還是以文本為主。4. Agent 流水線從“單次問答”到“多步執(zhí)行”4.1 Agent 和普通工具調(diào)用的本質(zhì)區(qū)別普通工具調(diào)用是“一問一答一工具”模型調(diào)一次工具拿到結(jié)果生成回答結(jié)束。Agent 是“規(guī)劃-執(zhí)行-觀察-再規(guī)劃”的循環(huán)。模型可以連續(xù)調(diào)多個(gè)工具根據(jù)上一步的結(jié)果決定下一步做什么直到任務(wù)完成。舉個(gè)例子。用戶說“幫我查一下訂單 12345如果還沒發(fā)貨就取消然后發(fā)郵件通知我”。這個(gè)任務(wù)里包含條件判斷和多個(gè)動(dòng)作。普通工具調(diào)用做不到Agent 可以先調(diào)查詢工具看到狀態(tài)是“待發(fā)貨”決定調(diào)取消工具再調(diào)郵件工具最后匯總結(jié)果。LangChain4j 的 Agent 能力體現(xiàn)在AiServices配合工具和記憶的組合上。你不需要自己寫循環(huán)框架會(huì)處理模型返回的工具調(diào)用請(qǐng)求執(zhí)行后把結(jié)果回填再次請(qǐng)求模型直到模型不再請(qǐng)求工具、直接給出最終回答。4.2 流水線的分層設(shè)計(jì)我在項(xiàng)目里把 Agent 流水線分成三層這個(gè)分層是我反復(fù)調(diào)整后定下來的分享給你參考。第一層是工具層。就是前面說的Tool方法純業(yè)務(wù)邏輯不涉及任何 AI 概念。這一層要保證每個(gè)方法獨(dú)立、可測(cè)試、無副作用或副作用可控。第二層是編排層。這一層定義 Agent 的行為邊界它能用哪些工具、記憶保留多少輪、系統(tǒng)提示詞怎么寫、遇到工具調(diào)用失敗怎么辦。我通常一個(gè)業(yè)務(wù)場(chǎng)景對(duì)應(yīng)一個(gè)AiServices實(shí)例比如“訂單助手”“客服助手”“數(shù)據(jù)分析助手”各自有各自的工具集。第三層是接入層。處理并發(fā)、限流、超時(shí)、日志、監(jiān)控。這一層和 AI 無關(guān)但決定了你的 Agent 能不能扛住真實(shí)流量。4.3 系統(tǒng)提示詞是 Agent 的靈魂工具決定 Agent 能做什么提示詞決定 Agent 怎么做。我寫提示詞有幾個(gè)固定套路。開頭明確角色和邊界“你是一個(gè)訂單處理助手只能處理訂單相關(guān)的查詢和操作其他問題禮貌拒絕?！敝虚g列出工具使用規(guī)則“查詢訂單前必須先確認(rèn)訂單號(hào)格式取消訂單前必須確認(rèn)用戶意圖不能自行決定取消?！苯Y(jié)尾規(guī)定輸出格式“最終回答用簡(jiǎn)潔的中文涉及金額和時(shí)間的字段要準(zhǔn)確不確定的信息要說明不確定。”這套結(jié)構(gòu)看起來簡(jiǎn)單但比那種一大段散文式的提示詞穩(wěn)定得多。我做過對(duì)比測(cè)試結(jié)構(gòu)化提示詞的工具調(diào)用準(zhǔn)確率比散文式高出兩成左右。4.4 記憶管理別讓上下文無限膨脹ChatMemory是 LangChain4j 里管理多輪對(duì)話的組件。默認(rèn)的MessageWindowChatMemory保留最近 N 條消息超出就丟棄最早的。這個(gè)策略簡(jiǎn)單有效但有個(gè)問題如果早期對(duì)話里有重要信息比如用戶一開始說的訂單號(hào)被丟棄后模型就忘了。我的做法是雙軌制窗口記憶保留最近 10 到 20 輪同時(shí)把關(guān)鍵實(shí)體訂單號(hào)、用戶 ID、產(chǎn)品名抽取出來單獨(dú)存一份每次請(qǐng)求時(shí)作為“已知信息”注入。這樣即使窗口滑走了關(guān)鍵信息還在。注意記憶不是越多越好。我試過保留 50 輪結(jié)果模型開始“翻舊賬”把很久之前的話題扯進(jìn)來回答變得發(fā)散。10 到 20 輪對(duì)大多數(shù)客服場(chǎng)景夠用了。5. 并發(fā)與性能Agent 上線后真正的考驗(yàn)5.1 AI Agent 怎么扛并發(fā)熱詞里“ai agent 怎么扛并發(fā)”這個(gè)問題我踩過的坑最多。Agent 的一次完整執(zhí)行可能包含多次模型調(diào)用和多次工具調(diào)用耗時(shí)是普通接口的好幾倍。如果每個(gè)請(qǐng)求都同步阻塞線程池很快就被打滿。我的方案是異步化加超時(shí)控制。LangChain4j 支持返回CompletableFuture或響應(yīng)式流我把 Agent 調(diào)用包在異步任務(wù)里前端用輪詢或 SSE 拿結(jié)果。同時(shí)給整個(gè) Agent 執(zhí)行設(shè)一個(gè)總超時(shí)比如 30 秒超時(shí)就返回“處理中請(qǐng)稍后查詢”避免請(qǐng)求堆積。另一個(gè)關(guān)鍵是模型調(diào)用的并發(fā)限制。云端 API 通常有 QPS 限制本地 Ollama 的并發(fā)能力也有限。我用信號(hào)量控制同時(shí)進(jìn)行的模型調(diào)用數(shù)量超出的請(qǐng)求排隊(duì)等待。這個(gè)信號(hào)量的值需要根據(jù)你的模型服務(wù)能力實(shí)測(cè)確定我本地 Ollama 跑 7B 模型時(shí)并發(fā)設(shè) 4 比較穩(wěn)再高延遲就明顯上升。5.2 緩存能省掉一半的調(diào)用很多用戶問題其實(shí)是重復(fù)的或者高度相似。我在 Agent 前面加了一層語義緩存把用戶問題向量化和緩存里的歷史問題比對(duì)相似度超過閾值就直接返回緩存答案。這一層對(duì)客服場(chǎng)景特別有效能擋掉三成左右的重復(fù)請(qǐng)求。工具調(diào)用結(jié)果也可以緩存。比如查詢訂單狀態(tài)同一個(gè)訂單號(hào)在短時(shí)間內(nèi)多次查詢結(jié)果是一樣的沒必要每次都打數(shù)據(jù)庫(kù)。我給工具方法加了簡(jiǎn)單的本地緩存TTL 設(shè) 30 秒既保證數(shù)據(jù)不太舊又減少了下游壓力。5.3 監(jiān)控指標(biāo)沒有度量就沒有優(yōu)化Agent 上線后我盯的幾個(gè)核心指標(biāo)單次執(zhí)行的平均模型調(diào)用次數(shù)、工具調(diào)用成功率、端到端延遲的 P95 和 P99、緩存命中率、超時(shí)率。這些指標(biāo)能快速定位問題。比如模型調(diào)用次數(shù)突然上升可能是提示詞被改壞了模型開始反復(fù)調(diào)工具工具調(diào)用成功率下降可能是下游服務(wù)出問題了。6. 常見問題與排查技巧實(shí)錄6.1 工具調(diào)用不觸發(fā)或觸發(fā)錯(cuò)誤這是最高頻的問題。模型該調(diào)工具時(shí)不調(diào)或者調(diào)了錯(cuò)誤的工具。排查順序我固定為三步。第一步檢查工具描述。描述是否清晰說明了使用場(chǎng)景參數(shù)描述是否完整我遇到過參數(shù)描述寫“訂單號(hào)”但沒寫格式模型傳了一個(gè)帶字母的字符串導(dǎo)致查詢失敗。第二步檢查系統(tǒng)提示詞。提示詞里有沒有明確告訴模型“你有這些工具可用”有些模型需要顯式提示才會(huì)調(diào)用工具。第三步檢查模型本身。不同模型對(duì)工具調(diào)用的支持程度差異很大。我實(shí)測(cè)下來同一條提示詞有的模型調(diào)用準(zhǔn)確率九成有的只有六成。如果前兩步都沒問題換個(gè)模型試試。6.2 RAG 檢索結(jié)果不相關(guān)檢索不相關(guān)八成是切分或向量化的問題。我的排查清單片段是不是太大或太小重疊夠不夠向量模型和檢索時(shí)的查詢向量是不是同一個(gè)模型元數(shù)據(jù)有沒有丟還有一個(gè)容易忽略的點(diǎn)查詢本身可能就有問題。用戶問“那個(gè)東西怎么弄”這種問題檢索什么都白搭需要先做查詢改寫。6.3 Agent 陷入死循環(huán)Agent 反復(fù)調(diào)用同一個(gè)工具或者在不同工具之間來回跳停不下來。這是提示詞和工具設(shè)計(jì)共同導(dǎo)致的。我的解法是加一個(gè)最大迭代次數(shù)限制比如 10 次超過就強(qiáng)制終止并返回當(dāng)前結(jié)果。同時(shí)在提示詞里明確“如果工具返回結(jié)果已經(jīng)足夠回答用戶問題不要再調(diào)用工具”。6.4 常見問題速查表問題現(xiàn)象可能原因排查方向工具不觸發(fā)描述不清、提示詞缺失、模型不支持檢查描述和提示詞換模型測(cè)試工具傳參錯(cuò)誤參數(shù)描述不完整、參數(shù)類型模糊補(bǔ)全參數(shù)描述明確格式要求檢索不相關(guān)切分不當(dāng)、向量模型不一致、查詢口語化調(diào)整切分參數(shù)統(tǒng)一向量模型加查詢改寫Agent 死循環(huán)提示詞未設(shè)終止條件、工具返回值有歧義加迭代上限優(yōu)化工具返回格式并發(fā)上不去同步阻塞、模型 QPS 限制異步化加信號(hào)量限流加緩存回答編造信息檢索沒命中、提示詞未約束檢查檢索鏈路提示詞加“不確定就說不知道”6.5 幾個(gè)我踩過的坑第一個(gè)坑工具方法里用了事務(wù)。Agent 調(diào)用工具時(shí)如果方法上有Transactional而整個(gè) Agent 執(zhí)行是異步的事務(wù)上下文會(huì)丟。我的做法是工具方法本身不開啟事務(wù)事務(wù)邏輯下沉到更底層的服務(wù)方法里。第二個(gè)坑向量庫(kù)選型隨意。我一開始用內(nèi)存向量庫(kù)開發(fā)階段沒問題一上生產(chǎn)數(shù)據(jù)量大了就崩。后來?yè)Q成支持持久化和索引的向量庫(kù)穩(wěn)定多了。選型時(shí)重點(diǎn)看是否支持增量寫入、是否支持元數(shù)據(jù)過濾、檢索延遲如何。第三個(gè)坑忽略 token 消耗。Agent 多輪調(diào)用每輪都帶完整上下文token 消耗是普通問答的好幾倍。我上線第一個(gè)月賬單超預(yù)算不少。后來加了 token 計(jì)數(shù)和預(yù)算告警才控制住。7. 我對(duì)這套技術(shù)棧的真實(shí)體會(huì)從Tool到 Agent 流水線LangChain4j 給我的最大感受是“夠用且不重”。它沒有試圖做一個(gè)大而全的平臺(tái)而是把模型接入、工具、記憶、檢索、編排這幾個(gè)核心能力做扎實(shí)剩下的交給你用 Java 的方式去組織。這對(duì) Java 團(tuán)隊(duì)特別友好因?yàn)椴恍枰胄碌恼Z言和運(yùn)行時(shí)現(xiàn)有的工程實(shí)踐、監(jiān)控、部署流程都能復(fù)用。我現(xiàn)在的新項(xiàng)目基本是這個(gè)套路先用Tool把業(yè)務(wù)能力暴露出來再根據(jù)場(chǎng)景決定要不要上 Agent。簡(jiǎn)單問答加單工具AiServices直接搞定多步任務(wù)和條件分支才上 Agent 流水線。RAG 作為獨(dú)立模塊接入和 Agent 解耦方便單獨(dú)調(diào)優(yōu)。這套組合跑下來開發(fā)效率和線上穩(wěn)定性都比我早期自己造輪子好太多。如果你剛開始我的建議是先跑通一個(gè)Tool的 demo感受一下模型調(diào)用工具的過程再逐步加記憶、加檢索、加 Agent。每一步都單獨(dú)驗(yàn)證別一上來就搭全套出了問題你根本不知道是哪一層的事。