구조화된 이벤트 및 SQL을 사용하여 AI 에이전트 평가
에이전트는 실행을 마쳐도 작업에는 실패할 수 있습니다. 실행, 분석할 모델 및 도구 호출, 평가 결과를 각각 별도의 이벤트로 기록하세요. SQL로 릴리스별 품질, 비용, 지연 시간, 재시도, 사람에게 넘긴 작업을 비교할 수 있습니다. 모델이 생성한 점수는 다른 근거와 비교한 뒤 정확한지 판단하세요.
Telemetry는 이 워크플로우의 분석 레이어입니다. 채점자를 실행하거나, 프롬프트 버전을 관리하거나, 평가 데이터세트를 관리하거나, 프롬프트 및 완료 재생을 제공하지 않습니다. 애플리케이션이나 전용 평가 시스템에 해당 워크플로를 유지한 다음 집계 분석에 필요한 승인된 결과 필드를 보냅니다.
operation_id는 릴리스 전체에서 고유해야 합니다.
먼저 평가 단위를 정의하세요.
"무엇이 점수를 받았나요?"라고 대답하는 행을 선택하세요. 메트릭을 선택하기 전에 일반적인 단위는 다음과 같습니다.
- 사용자에게 하나의 최종 답변이 표시됩니다.
- 하나의 완료된 에이전트 실행;
- 해결된 지원 케이스 1개
- 하나의 도구 선택 결정;
- 고정된 예에 대해 검색된 답변 1개;
- 여러 에이전트 시도를 포함할 수 있는 하나의 비즈니스 작업입니다.
해당 장치에 operation_id와 같은 안정적인 식별자를 제공하십시오. run_id, response_id 및 evaluation_id에 대해 별도의 식별자를 사용합니다. 재시도는 하나의 작업에 대해 여러 실행을 생성할 수 있으며 하나의 출력이 여러 평가를 받을 수 있습니다. 모든 그레인에 대해 단일 식별자를 재사용하면 잘못된 조인과 이중 계산 비용이 발생합니다.
별도의 실행, 요청 및 평가 이벤트
실제 시작 계약에서는 3개 또는 4개의 이벤트 테이블을 사용합니다.
| 이벤트 | 곡물 | 유용한 분야 |
|---|---|---|
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 |
평가자 1인 결과 | operation_id, evaluation_id, evaluator_type, evaluator_version, metric_name, score, passed, review_outcome, is_final, dataset_version, release |
네 개의 곡물을 모두 하나의 넓은 줄에 강제로 넣지 마십시오. 5번의 도구 시도와 2번의 평가로 실행하면 결합 시 비용이나 성공 횟수가 배가됩니다.
여러 종류의 증거를 사용하세요
모든 에이전트 워크플로에 대해 단일 평가자로는 충분하지 않습니다. 실제 결정에 해당하는 신호만 결합합니다.
- 결정론적 검사는 스키마, 필수 인용, 허용된 도구 선택, 정확한 계산, 정책 규칙 또는 알려진 최종 상태를 확인합니다.
- 사람의 검토는 정확함, 부분적으로 정확함, 안전하지 않음, 에스컬레이션 필요 등 제한된 기준표를 포착합니다. 개인 리뷰어 메모가 아닌 루브릭과 리뷰어 프로세스를 기록하세요.
- 모델 기반 채점은 더 높은 볼륨에서 반복 가능한 기준표를 적용할 수 있습니다. 심사위원 모델, 지침, 임계값의 버전을 지정하고 정기적으로 점수를 사람의 검토와 비교합니다.
- 제품 결과는 사용자가 결과를 수락, 저장, 수정, 재생성, 에스컬레이션 또는 포기했는지 여부를 기록합니다.
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,
isFinal,
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,
is_final: isFinal,
dataset_version: datasetVersion,
prompt_version: promptVersion,
release,
});
}
isFinal은 작업, 지표, 평가기 버전, 릴리스별로 권위 있는 최종 결정 한 건에만 true로 설정하세요. 에이전트 실행 완료가 평가 확정을 의미하지는 않습니다.
기본적으로 원시 프롬프트, 완성, 검색된 문서, 도구 인수, 비밀 및 자유 형식 검토자 메모를 이벤트에서 제외합니다. 안정적인 카테고리와 버전 식별자를 선호합니다. 콘텐츠 보존이 승인되면 해당 액세스 및 삭제 정책을 위해 설계된 시스템에 이를 저장하고 제한된 식별자와 연관시키십시오.
출시별 품질 비교
이 예시는 작업, 릴리스, 지표, 평가기 버전마다 is_final = true인 평가 한 건만 최종 결과로 취급합니다. 임시 평가는 is_final = false로 표시하세요. 최종 결정을 수정해야 한다면 새 평가기 버전이나 별도의 확정 이벤트를 사용하세요. 쿼리는 중복된 최종 평가를 제외하고 완료된 작업만 계산합니다. 중복을 조사하기 전에는 평가 비율이나 통과율을 해석하지 마세요.
WITH completed AS (
SELECT release, operation_id
FROM agent_run_completed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
AND status = 'success'
GROUP BY release, operation_id
),
final_reviews AS (
SELECT release, operation_id, MAX(score) AS score,
MAX(CASE WHEN passed THEN 1 ELSE 0 END) AS passed
FROM ai_output_reviewed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
AND metric_name = 'task_quality'
AND evaluator_version = 'quality-rubric-v3'
AND is_final = true
GROUP BY release, operation_id
HAVING COUNT(*) = 1
)
SELECT
c.release,
COUNT(*) AS completed_operations,
COUNT(f.operation_id) AS evaluated_operations,
ROUND(
100.0 * COUNT(f.operation_id)
/ NULLIF(COUNT(*), 0),
1
) AS evaluation_coverage_pct,
ROUND(
100.0 * SUM(CASE WHEN f.passed = 1 THEN 1 ELSE 0 END)
/ NULLIF(COUNT(f.operation_id), 0),
1
) AS evaluated_pass_rate_pct,
ROUND(AVG(f.score), 3) AS average_final_score
FROM completed c
LEFT JOIN final_reviews f
ON f.release = c.release AND f.operation_id = c.operation_id
GROUP BY c.release
ORDER BY c.release;
이 결과로 릴리스를 결정하기 전에 제외된 중복 최종 평가를 확인하세요:
SELECT release, operation_id, COUNT(*) AS conflicting_final_reviews
FROM ai_output_reviewed
WHERE timestamp_utc >= now() - INTERVAL '30 days'
AND metric_name = 'task_quality'
AND evaluator_version = 'quality-rubric-v3'
AND is_final = true
GROUP BY release, operation_id
HAVING COUNT(*) > 1
ORDER BY release, operation_id;
다양한 루브릭, 심사 모델, 임계값, 데이터세트 버전 또는 샘플링 규칙을 사용하는 릴리스를 해당 차원을 분리하지 않고 비교하지 마세요. 평가자가 변경된 후의 점수 변경은 제품 회귀의 증거가 아닙니다.
허용된 결과당 비용 계산
먼저 작업 단위로 비용을 합산한 뒤 하나의 최종 결정과 결합합니다. 이 예시의 operation_id는 릴리스 전체에서 고유합니다. 그렇지 않다면 양쪽 결합 키에 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'
AND metric_name = 'task_quality'
AND evaluator_version = 'quality-rubric-v3'
AND is_final = true
GROUP BY operation_id
HAVING COUNT(*) = 1
)
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 에이전트 모니터링을 참조하세요.