先拋個結(jié)論AI Agent 從來沒有那么玄乎它本質(zhì)上就是“大模型 記憶 RAG 工具調(diào)用”這四樣?xùn)|西按一定規(guī)則組合起來的執(zhí)行系統(tǒng)。網(wǎng)上教程一抓一大把但大部分只教你調(diào)某個框架的API很少講清楚這四塊是怎么協(xié)同的、為什么非這么拼不可、以及真正跑起來之后哪些地方會踩坑。我這篇文章不打算貼一堆框架源碼而是圍繞 Agent 的架構(gòu)邏輯把大模型、記憶、RAG、工具調(diào)用這四件事逐個拆開再用實際能落地的方案串起來。內(nèi)容適合正在做 Agent 開發(fā)的工程師、想給現(xiàn)有業(yè)務(wù)接入私有知識庫的產(chǎn)品技術(shù)負(fù)責(zé)人也適合那些被新概念繞暈、想建立起完整認(rèn)知框架的學(xué)習(xí)者。我會把關(guān)鍵參數(shù)、計算思路、選擇原因通通交代清楚盡量讓讀完的你能直接套用到自己的項目里。1. 一張圖看懂 Agent 的整體循環(huán)1.1 所有 Agent 都在跑同一個循環(huán)哪怕?lián)Q成不同的框架Agent 的內(nèi)核基本都長這樣用戶輸入 → 任務(wù)理解與拆解 → 決定下一步動作 → 執(zhí)行動作思考 / 檢索 / 調(diào)用工具 / 查詢記憶→ 觀察返回結(jié)果 → 繼續(xù)決策 → 直到產(chǎn)出最終答案。這個循環(huán)圖說出來簡單但很多人看架構(gòu)圖時把注意力全放在了“大模型有多強”上忽略了循環(huán)本身的設(shè)計。一個 Agent 能不能干活不只看模型聰明程度更看循環(huán)里每一步是否銜接得順暢。比如用戶問“幫我把最近的線上錯誤日志總結(jié)一下”如果循環(huán)里沒有“檢索日志”這個動作模型再強也只能亂編。所以我畫架構(gòu)圖時一定會把 Agent 描述成一個帶反饋的閉環(huán)而不是一條直線。大模型是閉環(huán)里的“決策器”它每次只決定“下一步該干什么”記憶是“檔案室”負(fù)責(zé)把歷史信息和偏好保存下來RAG 是“外部書籍”隨時把領(lǐng)域知識調(diào)出來給模型參考工具調(diào)用則是“手腳”讓模型真正操作外部系統(tǒng)。1.2 哪些環(huán)節(jié)決定 Agent 好不好用在實際開發(fā)中我認(rèn)為有三個環(huán)節(jié)最容易決定 Agent 的體驗上限。第一是意圖理解與任務(wù)拆解。用戶一句話進(jìn)來模型能不能準(zhǔn)確判斷這是簡單問答、需要多步推理、還是必須調(diào)外部接口。這一步做不好后面全白搭。第二是上下文組織。每次把哪些歷史消息、哪些檢索結(jié)果、哪些工具返回內(nèi)容拼進(jìn)提示詞拼錯了順序或塞太多噪聲結(jié)果會立刻變差。第三是終止條件控制。什么時候該停止調(diào)用工具、什么時候該直接回答這個判斷經(jīng)常被忽略但恰恰是 Agent 穩(wěn)住不跑偏的關(guān)鍵。這里有個挺常見的誤解很多人以為 Agent 的所有能力都來自“模型推理”其實推理只是骨架真正讓 Agent 適配具體業(yè)務(wù)的往往是記憶、RAG、工具調(diào)用這周圍的“輔助模塊”。所以架構(gòu)圖里必須把這幾塊畫進(jìn)去并且明確它們和核心模型之間的數(shù)據(jù)流向。1.3 圖解架構(gòu)時最容易忽略的“隱藏層”我見過不少漂亮的架構(gòu)圖模型、向量庫、工具節(jié)點都畫得很完整但缺了兩樣很容易被忽略的東西上下文管理中間層和可觀測性組件。上下文管理中間層負(fù)責(zé)做歷史消息截斷、摘要壓縮、檢索結(jié)果的重排和評分。不畫這一層圖上幾個模塊看起來都在實際跑起來卻會碰到“模型上下文塞滿”“檢索片段互相矛盾”這種問題?？捎^測性組件則是記錄每一次決策日志和工具返回值的地方?jīng)]有它Agent 出錯時你根本不知道它是哪一步?jīng)Q策錯了排查起來等于盲人摸象。我在自己的項目里習(xí)慣把這兩層在架構(gòu)圖里用獨立模塊標(biāo)注出來。這樣既方便自己和團隊理解也方便后續(xù)做性能定位。2. 大模型這顆“大腦”怎么選、怎么放2.1 API 調(diào)用和本地部署的取舍大模型在 Agent 里的角色是核心推理引擎選型第一件事是決定用云端 API 還是本地部署。這兩條路沒有絕對好壞只看你的使用場景。云端 API 的優(yōu)勢是省事、模型能力強、推理速度有保障特別適合需要復(fù)雜推理、代碼生成、多語言理解的任務(wù)。劣勢也很明顯數(shù)據(jù)要經(jīng)過第三方接口私有化要求高的業(yè)務(wù)會直接排除另外如果調(diào)用量特別大成本會線性上漲。本地部署則相反數(shù)據(jù)完全留存在自己的服務(wù)器上適合處理敏感數(shù)據(jù)的企業(yè)。而且現(xiàn)在開源模型的能力已經(jīng)相當(dāng)能打像 Qwen 系列、Llama 系列在不少任務(wù)上已經(jīng)接近甚至持平前兩年的商用閉源模型。但本地部署的隱形成本一點都不低GPU 采購、運維、推理優(yōu)化都要有人扛。我個人的選型標(biāo)準(zhǔn)是核心鏈路用成熟閉源 API 保效果涉及私有數(shù)據(jù)或成本敏感的輔助鏈路用本地小模型。不要幻想一套方案通吃所有場景Agent 架構(gòu)里本來就可以混用多個模型。2.2 本地跑模型的具體參數(shù)怎么算本地部署最常碰到的問題就是“我的顯卡到底帶不帶得動”這里有一個很簡單的估算公式模型顯存占用 ≈ 參數(shù)量 × 每個參數(shù)占用的字節(jié)數(shù)。以 7B 模型為例FP16 精度下每個參數(shù)占 2 字節(jié)那最低顯存理論值就是 14GB加上推理時的 KV Cache 和其他開銷實際建議至少留出 20GB 以上。如果換成 4-bit 量化每個參數(shù)大約占 0.5 字節(jié)理論值降到 3.5GB 左右實際 6GB 顯存的消費級顯卡也能跑一跑。這幾年我玩得比較順手的組合是 llama.cpp 配 GGUF 量化模型優(yōu)點是單機就能部署、依賴少、還能在 CPU 上跑小模型。需要注意一點本地模型對工具調(diào)用的原生支持不一定好有些模型需要你在提示詞里把工具列表和輸出格式寫得很細(xì)甚至要用特定的模板約束輸出。后面第 5 節(jié)我會單獨講工具調(diào)用。2.3 微調(diào)什么時候才該上很多人一上來就問“我要不要微調(diào)模型”我的建議是先別。微調(diào)的本意是讓模型適應(yīng)特定領(lǐng)域的表達(dá)風(fēng)格、輸出格式或私有術(shù)語它解決的是“模型不會說人話”的問題。但如果你的業(yè)務(wù)知識是結(jié)構(gòu)化、事實性的比如產(chǎn)品文檔、售后手冊RAG 往往比微調(diào)更劃算因為知識更新只需要換知識庫不用重新訓(xùn)練。真正適合微調(diào)的場景是模型輸出風(fēng)格或結(jié)構(gòu)需要嚴(yán)格統(tǒng)一的時候。舉個例子你要讓模型把用戶問題轉(zhuǎn)換成內(nèi)部數(shù)據(jù)庫查詢語句RAG 幫不上忙這時候用幾百到幾千條高質(zhì)量樣本微調(diào)一個小模型效果會非常明顯。注意控制成本微調(diào)不是越多的數(shù)據(jù)越好樣本質(zhì)量遠(yuǎn)比數(shù)量重要。2.4 上下文長度不是越大越好現(xiàn)在模型動輒支持 128K、200K 上下文聽起來很美好但千萬不要因此就不管上下文組織了。長上下文有兩個隱患一是計算成本和非注意力機制都呈超線性上升二是模型在超長上下文里對中部信息的注意力會明顯下降這就是所謂“l(fā)ost in the middle”問題。所以我的習(xí)慣是上下文窗口再大也要做內(nèi)容的優(yōu)先級排序。核心指令放最前歷史記憶做摘要壓縮RAG 檢索結(jié)果按相關(guān)度截斷工具返回內(nèi)容去掉無用字段。這就像整理行李箱箱子再大也要把常用物品放在好拿的位置。3. 記憶機制短期、長期與共享3.1 短期記憶會話窗口管理短期記憶在 Agent 里最直接的體現(xiàn)就是“當(dāng)前對話的歷史消息”通常以消息列表的形式拼進(jìn)模型輸入。實現(xiàn)不難但管理起來有講究。一個常見實現(xiàn)是維護一個會話窗口比如最近 20 輪對話超過之后就整體丟棄。更講究一點的做法是把舊對話先讓模型生成一段摘要再塞進(jìn)新上下文這樣既保留了關(guān)鍵事實又不會讓消息列表無限膨脹。這個方案比簡單截斷好得多因為它能跨輪次保留重要信息。強調(diào)一下短期記憶存儲的位置一般是內(nèi)存或 Redis速度快、生命周期短和后面說的長期記憶有本質(zhì)區(qū)別。3.2 長期記憶向量庫與雙網(wǎng)絡(luò)模型落地長期記憶解決的是“Agent 要記住跨會話的信息”比如用戶偏好、項目背景、歷史結(jié)論。技術(shù)上有兩類實現(xiàn)第一類是用向量庫做語義檢索把重要信息切片后 embedding 存進(jìn)去下次來了新問題先做相似度檢索第二類是用結(jié)構(gòu)化存儲例如用 PostgreSQL 或 Redis 存用戶特征和偏好標(biāo)簽。更高級的做法是“雙網(wǎng)絡(luò)記憶模型”簡單來說就是把記憶分成兩層網(wǎng)絡(luò)來管理。第一層是核心事實網(wǎng)絡(luò)存的是經(jīng)過驗證、不容易變化的穩(wěn)定事實第二層是情境網(wǎng)絡(luò)存的是短期相關(guān)、上下文敏感的臨時信息。查詢時先走核心網(wǎng)絡(luò)拿穩(wěn)定事實再結(jié)合情境網(wǎng)絡(luò)補當(dāng)前上下文線索。我理解這本質(zhì)上是對記憶做分層路由能顯著減少不相關(guān)信息的干擾。說實話大多數(shù)人剛開始做 Agent 記憶用不上這么復(fù)雜直接用 Redis 存最近狀態(tài) 向量庫做長期檢索已經(jīng)能覆蓋 80% 的需求。但理解雙網(wǎng)絡(luò)思路有助于你后期做記憶架構(gòu)的優(yōu)化。3.3 多 Agent 共享記憶怎么做多 Agent 協(xié)作已經(jīng)不算新鮮事共享記憶是其中一個非常實際的需求。最簡單的實現(xiàn)是多個 Agent 共同訪問同一個向量庫命名空間通過 collection/namespace 區(qū)分不同 Agent 或者不同項目的數(shù)據(jù)。但直接把所有 Agent 的寫入口開在一起很快就會亂套。我建議在寫入側(cè)做一道“記憶評估”流程Agent 想把一段信息寫進(jìn)共享記憶前先讓另一個評分器模型判斷它是否有長期保存價值、是否與已有記憶重復(fù)、是否涉及敏感信息。想實現(xiàn)得更穩(wěn)可以在寫入時附帶來源 Agent、時間戳、置信度等元數(shù)據(jù)方便之后溯源。3.4 記憶模塊的常見坑數(shù)據(jù)污染和過期召回記憶模塊如果只做加法不做減法最終會把整個系統(tǒng)拖垮。我在項目中遇到過兩個比較典型的問題。一是數(shù)據(jù)污染。某個 Agent 從一次失敗的對話里提取了錯誤結(jié)論寫進(jìn)了共享記憶之后所有 Agent 都基于這個錯誤結(jié)論做決策。要解決這個問題記憶寫入必須有準(zhǔn)入機制不能誰說什么都記下來。二是過期召回。業(yè)務(wù)變化之后舊知識可能完全失效但向量搜索依然會把過期的內(nèi)容高相關(guān)度地檢索出來。我就出現(xiàn)過知識庫里的舊版 API 接口文檔和最新版本沖突Agent 選擇了舊接口導(dǎo)致調(diào)用失敗的情況。后來我專門加了一個“最后一次更新時間”過濾字段檢索時強制要求只返回近 N 天內(nèi)的內(nèi)容才把這個坑填上。把記憶當(dāng)成一個獨立的、需要治理的數(shù)據(jù)系統(tǒng)來看待它才不會成為 Agent 的短板。4. RAG 知識庫從普通 RAG 到 Agentic RAG4.1 構(gòu)建知識庫的完整流程RAG 的核心價值是讓模型在不重新訓(xùn)練的情況下獲取動態(tài)、私有的領(lǐng)域知識。完成一個可用的 RAG 知識庫大致要經(jīng)過下面這幾步第一步準(zhǔn)備文檔先把 PDF、Word、HTML、Markdown 等格式統(tǒng)一清洗成純文本。第二步分塊Chunking把長文本切成一個一個語義完整的片段。第三步向量化把每個片段用 embedding 模型轉(zhuǎn)成向量。第四步入庫把向量和原始文本一起存進(jìn)向量數(shù)據(jù)庫。第五步檢索增強在 Agent 回答問題時先用問題向量去庫里檢索 Top K再把結(jié)果拼進(jìn)提示詞。第六步質(zhì)量評估持續(xù)檢驗檢索和回答效果并迭代。整個流程里分塊和檢索閾值的選擇是最耗精力的。分塊大小建議按內(nèi)容類型來定。純描述性文檔可以用大塊比如 800 到 1000 字粒度更接近完整語義操作性步驟、FAQ 類型建議用小一點的塊比如 300 到 500 字防止一塊里混雜多個主題。同時建議分塊時做過度重疊也就是下一塊從上一塊結(jié)尾往前重疊一小段避免關(guān)鍵信息剛好被攔腰截斷。檢索階段有兩個參數(shù)需要反復(fù)調(diào)試。一個是 Top K也就是取回多少個候選片段設(shè)置太小會漏設(shè)置太大會把噪聲引進(jìn)來另一個是相似度得分閾值低于閾值的片段直接丟棄這個閾值不能拍腦袋定要拿歷史真實問題做測試慢慢找平衡點。4.2 RAG 評估指標(biāo)怎么理解最近老有人問我“RAG 知識庫到底用什么指標(biāo)衡量好壞”我統(tǒng)一說下我的理解。先看檢索側(cè)最常用的是召回率RecallK意思是正確答案被檢索出來的比例。比如知識庫里明明有 10 條相關(guān)內(nèi)容檢索返回了 8 條那召回率就是 80%。另一個是命中率Hit Rate只有當(dāng)這 K 個結(jié)果里至少出現(xiàn)一條正確內(nèi)容就算命中單位是“問題級別的成功率”比 Recall 粗一些。還有 MRRMean Reciprocal Rank它會看重正確結(jié)果的排位如果正確答案排得越靠前MRR 越高這個指標(biāo)對“返回 Top K 給模型看”有比較強的指導(dǎo)意義。再看生成側(cè)最有名的是忠實度Faithfulness也就是模型生成內(nèi)容有沒有忠實基于檢索到的材料模型有沒有開始自己編這個指標(biāo)在 RAG 場景里格外重要。還有答案正確率這個一般靠人工評測或者用大模型裁判來打分。我建議 RAG 項目上線前至少把這些指標(biāo)跑一遍形成基線。沒有基線你后面改分塊參數(shù)、換 embedding 模型時根本不知道是變好了還是變壞了。4.3 從固定檢索到 Agentic RAG普通 RAG 的邏輯是“用戶問題來了 → 固定地從知識庫里檢索 → 拼裝回答”。這在問題比較標(biāo)準(zhǔn)化的場景下沒問題但一旦遇到跨領(lǐng)域復(fù)雜問題固定檢索就不夠靈活了。這時候就需要 Agentic RAG。Agentic RAG 的特征是檢索過程本身由 Agent 來動態(tài)決策。它不再局限于一個預(yù)設(shè)的向量庫檢索動作而是可以自己決定先查哪個知識庫、要不要做多次檢索、先查文檔再查表格、要不要調(diào)用搜索工具獲取外部信息。Agent 還能把一次檢索結(jié)果當(dāng)作新的輸入繼續(xù)追問等行為。本質(zhì)上它是把“檢索”從固定步驟升級成可規(guī)劃的工具和工具調(diào)用天然結(jié)合在一起。舉個例子用戶問“上個月的線上故障率趨勢以及和哪個版本發(fā)布有關(guān)”Agent 會先把問題拆成“查故障率統(tǒng)計”和“查版本發(fā)布記錄”兩個子任務(wù)再分別去數(shù)據(jù)表和發(fā)布文檔兩個知識庫檢索最后綜合回答。這就是 Agentic RAG 的威力。4.4 RAG 和模型自身記憶的邊界有一次我同事問我“既然模型自己也有知識為什么非要建 RAG”這問題其實問到了模式邊界。模型自身記憶是訓(xùn)練時固化下來的有截止日期遇見新知識它就不知道而 RAG 屬于運行時動態(tài)補充的知識可以做到實時更新。正確姿勢是把兩者當(dāng)作互補關(guān)系模型自身記憶負(fù)責(zé)通用推理、常識和語言能力RAG 負(fù)責(zé)提供業(yè)務(wù)事實。當(dāng)用戶問的問題涉及已有知識時優(yōu)先讓模型調(diào)用常識回答一旦判定問題與內(nèi)部文檔、私有數(shù)據(jù)相關(guān)就去走 RAG 檢索。不要把檢索結(jié)果盲目地每輪都硬塞給模型那樣只會無謂地增加成本、拉低響應(yīng)速度。加一個“是否走 RAG”的判斷節(jié)點會讓整個架構(gòu)輕量很多。5. 工具調(diào)用Agent 的手腳與跟外界握手的方式5.1 Tool / Function Calling 機制拆解工具調(diào)用屬于 Agent 的“行動層”它讓模型不再僅僅輸出文字而是輸出一個“我要調(diào)用某個函數(shù)”的結(jié)構(gòu)化指令。以 OpenAI 的 Function Calling 為例流程是把函數(shù)名、參數(shù)說明、函數(shù)描述以 JSON Schema 形式傳給模型模型根據(jù)用戶請求返回“應(yīng)該調(diào)用什么函數(shù)、傳什么參數(shù)”程序再去執(zhí)行實際函數(shù)把返回值再交給模型模型最終生成自然語言回復(fù)。這里有個比較關(guān)鍵的認(rèn)知模型本身并不執(zhí)行工具它只做“決策”——決定該調(diào)哪個工具、參數(shù)是什么。真正的執(zhí)行是由應(yīng)用代碼完成的。這層解耦非常重要它讓工具可以無限擴展而模型只需要理解工具的描述。所以工具描述寫得清不清楚直接決定了模型會不會用錯。務(wù)必在函數(shù)描述里寫清楚“這個工具是干什么的、什么時候該用、什么時候不該用、參數(shù)有哪些限制條件”。5.2 本地模型的工具調(diào)用配置如果你用的是本地模型比如通過 llama.cpp 部署 GGUF 格式的開源模型工具調(diào)用能力不是天然就有的需要做適配。llama.cpp 本身支持對輸出做一定程度的結(jié)構(gòu)化約束你可以通過 grammar 或者預(yù)定義的 JSON 格式限制模型輸出。實操中的一個可行路徑是在提示詞里把所有可用工具都列出來讓模型必須輸出一個 JSON 字符串字段包含 tool_name 和 parameters然后用 llama.cpp 的 JSON schema 約束來保證模型輸出的是合法 JSON。我在 Qwen 系列的 7B 模型上試過這個方案正確率還可以但比 GPT-4 級別的閉源模型要低不少尤其當(dāng)工具數(shù)量超過 5 個時模型偶爾會把參數(shù)名字編錯。降低這種錯誤率有兩個野路子把工具名稱設(shè)計成語義化更強的單詞以及在示例里給出兩個完整的調(diào)用例子。如果你的核心鏈路非常依賴工具調(diào)用準(zhǔn)確性請優(yōu)先考慮閉源 API或者選專門優(yōu)化過工具調(diào)用能力的開源模型或微調(diào)模型再搭配本地部署。不要為了省錢犧牲主鏈路效果。5.3 實戰(zhàn)案例通過 ES Rest API 讓 Agent 分析日志我拿一個自己做過的例子來演示工具調(diào)用如何落地。當(dāng)時業(yè)務(wù)方要求“讓 Agent 能夠分析 ELK 里的錯誤日志”我不需要把日志數(shù)據(jù)搬進(jìn)向量庫只讓 Agent 通過 Elasticsearch 的 Rest API 查詢?nèi)罩?。我定義了這樣一個工具search_logs(index, query, time_range, size)其中 index 指定日志索引query 是 ES Query DSLtime_range 是時間范圍size 是返回條數(shù)。然后把工具的 schema 傳給 Agent。當(dāng)用戶問“今天早上 9 點到現(xiàn)在 Nginx 的 5xx 錯誤有多少”Agent 會自動把問題轉(zhuǎn)成 search_logs 參數(shù)去 ES 查詢拿回結(jié)果后再組織語言做總結(jié)。這套方案里還有一個很實用的組合讓 Agent 先跑一次 count 統(tǒng)計總數(shù)再跑一次聚合查 Top 錯誤分布最后再寫一小段總結(jié)。這其實已經(jīng)把“工具調(diào)用 計劃能力”串起來了。落地時提醒一句ES 查詢語句里有大量嵌套結(jié)構(gòu)工具描述里一定要給 model 一個最小可用的 Query DSL 模板否則它容易產(chǎn)出非法查詢。5.4 工具調(diào)用設(shè)計的原則和防呆工具設(shè)計得不好Agent 再聰明也白搭。我總結(jié)出幾條很基礎(chǔ)但要牢記的原則。第一工具職責(zé)要單一。一個工具只做一件事讓“查詢?nèi)罩尽焙汀鞍l(fā)送郵件”分開不要讓模型在一堆混合工具里糾結(jié)。第二參數(shù)要盡量少。能傳 3 個參數(shù)就不要設(shè)計 8 個參數(shù)越多模型越容易出錯。第三要有明確的返回結(jié)構(gòu)。返回給模型的數(shù)據(jù)要簡潔去掉無關(guān)字段否則模型解讀時容易犯迷糊。第四所有外部操作類工具必須加確認(rèn)機制。比如“發(fā)送郵件”“刪除數(shù)據(jù)”“執(zhí)行訂單操作”這類有副作用的調(diào)用不能直接執(zhí)行建議在代碼層加一個人工確認(rèn)或者環(huán)境標(biāo)記防止 Agent 一條命令把生產(chǎn)庫給改了。真出過事我見過 Agent 把測試環(huán)境的數(shù)據(jù)批量刪除接口當(dāng)成清庫工具調(diào)用了還好當(dāng)時在工具層加了 yaml 配置的 allowlist只允許執(zhí)行只讀操作才沒釀成大禍。工具層一定要舍得加防護。6. 評估與調(diào)試Agent 不是跑通就完事6.1 為什么普通單元測試不夠Agent 的最大特點是“非確定性”同一個問題每次跑出來的中間路徑可能都不一樣。傳統(tǒng)單元測試斷言特定輸入一定返回特定輸出在 Agent 場景里很難成立。但這不代表不用測試而是要換一套思路。我建議把 Agent 測試分成三個層級。第一層是模塊級測試對單個工具、單個 RAG 檢索函數(shù)做確定性斷言保證輸入輸出符合預(yù)期。第二層是場景級測試設(shè)計用戶常見問題的標(biāo)準(zhǔn)測試集用 Agent 跑完整流程重點看“是否成功到達(dá)終點”“過程中是否調(diào)用了正確工具”。第三層是結(jié)果級評估對最終輸出做人工評分或者用大模型裁判打分評估答案的準(zhǔn)確性、完整性和忠實度。測試集來源很關(guān)鍵。不要只拿網(wǎng)上找的通用問題一定要把你線上真實用戶的問題脫敏后做成測試集。真實問題才能暴露 Agent 在邊界情況下的問題。6.2 從指標(biāo)到評測集第三方評測工具怎么選現(xiàn)在市面上已經(jīng)有不少第三方評測工具幫你管理測試集、跑批量評測、輸出對比報告。我了解到的有 LangSmith、Langfuse、OpenAI Evals、TruLens 等它們各有側(cè)重。LangSmith 和 Langfuse 偏 LLM 應(yīng)用的可觀測性能記錄每一次 trace對定位錯誤很有幫助。OpenAI Evals 是開源評測框架適合自定義評測邏輯。TruLens 更偏 RAG 質(zhì)量評估忠實度、上下文相關(guān)性這些指標(biāo)開箱即用。如果你剛起步不需要全家桶先選一個能記錄 trace 的工具再配套跑人工標(biāo)注的評測集就已經(jīng)非常能打了。評測指標(biāo)至少要盯住這五個任務(wù)完成率、工具調(diào)用成功率、平均回答準(zhǔn)確率、單次任務(wù)延遲、單次任務(wù)成本。前兩個好理解延遲和成本很多團隊上線之后才發(fā)現(xiàn)失控最好在設(shè)計階段就制定好預(yù)算上限。6.3 結(jié)構(gòu)化復(fù)盤把失敗 case 沉淀回知識庫Agent 評估做完最重要的動作是復(fù)盤。每次評測失敗我都會把失敗案例沉淀下來分成三類一類是工具描述不清晰導(dǎo)致模型理解錯那就改工具描述另一類是知識庫里缺少內(nèi)容或內(nèi)容碎片化那就補知識庫并優(yōu)化分塊還有一類是任務(wù)本身超出 Agent 當(dāng)前能力那就必須在架構(gòu)上增加新的工具或新的處理路徑。沉淀回知識庫的意思是把每個失敗 case 的診斷結(jié)論、修正動作和驗證結(jié)果記錄到一張評估清單里下次再評測時直接看這些歷史 case 有沒有改善。這本質(zhì)上是在給 Agent 項目做持續(xù)集成長期價值遠(yuǎn)大于一次性優(yōu)化。7. 常見問題與排錯速查表7.1 高頻故障與排查思路我把實際項目中遇到過的 Agent 典型問題整理成了一張速查表方便你遇到問題時直接定位現(xiàn)象可能原因排查思路模型不調(diào)用工具總是自己硬答工具描述不清、模型版本不支持、代碼里沒傳工具列表先查請求 payload 里有沒有帶 tools簡化工具描述并加示例換更強模型工具參數(shù)傳錯schema 描述不準(zhǔn)確、沒有給示例、模型本身工具能力弱給每個參數(shù)加描述和枚舉值示例中補充完整調(diào)用片段考慮換工具能力更強的模型歷史會話一長回答開始亂七八糟上下文溢出、中間信息被忽略對歷史消息做摘要壓縮只保留最近 N 輪全量文本RAG 檢索出來一堆無關(guān)內(nèi)容分塊太大、Top K 太大、embedding 模型不匹配縮小分塊尺寸降低 Top K重跑評測看指標(biāo)對比Agent 陷入工具調(diào)用死循環(huán)缺少終止條件、工具返回?zé)o法驗證增加最大輪數(shù)上限檢查返回結(jié)構(gòu)是否可解析讓模型輸出一個帶“判斷完成位”的表單共享記憶被寫入錯誤信息缺寫入準(zhǔn)入和更新機制加記憶寫入評分加來源字段建置信度分級7.2 一些我踩過的坑這里挑幾個最典型的展開說說。第一個坑是本地部署模型時只看顯存理論值忽略了推理吞吐。當(dāng)時我部署了一個 13B 模型顯存勉強夠但推理速度慢到用戶等不起整個 Agent 體驗徹底崩了。后來換成了 7B 量化模型犧牲一點效果換回來能被接受的響應(yīng)速度。第二個坑是 RAG 檢索結(jié)果不做去重和重排。有些知識庫里有多個不同文檔的相似內(nèi)容簡單向量檢索把兩份高度重疊的片段都拿回來導(dǎo)致模型回答里出現(xiàn)大量重復(fù)表述。加了重排Rerank模型之后這個問題明顯改善。第三個坑是評估結(jié)果不固定導(dǎo)致的誤判。同一批測試集前一天跑完成率 80%第二天跑了 70%一度讓我以為 Agent 退化了后來發(fā)現(xiàn)是評測環(huán)境里原模型灰度上線了一個新版本。后來我強制鎖定了評測環(huán)境的模型版本所有對比才變得有意義。7.3 排錯時的黃金日志策略Agent 排錯本質(zhì)上是一個追蹤問題。代碼邏輯出錯靠堆棧Agent 決策出錯只能靠日志。我的黃金日志策略很簡單在 Agent 循環(huán)的每個關(guān)鍵節(jié)點都打印結(jié)構(gòu)化日志包含四個字段步驟 ID、動作類型thinking / tool_call / memory_query / rag_retrieve、輸入摘要、輸出摘要。工具調(diào)用日志要額外記錄函數(shù)名、參數(shù) JSON、返回值長度和狀態(tài)碼。RAG 檢索日志要記錄檢索 query、候選數(shù)量、拉了多少條。記憶寫入日志要記錄寫入內(nèi)容摘要、來源 Agent、評分結(jié)果。有了這套日志當(dāng) Agent 出錯時你能快速回放它的每一步?jīng)Q策看到底是哪一步開始跑偏的。日志格式保持 JSON Lines每行一個事件后續(xù)可以接入 Elasticsearch 或任何日志平臺。最后分享一個我自己長期堅持的實操習(xí)慣每次接到 Agent 項目需求我會先用一張白紙把“輸入 → 判斷 → 工具 → 記憶 → 輸出”這個閉環(huán)畫出來再標(biāo)注每步用到的模型、數(shù)據(jù)存儲和備選方案。畫完這張圖整體架構(gòu)基本就清晰了一大半后面寫代碼只是機械地填坑而已。你如果能親手畫一遍可能比看我寫十篇文章更有用。