AI 評測
評測是一個可重複的測試，用以衡量 AI 系統是否完成其任務。本技能讓你以 aievals.co 指南所教導的方式工作：在測量任何東西之前先查看真實輸出，測量你實際發現的失敗，在信任任何 LLM 裁判之前先逐一比對人工標籤進行校準，並為每個數字加上區間估計。
指南位於 https://www.aievals.co。當你向使用者解釋某個選擇時，請引用其中的頁面。末尾列出的參考檔案包含了詳細資訊與來源。
基本規則
在每個評測任務中遵循以下規則，無論使用者要求什麼。
- 在撰寫指標之前先查看軌跡。 你無法指定一個你未曾觀察過的系統的失敗模式。如果使用者沒有軌跡，先取得一些：生產日誌，或是在 100 個真實輸入上運行系統。然後閱讀它們。
- 人員標註；你提出建議。 絕不要自行撰寫 Ground Truth 標籤並將其呈現為人工判斷。你可以草擬標記為
"provisional": true的標籤供人員確認。絕不要讓一個模型同時撰寫輸入及其黃金答案，除非程式碼可以計算答案（SQL 結果、測試、計算機）。 - 程式碼先於裁判。 任何字串比對、解析器、Schema 檢查、正則表達式或單元測試能決定的事情都是程式碼檢查。在建立任何評測之前，先用提示詞編輯修復你能修復的問題。將 LLM 裁判保留給仍然存在的主觀失敗。
- 每個失敗模式一個二元裁判。 PASS 或 FAIL 加上一句話的評論。沒有 1-5 分制。幾個品質維度就對應幾個二元裁判，報告為全通過率並附上每個檢查的細項。
- 在信任裁判之前先進行校準。 將其與人工標籤進行比較，並分別報告 PASS 召回率和 FAIL 召回率，每個都附上其樣本數 N。原始的一致性絕不是重點：一個總是說 PASS 的裁判在 5% 的輸出失敗時，其一致性可達 95%。
- 訓練、開發、測試。 Few-shot 範例僅來自訓練集。在開發集上迭代。測試集只讀一次，在最後。在更多編輯後再次讀取測試集，會使其變成第二個開發集。
- 鎖定裁判配置。 模型 ID、運算努力、評分規則文字、輸出 Schema 和 few-shot 順序都是量測工具的一部分。將它們與每個結果一起記錄，並在其中有任何變更時重新校準。不要假設確定性：在開發集上運行兩次並計算標籤翻轉次數。
- 每個數字都有樣本數 N 和區間。 對比率使用 Wilson 區間，永遠不要用常態近似。比較同一個輸入上的兩個版本時使用配對數據。
- 回歸測試集 100% 通過。 它包含重現的生產錯誤和政策邊界。一次失敗就會阻止發布，而一個不穩定的案例則是一個流程錯誤。
- 根據差異來設閘，而不是絕對比率。 使用 references/ci-and-release-gates.md 中的四個區間帶。
- 在運行器中限制花費。 裁判運行需要花錢。在程式碼中強制執行預算（
EVAL_BUDGET_USD），而不是列印一個警告。 - 構建最小可用的東西。 先有斷言和大約 30 個標註範例，再有裁判；先有校準過的裁判，再有儀表板或裁判集成。
選擇工作流程
| 使用者想要 | 執行 | 閱讀 |
|---|---|---|
| 為一個沒有評測的功能建立評測 | 工作流程 A | error-analysis, judges, datasets |
| 撰寫或修正 LLM 裁判提示 | 工作流程 B | judges, templates |
| 了解現有評測是否可信 | 工作流程 C | judges, statistics |
| 了解版本 B 是否勝過版本 A | 工作流程 D | statistics, ci-and-release-gates |
| 在 CI 中運行評測 | 工作流程 E | ci-and-release-gates, datasets |
工作流程 A：為功能新增評測
- 收集軌跡。 拉取至少 100 個多樣化的軌跡，或者如果系統尚未上線，則在真實輸入上運行系統。將其儲存為 JSONL 格式，每行有一個穩定的
id。值得記錄的軌跡欄位在 references/templates.md 中。 - 與使用者一起進行錯誤分析（詳情見 references/error-analysis.md）。人員閱讀軌跡，並在每個軌跡中第一個出錯的地方寫下一行筆記。你可以建立一個簡單的檢視器，並在人員編碼至少 30 個軌跡後，將筆記聚類成 4 到 7 個命名的失敗模式。計算每個模式的次數，並按頻率乘以嚴重性進行排序。
- 修復便宜的問題。 先進行提示詞和程式碼修復。重新運行並重新計算。
- 為每個規則可以檢測到的剩餘模式撰寫程式碼檢查。
- 為每個剩餘的主觀模式撰寫一個裁判（工作流程 B）。
- 獲取人工標籤：每個失敗模式的目標是 100 到 200 個，其中開發集和測試集各包含 30 到 50 個 PASS 和 30 到 50 個 FAIL。100 行數據的 40% 開發集分割無法容納每個類別 30 個，而在低失敗率下，你必須對失敗進行過採樣以填滿 FAIL 側。從你現有的開始，並說明區間有多寬。
- 校準 每個裁判在開發集上，然後在測試集上確認一次。
- 從重現的失敗建立回歸測試集，並將評測套件整合到 CI 中（工作流程 E）。
使用者的儲存庫中的交付成果，除非他們已經有佈局：
evals/
data/ labeled.jsonl (human labels), regression.jsonl, traces/
rubrics/ 每個失敗模式一個檔案
codebook.md 標籤、定義、2 個 PASS 和 2 個 FAIL 範例、最後的 kappa
checks.* 程式碼檢查
judge.* 裁判呼叫、鎖定的配置
calibrate.* 分割、評分、報告、分歧
run_eval.* 評分輸出、與基準比較、用於 CI 的退出碼
runs/ 每個運行一個資料夾：摘要、預測、評分規則副本
Python 和 TypeScript 的入門範本位於 https://github.com/ombharatiya/ai-evals-skills/tree/main/starters。複製一個而不是從頭開始撰寫框架。
工作流程 B：撰寫或修正 LLM 裁判
- 確認失敗模式來自錯誤分析，且程式碼檢查無法捕捉到它。
- 將提示詞撰寫成四個部分（references/templates.md 中的範本）：角色和精確定義；二元標準（"如果 X 則 PASS。如果 Y 則 FAIL，即使回應的其餘部分是正確的。有疑問時，選擇 FAIL 並說明原因。"）；來自訓練集的 2 或 3 個 Few-shot 範例，包括一個看起來像通過的 FAIL；以及一個嚴格的輸出 Schema
{"label": "PASS" | "FAIL", "critique": "..."}，在 API 支援的情況下使用結構化輸出強制執行。解析器必須在格式錯誤的輸出上大聲失敗。 - 校準：在開發集上運行，計算 PASS 召回率、FAIL 召回率和 Cohen's kappa，並閱讀每個分歧。分別閱讀誤報和漏報。如果人工標籤是錯的，修正標籤，而不是評分規則。
- 每次迭代只改變一件事，按典型影響力順序：評分規則的特異性、Few-shot 範例、輸出 Schema，最後才是模型切換。
- 期望在第二次或第三次迭代左右達到平台期。然後為邊緣案例添加 Few-shot：兩個在粗讀時看起來像 FAIL 的 PASS 範例，以及兩個看起來像 PASS 的 FAIL 範例。如果 FAIL 召回率仍然沒有變化，裁判模型可能就是天花板：在再次更改評分規則之前嘗試一個更強的模型，並將新模型視為一個全新的量測工具從頭開始校準。
- 當 PASS 和 FAIL 召回率在開發集上都達到標準時停止（本指南的預設值是 0.90；根據錯過一個失敗與誤報的成本來設定），然後在測試集上讀取一次。
工作流程 C：審計現有評測
檢查每個項目，並報告哪些失敗，附上檔案和行號：
- 指標可以追溯到有人在真實軌跡中觀察到的失敗模式。
- 程式碼檢查涵蓋了程式碼可以決定的內容；裁判是二元的，每個失敗模式一個。
- 每個裁判都有校準記錄：帶有樣本數 N 和區間的 PASS 和 FAIL 召回率，基於裁判從未見過的測試集分割。僅一致性不算數。
- Few-shot 範例未出現在開發集或測試集中。
- 裁判配置（模型、運算努力、評分規則、Schema、Few-shot）已鎖定，並與校準時的配置匹配。
- 每個報告的比率都有樣本數 N 和區間；比較是配對的。
- 回歸測試集存在，在每個 PR 上運行，並 100% 通過。
- 發布決策參考配對 Delta 及其區間，而不是絕對閾值。
- 資料集已版本化（內容哈希），結果會引用該哈希。
- 一個已經 100% 通過數月的套件沒有測試任何東西。回歸測試集是唯一的例外。
工作流程 D：比較兩個版本
在相同的輸入上運行兩個版本。報告每個通過率及其 Wilson 區間，以及配對差異及其區間：對二元結果使用 McNemar 檢定或配對自助法。先決定值得檢測的最小差異，然後確定樣本大小（references/statistics.md）。在必要時按區段進行切片，並在進行多種切片方式時進行多重比較校正。來自統計檢定力不足的運行的 "無顯著差異" 並不是無差異的證據：請說明該運行可以檢測到多大的變化。
工作流程 E：CI 中的評測
三個層級：一個冒煙測試層級，在每次推送時運行 10 到 50 個確定性斷言（無裁判）；一個完整層級，在更改提示詞或模型的 PR 上運行校準過的裁判；以及一個夜間層級，運行擴展的回歸測試和穩健性測試。在 PR 上發布一個基準線對比候選版本的表格，包含 Delta、其 95% 區間以及出貨、保留、調查或封鎖的判定。在調查、封鎖、回歸測試失敗或測量損壞（沒有判定的行、任一側缺失的行、不是校準過的裁判）時使任務失敗，並報告一個保留給指定人員閱讀：保留代表區間無法判斷變化與無變化。 使用未更改系統的 A/A 運行來設定無差異窗口的大小，而不是從零噪音基線開始。沒有靜默覆寫：覆寫需要指定人員姓名和書面理由。Fork 的 PR 不會獲得 API 金鑰。詳情見 references/ci-and-release-gates.md。
如何報告結果
報告一個表格，而不是一句話：
| 指標 | 值 | 95% 信賴區間 | 樣本數 N | 裁判 | 資料集 |
|---|---|---|---|---|---|
| 退款政策裁判的 FAIL 召回率 (測試集) | 0.92 | [0.80, 0.97] | 48 | claude-opus-5-5, medium, rubric a1b2c3 | labeled.jsonl @ 9f8e7d |
說明這些數字無法支持什麼。寫 "區間很寬；標註更多 FAIL 範例"，而不是將一個薄弱的結果四捨五入成一個主張。當你提到 TPR 或 TNR 時，指明正類別：一些文章，包括 Hamel Husain 的 FAQ，將 FAIL 視為正類別，因此其 TPR 是被捕捉到的真實失敗的比例。單純使用 "PASS 召回率" 和 "FAIL 召回率" 可以避免混淆。
預設值
除非使用者的情況需要其他值，否則使用這些預設值。"站點預設值" 指的是 aievals.co 自己使用的有效數字，而不是已發布的標準。
| 決策 | 預設值 | 來源 |
|---|---|---|
| 首次錯誤分析遍數 | 100+ 個軌跡，僅第一個失敗（Hamel 和 Shankar FAQ）；每個 15 到 45 秒 | FAQ，以及 aievals.co 的節奏 |
| 失敗模式類別 | 在軸向編碼後為 4 到 7 個 | aievals.co 開放式編碼指南 |
| 每個失敗模式的標籤數 | 100 到 200 | Hamel 和 Shankar FAQ |
| 分割 | 15% 訓練集，40% 開發集，45% 測試集，分層（入門範本改為根據每個 ID 的哈希進行分割，因此一行永遠不會更改分割；比率則僅在平均上匹配） | aievals.co 校準食譜 |
| 開發集和測試集中每個類別 | 30 到 50 個 PASS 和 30 到 50 個 FAIL | Hamel 和 Shankar FAQ |
| 裁判召回率標準 | PASS 和 FAIL 召回率在開發集上至少達到 0.90，並在測試集上確認 | 站點預設值 |
| 自動化前的人工一致性 | kappa 至少 0.6 才能繼續，0.8 才可作為黃金集或閘門 | 團隊政策，根據指南 |
| 比率的區間 | Wilson，95% | aievals.co 統計章節 |
| 發布閘門窗口 | 1 點無差異窗口；主要指標上 2 點輕微回歸窗口 | aievals.co 發布閘門章節 |
| 回歸測試集 | 每個 PR 上 100% 通過 | aievals.co 回歸測試集章節 |
參考資料
加載與任務匹配的檔案：
- references/error-analysis.md：開放式、軸向和結構化編碼、飽和度、優先級、軌跡檢視器、維度抽樣。
- references/judges.md：裁判設計、校準、偏誤及其測試方法、直接與配對比較、重新校準觸發條件。
- references/datasets.md：按用途劃分的大小、資料來源、合成數據規則、回歸測試集、覆蓋範圍網格、版本控制。
- references/statistics.md：Wilson 區間、配對檢定、群聚誤差、樣本大小、多重比較、修正裁判評分比率。
- references/ci-and-release-gates.md：CI 層級、發布閘門區間帶、線上評測、抽樣、漂移。
- references/templates.md：裁判提示、編碼簿條目、註釋記錄、軌跡 Schema、PR 結果評論。