어노테이션 큐
어노테이션 큐
어노테이션 큐가 무엇인지, 그리고 팀원이 어노테이션할 항목을 배정하는 방법을 배워요.
출처: 문서
본문
개요
Confident AI는 Confident API를 통한 사용자 피드백 자동 수집에 더해, 내부 도메인 전문가가 트레이스, 스팬, 스레드에 어노테이션을 남길 수 있게 해요.
어노테이션은 두 가지 방식으로 남길 수 있어요:
- 임시(Ad-hoc) 독립 태스크로, 또는
- 어노테이션 큐의 일부로
두 워크플로 모두 같은 최종 결과를 줘요.
"어노테이션 큐"는 평가 대기 중인 트레이스, 스팬, 스레드의 그룹을 말해요. 서로 다른 팀원의 어노테이션을 더 효과적으로 관리하는 추상화 레이어를 제공해요.
독립 태스크로 어노테이션하기
독립 태스크로 어노테이션을 남기는 것은 매우 단순해요. Observatory 아래 Traces, Spans, Threads 페이지로 이동하기만 하면 됩니다.
클릭하는 모든 트레이스/스팬/스레드에서 다음과 같은 형태로 점수를 남길 수 있어요:
- 엄지 위/아래(thumbs up/down), 또는
- 1-5 스타 평점
다음 같은 선택 필드도 남길 기회가 있어요:
- Explanation
- Expected output (트레이스, 스팬)
- Expected outcome (스레드)
트레이스·스팬과 스레드 어노테이션의 차이를 이해하려면 single vs multi-turn 어노테이션 섹션을 읽어 보세요.
Traces
Spans
Threads
어노테이션 큐 사용하기
특히 도메인 전문가의 어노테이션이 필요한 규모가 큰 팀에서 자주 선호되는 방법은 어노테이션 큐를 쓰는 것이에요.
어노테이션 큐는 기본적으로 평가 대기 중인 트레이스/스팬/스레드의 그룹이에요. 어노테이션 팀에게 위의 임시 방식보다 더 체계적이고 매끄러운 데이터 어노테이션 인터페이스를 제공해요.
Confident AI에는 Traces, Spans, Threads 세 종류의 어노테이션 큐가 있어요. 이 말은 트레이스용 큐에 스레드를 추가할 수 없고, 그 반대도 마찬가지라는 뜻이에요.
어노테이션 큐 만들기
먼저 어노테이션 큐를 만들어요. 이 전체 예시에서는 트레이스용 큐를 보여줄 거예요. 하지만 스팬과 스레드에서도 거의 동일해요.
트레이스용 큐를 만들려면 반드시 Traces 탭을 클릭해야 해요. Spans와 Threads에도 똑같이 적용돼요.
어노테이션 큐 만들기
큐에 항목 추가하기
플랫폼 어디에서든 트레이스, 스팬, 스레드를 보는 순간 어노테이션 큐에 추가할 수 있어요. 주로 Traces, Spans, Threads용 Observatory가 여기 포함되지만, 트레이스와 스팬이 표시되는 컴포넌트 수준 테스트 리포트도 포함돼요.
여러 큐에 한 번에 추가할 수 있고, 큐에 넣는 항목을 어노테이션할 팀원을 배정할 수도 있어요. 배정하는 사람(큐 시점이든 나중에 Queue Settings에서든)은 앱 내 알림과 자신에게 라우팅된 내용을 요약하는 이메일을 받아요.
추가할 수 있는 큐가 보이지 않으면, 추가하는 데이터에 특화된 큐를 만들었는지 확인하세요(예: 트레이스는 trace 큐, 스팬은 span 큐, 스레드는 thread 큐).
큐에 트레이스 추가하기
새 데이터가 도착할 때 자동으로 되길 원하나요? 자동 수집으로 건너뛰어서 매 몇 분마다 매칭되는 프로덕션 데이터를 큐로 흘려보내는 ingestion task를 설정하세요.
큐 항목 어노테이션하기
항목을 어노테이션 큐에 추가한 뒤에는, 그것들이 큐에서 어노테이션할 수 있게 보여요:
큐에 담긴 트레이스 어노테이션하기
다음을 할 수 있어요:
- 완료 진행도 추적
- 완료되었거나, 진행 중이거나, 자기에게 배정된 항목으로 필터
- 어노테이션을 마치면 항목을 자동으로 완료로 표시
- 트레이스/스팬/스레드의 전체 세부 정보 보기
기본적으로 Queue Annotator는 입력, 출력, 메타데이터, (스레드의) 턴 이외의 모든 정보를 제거해요.
진행도 추적하기
끝나면 Queue Settings로 가서 완료된/진행 중인 항목의 개요를 확인해요.
큐 항목 관리하기
어노테이션용으로 큐에 넣은 항목은 Queue Settings 페이지에서 언제나 관리할 수 있어요. 여기에는 사용자 배정/배정 해제, 항목을 완료/진행 중으로 표시, 큐에서 항목 제거가 포함됩니다.
Queue Settings 관리하기
항목을 개별로든 일괄로든 재배정하면 새 담당자에게 앱 내 알림과 이메일이 가요.
CSV로 내보내기
Queue Settings → Queued Items 툴바에서 Export as CSV를 클릭하면 큐의 항목과 그 어노테이션을 다운로드할 수 있어요.
큐 항목을 CSV로 내보내기
드롭다운에는 두 가지 옵션이 있어요:
- Download selected — 체크한 행만 내보내요. 선택은 페이지 간에 유지되므로, 내보내기 전에 정확한 부분집합을 큐레이션할 수 있어요.
- Download all filtered — 현재 필터(상태 필터, 정렬 등)와 일치하는 모든 행을, 아직 페이지를 넘기지 않은 행까지 내보내요.
CSV는 (큐 항목 × 어노테이션) 하나당 한 행을 내보내요. 어노테이션이 없는 항목도 나타나므로, 완료 여부와 관계없이 큐의 전체 상태를 반영해요.
| Column type | Columns |
|---|---|
| Lookup keys | queueItemId, entityType, entityId |
| Queue lifecycle | completed, assignedToEmail, addedAt |
| Annotation fields | annotationId, annotationName, annotationType, annotationRating, annotationExplanation, expectedOutput, expectedOutcome, annotatedBy, annotatedAt |
내보내기는 어노테이션 중심이에요 — 각 트레이스/스팬/스레드의 전체 입력/출력은 포함하지 않아요. 기저 페이로드가 필요하면 룩업 키(
entityType
entityId)로 항목을 플랫폼에 다시 교차 참조하세요.
자동 수집
지속적인 검토 작업이라면, 생성되는 대로 매칭되는 데이터를 큐로 자동 끌어오는 ingestion tasks를 구성할 수 있어요 — 수동 "Add to queue" 단계가 필요 없어요.
큐의 ingestion tasks
큐를 열고 Automations 탭을 골라 ingestion task를 관리해요. 각 태스크는 큐의 데이터 타입을 겨냥해요 — trace 큐는 트레이스를, thread 큐는 스레드를 수집하죠.
Ingestion Task 만들기
ingestion task 만들기 또는 편집하기
Automations 열기
왼쪽 사이드바에서 어노테이션 큐의 Automations로 이동하고 Add ingestion task를 클릭해요.
이름 짓고 설명하기
명확한 Name(예: Production billing complaints)과 선택적 Description을 정해요. 데이터 모델은 큐 타입에 고정돼요 — thread 큐는 스레드를, trace 큐는 트레이스를 수집해요.
필터 구성하기
Filters를 추가해 태스크가 수집할 항목을 좁혀요. 필터는 Observatory와 Dashboards와 같은 구문을 쓰므로, 환경, 태그, 메타데이터 필드, 클래스파이어 라벨, 점수, 지연 또는 어떤 조합으로도 매칭할 수 있어요.
샘플 비율과 최대 항목 조정하기
Sample Rate를 0과 1 사이로 설정해 매칭의 일부만 수집하게 해요(예: 0.2는 매칭 항목의 20%를 수집). 선택적으로 Max Items를 설정해 태스크가 큐 합계에 추가할 수 있는 항목 수를 상한으로 잡아요 — 제한 없음이면 비워 두세요.
배정 전략 고르기
수집된 각 항목이 누구에게 라우팅될지 정해요. 다음 중 하나를 고르세요:
- Unassigned — 항목이 소유자 없이 큐에 들어가요. 검토자가 큐에서 직접 가져와요.
- Single user — 수집된 모든 항목이 같은 프로젝트 멤버에게 배정돼요.
- Round robin — 검토자 집합에 걸쳐 수집 항목을 순환 배분해요. 가중치는 가장 적게 배정받은 사람 우선(타이브레이커는
lastAssignedAt)이에요. 균등 분배가 목표예요 — 태스크가 누군가의 비근무 시간에 더 자주 돌았다고 검토자가 편중되게 끝나지 않아요. - Random — 각 수집 항목에 대해 집합에서 검토자를 무작위로 하나 뽑아요. 균등 분배보다 통계적 커버리지를 원할 때 유용해요.
Round robin은 이 ingestion task에 스코프된 검토자별 카운터를 추적해요. 검토자를 추가하거나 제거하면 다음 틱에서 순환이 재조정돼요 — 지금까지 가장 적게 배정받은 검토자가 먼저 뽑히므로 새로 온 사람이 자동으로 따라잡아요.
어떤 전략을 골라도 각 담당자는 앱 내 알림과 자기에게 라우팅된 항목 수를 요약하는 이메일을 받아요. 알림은 ingestion 실행별로 배치되므로, 한 틱이 한 검토자에게 열 항목을 배정해도 하나의 알림이 발화되지, 열 개가 아니에요.
저장하기
태스크를 저장해요. 새 항목이 다음 ingestion 틱부터 도착하기 시작해요 — 실행은 매 5분마다 돌아요.
작업 예시
단일 검토자 — 프로덕션의 피드백이 낮은 결제 트레이스 큐로, 가볍게 샘플링하고 한 검토자에게 자동 라우팅해요:
| Field | Value |
|---|---|
| Name | Billing Quality — low feedback |
| Filters | tag = "billing" AND feedback.rating < 3 AND env = "prod" |
| Sample Rate | 0.2 |
| Max Items | 200 |
| Strategy | Single user |
| Assign To | [email protected] |
활성화하면 태스크가 매 5분마다 매칭되는 트레이스 대략 다섯 개 중 하나를(총 200개로 상한) 수집하고 이름 붙은 검토자에게 배정해요.
팀 전체에 round robin — 모든 프로덕션 스레드 큐로, 세 명의 온콜 검토자에게 균등 배분해요:
| Field | Value |
|---|---|
| Name | Production threads — daily review |
| Filters | env = "prod" |
| Sample Rate | 1 |
| Max Items | (unset) |
| Strategy | Round robin |
| Reviewers | alice@…, bob@…, carol@… |
수집된 각 스레드는 이 태스크에서 지금까지 배정이 가장 적은 세 명 중 하나로 가요. 각 검토자는 틱당 배치된 하나의 알림으로 자신이 받은 항목 수를 받아요.
끝나면 인라인 스위치로 태스크를 비활성화해요 — 큐와 이미 수집된 항목은 그대로예요.
수동으로 추가한 항목과 함께 ingestion task를 실행할 수 있고, 같은 큐의 태스크 간에 전략을 섞을 수도 있어요(예: 대량 볼륨용 round-robin task 하나 + 특정 필터용 single-user task 하나). 검토자 UI는 둘을 구분하지 않아요 — 큐는 그냥 큐예요.
Eval Alignment
같은 큐 항목에서 메트릭 평가를 인간 어노테이션과 비교하고, 메트릭별 혼동 행렬 분해를 제공해요.
Error Analysis
인간 피드백에서 실패 패턴을 발견하고, 자동 감지용 메트릭 제안을 수락해요.