에이전트 평가
에이전트 평가는 같은 질문과 기준으로 실행 결과를 비교하는 기능입니다. 평가를 시작하려면 먼저 dataset과 case를 준비하고, 결과를 판정할 evaluator를 선택합니다. 실행이 끝나면 run 상태와 결과를 확인하고 대시보드 또는 결과 export로 집계 자료를 검토합니다.
평가에 필요한 자원
평가는 다음 자원을 조합해 진행합니다.
| 자원 | 용도 |
|---|---|
| Dataset | 평가에 사용할 case의 모음 |
| Case | 질문과 기대 답변으로 구성된 개별 평가 항목 |
| Evaluator | 결과를 판정하는 기준 |
| Run | dataset과 evaluator를 사용한 평가 실행 |
| Result | case별 평가 결과 |
| Dashboard | 호출자가 소유한 agent 범위의 집계 |
Dataset과 evaluator는 사용자 또는 workspace 범위로 관리할 수 있습니다. Evaluator는 preset, workspace, user 범위로 구분되며, 판정 유형은 binary, score, rubric으로 나뉩니다.
Dataset과 case 준비
Dataset은 생성, 조회, import, 상세 조회, 삭제를 지원합니다. Dataset 삭제는 삭제 시각을 기록하는 soft delete입니다. 반면 case 삭제는 영구 삭제이며, dataset의 total_cases도 같은 transaction에서 1 감소합니다.
CSV로 case를 가져올 때 파일 크기는 최대 5 MiB, 행 수는 최대 1,000행입니다. 필수 header는 question과 answer입니다. 입력 파일은 UTF-8 BOM, CP949, Latin-1 순서로 해석됩니다. question은 50,000자, answer는 100,000자까지 입력할 수 있습니다.
평가에 사용할 질문은 실제 업무에서 확인하려는 입력을 대표해야 합니다. 기대 답변은 비교 기준으로 사용할 내용을 담되, 평가 결과가 곧 업무 적합성이나 배포 승인을 뜻하지는 않습니다.
Evaluator 선택
Evaluator를 만들거나 수정할 때 판정 유형과 범위를 함께 확인합니다. score evaluator는 score_min이 score_max보다 작아야 합니다. 미리 제공되는 preset evaluator는 6개입니다.
Evaluator를 선택할 때는 평가 목적에 맞는 판정 방식을 사용합니다.
- binary는 통과와 실패처럼 두 상태를 판정할 때 사용합니다.
- score는 점수 범위로 결과를 비교할 때 사용합니다.
- rubric은 여러 기준을 나눠 결과를 검토할 때 사용합니다.
이 목록은 판정 유형의 의미를 설명한 것이며, 각 유형이 어떤 점수 계산을 보장하는지는 해당 evaluator 설정과 결과를 기준으로 확인합니다.
평가 실행
평가 실행은 평가 run을 생성한 뒤 worker queue에 작업을 넣는 방식으로 진행됩니다. 새 run은 201 응답으로 생성되며, 이후 조회, 결과 조회, 결과 export, 취소를 수행할 수 있습니다.
run 상태는 pending에서 running으로 이동한 뒤 success, error, cancelled 또는 timeout으로 끝납니다. 상태 enum에는 drained도 포함되어 있으므로, 화면에 표시되는 상태와 서버가 반환한 실제 상태를 구분해 확인합니다.
사용자별 동시 실행은 PostgreSQL advisory lock으로 제한합니다. 기본 동시 실행 한도는 2이며, EVALUATION_MAX_CONCURRENT_RUNS로 변경할 수 있습니다. 실행이 이미 terminal 상태라면 취소 요청은 409로 처리됩니다.
평가 run을 시작할 때는 workspace dataset을 조회할 수 있는 범위와 실행할 수 있는 범위를 따로 봐야 합니다. run 시작은 생성자 기준으로 제한되므로, workspace dataset을 조회할 수 있다는 사실만으로 다른 사용자가 그 run을 시작할 수 있다고 판단하지 않습니다.
취소와 오류 확인
취소 요청이 성공해도 모든 case 처리가 즉시 멈춘다고 단정하지 않습니다. DB에 취소 상태를 기록한 뒤 Redis flag 전달이 실패하면 worker가 남은 case를 계속 처리할 수 있습니다. 취소 후에는 run 상태와 남은 결과를 다시 조회합니다.
주요 오류 상태는 다음과 같습니다.
- 400 VALIDATION_ERROR: 입력 검증 실패
- 403 WBAC_DENIED 또는 ABAC_DENIED: 권한 거부
- 404 NOT_FOUND: 대상을 찾지 못함
- 409 CONFLICT: 현재 상태와 요청이 충돌함
- 413 PAYLOAD_TOO_LARGE: 허용 크기 초과
- 422: 요청을 처리할 수 없는 상태
- 429 RATE_LIMITED: 요청 제한 초과
오류 코드만 보고 재시도 여부를 결정하지 않습니다. 대상 dataset, case, evaluator, run의 상태와 호출자의 권한을 함께 확인해야 합니다.
결과와 대시보드 확인
Results에서는 case별 평가 결과를 조회할 수 있고, results export에서는 전체 결과 JSON을 받을 수 있습니다. Dashboard는 호출자가 소유한 agent 범위로 집계합니다. 따라서 대시보드 수치와 개별 결과를 비교할 때는 같은 agent 범위를 사용했는지 먼저 확인합니다.
결과를 해석할 때는 evaluator 유형, dataset의 case 구성, run 상태를 함께 기록합니다. 일부 case만 처리된 run이나 timeout으로 끝난 run은 성공한 결과만으로 전체 평가를 대표한다고 보지 않습니다.
권장 실행 순서
- 평가 목적에 맞는 dataset과 case를 준비합니다.
- CSV를 import했다면 필수 header, 파일 크기, 행 수와 문자 인코딩을 확인합니다.
- evaluator의 범위, 유형, 점수 범위를 확인합니다.
- dataset과 evaluator를 사용해 run을 생성합니다.
- pending, running 이후의 terminal 상태를 조회합니다.
- 개별 results와 전체 결과 export를 확인합니다.
- Dashboard 집계 범위와 run 결과의 agent 범위를 비교합니다.
- 취소 또는 오류가 있었다면 남은 case와 최종 상태를 다시 확인합니다.
평가 결과는 설정 변경의 근거로 사용할 수 있지만, 결과 조회가 곧 품질 보증을 의미하지는 않습니다. 비교하려는 모델, 지침, 도구 구성이 달라졌다면 같은 dataset을 사용해도 결과 차이의 원인을 별도로 기록해야 합니다.