傳統測試假設被打破的四個瞬間：輸出非唯一、過程隱蔽、隨機性、真實副作用——再加一條悄悄的「版本漂移」。
== 比對。如果你是決策者——
下一步——
所有 Agent 都適用的公共底座，回答「這個智能體本身可靠嗎」。七類角度從結果到過程、從依據到記憶、從邊界到穩定性，構成遞進鏈條。
通用七類是公共底座，每類業務 Agent 還有自己的特殊角度。用法是查閱式而非背誦式——拿到具體 Agent，先查表挑選，再疊加通用七類。
檢索相關性、引用準確性、幻覺率。Context Precision / Recall / Faithfulness。
OCR、切塊、欄位抽取是否正確——表單、契約、發票類 Agent 的標配。
SQL 是否正確、結論是否由資料支撐——Text-to-SQL Agent 的標配。
測試是否通過、有無引入 bug。SWE-bench 類場景。
是否越權存取檔案、網路、系統資源——隔離與權限邊界。
節點順序、條件分支是否正確觸發。
長任務進度、上下文是否正確演進、是否掉線。
真實副作用是否落盤正確——記帳、發票、訂單類的關鍵風險點。
角色分工是否清晰、交接是否順暢、無訊息遺漏。
即時觸發、回應節奏、節流降級是否合理。
是否在危險動作前主動確認——HITL 觸發率。
入庫去重、切塊品質、版本控制——RAG 上游的隱形瓶頸。
結構、引用、結論可讀性——交付物級的最終檢核。
LangSmith 是 LangChain 團隊的 Agent 可觀測與評估平台。四塊對應「看一次跑 → 看一批跑 → 比版本 → 校準裁判」的遞進鏈路，串起第一章所有評估角度。
記錄單次運行的完整軌跡。
承接過程軌跡評估的資料來源。
用題庫批量打分出成績單。
任務結果、工具動作、依據等量化。
把多個版本的成績單並排比。
回歸穩定性評估的核心工具。
人工逐條打分校準機器裁判。
為 LLM-as-judge 做金標準校準。
把 Agent 每次運行的調用鏈路、模型思考、工具動作自動記錄下來，像監控錄影一樣可回放；同時把一批測試用例掛上打分規則批量跑，得到多維成績單。
P6 搭最小 Agent → P7 接上 LangSmith → P8 看軌跡 → P9 建題庫、跑評估、比版本、人工校準——本章閉環的最終結果。
接入 LangSmith 之前，先徒手搭一個跟平台完全無關的最小 Agent，才能清楚看見「接入」到底改了什麼。本節無任何 LangSmith 程式碼——作為對照基準。
CompiledStateGraph，溫度鎖 0 是可複現前提。temperature=0 固定，保證同一條用例兩次跑出同一條軌跡——可複現的前提。.invoke() 的 Agent。大數相乘模型自己心算幾乎必錯，必須老實調用工具才能算對——正好凸顯 Agent 調用工具的價值。
只需三件事——生成 API Key、補上四個環境變數、加一行 @traceable 裝飾器。業務邏輯幾乎一行未改，這就是「零侵入式可觀測性」。
@traceable(name="call_math_agent")TRACING=true 後，所有 OpenAI / 工具調用由 SDK 自動寫入 trace 樹——業務代碼零改動。
把這次調用立成 trace 樹根節點，底下掛上模型推理與工具調用——一條完整的調用鏈。
系統代理會讓 SDK 上報卡住，把 LangSmith 服務地址加進 no_proxy 環境變數直連。
Tracing 把 Agent 每次運行的完整軌跡記錄下來。三種粒度、Run Tree 瀑布圖、每步耗時 token 參數——過程軌跡評估唯一的資料來源。
按會話線程把多輪對話歸在一起——適合追一整段連續對話。
按單次運行平鋪，每一行是一條獨立 trace——逐次排查某一回的執行。
最細顆粒度——Run Tree 的每一個節點。
Tracing 把鏈路寫入資料庫，但本身不打分；要把記錄變成分數，要靠下一塊 Datasets & Experiments。
沒有 Tracing 提供的完整鏈路，過程軌跡評估無從下手——這是 1.3 的基礎設施。
耗時 · token · 輸入輸出 · 工具收到的真實參數與返回結果——這正是工具與動作評估要核對的原始數據。
本章後半段把 Datasets & Experiments、Comparison、Annotation Queues 三塊全部動手跑過一遍。一份 Dataset 可以掛多個評估器——這是第三章記帳 Agent 的地基。
Dataset ＝ 題庫
Example ＝ 一道題
Experiment ＝ 成績單
evaluate(target, data, evaluators, prefix)
四要素一次講清
PROMPT_MODE 切換
一般版 vs. 優化版並排比
機器批量初筛
人工抽樣精校
target(inputs) -> dict{key, score, comment}exact_match，快穩零成本，適合唯一答案題把整套評估能力從計算器搬到真實業務——一個能用自然語言記帳、查帳、改帳、管預算的中文記帳 Agent。模型用 qwen3-coder-flash：基礎夠用但有明顯短板。
MoE 混合專家架構，總參數 30.5B，每次推理僅激活 3.3B（128 專家中選 8 個），原生 256K 上下文。
選型理由：基礎夠用但有明顯短板——多輪指代、主動查預算、如實復述工具結果時容易掉鏈，為第四章優化留足空間。
create_agent 裝配 · @traceable 標記業務入口 · 模型走環境變數——差異僅在工具從 1 個變 14 個、prompt 更複雜、評估要求更嚴格。
把能控制的變量都固定住，讓每次評估都在同樣條件下進行——這是整套評估工程能拿來做回歸對比的地基。三件套各自擋住一種破壞可複現性的環境因素。
EVAL_NOW = "2026-06-04T12:00:00"
解決「上週三」這類相對日期漂移
db.reset_db(seed=True)
避免上一條用例污染帳本
max_concurrency = 1
避免並發寫入衝突
模型自身隨機性：無法消除——同一條用例這次調了工具、下次可能自己心算。
環境層面雜訊：必須摁住——時間漂移、帳本污染、並發衝突。
final_answer · tool_calls · db_after · accounts_after · budgets_after
後續所有評估器都讀這份結構——沒有第二個入口。
核心集 20 道題的 CSV 設計，讓一行用例可以同時被多個評估器讀取——直接落地第二章「一份 Dataset 掛多個 Evaluators」的核心哲學。四套題庫合計 80 道評估用例。
| 欄位 | 用途 | 對應評估角度 |
|---|---|---|
case_id | 用例唯一編號 | 索引 |
user_input | 給 Agent 的自然語言輸入 | 輸入源 |
expected_tool | 期望調用的工具（多個用 | 分隔） | 1.2 工具動作 |
expected_amount | 期望抽取的金額 | 參數抽取 |
expected_category | 期望分類 | 參數抽取 |
expected_date | 期望日期（已轉為固定錨點） | 參數抽取 |
expected_account | 期望帳戶 | 參數抽取 |
answer_contains | 查詢類期望包含的真實統計值 | 1.4 依據一致性 |
expect_alert | 是否應觸發超支提醒（0/1） | 業務規則 |
expect_clarify | 資訊不全是否應反問（0/1） | 業務禮儀 |
case_type | 用例類型標籤 | 分類索引 |
統一約定為 (inputs, outputs, reference_outputs) -> {key, score, comment}，score=None 代表不適用——LangSmith 自動跳過，不拉低分母。最終合併成一個 evaluate_all，只報適用指標、不刷屏。
工具與動作評估。從參考答案取期望工具（多個用 |），任一命中即對；查詢類、反問類用例直接 score=None 跳過。
依據與狀態一致性評估。不看 Agent 說了什麼，只看帳本真實狀態——「不信 Agent 的嘴，只信資料庫的真實狀態」。
過程軌跡評估。只看 Agent 有沒有走「先調日期工具再記帳」這條正確軌跡——好的結果可能矇對，好的過程才穩定可靠。
閉環不是「我覺得可以更好」，而是「指標 X 從 0.62 升到 0.91，其它指標沒有回歸」。每一次 prompt 改動都跑全 80 道題，沒有捷徑。
用預設 prompt 跑完 80 道題，產生 experiment_prefix="v0-baseline" 成績單——這是所有後續優化的對照組。
過濾掉 score=0 的用例，按失敗指標聚類——找出最常掉鏈的 1–3 個指標。
針對弱點指標的 prompt 段落做最小變更——一次只動一個變量，避免多變量混淆歸因。
用改進後的 prompt 重跑 80 道題，得到 v1-targeted-fix 成績單——只看一版結果就下結論是危險的。
在 LangSmith 上勾選 v0 與 v1 點 Compare——逐指標看升降、逐用例看翻盤或退化。
修好了 A 不能弄壞 B——沒有退步的指標（守門員）必須維持；任何指標顯著下降則判定此次變更不通過。
同一條用例、同一份題庫、同一個模型，僅 prompt 變動；以下三組指標展示「評估閉環真的能改變行為」。守門員指標必須維持——這是對比的底線。
| 指標 | 守門員？ | v0 baseline | v1 targeted-fix | Δ | 說明 |
|---|---|---|---|---|---|
| used_date_tool | — | 0.62 | 0.91 | +0.29 | 加入「先確認日期」顯式指令後，調日期工具率大幅上升 |
| clarify_when_under | — | 0.55 | 0.83 | +0.28 | 加入「資訊不全時必須反問」規範後，反問率上升 |
| alert_on_overspend | — | 0.48 | 0.86 | +0.38 | 「記帳後主動核對預算」指令化後，超支提醒率最大幅提升 |
| tool_selection | ✓ 守門員 | 0.94 | 0.93 | −0.01 | 維持——沒有為了抓新指標而弄壞既有正確率 |
| amount_correct | ✓ 守門員 | 0.96 | 0.96 | ±0.00 | 維持——金額抽取是底線，任何變更都不能影響 |
| no_redundant_call | ✓ 守門員 | 0.89 | 0.90 | +0.01 | 維持——重複調用率未因 prompt 變長而惡化 |
弱點指標大幅上升、守門員指標維持——這是一次通過的 prompt 變更。下一步：把這版 prompt 標記為 v1.0-candidate，跑 robustness 與 multi-turn 兩套題庫做交叉驗證。
把評估當成心跳——每一次 prompt 變動、每一次模型升級、每一次 prompt 模板更換，都必須經過完整評估閉環，才能算「交付」。
80 道題
全指標打分
失敗聚類
定位短板
最小變更
一次一變量
全題庫重跑
Comparison 並排
守住守門員
標記候選版
節奏太快 → 變更沒有充分驗證，容易回歸；節奏太慢 → 失去對問題的敏感度。每週一次完整評估，是工程效率與風險控制的平衡點。
事故發生時不走完整節奏——用 mini-suite（10–15 道核心用例）快速驗證假設，確認修復後再回到週節奏補跑完整題庫。
能跑評估是工具素養，把評估變成組織的決策依據是制度素養。三層能力缺一不可：工具層讓評估可執行、流程層讓評估可重複、文化層讓評估可依賴。
LangSmith / RAGAS / TruLens 接入、題庫治理、評估器庫、版本管理。沒有工具，再好的方法論也跑不起來。
PR 合併前必須跑過 mini-suite、模型升級前必須跑過完整題庫、事故修復必須有 baseline 對照——把評估寫進流程。
沒人會在沒有評估報告的 prompt 變更上簽字、決策會引用最新評估結果、評估報告變成可審計的組織資產。
① 一個工程師提的 PR，沒跑評估能不能合併？
② 一個 prompt 變更上線，沒有完整評估報告，決策層會不會放行？
③ 一個月後回頭看，這個月跑過幾輪評估、出了幾份對比報告？
三題答案皆「是」，組織的評估成熟度就算到位。
不是「哪個平台最厲害」，而是「哪個平台最貼合我們的評估閉環」。四個問題決定平台選擇——少一個，閉環就缺一角。
若 Agent 已進入生產 → 必須可觀測（Tracing）。
若仍在 demo 階段 → 可觀測可稍後補。
→ 結論：langchain 系統一票 LangSmith；非 langchain 系考慮 OpenTelemetry + 自建或 Arize。
≤ 100 題、季度更新 → LangSmith / RAGAS 都行。
> 1000 題、週更 → 需要支援 batch API、版本化、CI 整合。
→ 結論：大題庫強烈建議 LangSmith + 外部 Git 雙軌治理。
偶爾切換 → 自建 + 試算表夠用。
頻繁切換（每月一次以上）→ 需要 Comparison + 自動 baseline。
→ 結論：Comparison 是這門課反覆強調的核心能力，必須原生支援。
偶爾人工抽樣 → 試算表 / 表單夠用。
每週例行校準 → 需要 Annotation Queues + LLM-as-judge 對齊。
→ 結論：人工校準一旦例行化，平台就是標配。
從「憑感覺覺得它還行」到「用一份可複現的成績單證明它行」——這門課的全部內容，可以被收束在這一句話裡。
把 Agent 評估當成工程問題而非藝術——有題庫、有指標、有基線、有守門員、有節奏。這不是品味問題，是交付問題。
LangSmith 把「記錄、批量打分、版本對比、人工校準」四件事做成原生能力——選對平台比選強模型更能放大工程團隊的產出。
計算器 demo 是用來摸工具的，記帳 Agent 才是這門課真正想讓你做的事——把方法論沉到真實業務上，沉到你的業務上。
三個動詞開頭的行動——把這門課的結論變成下週可以開始做的事。
@traceable 開始——一周內完成最小可用可觀測。優先級最高，因為它是後續所有評估動作的基礎設施。
① 評估器庫擴充 從 13 個核心指標擴到 30+，覆蓋 RAG / 多輪 / 安全 / 工作流四大場景。
② CI/CD 整合 把 evaluate() 接到 GitHub Actions，PR 級別跑 mini-suite。
③ 組織級評估儀表板 跨團隊共享題庫與評估結果，把個人閉環升級成組織資產。