使用結構化事件和 SQL 評估 AI 代理
當 AI 代理評估能夠區分技術上完成的執行和實際滿足任務的結果時，它非常有用。可靠的設計會記錄執行的緊湊事件、任何值得分析的模型或工具活動以及後續的評估結果。然後，SQL 可以透過發布來比較品質、成本、延遲、重試和人工切換，而無需將追蹤或模型生成的分數視為基本事實。
Telemetry 是該工作流程中的分析層。它不執行記分器、管理提示版本、管理評估資料集或提供提示和完成重播。將這些工作流程保留在您的應用程式或專用評估系統中，然後傳送聚合分析所需的批准結果欄位。
首先定義評估單位
選擇回答“什麼獲得了分數？”的行在選擇指標之前。常見單位包括：
- 向使用者顯示一個最終答案；
- 一次已完成的代理執行；
- 一個已解決的支援案例；
- 一項工具選擇決策；
- 針對凍結範例檢索到的答案；
- 一項業務操作可以包括多次代理嘗試。
為該單元指定一個穩定的識別符號，例如 operation_id。對 run_id、response_id 和 evaluation_id 使用單獨的識別符號。一次重試可以為一項操作建立多次執行，並且一個輸出可以接受多次評估。對每個grain重複使用單個識別符號會產生錯誤的連線和重複計算的成本。
單獨的執行、請求和評估事件
實用的起始合約使用三個或四個事件資料表：
| 活動 | 穀物 | 有用的欄位 |
|---|---|---|
agent_run_completed |
一臺終端代理執行 | operation_id、run_id、workflow、status、duration_ms、tool_call_count、human_handoff、prompt_version、release |
llm_request_completed |
一位提供商請求 | operation_id、run_id、response_id、provider、model、input_tokens、output_tokens、estimated_cost_usd、latency_ms |
agent_tool_completed |
一種工具嘗試 | run_id、tool_call_id、tool_name、status、duration_ms、retry_count、error_type |
ai_output_reviewed |
一項評估結果 | operation_id、evaluation_id、evaluator_type、evaluator_version、metric_name、score、passed、review_outcome、dataset_version |
不要將所有四粒穀物強行擠成一排。否則，進行五次工具嘗試和兩次評估的執行會增加成本或加入時的成功次數。
使用多種證據
沒有一個評估者足以滿足每個代理工作流程。僅組合與實際決策相對應的訊號：
- 確定性檢查驗證模式、所需引用、允許的工具選擇、精確計算、策略規則或已知的最終狀態。
- 人工審查捕獲有界的標題，例如正確、部分正確、不安全或需要升級。記錄標題和審稿人流程，而不是私人審稿人筆記。
- 基於模型的評分可以以更高的量應用可重複的評分標準。對判斷模型、指令和閾值進行版本控制，並定期將分數與人工審查進行比較。
- 產品結果記錄使用者是否接受、儲存、更正、重新生成、升級或放棄結果。
LLM評委是一個衡量工具，而不是一個客觀標籤。追蹤分歧、缺失評估以及法官設定的變化。 Langfuse評價理念 和 Arize Phoenix 評估文件 描述了可以保留在 Telemetry 上游的附加評估工作流程。
發出經過審查的結果事件
此 JavaScript 範例在評分者或人工審查工作流程完成後傳送緊湊的評估器結果：
import telemetry from "telemetry-sh";
telemetry.init(process.env.TELEMETRY_API_KEY);
export async function recordAgentEvaluation({
operationId,
evaluationId,
evaluatorType,
evaluatorVersion,
metricName,
score,
threshold,
reviewOutcome,
datasetVersion,
promptVersion,
release,
}) {
await telemetry.log("ai_output_reviewed", {
operation_id: operationId,
evaluation_id: evaluationId,
evaluator_type: evaluatorType,
evaluator_version: evaluatorVersion,
metric_name: metricName,
score,
threshold,
passed: score >= threshold,
review_outcome: reviewOutcome,
dataset_version: datasetVersion,
prompt_version: promptVersion,
release,
});
}
預設情況下，將原始提示、完成、檢索到的文件、工具參數、秘密和自由格式的審閱者註釋保留在事件之外。更喜歡穩定的類別和版本識別符號。如果內容保留獲得批准，請將其儲存在專為該存取和刪除策略設計的系統中，並將其與受限識別符號相關聯。
按版本比較品質
此查詢計算單個指標的覆蓋率和透過率。顯式評估計數可防止未評估的版本看起來人為成功。
WITH run_counts AS (
SELECT
release,
COUNT(DISTINCT operation_id) AS completed_operations
FROM agent_run_completed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
AND status = 'success'
GROUP BY release
),
evaluation_counts AS (
SELECT
release,
COUNT(DISTINCT operation_id) AS evaluated_operations,
COUNT(DISTINCT CASE WHEN passed THEN operation_id END) AS passed_operations,
AVG(score) AS average_score
FROM ai_output_reviewed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
AND metric_name = 'task_quality'
AND evaluator_version = 'quality-rubric-v3'
GROUP BY release
)
SELECT
r.release,
r.completed_operations,
COALESCE(e.evaluated_operations, 0) AS evaluated_operations,
ROUND(
100.0 * COALESCE(e.evaluated_operations, 0)
/ NULLIF(r.completed_operations, 0),
1
) AS evaluation_coverage_pct,
ROUND(
100.0 * COALESCE(e.passed_operations, 0)
/ NULLIF(e.evaluated_operations, 0),
1
) AS evaluated_pass_rate_pct,
ROUND(e.average_score, 3) AS average_score
FROM run_counts r
LEFT JOIN evaluation_counts e ON e.release = r.release
ORDER BY r.release;
不要在不分離這些維度的情況下比較使用不同標準的版本、判斷模型、閾值、資料集版本或取樣規則。評估者變更後的分數變化並不是產品迴歸的證據。
計算每個可接受結果的成本
在將其加入到最終結果之前，操作粒度的聚合提供商成本：
WITH operation_cost AS (
SELECT
operation_id,
SUM(estimated_cost_usd) AS total_cost_usd
FROM llm_request_completed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
GROUP BY operation_id
),
terminal_outcome AS (
SELECT
operation_id,
MAX(CASE WHEN review_outcome = 'accepted' THEN 1 ELSE 0 END) AS accepted
FROM ai_output_reviewed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
GROUP BY operation_id
)
SELECT
COUNT(*) AS evaluated_operations,
SUM(accepted) AS accepted_operations,
ROUND(SUM(total_cost_usd), 4) AS evaluated_cost_usd,
ROUND(
SUM(total_cost_usd) / NULLIF(SUM(accepted), 0),
4
) AS cost_per_accepted_operation_usd
FROM operation_cost c
JOIN terminal_outcome o ON o.operation_id = c.operation_id;
只有當“接受”有穩定的定義時，這個指標才有意義。複製的答案、使用者可見的答案、無需重新開啟即可解決的案例以及人工評分通行證是不同的結果。
建置迴歸門
對於每個提議的版本：
- 使用相同的評估器設定執行相同的凍結資料集。
- 記錄候選
release、prompt_version、dataset_version和evaluator_version。 - 將透過率、嚴重失敗率、切換率、p95 持續時間以及每個接受操作的成本與批准的基線進行比較。
- 檢查源評估系統中的失敗範例。
- 使用執行前選擇的閾值批准或拒絕發布。
- 單獨監控生產結果，因為凍結資料集無法代表每個即時輸入。
當決策需要時，包括最小樣本量和置信區間。避免對分母很小的百分比發出警示。還追蹤評估覆蓋範圍：20 次審查執行的及格分數並不代表 10,000 次未經審查的執行。
何時保留專用評估平臺
當團隊需要提示和完成檢查、資料集管理、註釋佇列、提示管理、實驗執行、追蹤重放或內建評估器時，請使用專業平臺。 Telemetry 可以收到 SQL 分析的版本化分數和結果；它不是功能對功能的替代。
接下來，使用 AI品質回歸秘訣、代理任務成功和移交秘訣 和 每美元配方可接受的產出。對於更廣泛的實現邊界，請參閱 AI代理監控。