使用结构化事件和 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代理监控。