> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 어노테이션 큐 설정
> 어노테이션 큐를 생성하여 트레이스를 도메인 전문가에게 할당하고, 구조화된 피드백을 내보냅니다.
export const GitHubLink = ({url, compact = false}) =>
{compact ? "View source" : <>
GitHub source
}
;
export const ColabLink = ({url}) =>
Try in Colab
;
개요
이 가이드에서는 Weave에서 어노테이션 큐를 설정하고, 선택한 트레이스에 대해 도메인 전문가로부터 구조화된 피드백을 수집하는 방법을 설명합니다. 평가, 실패 분석 또는 데이터셋 생성에 전문가가 레이블을 지정한 데이터가 필요하다면 어노테이션 큐를 사용하세요. 어노테이션 큐를 사용하면 검토자가 Weights & Biases UI 전체를 살펴볼 필요 없이 선별된 트레이스에만 집중할 수도 있습니다.
어노테이션 큐를 사용하면 선택한 트레이스를 도메인 전문가에게 전달해 구조화된 검토를 받을 수 있으며, 전문가는 Weights & Biases UI 전체를 탐색할 필요가 없습니다. 수집할 피드백을 정의하고 검토가 필요한 트레이스를 선택한 뒤, 완료된 어노테이션을 내보내 분석하거나 데이터셋을 생성하는 데 활용할 수 있습니다. 사용 사례는 다음과 같습니다.
* **수동 트레이스 점수화**: SME가 모델 출력의 정확성, 품질 또는 스타일을 평가합니다.
* **실패 분석**: 실패 유형(할루시네이션, 응답 거부, 루프)에 어노테이션을 달아 모델이 어디에서 실패하는지 파악합니다.
* **도메인 전문가 검토**: 의료, 법률 또는 안전 분야 전문가가 작업 중심 인터페이스에서 콘텐츠를 검토할 수 있습니다.
* **데이터셋 생성**: 어노테이션된 트레이스를 평가용 또는 트레이닝용 데이터셋으로 만듭니다.
엔드투엔드 워크플로
다음은 어노테이션 큐를 사용해 리뷰를 획득하는 워크플로를 요약한 것입니다. 각 단계는 이어지는 섹션에서 자세히 설명합니다.
1. 어노테이션 필드를 정의합니다.
2. 어노테이션 큐를 생성합니다.
3. 리뷰할 트레이스를 큐에 로드합니다.
4. 도메인 전문가가 리뷰를 진행하는 동안 진행 상황을 모니터링합니다.
5. 완료된 어노테이션을 필터링하고 내보냅니다.
어노테이션 필드 정의하기
어노테이션 큐를 만들기 전에 어노테이션 필드를 먼저 정의해 두어야 큐를 설정할 때 선택할 수 있습니다. 어노테이션 필드는 어노테이터가 각 트레이스 항목에 대해 제공하는 피드백을 정의합니다. 필드는 여러 큐와 프로젝트에서 재사용할 수 있습니다.
필드 유형은 다음과 같습니다.
* 정확성이나 허용 가능 여부와 같은 불리언 판단
* 품질이나 신뢰도와 같은 숫자 또는 정수 값
* 실패 유형이나 의도와 같은 범주형 레이블
* 정성적 피드백을 위한 자유 형식 텍스트
어노테이션 필드를 만들려면 다음 단계를 따르세요.
1. [Forge](https://forge.coreweave.com/wandb)로 이동하여 프로젝트를 선택하세요.
2. Weave 프로젝트 사이드바에서 **Annotate**를 클릭하세요. **Annotate**가 보이지 않으면 **More** 메뉴 아래에 있을 수 있습니다.
3. 탭 바에서 **Fields** 탭을 클릭하세요.
4. Fields table 툴바에서 **New Field**를 클릭하세요.
5. **Create annotation field** 모달 대화 상자에서 다음 항목을 설정하세요.
* **Type**: Boolean, Integer, Number, String 또는 범주형 옵션.
* **Name**: 어노테이터에게 표시할 필드 이름.
* **Description** (선택): 어노테이터에게 표시할, 이 필드의 평가 기준에 대한 세부 설명.
6. **Create annotation field**를 클릭하여 필드를 저장하세요.
새 필드는 **Fields** 탭에 표시되며, 프로젝트 내 모든 어노테이션 큐에 추가할 수 있습니다.
어노테이션의 일관성을 유지하기 위해 필드는 생성한 후에는 편집할 수 없습니다.
어노테이션 큐 만들기
어노테이션 필드를 정의했다면 이제 어노테이터가 작업할 큐를 만들 차례입니다. 어노테이션 큐는 다음으로 구성됩니다.
* 어노테이션 필드 세트
* 어노테이터에게 작업 방법을 안내하는 가이드라인
* 검토를 기다리는 트레이스 항목 컬렉션
어노테이션 큐를 만들려면 다음 단계를 따르세요.
1. Weave 프로젝트 사이드바에서 **Annotate**를 클릭하세요.
2. 탭 바에서 **Queues** 탭을 클릭하세요.
3. Queues table 툴바에서 **Create Queue**를 클릭하세요.
4. **Create Annotation Queue** 모달 대화 상자에서 다음 항목을 설정하세요.
* **Queue name**: 어노테이터가 작업할 때 선택하는 큐 이름입니다.
* **Guidelines** (선택): 어노테이터에게 전달할 추가 지침입니다.
5. **Next**를 클릭하세요.
6. **Manage fields**를 클릭하고 이 검토 작업에 포함할 어노테이션 필드를 선택하세요. 프로젝트에 있는 모든 어노테이션 필드를 선택할 수 있습니다.
7. 큐에 사용할 필드를 모두 선택했으면 **Create Queue**를 클릭하여 큐를 저장하세요.
프로젝트의 모든 어노테이션 큐는 Annotation Queues 페이지에서 확인할 수 있습니다.
어노테이션 큐를 만들면 평가에 사용할 필드와 가이드라인이 정의됩니다. 하지만 평가할 데이터를 지정하려면 큐에 트레이스를 추가해야 합니다.
큐에 트레이스 추가하기
큐를 만든 후에는 검토할 트레이스를 골라 큐에 추가합니다. 어노테이션 큐에 트레이스를 추가하는 작업은 **Traces** 페이지에서 바로 할 수 있습니다.
어노테이션 큐에 트레이스를 추가하려면 다음을 수행하세요.
1. Weave 프로젝트 사이드바에서 **Traces**를 클릭하세요.
2. Traces table 툴바에서 필요에 따라 트레이스를 필터링하세요(예: 할루시네이션 점수, 실패 유형, 특정 Op 기준).
3. table에서 어노테이션할 트레이스를 선택하세요.
4. table의 액션 바에서 **Add to queue**를 클릭하여 선택한 행을 어노테이션 큐에 추가하세요.
5. **Add to annotation queue** 모달 대화 상자에서 다음을 설정하세요.
* **Queue Name**: 목록에서 트레이스를 추가할 기존 큐의 이름을 선택하세요.
* **Select trace data to display**: 어노테이터가 결과를 평가할 때 표시할 Weave 트레이스 데이터 요소를 선택하세요.
* **Inputs**: 어노테이션 중에 표시할 트레이스 입력 필드를 선택하세요.
* **Outputs**: 어노테이션 중에 표시할 트레이스 출력 필드를 선택하세요.
6. **Add `[COUNT]` traces to annotation queue**를 클릭하여 선택한 트레이스를 어노테이션 큐의 검토 대상으로 지정하세요.
트레이스를 추가할 때 검토할 트레이스 입력과 출력(또는 모델 응답)을 직접 지정할 수 있으므로, 어노테이터에게는 정확한 판단에 필요한 컨텍스트만 표시됩니다.
검토 진행 상황 모니터링
트레이스를 추가하면 어노테이터가 작업을 시작할 수 있으며, 검토가 어떻게 진행되는지 추적할 수 있습니다. 어노테이터가 검토를 시작할 수 있도록 큐 이름을 공유하세요. 검토 프로세스에 대한 자세한 내용은 [어노테이션 큐의 항목 검토](/ko/products/wandb/weave/guides/tracking/annotation-review)를 참조하세요.
어노테이터에게 어노테이션 큐의 직접 링크를 공유하려면 다음 단계를 따르세요.
1. Weave 프로젝트 사이드바에서 **Annotate**를 클릭합니다.
2. 탭 표시줄에서 **Queues** 탭을 클릭합니다.
3. Annotation Queues table에서 큐 이름을 클릭하여 큐 항목을 엽니다.
4. Queue 헤더 표시줄에서 링크 버튼을 클릭하여 이 큐의 직접 링크를 복사합니다. 브라우저 주소 표시줄에서 URL을 복사해도 됩니다.
Annotation Queues table의 **State** 열에서 검토 진행 상황을 확인할 수 있습니다.
* **Not started**: 큐에 항목은 있지만 아직 제출된 어노테이션이 없습니다.
* **In progress**: 하나 이상의 항목이 검토되었습니다.
* **Completed**: 모든 항목이 검토되었습니다.
Annotation Queues table의 **Calls with responses** 열은 전체 **Calls** 수 중 제출된 검토가 하나 이상 있는 항목의 비율을 나타냅니다.
어노테이션 필터링 및 내보내기
어노테이터가 검토를 제출하면 그 결과로 수집된 피드백을 분석, 평가 또는 트레이닝에 활용할 수 있습니다. Weave는 완료된 어노테이션을 트레이스에 구조화된 메타데이터로 저장합니다.
다음 작업을 수행할 수 있습니다.
* 큐 할당 및 어노테이션 완료 여부를 기준으로 트레이스를 필터링합니다.
* 필터링된 뷰를 저장하여 재사용합니다.
* 어노테이션된 트레이스를 데이터셋으로 내보내 평가 또는 트레이닝 워크플로에 사용합니다.
이를 통해 전문가의 인적 피드백을 모델 평가 및 반복 개선에 곧바로 반영할 수 있습니다.
어노테이션된 트레이스 필터링
**Traces** 페이지의 필터 컨트롤을 사용하면 어노테이션이 있는 트레이스만 표시할 수 있습니다.
어노테이션이 있는 트레이스만 보려면 다음 단계를 따르세요.
1. Weave 프로젝트 사이드바에서 **Traces**를 클릭하세요.
2. Traces table 툴바에서 **Filter**를 클릭하세요.
3. 필터 행에 다음 세 가지 값을 추가하세요.
* **Column**에 "Queue"를 입력한 다음 **Enter** 키를 누르세요.
* 두 번째 목록에서 \*\*Text: "is"\*\*를 선택하세요.
* **Select a queue**에서 어노테이션 큐 이름을 선택하세요.
4. '완료된' 큐 항목만 추가로 필터링하려면 **+ Add Filter**를 클릭하세요.
* **Column**에 "feedback"을 입력하세요. 대화 상자에 어노테이션 필드 이름을 포함한 어노테이션 목록이 표시됩니다. 큐의 필수 필드 중 하나를 선택하세요.
* 두 번째 목록에서 \*\*Other: "is not empty"\*\*를 선택하세요.
5. 필터 행은 자동으로 적용됩니다. 필터 입력 창을 닫으려면 페이지의 다른 곳을 클릭하세요.
6. 선택 사항: 빠르게 액세스할 수 있도록 뷰로 저장하세요. Traces table 헤더에서 **Save View**를 클릭하면 됩니다.
어노테이션된 트레이스를 데이터셋으로 내보내기
데이터 활용 방식에 따라 어노테이션된 트레이스를 UI에서 내보내거나 프로그래밍 방식으로 내보낼 수 있습니다.
어노테이션된 트레이스를 데이터셋에 추가하기
어노테이션된 트레이스를 선택하고 **Add to dataset**을 클릭하면 전문가 레이블을 평가 데이터나 트레이닝 데이터에 포함할 수 있습니다.
어노테이션된 트레이스를 데이터셋에 추가하려면 다음 단계를 따르세요.
1. Weave 프로젝트 사이드바에서 **Traces**를 클릭합니다.
2. Traces table에서 내보낼 트레이스를 선택합니다.
3. table 툴바에서 **Add to dataset**을 클릭한 다음, 화면의 안내에 따라 추가를 완료합니다.
데이터셋 사용에 대한 자세한 내용은 [데이터셋 수집 및 추적](/ko/products/wandb/weave/guides/core-types/datasets)을 참조하세요.
프로그래밍 방식으로 어노테이션에 액세스하기
UI 워크플로 외에 프로그래밍 방식으로도 어노테이션 데이터를 조회할 수 있습니다. 이 방법은 분석을 자동화하거나, 맞춤형 보고서를 구축하거나, 어노테이션을 다운스트림 파이프라인에 통합할 때 유용합니다. 프로그래밍 방식으로 어노테이션을 통합하려면 프로젝트 이름과 큐 ID가 필요합니다.
* **Project**: Weights & Biases 프로젝트 이름입니다(project 또는 team/project 형식). CoreWeave Forge 팀을 지정하지 않으면(예: "team/project") 기본 팀이 사용됩니다.
* **Queue ID**: 어노테이션 큐의 고유 식별자입니다.
큐 ID를 확인하는 방법은 다음과 같습니다.
1. **Annotation Queues** table에서 큐 이름을 선택하여 해당 큐의 항목을 여세요.
2. 페이지 URL 끝에 있는 ID를 복사하세요.
**예시**
```text theme={"system"}
https://wandb.ai/.../annotation-queues/019c0f63-7acb-7497-8f87-08873368fcd4
```
이 예제에서 큐 ID는 다음과 같습니다.
`019c0f63-7acb-7497-8f87-08873368fcd4`
다음 코드를 사용하면 큐에 있는 트레이스(Call)를 순회할 수 있습니다.
```python lines theme={"system"}
import weave
from weave.trace_server.trace_server_interface import AnnotationQueueItemsQueryReq
# 프로젝트 및 큐 식별자를 실제 사용하는 값으로 변경하세요.
PROJECT = "your-team-name/your-project-name"
QUEUE_ID = "019c0f63-7acb-7497-8f87-08873368fcd4"
# Weave를 초기화합니다.
client = weave.init(PROJECT)
# 큐에 있는 Call의 call ID를 조회합니다.
calls = client.server.annotation_queue_items_query(
AnnotationQueueItemsQueryReq(
project_id=PROJECT,
queue_id=QUEUE_ID,
)
)
# 각 Call을 순회하며 피드백을 조회합니다.
for i, item in enumerate(calls.items):
call = client.get_call(call_id=item.call_id, include_feedback=True)
feedback = call.feedback or {}
# Call의 전체 피드백 항목 수를 계산합니다.
total_feedback_items = len(feedback)
print(f"\nItem {i}, call_id: {item.call_id}, total feedback items: {total_feedback_items}")
if not feedback:
print("No feedback for item")
continue
# 첫 번째 주석 값을 조회합니다.
# 필드 주석이 추가되는 순서는 매번 같지 않으므로 첫 번째 필드는 달라질 수 있습니다.
field_name = next(iter(feedback))
field_value = feedback[0]
print(f" {field_name}: {field_value}")
```
다음 Google Colab 노트북에서는 프로그래밍 방식으로 어노테이션 데이터에 액세스하고 분석 보고서를 생성하는 방법을 자세한 예시와 함께 보여 줍니다.
## Related topics
- [예시 코드 및 노트북](/ko/products/wandb/examples.md)
새 필드는 **Fields** 탭에 표시되며, 프로젝트 내 모든 어노테이션 큐에 추가할 수 있습니다.
어노테이션 큐를 만들면 평가에 사용할 필드와 가이드라인이 정의됩니다. 하지만 평가할 데이터를 지정하려면 큐에 트레이스를 추가해야 합니다.
5. **Add to annotation queue** 모달 대화 상자에서 다음을 설정하세요.
* **Queue Name**: 목록에서 트레이스를 추가할 기존 큐의 이름을 선택하세요.
* **Select trace data to display**: 어노테이터가 결과를 평가할 때 표시할 Weave 트레이스 데이터 요소를 선택하세요.
* **Inputs**: 어노테이션 중에 표시할 트레이스 입력 필드를 선택하세요.
* **Outputs**: 어노테이션 중에 표시할 트레이스 출력 필드를 선택하세요.
6. **Add `[COUNT]` traces to annotation queue**를 클릭하여 선택한 트레이스를 어노테이션 큐의 검토 대상으로 지정하세요.
트레이스를 추가할 때 검토할 트레이스 입력과 출력(또는 모델 응답)을 직접 지정할 수 있으므로, 어노테이터에게는 정확한 판단에 필요한 컨텍스트만 표시됩니다.
Annotation Queues table의 **State** 열에서 검토 진행 상황을 확인할 수 있습니다.
* **Not started**: 큐에 항목은 있지만 아직 제출된 어노테이션이 없습니다.
* **In progress**: 하나 이상의 항목이 검토되었습니다.
* **Completed**: 모든 항목이 검토되었습니다.
Annotation Queues table의 **Calls with responses** 열은 전체 **Calls** 수 중 제출된 검토가 하나 이상 있는 항목의 비율을 나타냅니다.
5. 필터 행은 자동으로 적용됩니다. 필터 입력 창을 닫으려면 페이지의 다른 곳을 클릭하세요.
6. 선택 사항: 빠르게 액세스할 수 있도록 뷰로 저장하세요. Traces table 헤더에서 **Save View**를 클릭하면 됩니다.