Agent 評測是 Agent 工程化落地中最容易被低估的一環(huán)。很多團隊能快速搭出一個能跑的 Agent卻很難回答三個基礎問題新版提示詞真的比舊版好嗎同一個任務連續(xù)運行二十次成功率是多少失敗的回合到底是模型理解錯了、工具調用錯了還是任務定義本身有歧義。Agent Review Studio 這類 local-first agent evaluation workbench解決的就是這件事把評測集組織、運行軌跡記錄、指標計算和結果審查整合到一個本地工作臺中讓 Agent 的行為變化可復現(xiàn)、可對比、可人工核查。這篇文章不假定你已經擁有完整的評測平臺也不綁定某個具體 Agent 框架。我會從評測工作臺解決的底層問題開始再給出一個可以在本地跑通的最小實現(xiàn)內容包括評測集定義、運行器、軌跡存儲、指標計算和結果審查。讀完以后你可以把同一套思路遷移到自己的 Agent 項目里底層不管是自研模型調用、LangChain 這類編排框架還是企業(yè)內部封裝好的 SDK都只影響適配層不影響工作臺的整體設計。1. Agent 評測為什么不能只靠普通測試腳本1.1 Agent 行為和普通函數測試有本質差別傳統(tǒng)單元測試有一個隱含前提相同的輸入會產生穩(wěn)定輸出。對一個純函數來說入參確定、執(zhí)行環(huán)境確定返回值就可以被精確斷言。Agent 不具備這個特性。Agent 的輸入是自然語言任務執(zhí)行過程是模型推理、工具調用、結果觀察的循環(huán)最后的輸出既受模型版本和溫度參數影響也受上下文長度、工具返回內容、網絡延遲甚至并發(fā)順序影響。同樣是幫我查一下本月訂單金額并生成匯總模型第一次可能直接調用查詢工具第二次可能先問用戶要具體日期范圍第三次可能選擇了錯誤的時間字段。三個回合的最終結果可能完全不同但每個回合內部都有完整推理鏈路。只用斷言結果正確與否的測試腳本無法回答為什么會失敗失敗在哪一步是不是工具返回格式變了這類問題。所以 Agent 評測的核心對象不是單個輸出值而是執(zhí)行過程本身。評測工作臺必須能記錄每一輪推理、每一次工具調用、每一個中間觀察結果把黑盒輸出變成可審查的白盒軌跡。軌跡回放能力是評測工作臺和普通測試腳本最本質的區(qū)別。1.2 local-first 解決的是數據主權和可復現(xiàn)問題local-first 這個詞在 Agent 評測場景下有兩層含義。第一層是數據不出本機。Agent 運行軌跡里通常包含用戶問題、業(yè)務字段、工具返回的原始數據這些內容很可能涉及敏感信息。如果評測平臺是云端 SaaS軌跡上傳意味著業(yè)務數據離開本地網絡很多團隊在合規(guī)上無法接受。本地優(yōu)先的工作臺把 SQLite 文件、軌跡目錄和評測報告都放在本機評測數據的所有權和使用權都留在團隊自己手里。第二層是環(huán)境可控。云端評測平臺往往黑盒管理模型版本、參數和依賴版本出現(xiàn)問題后很難回溯。本地工作臺可以把模型版本、提示詞版本、工具定義版本、依賴鎖文件一起記錄成一次評測快照。出問題時按快照重建環(huán)境就能復現(xiàn)不需要猜測線上環(huán)境發(fā)生了什么變化。需要說明的是local-first 不等于完全離線。評測運行器仍然需要調用模型 API只是評測框架本身、存儲、審查界面都在本地運行。文章后面說的架構也是這種形態(tài)框架本地化模型遠端調用。1.3 評測工作臺的五個能力層次從功能角度看一個可用的 Agent 評測工作臺至少包含五層能力評測集管理組織和版本化用例集合支持分類、標簽、預期結果描述。運行器批量執(zhí)行評測任務統(tǒng)一注入環(huán)境變量、模型參數和工具配置。軌跡存儲把一次運行的所有步驟按時間順序落盤形成可回放證據。指標計算在軌跡基礎上計算成功率、工具調用有效率、延遲、Token 消耗等。審查與對比把多次運行結果放在一起比較定位差異和回歸。這五層缺了任何一層評測都會退回成跑一遍看日志。下面各部分會按這個層次順序展開實現(xiàn)。2. 先理解評測工作臺的核心概念2.1 評測集Suite和用例Case評測集是若干評測用例的集合。一個用例代表一個要驗證的任務場景包含任務輸入、任務描述、預期行為、標簽和可選的環(huán)境配置。id: case-001 name: 查詢訂單狀態(tài)并回復用戶 description: 用戶想知道訂單 20240315001 當前處于什么狀態(tài) input: message: 我的訂單 20240315001 現(xiàn)在到哪一步了 expected: type: contains values: - 已發(fā)貨 - 運輸中 - 已完成 tags: - order - retrieval difficulty: easy這里的expected不是硬編碼最終答案而是描述什么結果可以接受。常見判斷方式有四類判斷方式適用場景說明exact match結構化輸出、JSON 字段輸出必須精確相等適合工具返回校驗contains / regex自然語言回復判斷關鍵信息是否出現(xiàn)JSON Schema 校驗工具參數、結構化結果校驗字段類型和必填項不關心具體值LLM-as-judge / 人工審查開放性任務由模型或人判斷結果質量需要額外控制偏差在最小實現(xiàn)里可以先支持前三種把 fourth 種留到后面擴展。2.2 軌跡Trace是評測的第一手證據軌跡是一次評測運行從開始到結束的完整事件序列。一個最小軌跡應該包含以下字段{ runId: run-20250315-001, caseId: case-001, startedAt: 2025-03-15T10:00:00.000Z, finishedAt: 2025-03-15T10:02:31.000Z, status: completed, steps: [ { seq: 1, type: model, input: 我的訂單 20240315001 現(xiàn)在到哪一步了, output: 我需要查詢訂單狀態(tài)先調用訂單查詢工具。, model: gpt-4o-mini, temperature: 0, tokensIn: 120, tokensOut: 45, durationMs: 800 }, { seq: 2, type: tool_call, name: query_order, arguments: {\orderId\: \20240315001\}, result: {\status\: \shipped\, \updated\: \2025-03-15T08:30:00Z\}, durationMs: 210 } ] }軌跡的價值在于事后審查。當最終結果失敗時審查者需要知道模型在哪一步產生了錯誤判斷工具返回了什么引起誤解后續(xù)步驟是否基于錯誤信息繼續(xù)執(zhí)行。沒有軌跡指標就是沒有根據的數字有了軌跡指標才能被追責和復盤。2.3 指標分為結果指標和過程指標指標不能只看最終成功率。一個 Agent 可能最后輸出了正確答案但中間調用了八次工具、繞了很多彎路也可能最終失敗但失敗原因是外部 API 超時而非 Agent 邏輯錯誤。所以要把指標分成兩類指標類別指標名稱計算方法說明結果指標Success Rate成功用例數 / 總用例數最直觀的總體質量指標結果指標Task Score按完成度打分 0-100適合部分完成也算分的情況過程指標Tool Success Rate工具成功調用數 / 總調用數反映工具使用能力過程指標Avg Steps總步驟數 / 運行次數步驟多不一定差但可以反映繞路過程指標Avg Latency總耗時 / 運行次數和成本一起決定可用性過程指標Token Usage總 Token 數或單次平均直接對應 API 成本過程指標Abort Rate超時或異常終止數 / 總運行數反映穩(wěn)定性真實項目里結果指標決定功能是否達標過程指標決定 Agent 是否值得上線。一個步驟少、延遲低、成本可控的 Agent即使成功率略低也往往更容易被用戶接受。2.4 回歸對比把單次運行變成趨勢Agent 評測最大的陷阱是拿一次運行結果下結論。同樣的提示詞溫度為零時也可能因為非確定性采樣產生不同輸出工具服務波動也會影響結果。正確做法是對同一套評測集反復運行多次把結果當成分布來看?；貧w對比指兩件事一是同一個 Agent 版本在多次運行之間的穩(wěn)定性對比二是新舊版本在相同評測集上的效果差異。工作臺應該把兩次運行的用例結果對齊逐條顯示這個用例舊版成功、新版失敗或新舊都成功但新版多用了兩步。這種差異視圖是決定是否發(fā)布新版本的主要依據。3. 環(huán)境準備搭建一個本地可跑通的腳手架3.1 技術棧選擇與版本要求下面示例用于說明思路實際項目可以按團隊熟悉程度替換。核心原則是運行器用你熟悉的后端語言存儲用本地文件或 SQLite審查界面用最簡單的方式呈現(xiàn)。推薦一個低成本的組合組件推薦選擇備選方案選擇理由運行器Node.js TypeScriptPython FastAPI類型約束對軌跡數據結構很有幫助存儲SQLitebetter-sqlite3JSON Lines 文件單文件、零運維、適合本地評測集定義YAMLJSON可讀性好適合寫注釋審查界面本地 Express 服務 靜態(tài) HTMLReact/Vue最小實現(xiàn)避免構建復雜度命令行入口Commander直接 npm script方便在本地和 CI 復用環(huán)境要求很簡單Node.js 18 以上npm 或 pnpm一臺能訪問模型 API 的開發(fā)機。不需要部署數據庫不需要申請額外的評測平臺賬號。注意如果你要接不同模型 API請先確認項目使用模型的版本、baseURL 和鑒權方式。模型版本不固定評測結果的可復現(xiàn)性會大打折扣。3.2 目錄結構設計一個最小項目可以按功能拆分目錄agent-review-studio/ ├── package.json ├── tsconfig.json ├── data/ │ └── eval.db # SQLite 數據庫本地自動生成 ├── suites/ │ ├── order-basic.yaml # 評測集定義 │ └── order-edge.yaml ├── src/ │ ├── cli.ts # 命令行入口 │ ├── types.ts # 軌跡、用例、指標類型 │ ├── runner.ts # 評測運行器 │ ├── store.ts # SQLite 持久化 │ ├── metrics.ts # 指標計算 │ ├── adapter.ts # Agent 適配層隔離不同框架 │ └── server.ts # 本地審查服務 └── reports/ # 生成的報告目錄這里的adapter.ts是關鍵。評測工作臺不應該關心 Agent 內部是 LangChain 還是自研實現(xiàn)它只要求適配層暴露一個統(tǒng)一方法接收消息和歷史上下文返回本輪輸出、工具調用列表和 token 消耗。評測集、指標、存儲全部建立在統(tǒng)一接口之上替換底層框架只需要重寫適配層。3.3 SQLite 表結構設計評測數據核心是四張表用例、運行、步驟、指標。CREATE TABLE cases ( id TEXT PRIMARY KEY, suite TEXT NOT NULL, name TEXT NOT NULL, input TEXT NOT NULL, expected TEXT NOT NULL, tags TEXT DEFAULT [], created_at TEXT DEFAULT (datetime(now)) ); CREATE TABLE runs ( id TEXT PRIMARY KEY, case_id TEXT NOT NULL, status TEXT NOT NULL, -- running / completed / failed / aborted model TEXT, prompt_version TEXT, started_at TEXT, finished_at TEXT, error TEXT ); CREATE TABLE steps ( id INTEGER PRIMARY KEY AUTOINCREMENT, run_id TEXT NOT NULL, seq INTEGER NOT NULL, type TEXT NOT NULL, -- model / tool_call / tool_result / error name TEXT, input TEXT, output TEXT, duration_ms INTEGER, tokens_in INTEGER, tokens_out INTEGER, created_at TEXT DEFAULT (datetime(now)) ); CREATE TABLE metrics ( run_id TEXT PRIMARY KEY, success INTEGER, task_score REAL, tool_success_rate REAL, avg_latency_ms REAL, total_tokens INTEGER, steps INTEGER );表結構的設計要點是把運行的原始軌跡和計算出的指標分開存儲。軌跡是證據指標是結論。證據不能因為之后改了算法而丟失所以任何指標計算都應該是從軌跡重新推導而不是在軌跡上原地修改。這樣后面優(yōu)化指標算法時歷史運行記錄還能重新計算不需要重跑評測。4. 實現(xiàn)一個最小評測閉環(huán)4.1 定義評測任務和預期結果在suites/order-basic.yaml中定義兩個用例一個驗證正常查詢一個驗證無效訂單處理suite: order-basic description: 訂單查詢基礎能力評測 cases: - id: order-001 name: 查詢已發(fā)貨訂單 input: message: 我的訂單 20240315001 現(xiàn)在到哪一步了 expected: type: contains values: [已發(fā)貨, 運輸中, 已完成] tags: [order, happy-path] - id: order-002 name: 查詢不存在的訂單 input: message: 查一下訂單 999999 的物流狀態(tài) expected: type: contains values: [不存在, 沒有找到, 無效] tags: [order, edge-case]這里隱藏了一個 Agent 評測的常見誤區(qū)預期結果描述的是用戶可接受的信息而不是模型逐字輸出。如果寫死values: [已發(fā)貨]當模型回復您的訂單已經發(fā)出正在運輸途中時正確信息因為措辭不同被判失敗。評測集要站在用戶價值角度設計而不是站在字符串匹配角度設計。4.2 實現(xiàn)評測運行器運行器負責讀取評測集、逐條調用 Agent 適配層、收集軌跡。下面是一個最小實現(xiàn)// src/runner.ts import { readFile } from fs/promises; import yaml from yaml; import { RunResult, Step, Suite } from ./types; import { runAgent, AgentAdapterOptions } from ./adapter; export async function runSuite(filePath: string, adapter: AgentAdapterOptions) { const raw await readFile(filePath, utf-8); const suite yaml.parse(raw) as Suite; const results: RunResult[] []; for (const testCase of suite.cases) { const steps: Step[] []; const startedAt new Date().toISOString(); let status: RunResult[status] completed; let error: string | undefined; try { // 調用適配層執(zhí)行 Agent接收逐步回調以記錄軌跡 await runAgent( { message: testCase.input.message, suite: suite.suite, caseId: testCase.id, }, adapter, (step) steps.push(step) ); } catch (e) { status failed; error e instanceof Error ? e.message : String(e); } results.push({ runId: ${testCase.id}-${Date.now()}, caseId: testCase.id, status, startedAt, finishedAt: new Date().toISOString(), steps, error, }); } return results; }這段代碼的關鍵在于runAgent的第三步回調。很多初版評測框架只會收集最終輸出丟掉了中間步驟。正確的做法是讓適配層在每個事件發(fā)生時就上報一次運行器只負責按順序追加。這樣軌跡的完整性由運行器保證不屬于自定義 Agent 邏輯的一部分。4.3 保存軌跡和計算結果運行完成后需要把軌跡寫入 SQLite并計算指標。寫入順序很重要先寫運行主記錄再寫步驟再寫指標。任何一步失敗都應該讓整次運行標記為 failed避免出現(xiàn)有指標沒軌跡的殘缺數據。import Database from better-sqlite3; export function persistRun(db: Database, result: RunResult) { const insertRun db.prepare( INSERT INTO runs (id, case_id, status, error, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?) ); const insertStep db.prepare( INSERT INTO steps (run_id, seq, type, name, input, output, duration_ms, tokens_in, tokens_out) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ); const insertMetric db.prepare( INSERT INTO metrics (run_id, success, task_score, tool_success_rate, avg_latency_ms, total_tokens, steps) VALUES (?, ?, ?, ?, ?, ?, ?) ); const tx db.transaction(() { insertRun.run( result.runId, result.caseId, result.status, result.error ?? null, result.startedAt, result.finishedAt ); for (const step of result.steps) { insertStep.run( result.runId, step.seq, step.type, step.name ?? null, step.input ?? null, step.output ?? null, step.durationMs ?? null, step.tokensIn ?? null, step.tokensOut ?? null ); } const metrics computeMetrics(result); insertMetric.run( result.runId, metrics.success ? 1 : 0, metrics.taskScore, metrics.toolSuccessRate, metrics.avgLatencyMs, metrics.totalTokens, metrics.steps ); }); tx(); }使用db.transaction的目的是保證一批數據要么全部寫入要么全部不寫入。否則一旦運行到第三步失敗數據庫里就會留存一條沒有步驟記錄的 runs 數據后續(xù)統(tǒng)計時會污染成功率。4.4 生成審查報告本地工作臺的最小審查形態(tài)可以是一份靜態(tài) HTML 報告或者一個本地 Web 服務。最簡單方式是讓 CLI 在執(zhí)行完評測后輸出一個reports/report.html里面按用例列出每次運行的成功狀態(tài)和軌跡摘要。!-- 生成報告的簡化模板實際由代碼動態(tài)渲染 -- ul li strongorder-001/strongcompleted details summary查看軌跡/summary p第 1 步模型調用輸入用戶消息輸出我需要查詢訂單。/p p第 2 步工具調用 query_order參數 {orderId:20240315001}。/p p第 3 步工具返回 {status:shipped}。/p /details /li /ul報告不是給機器看的是給人審查的。所以每一條用例都要有展開軌跡的入口并且標記該用例使用的預期判斷方式。這個階段的報告可以很粗糙但它必須讓審查者能回答為什么判定成功或為什么判定失敗。5. 關鍵模塊設計指標計算、軌跡審查和回歸對比5.1 指標計算模塊指標計算不應該散落在插入數據的邏輯里而應該獨立成一個純函數模塊。這樣歷史軌跡可以重新計算指標不同指標算法可以并行比較。// src/metrics.ts import { RunResult, Metrics } from ./types; export function computeMetrics(result: RunResult): Metrics { const steps result.steps; const toolCalls steps.filter((s) s.type tool_call); const toolSuccess toolCalls.filter((s) s.output !s.output.startsWith(ERROR)); let totalTokens 0; let totalLatency 0; for (const step of steps) { totalTokens (step.tokensIn ?? 0) (step.tokensOut ?? 0); totalLatency step.durationMs ?? 0; } return { success: result.status completed, taskScore: result.status completed ? 100 : 0, toolSuccessRate: toolCalls.length ? toolSuccess.length / toolCalls.length : 1, avgLatencyMs: steps.length ? totalLatency / steps.length : 0, totalTokens, steps: steps.length, }; }現(xiàn)在computeMetrics里的 success 只判斷狀態(tài)沒有做預期結果的匹配。真實實現(xiàn)里應該在運行器判斷完 expected 之后把匹配結果傳進來。這一步留給你的實際項目擴展關鍵是保持軌跡數據不隨指標變化的原則。5.2 軌跡審查頁面軌跡審查頁面至少有三種視圖列表視圖按套件和用例列出所有運行記錄綠綠紅紅一眼看出失敗集中在哪個用例。時間線視圖單個運行記錄的步驟按時間展開模型推理、工具調用、工具結果依次排列任何一步耗時異常都容易發(fā)現(xiàn)。對比視圖同一用例的新舊兩次運行并排展示高亮模型推理差異、工具參數差異和結果差異。時間線視圖最容易暴露問題。例如一個 Agent 在工具調用失敗后反復重試時間線會連續(xù)出現(xiàn)五次相同的tool_call這比任何指標都直觀。如果工具報錯是 401說明權限配置有問題如果是參數校驗失敗說明 Agent 對參數理解有誤。審查頁面應該讓這些信息第一眼可見而不是藏在日志里。5.3 回歸對比和門禁判斷回歸對比的核心是找出從好變壞的用例。工作臺可以把新舊兩次運行的數據按case_id對齊生成一張差異表case_id舊版結果新版結果舊版步驟數新版步驟數差異判斷order-001successsuccess34步驟增加可接受order-002successfailed2-回歸必須修復order-003failedsuccess-3修復項確認有效性這里的門禁可以簡單到一句話如果存在任何success - failed的用例且該用例標簽不在豁免列表中則本次評測不通過。這個規(guī)則應該寫進 CI 腳本防止新版 Agent 或者新提示詞在修復 A 場景時弄壞 B 場景。6. 運行驗證從命令行到本地 Web 工作臺6.1 啟動流程按以下順序操作可以跑通最小閉環(huán)# 1. 初始化項目并安裝依賴 npm install # 2. 初始化數據庫 npm run init-db # 3. 將模型 API 密鑰寫入本地環(huán)境變量 export MODEL_API_KEYyour_key_here # 4. 運行評測集 npm run eval -- --suite suites/order-basic.yaml # 5. 啟動本地審查服務 npm run review這里要特別提醒API 密鑰不要寫進評測集 YAML也不要提交到 git 倉庫。評測集是團隊共享的版本化文件密鑰應該通過環(huán)境變量或本地的.env.local注入并且這個文件必須加入.gitignore。6.2 預期結果和驗證方式第一次運行結束后你應該能看到類似下面的輸出suite: order-basic cases: 2 passed: 1 failed: 1 success rate: 50.0% tool success rate: 100.0% avg latency: 820ms total tokens: 1840 report: reports/report.html但這只是第一步。要確認評測真的有效至少還需要驗證三件事失敗的用例點擊軌跡后能看到具體的失敗步驟而不是只看到一個 failed 狀態(tài)。把同一個用例故意改成錯誤預期運行結果應該從成功變失敗證明預期判斷邏輯有效。連續(xù)運行三次同一評測集觀察成功率波動范圍。如果波動超過 20 個百分點說明用例設計或評測環(huán)境本身不穩(wěn)定需要先解決穩(wěn)定性問題。6.3 學習環(huán)境和生產環(huán)境的區(qū)別上面這套流程適合在本地快速驗證想法。進入團隊協(xié)作或生產環(huán)境后需要額外補上幾塊項目學習環(huán)境生產環(huán)境存儲本地 SQLite 文件SQLite 文件加入版本管理或備份機制評測集手工編輯 YAML評測集變更走 MR 流程記錄版本運行結果本地命令行在 CI 中運行結果上傳為構建產物模型配置環(huán)境變量手動指定固定模型版本、采樣參數寫入配置快照人工審查本地 HTML 報告審查結果可注釋、可標記、可追蹤數據備份不必須定期備份數據庫設置保留策略生產環(huán)境最關鍵的差異化動作是可追溯。一次發(fā)布對應的評測結果必須能關聯(lián)到具體的代碼版本、評測集版本、模型版本和運行時間。缺失任何一個出現(xiàn)線上問題時都無法回查。7. 常見問題與排查鏈路7.1 評測任務大面積失敗現(xiàn)象同一個評測集大部分用例都返回 failed。排查順序先看錯誤信息。如果所有失敗都報 401、403通常是 API Key 無效或沒有對應模型權限。再看超時配置。如果失敗集中在某個工具調用步驟且每條軌跡都在同一工具處中斷優(yōu)先懷疑工具本身報錯或網絡不通。然后看預期判斷方式。如果失敗用例的軌跡正常完成但被判定失敗檢查expected.type是否和實際輸出匹配。例如模型回復您的訂單已發(fā)出而預期寫死了已發(fā)貨就會誤判。最后檢查評測集本身。如果用例輸入格式和 Agent 訓練數據差異過大失敗是正常的需要調整用例設計。對應處理建議問題現(xiàn)象常見原因檢查方式處理建議全部用例 401API Key 無效或無權限查看運行器日志的第一個錯誤重新配置環(huán)境變量并確認模型白名單全部用例超時模型或工具響應過慢查看軌跡中耗時最長的步驟增加單步超時時間或排查工具性能完成但判失敗expected 寫得太死打印實際輸出對比預期配置改用 contains 或人工審查判斷結果時好時壞采樣參數或環(huán)境不穩(wěn)定連續(xù)運行 5 次統(tǒng)計分布固定溫度記錄模型版本擴大樣本量7.2 軌跡丟失或結果對不上現(xiàn)象metrics 表里有運行記錄但 steps 表為空或者審查頁面顯示的成功數和 CLI 輸出不一致。排查鏈路檢查寫入順序。如果insertMetric不在insertRun和insertStep的同一個事務里先寫指標后寫步驟就容易出現(xiàn)只有指標沒有軌跡的半截數據。檢查異常處理。運行器 catch 到異常后是否仍然執(zhí)行了持久化邏輯。如果異常發(fā)生在步驟還沒有回調時直接跳到失敗分支軌跡為空是正常的但如果你期望保留異常發(fā)生前已經記錄的部分步驟需要在 catch 里顯式維護steps數組。檢查統(tǒng)計口徑。CLI 輸出的 success rate 是基于 runs 表統(tǒng)計還是基于 metrics 表統(tǒng)計。兩個來源結果不一致時說明代碼中有第二個統(tǒng)計入口應統(tǒng)一成一個函數。7.3 指標偏高或偏低的可信度問題現(xiàn)象本地跑成功率 90%但線上表現(xiàn)明顯更差。原因通常不在評測代碼而在評測設計評測集和調優(yōu)數據重疊。如果評測用例來自 Agent 調優(yōu)時見過的數據結果虛高屬于數據泄漏。樣本量太小。10 個用例只跑一次成功率 90% 意味著只有一個 fail置信度非常低。評測集難度失衡。大量簡單用例撐高整體成功率掩蓋了困難場景的問題。處理方式是分層看指標按 tag 統(tǒng)計成功率單獨篩出edge-case類用例的結果而不是只看總體成功率。同時在報告中展示每個用例的單次結果不合并成一個數字。7.4 本地環(huán)境與 CI 結果不一致現(xiàn)象本地運行全部通過CI 里同一評測集大量失敗。這是 Agent 評測最常見的環(huán)境問題之一。排查順序對比模型版本。CI 里是否用了不同的 model 名稱或 default 版本導致推理行為不一致。對比環(huán)境變量。CI 里是否缺少MODEL_API_KEY或使用了不同 key 導致速率限制。對比網絡和依賴。CI 是否能訪問模型 APIpackage-lock.json是否提交依賴版本是否已鎖定。對比并發(fā)設置。本地順序執(zhí)行和 CI 并發(fā)執(zhí)行可能觸發(fā)速率限制或超時失敗位置通常分布在tool_call步驟。預防做法是在評測配置中記錄環(huán)境指紋模型版本、溫度、top_p、依賴版本、Node 版本、關鍵環(huán)境變量的 hash。評測報告第一頁就展示這些信息本地和 CI 不一致時先比對指紋。8. 評測工作臺的最佳實踐和擴展方向8.1 設計評測集的檢查清單一個評測集在合并進工程之前應該逐條確認每個用例是否描述了一個完整用戶場景而不是一個孤立的模型指令。預期結果是否站在用戶可接受信息的角度描述而不是模型逐字輸出。是否覆蓋 happy path、edge case、異常輸入、權限不足、工具失敗五類基礎場景。用例輸入中是否包含真實業(yè)務敏感數據如果是是否做了脫敏。每個用例是否有明確的維護人需求變更時由誰更新評測集。評測集是否在獨立目錄下版本化管理和代碼變更同步提交。8.2 發(fā)布前評測檢查清單Agent 版本發(fā)布前建議依次確認評測集版本已固定和本次發(fā)布意圖匹配。在固定模型版本和采樣參數下完成至少三輪完整評測。新舊版本回歸對比中不存在非豁免的success - failed用例。失敗的用例都有軌跡可供人工審查且每一條失敗原因已經被歸類。指標統(tǒng)計同時包含結果指標和過程指標避免只匯報成功率。評測數據已備份報告已歸檔對應代碼 commit 可追溯。8.3 擴展方向從最小工作臺繼續(xù)往下走有三個值得投入的方向。第一個是引入更豐富的判斷方式。除了字符串匹配可以增加 LLM-as-judge讓一個獨立模型按評分標準判斷結果質量并將評判斷模型的結果也作為一條軌跡保存方便進一步審查。第二個是支持評測集和數據集的版本化。用 Git 管理 YAML 評測集是第一步第二步是給每個用例增加expected的變更歷史讓為什么這個用例被改弱了有據可查。第三個是把評測工作臺接入日常開發(fā)流。本地運行只是調試手段真正能防止 Agent 退化的機制是 CI 門禁每次提示詞變更或 Agent 邏輯變更都自動觸發(fā)一輪回歸評測把差別結果直接貼到 MR 里。做到這一步評測工作臺就不再是一個輔助工具而是 Agent 工程化質量體系的一部分。Agent 評測的本質是給看起來智能的系統(tǒng)建立可驗證的行為邊界。Agent Review Studio 這類 local-first 工作臺提供了一個正確的方向讓評測數據留在本地讓軌跡成為證據讓差異可以被看見。先把最小閉環(huán)跑起來再用指標、軌跡和回歸對比慢慢逼近真實業(yè)務的質量要求這才是評測體系能長期運轉的方式。 Agent評測工作臺：從軌跡回放到回歸對比的落地實踐
Agent 評測是 Agent 工程化落地中最容易被低估的一環(huán)。很多團隊能快速搭出一個能跑的 Agent卻很難回答三個基礎問題新版提示詞真的比舊版好嗎同一個任務連續(xù)運行二十次成功率是多少失敗的回合到底是模型理解錯了、工具調用錯了還是任務定義本身有歧義。Agent Review Studio 這類 local-first agent evaluation workbench解決的就是這件事把評測集組織、運行軌跡記錄、指標計算和結果審查整合到一個本地工作臺中讓 Agent 的行為變化可復現(xiàn)、可對比、可人工核查。這篇文章不假定你已經擁有完整的評測平臺也不綁定某個具體 Agent 框架。我會從評測工作臺解決的底層問題開始再給出一個可以在本地跑通的最小實現(xiàn)內容包括評測集定義、運行器、軌跡存儲、指標計算和結果審查。讀完以后你可以把同一套思路遷移到自己的 Agent 項目里底層不管是自研模型調用、LangChain 這類編排框架還是企業(yè)內部封裝好的 SDK都只影響適配層不影響工作臺的整體設計。1. Agent 評測為什么不能只靠普通測試腳本1.1 Agent 行為和普通函數測試有本質差別傳統(tǒng)單元測試有一個隱含前提相同的輸入會產生穩(wěn)定輸出。對一個純函數來說入參確定、執(zhí)行環(huán)境確定返回值就可以被精確斷言。Agent 不具備這個特性。Agent 的輸入是自然語言任務執(zhí)行過程是模型推理、工具調用、結果觀察的循環(huán)最后的輸出既受模型版本和溫度參數影響也受上下文長度、工具返回內容、網絡延遲甚至并發(fā)順序影響。同樣是幫我查一下本月訂單金額并生成匯總模型第一次可能直接調用查詢工具第二次可能先問用戶要具體日期范圍第三次可能選擇了錯誤的時間字段。三個回合的最終結果可能完全不同但每個回合內部都有完整推理鏈路。只用斷言結果正確與否的測試腳本無法回答為什么會失敗失敗在哪一步是不是工具返回格式變了這類問題。所以 Agent 評測的核心對象不是單個輸出值而是執(zhí)行過程本身。評測工作臺必須能記錄每一輪推理、每一次工具調用、每一個中間觀察結果把黑盒輸出變成可審查的白盒軌跡。軌跡回放能力是評測工作臺和普通測試腳本最本質的區(qū)別。1.2 local-first 解決的是數據主權和可復現(xiàn)問題local-first 這個詞在 Agent 評測場景下有兩層含義。第一層是數據不出本機。Agent 運行軌跡里通常包含用戶問題、業(yè)務字段、工具返回的原始數據這些內容很可能涉及敏感信息。如果評測平臺是云端 SaaS軌跡上傳意味著業(yè)務數據離開本地網絡很多團隊在合規(guī)上無法接受。本地優(yōu)先的工作臺把 SQLite 文件、軌跡目錄和評測報告都放在本機評測數據的所有權和使用權都留在團隊自己手里。第二層是環(huán)境可控。云端評測平臺往往黑盒管理模型版本、參數和依賴版本出現(xiàn)問題后很難回溯。本地工作臺可以把模型版本、提示詞版本、工具定義版本、依賴鎖文件一起記錄成一次評測快照。出問題時按快照重建環(huán)境就能復現(xiàn)不需要猜測線上環(huán)境發(fā)生了什么變化。需要說明的是local-first 不等于完全離線。評測運行器仍然需要調用模型 API只是評測框架本身、存儲、審查界面都在本地運行。文章后面說的架構也是這種形態(tài)框架本地化模型遠端調用。1.3 評測工作臺的五個能力層次從功能角度看一個可用的 Agent 評測工作臺至少包含五層能力評測集管理組織和版本化用例集合支持分類、標簽、預期結果描述。運行器批量執(zhí)行評測任務統(tǒng)一注入環(huán)境變量、模型參數和工具配置。軌跡存儲把一次運行的所有步驟按時間順序落盤形成可回放證據。指標計算在軌跡基礎上計算成功率、工具調用有效率、延遲、Token 消耗等。審查與對比把多次運行結果放在一起比較定位差異和回歸。這五層缺了任何一層評測都會退回成跑一遍看日志。下面各部分會按這個層次順序展開實現(xiàn)。2. 先理解評測工作臺的核心概念2.1 評測集Suite和用例Case評測集是若干評測用例的集合。一個用例代表一個要驗證的任務場景包含任務輸入、任務描述、預期行為、標簽和可選的環(huán)境配置。id: case-001 name: 查詢訂單狀態(tài)并回復用戶 description: 用戶想知道訂單 20240315001 當前處于什么狀態(tài) input: message: 我的訂單 20240315001 現(xiàn)在到哪一步了 expected: type: contains values: - 已發(fā)貨 - 運輸中 - 已完成 tags: - order - retrieval difficulty: easy這里的expected不是硬編碼最終答案而是描述什么結果可以接受。常見判斷方式有四類判斷方式適用場景說明exact match結構化輸出、JSON 字段輸出必須精確相等適合工具返回校驗contains / regex自然語言回復判斷關鍵信息是否出現(xiàn)JSON Schema 校驗工具參數、結構化結果校驗字段類型和必填項不關心具體值LLM-as-judge / 人工審查開放性任務由模型或人判斷結果質量需要額外控制偏差在最小實現(xiàn)里可以先支持前三種把 fourth 種留到后面擴展。2.2 軌跡Trace是評測的第一手證據軌跡是一次評測運行從開始到結束的完整事件序列。一個最小軌跡應該包含以下字段{ runId: run-20250315-001, caseId: case-001, startedAt: 2025-03-15T10:00:00.000Z, finishedAt: 2025-03-15T10:02:31.000Z, status: completed, steps: [ { seq: 1, type: model, input: 我的訂單 20240315001 現(xiàn)在到哪一步了, output: 我需要查詢訂單狀態(tài)先調用訂單查詢工具。, model: gpt-4o-mini, temperature: 0, tokensIn: 120, tokensOut: 45, durationMs: 800 }, { seq: 2, type: tool_call, name: query_order, arguments: {\orderId\: \20240315001\}, result: {\status\: \shipped\, \updated\: \2025-03-15T08:30:00Z\}, durationMs: 210 } ] }軌跡的價值在于事后審查。當最終結果失敗時審查者需要知道模型在哪一步產生了錯誤判斷工具返回了什么引起誤解后續(xù)步驟是否基于錯誤信息繼續(xù)執(zhí)行。沒有軌跡指標就是沒有根據的數字有了軌跡指標才能被追責和復盤。2.3 指標分為結果指標和過程指標指標不能只看最終成功率。一個 Agent 可能最后輸出了正確答案但中間調用了八次工具、繞了很多彎路也可能最終失敗但失敗原因是外部 API 超時而非 Agent 邏輯錯誤。所以要把指標分成兩類指標類別指標名稱計算方法說明結果指標Success Rate成功用例數 / 總用例數最直觀的總體質量指標結果指標Task Score按完成度打分 0-100適合部分完成也算分的情況過程指標Tool Success Rate工具成功調用數 / 總調用數反映工具使用能力過程指標Avg Steps總步驟數 / 運行次數步驟多不一定差但可以反映繞路過程指標Avg Latency總耗時 / 運行次數和成本一起決定可用性過程指標Token Usage總 Token 數或單次平均直接對應 API 成本過程指標Abort Rate超時或異常終止數 / 總運行數反映穩(wěn)定性真實項目里結果指標決定功能是否達標過程指標決定 Agent 是否值得上線。一個步驟少、延遲低、成本可控的 Agent即使成功率略低也往往更容易被用戶接受。2.4 回歸對比把單次運行變成趨勢Agent 評測最大的陷阱是拿一次運行結果下結論。同樣的提示詞溫度為零時也可能因為非確定性采樣產生不同輸出工具服務波動也會影響結果。正確做法是對同一套評測集反復運行多次把結果當成分布來看?；貧w對比指兩件事一是同一個 Agent 版本在多次運行之間的穩(wěn)定性對比二是新舊版本在相同評測集上的效果差異。工作臺應該把兩次運行的用例結果對齊逐條顯示這個用例舊版成功、新版失敗或新舊都成功但新版多用了兩步。這種差異視圖是決定是否發(fā)布新版本的主要依據。3. 環(huán)境準備搭建一個本地可跑通的腳手架3.1 技術棧選擇與版本要求下面示例用于說明思路實際項目可以按團隊熟悉程度替換。核心原則是運行器用你熟悉的后端語言存儲用本地文件或 SQLite審查界面用最簡單的方式呈現(xiàn)。推薦一個低成本的組合組件推薦選擇備選方案選擇理由運行器Node.js TypeScriptPython FastAPI類型約束對軌跡數據結構很有幫助存儲SQLitebetter-sqlite3JSON Lines 文件單文件、零運維、適合本地評測集定義YAMLJSON可讀性好適合寫注釋審查界面本地 Express 服務 靜態(tài) HTMLReact/Vue最小實現(xiàn)避免構建復雜度命令行入口Commander直接 npm script方便在本地和 CI 復用環(huán)境要求很簡單Node.js 18 以上npm 或 pnpm一臺能訪問模型 API 的開發(fā)機。不需要部署數據庫不需要申請額外的評測平臺賬號。注意如果你要接不同模型 API請先確認項目使用模型的版本、baseURL 和鑒權方式。模型版本不固定評測結果的可復現(xiàn)性會大打折扣。3.2 目錄結構設計一個最小項目可以按功能拆分目錄agent-review-studio/ ├── package.json ├── tsconfig.json ├── data/ │ └── eval.db # SQLite 數據庫本地自動生成 ├── suites/ │ ├── order-basic.yaml # 評測集定義 │ └── order-edge.yaml ├── src/ │ ├── cli.ts # 命令行入口 │ ├── types.ts # 軌跡、用例、指標類型 │ ├── runner.ts # 評測運行器 │ ├── store.ts # SQLite 持久化 │ ├── metrics.ts # 指標計算 │ ├── adapter.ts # Agent 適配層隔離不同框架 │ └── server.ts # 本地審查服務 └── reports/ # 生成的報告目錄這里的adapter.ts是關鍵。評測工作臺不應該關心 Agent 內部是 LangChain 還是自研實現(xiàn)它只要求適配層暴露一個統(tǒng)一方法接收消息和歷史上下文返回本輪輸出、工具調用列表和 token 消耗。評測集、指標、存儲全部建立在統(tǒng)一接口之上替換底層框架只需要重寫適配層。3.3 SQLite 表結構設計評測數據核心是四張表用例、運行、步驟、指標。CREATE TABLE cases ( id TEXT PRIMARY KEY, suite TEXT NOT NULL, name TEXT NOT NULL, input TEXT NOT NULL, expected TEXT NOT NULL, tags TEXT DEFAULT [], created_at TEXT DEFAULT (datetime(now)) ); CREATE TABLE runs ( id TEXT PRIMARY KEY, case_id TEXT NOT NULL, status TEXT NOT NULL, -- running / completed / failed / aborted model TEXT, prompt_version TEXT, started_at TEXT, finished_at TEXT, error TEXT ); CREATE TABLE steps ( id INTEGER PRIMARY KEY AUTOINCREMENT, run_id TEXT NOT NULL, seq INTEGER NOT NULL, type TEXT NOT NULL, -- model / tool_call / tool_result / error name TEXT, input TEXT, output TEXT, duration_ms INTEGER, tokens_in INTEGER, tokens_out INTEGER, created_at TEXT DEFAULT (datetime(now)) ); CREATE TABLE metrics ( run_id TEXT PRIMARY KEY, success INTEGER, task_score REAL, tool_success_rate REAL, avg_latency_ms REAL, total_tokens INTEGER, steps INTEGER );表結構的設計要點是把運行的原始軌跡和計算出的指標分開存儲。軌跡是證據指標是結論。證據不能因為之后改了算法而丟失所以任何指標計算都應該是從軌跡重新推導而不是在軌跡上原地修改。這樣后面優(yōu)化指標算法時歷史運行記錄還能重新計算不需要重跑評測。4. 實現(xiàn)一個最小評測閉環(huán)4.1 定義評測任務和預期結果在suites/order-basic.yaml中定義兩個用例一個驗證正常查詢一個驗證無效訂單處理suite: order-basic description: 訂單查詢基礎能力評測 cases: - id: order-001 name: 查詢已發(fā)貨訂單 input: message: 我的訂單 20240315001 現(xiàn)在到哪一步了 expected: type: contains values: [已發(fā)貨, 運輸中, 已完成] tags: [order, happy-path] - id: order-002 name: 查詢不存在的訂單 input: message: 查一下訂單 999999 的物流狀態(tài) expected: type: contains values: [不存在, 沒有找到, 無效] tags: [order, edge-case]這里隱藏了一個 Agent 評測的常見誤區(qū)預期結果描述的是用戶可接受的信息而不是模型逐字輸出。如果寫死values: [已發(fā)貨]當模型回復您的訂單已經發(fā)出正在運輸途中時正確信息因為措辭不同被判失敗。評測集要站在用戶價值角度設計而不是站在字符串匹配角度設計。4.2 實現(xiàn)評測運行器運行器負責讀取評測集、逐條調用 Agent 適配層、收集軌跡。下面是一個最小實現(xiàn)// src/runner.ts import { readFile } from fs/promises; import yaml from yaml; import { RunResult, Step, Suite } from ./types; import { runAgent, AgentAdapterOptions } from ./adapter; export async function runSuite(filePath: string, adapter: AgentAdapterOptions) { const raw await readFile(filePath, utf-8); const suite yaml.parse(raw) as Suite; const results: RunResult[] []; for (const testCase of suite.cases) { const steps: Step[] []; const startedAt new Date().toISOString(); let status: RunResult[status] completed; let error: string | undefined; try { // 調用適配層執(zhí)行 Agent接收逐步回調以記錄軌跡 await runAgent( { message: testCase.input.message, suite: suite.suite, caseId: testCase.id, }, adapter, (step) steps.push(step) ); } catch (e) { status failed; error e instanceof Error ? e.message : String(e); } results.push({ runId: ${testCase.id}-${Date.now()}, caseId: testCase.id, status, startedAt, finishedAt: new Date().toISOString(), steps, error, }); } return results; }這段代碼的關鍵在于runAgent的第三步回調。很多初版評測框架只會收集最終輸出丟掉了中間步驟。正確的做法是讓適配層在每個事件發(fā)生時就上報一次運行器只負責按順序追加。這樣軌跡的完整性由運行器保證不屬于自定義 Agent 邏輯的一部分。4.3 保存軌跡和計算結果運行完成后需要把軌跡寫入 SQLite并計算指標。寫入順序很重要先寫運行主記錄再寫步驟再寫指標。任何一步失敗都應該讓整次運行標記為 failed避免出現(xiàn)有指標沒軌跡的殘缺數據。import Database from better-sqlite3; export function persistRun(db: Database, result: RunResult) { const insertRun db.prepare( INSERT INTO runs (id, case_id, status, error, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?) ); const insertStep db.prepare( INSERT INTO steps (run_id, seq, type, name, input, output, duration_ms, tokens_in, tokens_out) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ); const insertMetric db.prepare( INSERT INTO metrics (run_id, success, task_score, tool_success_rate, avg_latency_ms, total_tokens, steps) VALUES (?, ?, ?, ?, ?, ?, ?) ); const tx db.transaction(() { insertRun.run( result.runId, result.caseId, result.status, result.error ?? null, result.startedAt, result.finishedAt ); for (const step of result.steps) { insertStep.run( result.runId, step.seq, step.type, step.name ?? null, step.input ?? null, step.output ?? null, step.durationMs ?? null, step.tokensIn ?? null, step.tokensOut ?? null ); } const metrics computeMetrics(result); insertMetric.run( result.runId, metrics.success ? 1 : 0, metrics.taskScore, metrics.toolSuccessRate, metrics.avgLatencyMs, metrics.totalTokens, metrics.steps ); }); tx(); }使用db.transaction的目的是保證一批數據要么全部寫入要么全部不寫入。否則一旦運行到第三步失敗數據庫里就會留存一條沒有步驟記錄的 runs 數據后續(xù)統(tǒng)計時會污染成功率。4.4 生成審查報告本地工作臺的最小審查形態(tài)可以是一份靜態(tài) HTML 報告或者一個本地 Web 服務。最簡單方式是讓 CLI 在執(zhí)行完評測后輸出一個reports/report.html里面按用例列出每次運行的成功狀態(tài)和軌跡摘要。!-- 生成報告的簡化模板實際由代碼動態(tài)渲染 -- ul li strongorder-001/strongcompleted details summary查看軌跡/summary p第 1 步模型調用輸入用戶消息輸出我需要查詢訂單。/p p第 2 步工具調用 query_order參數 {orderId:20240315001}。/p p第 3 步工具返回 {status:shipped}。/p /details /li /ul報告不是給機器看的是給人審查的。所以每一條用例都要有展開軌跡的入口并且標記該用例使用的預期判斷方式。這個階段的報告可以很粗糙但它必須讓審查者能回答為什么判定成功或為什么判定失敗。5. 關鍵模塊設計指標計算、軌跡審查和回歸對比5.1 指標計算模塊指標計算不應該散落在插入數據的邏輯里而應該獨立成一個純函數模塊。這樣歷史軌跡可以重新計算指標不同指標算法可以并行比較。// src/metrics.ts import { RunResult, Metrics } from ./types; export function computeMetrics(result: RunResult): Metrics { const steps result.steps; const toolCalls steps.filter((s) s.type tool_call); const toolSuccess toolCalls.filter((s) s.output !s.output.startsWith(ERROR)); let totalTokens 0; let totalLatency 0; for (const step of steps) { totalTokens (step.tokensIn ?? 0) (step.tokensOut ?? 0); totalLatency step.durationMs ?? 0; } return { success: result.status completed, taskScore: result.status completed ? 100 : 0, toolSuccessRate: toolCalls.length ? toolSuccess.length / toolCalls.length : 1, avgLatencyMs: steps.length ? totalLatency / steps.length : 0, totalTokens, steps: steps.length, }; }現(xiàn)在computeMetrics里的 success 只判斷狀態(tài)沒有做預期結果的匹配。真實實現(xiàn)里應該在運行器判斷完 expected 之后把匹配結果傳進來。這一步留給你的實際項目擴展關鍵是保持軌跡數據不隨指標變化的原則。5.2 軌跡審查頁面軌跡審查頁面至少有三種視圖列表視圖按套件和用例列出所有運行記錄綠綠紅紅一眼看出失敗集中在哪個用例。時間線視圖單個運行記錄的步驟按時間展開模型推理、工具調用、工具結果依次排列任何一步耗時異常都容易發(fā)現(xiàn)。對比視圖同一用例的新舊兩次運行并排展示高亮模型推理差異、工具參數差異和結果差異。時間線視圖最容易暴露問題。例如一個 Agent 在工具調用失敗后反復重試時間線會連續(xù)出現(xiàn)五次相同的tool_call這比任何指標都直觀。如果工具報錯是 401說明權限配置有問題如果是參數校驗失敗說明 Agent 對參數理解有誤。審查頁面應該讓這些信息第一眼可見而不是藏在日志里。5.3 回歸對比和門禁判斷回歸對比的核心是找出從好變壞的用例。工作臺可以把新舊兩次運行的數據按case_id對齊生成一張差異表case_id舊版結果新版結果舊版步驟數新版步驟數差異判斷order-001successsuccess34步驟增加可接受order-002successfailed2-回歸必須修復order-003failedsuccess-3修復項確認有效性這里的門禁可以簡單到一句話如果存在任何success - failed的用例且該用例標簽不在豁免列表中則本次評測不通過。這個規(guī)則應該寫進 CI 腳本防止新版 Agent 或者新提示詞在修復 A 場景時弄壞 B 場景。6. 運行驗證從命令行到本地 Web 工作臺6.1 啟動流程按以下順序操作可以跑通最小閉環(huán)# 1. 初始化項目并安裝依賴 npm install # 2. 初始化數據庫 npm run init-db # 3. 將模型 API 密鑰寫入本地環(huán)境變量 export MODEL_API_KEYyour_key_here # 4. 運行評測集 npm run eval -- --suite suites/order-basic.yaml # 5. 啟動本地審查服務 npm run review這里要特別提醒API 密鑰不要寫進評測集 YAML也不要提交到 git 倉庫。評測集是團隊共享的版本化文件密鑰應該通過環(huán)境變量或本地的.env.local注入并且這個文件必須加入.gitignore。6.2 預期結果和驗證方式第一次運行結束后你應該能看到類似下面的輸出suite: order-basic cases: 2 passed: 1 failed: 1 success rate: 50.0% tool success rate: 100.0% avg latency: 820ms total tokens: 1840 report: reports/report.html但這只是第一步。要確認評測真的有效至少還需要驗證三件事失敗的用例點擊軌跡后能看到具體的失敗步驟而不是只看到一個 failed 狀態(tài)。把同一個用例故意改成錯誤預期運行結果應該從成功變失敗證明預期判斷邏輯有效。連續(xù)運行三次同一評測集觀察成功率波動范圍。如果波動超過 20 個百分點說明用例設計或評測環(huán)境本身不穩(wěn)定需要先解決穩(wěn)定性問題。6.3 學習環(huán)境和生產環(huán)境的區(qū)別上面這套流程適合在本地快速驗證想法。進入團隊協(xié)作或生產環(huán)境后需要額外補上幾塊項目學習環(huán)境生產環(huán)境存儲本地 SQLite 文件SQLite 文件加入版本管理或備份機制評測集手工編輯 YAML評測集變更走 MR 流程記錄版本運行結果本地命令行在 CI 中運行結果上傳為構建產物模型配置環(huán)境變量手動指定固定模型版本、采樣參數寫入配置快照人工審查本地 HTML 報告審查結果可注釋、可標記、可追蹤數據備份不必須定期備份數據庫設置保留策略生產環(huán)境最關鍵的差異化動作是可追溯。一次發(fā)布對應的評測結果必須能關聯(lián)到具體的代碼版本、評測集版本、模型版本和運行時間。缺失任何一個出現(xiàn)線上問題時都無法回查。7. 常見問題與排查鏈路7.1 評測任務大面積失敗現(xiàn)象同一個評測集大部分用例都返回 failed。排查順序先看錯誤信息。如果所有失敗都報 401、403通常是 API Key 無效或沒有對應模型權限。再看超時配置。如果失敗集中在某個工具調用步驟且每條軌跡都在同一工具處中斷優(yōu)先懷疑工具本身報錯或網絡不通。然后看預期判斷方式。如果失敗用例的軌跡正常完成但被判定失敗檢查expected.type是否和實際輸出匹配。例如模型回復您的訂單已發(fā)出而預期寫死了已發(fā)貨就會誤判。最后檢查評測集本身。如果用例輸入格式和 Agent 訓練數據差異過大失敗是正常的需要調整用例設計。對應處理建議問題現(xiàn)象常見原因檢查方式處理建議全部用例 401API Key 無效或無權限查看運行器日志的第一個錯誤重新配置環(huán)境變量并確認模型白名單全部用例超時模型或工具響應過慢查看軌跡中耗時最長的步驟增加單步超時時間或排查工具性能完成但判失敗expected 寫得太死打印實際輸出對比預期配置改用 contains 或人工審查判斷結果時好時壞采樣參數或環(huán)境不穩(wěn)定連續(xù)運行 5 次統(tǒng)計分布固定溫度記錄模型版本擴大樣本量7.2 軌跡丟失或結果對不上現(xiàn)象metrics 表里有運行記錄但 steps 表為空或者審查頁面顯示的成功數和 CLI 輸出不一致。排查鏈路檢查寫入順序。如果insertMetric不在insertRun和insertStep的同一個事務里先寫指標后寫步驟就容易出現(xiàn)只有指標沒有軌跡的半截數據。檢查異常處理。運行器 catch 到異常后是否仍然執(zhí)行了持久化邏輯。如果異常發(fā)生在步驟還沒有回調時直接跳到失敗分支軌跡為空是正常的但如果你期望保留異常發(fā)生前已經記錄的部分步驟需要在 catch 里顯式維護steps數組。檢查統(tǒng)計口徑。CLI 輸出的 success rate 是基于 runs 表統(tǒng)計還是基于 metrics 表統(tǒng)計。兩個來源結果不一致時說明代碼中有第二個統(tǒng)計入口應統(tǒng)一成一個函數。7.3 指標偏高或偏低的可信度問題現(xiàn)象本地跑成功率 90%但線上表現(xiàn)明顯更差。原因通常不在評測代碼而在評測設計評測集和調優(yōu)數據重疊。如果評測用例來自 Agent 調優(yōu)時見過的數據結果虛高屬于數據泄漏。樣本量太小。10 個用例只跑一次成功率 90% 意味著只有一個 fail置信度非常低。評測集難度失衡。大量簡單用例撐高整體成功率掩蓋了困難場景的問題。處理方式是分層看指標按 tag 統(tǒng)計成功率單獨篩出edge-case類用例的結果而不是只看總體成功率。同時在報告中展示每個用例的單次結果不合并成一個數字。7.4 本地環(huán)境與 CI 結果不一致現(xiàn)象本地運行全部通過CI 里同一評測集大量失敗。這是 Agent 評測最常見的環(huán)境問題之一。排查順序對比模型版本。CI 里是否用了不同的 model 名稱或 default 版本導致推理行為不一致。對比環(huán)境變量。CI 里是否缺少MODEL_API_KEY或使用了不同 key 導致速率限制。對比網絡和依賴。CI 是否能訪問模型 APIpackage-lock.json是否提交依賴版本是否已鎖定。對比并發(fā)設置。本地順序執(zhí)行和 CI 并發(fā)執(zhí)行可能觸發(fā)速率限制或超時失敗位置通常分布在tool_call步驟。預防做法是在評測配置中記錄環(huán)境指紋模型版本、溫度、top_p、依賴版本、Node 版本、關鍵環(huán)境變量的 hash。評測報告第一頁就展示這些信息本地和 CI 不一致時先比對指紋。8. 評測工作臺的最佳實踐和擴展方向8.1 設計評測集的檢查清單一個評測集在合并進工程之前應該逐條確認每個用例是否描述了一個完整用戶場景而不是一個孤立的模型指令。預期結果是否站在用戶可接受信息的角度描述而不是模型逐字輸出。是否覆蓋 happy path、edge case、異常輸入、權限不足、工具失敗五類基礎場景。用例輸入中是否包含真實業(yè)務敏感數據如果是是否做了脫敏。每個用例是否有明確的維護人需求變更時由誰更新評測集。評測集是否在獨立目錄下版本化管理和代碼變更同步提交。8.2 發(fā)布前評測檢查清單Agent 版本發(fā)布前建議依次確認評測集版本已固定和本次發(fā)布意圖匹配。在固定模型版本和采樣參數下完成至少三輪完整評測。新舊版本回歸對比中不存在非豁免的success - failed用例。失敗的用例都有軌跡可供人工審查且每一條失敗原因已經被歸類。指標統(tǒng)計同時包含結果指標和過程指標避免只匯報成功率。評測數據已備份報告已歸檔對應代碼 commit 可追溯。8.3 擴展方向從最小工作臺繼續(xù)往下走有三個值得投入的方向。第一個是引入更豐富的判斷方式。除了字符串匹配可以增加 LLM-as-judge讓一個獨立模型按評分標準判斷結果質量并將評判斷模型的結果也作為一條軌跡保存方便進一步審查。第二個是支持評測集和數據集的版本化。用 Git 管理 YAML 評測集是第一步第二步是給每個用例增加expected的變更歷史讓為什么這個用例被改弱了有據可查。第三個是把評測工作臺接入日常開發(fā)流。本地運行只是調試手段真正能防止 Agent 退化的機制是 CI 門禁每次提示詞變更或 Agent 邏輯變更都自動觸發(fā)一輪回歸評測把差別結果直接貼到 MR 里。做到這一步評測工作臺就不再是一個輔助工具而是 Agent 工程化質量體系的一部分。Agent 評測的本質是給看起來智能的系統(tǒng)建立可驗證的行為邊界。Agent Review Studio 這類 local-first 工作臺提供了一個正確的方向讓評測數據留在本地讓軌跡成為證據讓差異可以被看見。先把最小閉環(huán)跑起來再用指標、軌跡和回歸對比慢慢逼近真實業(yè)務的質量要求這才是評測體系能長期運轉的方式。