AI 평가(Eval)
평가( eval)는 AI 시스템이 제 역할을 하는지 측정하는 반복 가능한 테스트입니다. 이 스킬은 aievals.co 가이드가 가르치는 대로 작업하게 합니다: 아무것도 측정하기 전에 실제 출력을 살펴보고, 실제로 찾은 실패만 측정하며, 모든 LLM 판정을 신뢰하기 전에 인간 레이블과 비교하여 보정하고, 모든 숫자에 구간을 붙입니다.
가이드는 https://www.aievals.co 에 있습니다. 사용자에게 선택을 설명할 때 해당 페이지를 인용하세요. 마지막에 나열된 참조 파일에 세부 사항과 출처가 있습니다.
기본 규칙
사용자가 무엇을 요청했든 모든 평가 작업에서 다음을 따르세요.
- 메트릭을 작성하기 전에 트레이스를 살펴보세요. 관찰하지 않은 시스템의 실패 모드를 지정할 수 없습니다. 사용자에게 트레이스가 없으면 먼저 얻으세요: 프로덕션 로그, 또는 100개의 현실적인 입력에서 시스템을 실행한 결과. 그런 다음 읽으세요.
- 사람이 레이블을 지정하고, 당신이 제안합니다. 직접 정답 레이블을 작성하여 인간 판단으로 제시하지 마세요. 사람이 확인할 수 있도록
"provisional": true로 표시된 레이블 초안을 작성할 수 있습니다. 코드가 답을 계산하는 경우(SQL 결과, 테스트, 계산기)를 제외하고, 모델이 입력과 정답을 모두 작성하도록 하지 마세요. - 판정보다 코드를 먼저 사용하세요. 문자열 일치, 파서, 스키마 검사, 정규식 또는 단위 테스트로 결정할 수 있는 것은 코드 검사입니다. 프롬프트 편집으로 고칠 수 있는 것은 평가를 구축하기 전에 고치세요. 남아 있는 주관적인 실패에 대해서만 LLM 판정을 사용하세요.
- 실패 모드당 하나의 이진 판정. 합격(PASS) 또는 불합격(FAIL)과 한 문장 비평. 1-5 척도는 없습니다. 여러 품질 차원은 여러 이진 판정을 의미하며, 모든 검사 통과율(all-pass rate)과 각 검사별 분석으로 보고합니다.
- 판정을 신뢰하기 전에 보정하세요. 인간 레이블과 비교하고 합격 재현율(PASS recall)과 불합격 재현율(FAIL recall)을 각각 N과 함께 보고하세요. 단순 일치율은 결코 주요 지표가 아닙니다: 항상 합격이라고 말하는 판정은 출력의 5%가 실패할 때 95%의 시간 동안 일치합니다.
- 훈련, 개발, 테스트. 퓨샷 예제는 훈련 세트에서만 가져옵니다. 개발 세트에서 반복합니다. 테스트 세트는 마지막에 한 번만 읽습니다. 추가 편집 후 테스트를 다시 읽으면 두 번째 개발 세트가 됩니다.
- 판정을 고정하세요. 모델 ID, effort, 루브릭 텍스트, 출력 스키마 및 퓨샷 순서는 도구의 일부입니다. 모든 결과와 함께 기록하고, 이 중 하나라도 변경되면 다시 보정하세요. 결정론적이라고 가정하지 마세요: 개발 세트를 두 번 실행하고 레이블 변경을 계산하세요.
- 모든 숫자는 N과 구간을 가집니다. 비율에는 정규 근사가 아닌 Wilson 구간을 사용하세요. 두 버전을 동일한 입력에서 쌍체 데이터로 비교하세요.
- 회귀 세트는 100% 통과합니다. 재현된 프로덕션 버그와 정책 경계를 포함합니다. 하나의 실패가 릴리스를 차단하며, 불안정한 사례는 프로세스 버그입니다.
- 절대 비율이 아닌 차이로 게이트하세요. references/ci-and-release-gates.md의 네 가지 밴드를 사용하세요.
- 러너에서 지출을 제한하세요. 판정 실행에는 비용이 듭니다. 코드로 예산을 강제하세요(
EVAL_BUDGET_USD), 출력된 경고가 아닙니다. - 작동하는 가장 작은 것을 구축하세요. 단언문과 약 30개의 레이블이 지정된 예제가 판정보다 먼저 오고, 보정된 판정이 대시보드나 판정 앙상블보다 먼저 옵니다.
워크플로우 선택
| 사용자가 원하는 것 | 수행할 작업 | 읽을 내용 |
|---|---|---|
| 평가가 없는 기능에 평가 추가 | 워크플로우 A | error-analysis, judges, datasets |
| LLM-as-judge 프롬프트 작성 또는 수정 | 워크플로우 B | judges, templates |
| 기존 평가를 신뢰할 수 있는지 확인 | 워크플로우 C | judges, statistics |
| 버전 B가 버전 A보다 나은지 확인 | 워크플로우 D | statistics, ci-and-release-gates |
| CI에서 평가 실행 | 워크플로우 E | ci-and-release-gates, datasets |
워크플로우 A: 기능에 평가 추가
- 트레이스를 수집하세요. 최소 100개의 다양한 트레이스를 수집하거나, 시스템이 운영 중이지 않으면 현실적인 입력으로 실행하세요. 행당 안정적인
id와 함께 JSONL로 저장하세요. 기록할 가치가 있는 트레이스 필드는 references/templates.md에 있습니다. - 사용자와 함께 오류 분석을 실행하세요 (세부 사항은 references/error-analysis.md에 있음). 사람이 트레이스를 읽고 각각에서 처음으로 잘못된 점에 대한 한 줄 메모를 작성합니다. 사람이 최소 30개를 코딩한 후 간단한 뷰어를 구축하고 메모를 4~7개의 명명된 실패 모드로 클러스터링할 수 있습니다. 각 모드를 세고 빈도와 심각도를 곱하여 순위를 매깁니다.
- 저렴한 것을 고치세요. 프롬프트 및 코드 수정이 먼저입니다. 다시 실행하고 다시 세세요.
- 코드 검사를 작성하세요 규칙으로 감지할 수 있는 모든 남은 모드에 대해.
- 남은 각 주관적 모드에 대해 하나의 판정을 작성하세요 (워크플로우 B).
- 인간 레이블을 얻으세요: 실패 모드당 100
200개가 목표이며, 개발 및 테스트 각각에 3050개의 PASS와 30~50개의 FAIL이 있어야 합니다. 100개 행의 40% 개발 분할은 각 클래스의 30개를 담을 수 없으며, 낮은 실패율에서는 FAIL 측을 채우기 위해 실패를 과도하게 샘플링해야 합니다. 가진 것부터 시작하고 구간이 얼마나 넓은지 말하세요. - 각 판정을 보정하세요 개발 세트에서, 그런 다음 테스트 세트에서 한 번 확인하세요.
- 회귀 세트를 구축하세요 재현된 실패에서, 그리고 스위트를 CI에 연결하세요 (워크플로우 E).
사용자 저장소의 산출물(이미 레이아웃이 없는 경우):
evals/
data/ labeled.jsonl (인간 레이블), regression.jsonl, traces/
rubrics/ 실패 모드당 하나의 파일
codebook.md 레이블, 정의, PASS 예 2개와 FAIL 예 2개, 마지막 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개의 퓨샷 예제(통과처럼 보이는 FAIL 하나 포함); 그리고 엄격한 출력 스키마,
{"label": "PASS" | "FAIL", "critique": "..."}, API가 지원하는 경우 구조화된 출력으로 강제. 파서는 잘못된 형식의 출력에서 크게 실패해야 합니다. - 보정: 개발 세트에서 실행하고, PASS 재현율, FAIL 재현율 및 Cohen의 kappa를 계산하고, 모든 불일치를 읽으세요. 거짓 통과(PASS)와 거짓 실패(FAIL)를 별도로 읽으세요. 인간 레이블이 잘못된 경우 루브릭이 아닌 레이블을 수정하세요.
- 반복당 하나의 항목을 변경하세요, 일반적인 영향 순서: 루브릭 특이성, 퓨샷 예제, 출력 스키마, 마지막으로 모델 교체.
- 두 번째 또는 세 번째 반복 주변에서 정체를 예상하세요. 그런 다음 가장자리 사례에 대한 퓨샷을 추가하세요: 부주의하게 읽으면 FAIL처럼 보이는 두 개의 PASS 예제와 PASS처럼 보이는 두 개의 FAIL 예제. FAIL 재현율이 여전히 움직이지 않으면 판정 모델이 한계일 수 있습니다: 루브릭을 다시 변경하기 전에 더 강력한 모델을 시도해보고, 새 모델을 처음부터 보정할 새 도구로 취급하세요.
- PASS와 FAIL 재현율이 모두 개발 세트에서 기준에 도달하면 중지하세요 (이 가이드의 기본값은 0.90; 놓친 실패 비용과 오경보 비용에서 설정), 그런 다음 테스트 세트를 한 번 읽으세요.
워크플로우 C: 기존 평가 감사
각 항목을 확인하고 실패하는 것을 파일과 줄과 함께 보고하세요:
- 메트릭이 실제 트레이스에서 누군가가 관찰한 실패 모드로 추적됩니다.
- 코드 검사는 코드가 결정할 수 있는 것을 다룹니다; 판정은 이진이며, 실패 모드당 하나입니다.
- 각 판정은 보정 기록이 있습니다: PASS 및 FAIL 재현율과 N 및 구간, 판정이 본 적 없는 테스트 분할에서. 단순 일치율만으로는 충분하지 않습니다.
- 퓨샷 예제가 개발 또는 테스트 세트에 나타나지 않습니다.
- 판정 구성(모델, effort, 루브릭, 스키마, 퓨샷)이 고정되어 있고 보정된 구성과 일치합니다.
- 보고된 모든 비율에는 N과 구간이 있습니다; 비교는 쌍체입니다.
- 회귀 세트가 존재하고, 모든 PR에서 실행되며, 100% 통과합니다.
- 릴리스 결정은 절대 임계값이 아닌 쌍체 델타와 그 구간을 읽습니다.
- 데이터 세트는 버전이 지정되고(콘텐츠 해시) 결과는 해시를 명명합니다.
- 몇 달 동안 100%로 유지된 스위트는 아무것도 테스트하지 않습니다. 회귀 세트는 유일한 예외입니다.
워크플로우 D: 두 버전 비교
두 버전을 동일한 입력에서 실행하세요. 각 통과율을 Wilson 구간과 함께 보고하고, 쌍체 차이를 그 구간과 함께 보고하세요: 이진 결과에 대한 McNemar의 검정 또는 쌍체 부트스트랩. 먼저 감지할 가치가 있는 가장 작은 차이를 결정한 다음 표본 크기를 결정하세요 (references/statistics.md 참조). 중요한 경우 세그먼트별로 슬라이스하고, 여러 방식으로 슬라이스할 때 다중 비교를 보정하세요. 검정력이 부족한 실행에서 "유의미한 차이 없음"은 차이가 없다는 증거가 아닙니다: 실행이 감지할 수 있었던 변화의 크기를 말하세요.
워크플로우 E: CI의 평가
세 가지 계층: 모든 푸시에서 10~50개의 결정론적 단언을 포함하는 smoke 계층(판정 없음), 프롬프트나 모델을 변경하는 PR에 보정된 판정을 포함하는 전체 계층, 확장된 회귀 및 견고성 세트를 포함하는 야간 계층. PR에 기준선 대 후보 테이블을 델타, 95% 구간 및 출시(ship), 보류(hold), 조사(investigate) 또는 차단(block) 판정과 함께 게시하세요. 조사, 차단, 회귀 세트 실패 또는 측정 중단(판정이 없는 행, 양쪽에 누락된 행, 보정된 판정이 아닌 판정) 시 작업을 실패시키고, 보류는 지정된 사람이 읽도록 보고하세요: 보류는 구간이 변화와 변화 없음을 구분할 수 없음을 의미합니다. 무관심 창의 크기는 변경되지 않은 시스템의 A/A 실행에서, 제로 노이즈 바닥이 아닌 것으로 결정하세요. 무음 재정의는 없습니다: 재정의는 지정된 사람과 서면 이유가 필요합니다. 포크 PR은 API 비밀을 얻지 못합니다. 세부 사항은 references/ci-and-release-gates.md에 있습니다.
결과 보고 방법
문장이 아닌 테이블로 보고하세요:
| 메트릭 | 값 | 95% CI | N | 판정 | 데이터 세트 |
|---|---|---|---|---|---|
| FAIL 재현율, 환불 정책 판정 (테스트) | 0.92 | [0.80, 0.97] | 48 | claude-opus-5-5, medium, 루브릭 a1b2c3 | labeled.jsonl @ 9f8e7d |
숫자가 뒷받침할 수 없는 것을 말하세요. 약한 결과를 주장으로 반올림하기보다 "구간이 넓습니다. 더 많은 FAIL 예제에 레이블을 지정하세요"라고 작성하세요. TPR 또는 TNR을 말할 때 양성 클래스를 명명하세요: 일부 글, 그중 Hamel Husain의 FAQ는 FAIL을 양성으로 취급하므로, 그 TPR은 잡힌 실제 실패의 비율입니다. "PASS 재현율"과 "FAIL 재현율"은 혼란을 피합니다.
기본값
사용자의 상황이 다른 것을 요구하지 않는 한 이를 사용하세요. "사이트 기본값"은 공개된 표준이 아닌 aievals.co 자체의 작업 번호를 의미합니다.
| 결정 | 기본값 | 출처 |
|---|---|---|
| 첫 번째 오류 분석 패스 | 100개 이상의 트레이스, 첫 번째 실패만 (Hamel and Shankar FAQ); 각 15~45초 | FAQ, 그리고 속도에 대해 aievals.co |
| 실패 모드 범주 | 축 코딩 후 4~7개 | aievals.co 오픈 코딩 가이드 |
| 실패 모드당 레이블 | 100~200개 | Hamel and Shankar FAQ |
| 분할 | 15% 훈련, 40% 개발, 45% 테스트, 층화 (스타터는 대신 각 id의 해시로 분할하여 행이 분할을 변경하지 않음; 비율은 평균적으로만 일치) | aievals.co 보정 레시피 |
| 개발 및 테스트의 클래스당 | 30 | Hamel and 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: 판정 프롬프트, 코드북 항목, 주석 기록, 트레이스 스키마, PR 결과 댓글.