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