> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-hivemind-launch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# annotation 큐 설정
> annotation 큐를 생성하고, 트레이스를 도메인 전문가에게 전달하고, 구조화된 피드백을 내보냅니다.
export const GitHubLink = ({url}) =>
GitHub 소스 코드
;
export const ColabLink = ({url}) =>
Colab에서 사용해 보기
;
## Overview
annotation 큐를 사용하면 도메인 전문가가 전체 Weave UI로 이동하지 않고도 선택한 트레이스를 구조화된 방식으로 검토할 수 있도록 전달할 수 있습니다. 어떤 피드백을 수집할지 정의하고, 검토가 필요한 트레이스를 선택한 다음, 나중에 완료된 annotation을 분석하거나 데이터셋을 만드는 데 사용할 수 있도록 내보낼 수 있습니다. 사용 사례는 다음과 같습니다.
* **수동 트레이스 점수화**: SME가 모델 출력의 정확성, 품질, 스타일을 평가하도록 합니다.
* **실패 분석**: 실패 모드(환각, 거부, 루프)를 annotation하여 모델이 어디에서 문제가 생기는지 파악합니다.
* **도메인 전문가 검토**: 의료, 법률, 안전 분야 전문가가 작업 중심 인터페이스에서 콘텐츠를 검토할 수 있게 합니다.
* **데이터셋 생성**: annotation이 완료된 트레이스를 Evaluation 또는 트레이닝 데이터셋으로 전환합니다.
## 엔드투엔드 워크플로
다음 워크플로는 annotation 큐를 사용해 검토를 획득하는 과정을 요약합니다:
1. 어노테이션 필드를 정의합니다.
2. annotation 큐를 생성합니다.
3. 검토할 트레이스를 큐에 로드합니다.
4. 도메인 전문가가 검토를 완료하는 동안 진행 상황을 모니터링합니다.
5. 완료된 어노테이션을 필터링하고 내보냅니다.
## 어노테이션 필드 정의
어노테이션 큐를 만들기 시작하려면 먼저 어노테이션 필드를 정의해야 합니다. 그래야 큐를 설정할 때 해당 필드를 선택할 수 있습니다. 어노테이션 필드는 각 트레이스 항목에 대해 어노테이터가 제공하는 피드백을 정의합니다. 필드는 여러 큐와 프로젝트에서 재사용할 수 있습니다.
필드 유형은 다음과 같습니다.
* 정확성이나 수용 가능성과 같은 불리언 판단
* 품질이나 신뢰도와 같은 숫자 또는 정수 값
* 실패 모드나 의도와 같은 범주형 레이블
* 정성적 피드백을 위한 자유 형식 텍스트
어노테이션 필드를 만들려면 다음 단계를 따르세요.
1. [wandb.ai](https://wandb.ai)로 이동하여 프로젝트를 선택합니다.
2. Weave 프로젝트 사이드바에서 **Annotate**를 클릭합니다. **Annotate**가 보이지 않으면 **More** 아래 메뉴에 있을 수 있습니다.
3. 탭 바에서 **Fields** 탭을 클릭합니다.
4. Fields 테이블 툴바에서 **New Field**를 클릭합니다.
5. **Create annotation field** 모달 대화상자에서 다음을 설정합니다.
* **Type**: Boolean, Integer, Number, String 또는 범주형 옵션
* **Name**: 어노테이터에게 표시할 필드 이름
* **Description** (선택): 어노테이터에게 표시할, 이 필드를 평가하기 위한 세부 정보
6. **Create annotation field**를 클릭하여 필드를 저장합니다.
어노테이션의 일관성을 보장하기 위해 필드는 생성 후 수정할 수 없습니다.
## 주석 큐 만들기
주석 큐는 다음으로 구성됩니다.
* 주석 필드 세트
* 주석 작업자에게 작업 지침을 제공하는 가이드라인
* 검토를 기다리는 트레이스 항목 모음
주석 큐를 만들려면 다음 단계를 따르세요.
1. Weave 프로젝트 사이드바에서 **Annotate**를 클릭합니다.
2. 탭 바에서 **Queues** 탭을 클릭합니다.
3. Queues 테이블 툴바에서 **Create Queue**를 클릭합니다.
4. **Create Annotation Queue** 모달 대화상자에서 다음을 설정합니다.
* **Queue name**: 주석 작업자가 작업을 완료할 때 선택하는 큐 이름입니다.
* **Guidelines** (선택): 주석 작업자를 위한 추가 지침입니다.
5. **Next**를 클릭합니다.
6. **Manage fields**를 클릭하고 이번 검토 작업에 포함할 Annotation Fields를 선택합니다. 프로젝트의 기존 Annotation Fields는 모두 선택할 수 있습니다.
7. 큐에 사용할 모든 필드를 선택한 후 **Create Queue**를 클릭해 큐를 저장합니다.
프로젝트의 모든 주석 큐는 Annotation Queues 페이지에 나열됩니다.
주석 큐를 만들면 평가에 사용할 필드와 가이드라인이 정의되지만, 어떤 데이터를 평가할지 파악하려면 여전히 큐에 트레이스를 추가해야 합니다.
### 큐에 트레이스 추가
**트레이스** 페이지에서 직접 트레이스를 annotation queue에 추가합니다.
annotation queue에 트레이스를 추가하려면 다음과 같이 하세요.
1. Weave 프로젝트 사이드바에서 **트레이스**를 클릭합니다.
2. 트레이스 테이블 툴바에서 필요에 따라 트레이스를 필터링합니다(예: 할루시네이션 점수, 실패 모드 또는 특정 op 기준).
3. 테이블에서 annotation할 트레이스를 선택합니다.
4. 테이블의 작업 표시줄에서 **Add to queue**를 클릭해 선택한 행을 annotation queue에 추가합니다.
5. **Add to annotation queue** 모달 대화상자에서 다음을 설정합니다.
* **Queue Name**: 목록에서 이 트레이스를 추가할 기존 큐의 이름을 선택합니다.
* **Select trace data to display**: annotator가 결과를 평가할 때 표시할 Weave 트레이스 데이터 요소를 선택합니다.
* **Inputs**: annotation 중에 표시할 트레이스 입력 필드를 선택합니다.
* **Outputs**: annotation 중에 표시할 트레이스 출력 필드를 선택합니다.
6. **Add ***\[Count]*** traces to annotation queue**를 클릭하여 이 트레이스를 annotation queue 검토의 일부로 할당합니다.
트레이스를 추가할 때는 검토할 트레이스 입력과 출력 또는 모델 응답을 제어할 수 있습니다. 이렇게 하면 annotator가 정확한 판단을 내리는 데 필요한 맥락만 제시할 수 있습니다.
## 검토 진행 상황 모니터링
annotation queue를 생성하고 여기에 트레이스를 추가한 후, annotator가 검토를 시작할 수 있도록 큐 이름을 공유하세요. 검토 프로세스에 대한 자세한 내용은 [annotation queue에서 항목 검토하기](/ko/weave/guides/tracking/annotation-review)를 참조하세요.
annotator와 annotation queue의 직접 링크를 공유하려면 다음과 같이 하세요.
1. Weave 프로젝트 사이드바에서 **Annotate**를 클릭합니다.
2. 탭 바에서 **Queues** 탭을 클릭합니다.
3. Annotation Queues 테이블에서 큐 이름을 클릭해 큐 항목을 엽니다.
4. Queue 헤더 바에서 링크 버튼을 클릭해 이 큐의 직접 링크를 복사합니다. 브라우저 주소 표시줄에서 URL을 복사할 수도 있습니다.
Annotation Queues 테이블에서 **State** 열은 검토 진행 상황을 나타냅니다.
* **Not started**: 큐에 항목은 있지만 제출된 annotation은 없습니다.
* **In progress**: 하나 이상의 항목이 검토되었습니다.
* **Completed**: 모든 항목이 검토되었습니다.
Annotation Queues 테이블에서 **Calls with responses** 열은 제출된 검토가 하나 이상 있는 항목의 비율(전체 **Calls** 수 기준)을 나타냅니다.
## 어노테이션 필터링 및 내보내기
Weave는 완료된 어노테이션을 트레이스의 구조화된 메타데이터로 저장합니다.
다음을 할 수 있습니다:
* 큐 할당과 어노테이션 완료 여부를 기준으로 트레이스를 필터링합니다.
* 필터링한 뷰를 다시 사용할 수 있도록 저장합니다.
* 어노테이션된 트레이스를 평가 또는 트레이닝 워크플로용 데이터셋으로 내보냅니다.
이렇게 하면 전문가의 피드백을 모델 평가와 반복 개선에 직접 연결할 수 있습니다.
### 주석이 있는 트레이스 필터링
주석이 있는 트레이스만 표시하려면 **Traces** 페이지의 필터 컨트롤을 사용할 수 있습니다.
주석이 있는 트레이스만 보려면 다음과 같이 하세요.
1. Weave 프로젝트 사이드바에서 **Traces**를 클릭합니다.
2. Traces 테이블 툴바에서 **Filter**를 클릭합니다.
3. 필터 행에 값 3개를 추가합니다.
* **Column**에 "Queue"를 입력한 다음 **Enter**를 누릅니다.
* 두 번째 목록에서 \*\*Text: "is"\*\*를 선택합니다.
* **Select a queue**에서 주석 큐 이름을 선택합니다.
4. 'completed' 큐 항목만 추가로 필터링하려면 **+ Add Filter**를 클릭합니다.
* **Column**에 "feedback"을 입력합니다. 그러면 Annotations가 포함되고 Annotation Field 이름이 표시된 대화상자가 나타납니다. 큐에서 필수 Field를 선택합니다.
* 두 번째 목록에서 \*\*Other: "is not empty"\*\*를 선택합니다.
4. 필터 행은 자동으로 적용됩니다. 필터 항목을 닫으려면 페이지의 다른 곳을 클릭합니다.
5. (선택 사항) 빠르게 액세스할 수 있도록 뷰로 저장합니다. Traces 테이블 헤더에서 **Save View**를 클릭합니다.
### 주석 처리된 트레이스를 Datasets로 내보내기
데이터를 어떻게 사용할지에 따라 UI 또는 프로그래밍 방식으로 주석 처리된 트레이스를 내보낼 수 있습니다.
#### 주석 처리된 트레이스를 데이터셋에 추가
주석 처리된 트레이스를 선택한 다음 **데이터셋에 추가**를 클릭하여 eval 또는 트레이닝 데이터에 전문가 레이블을 포함하세요.
주석 처리된 트레이스를 데이터셋에 추가하려면 다음과 같이 하세요:
1. Weave 프로젝트 사이드바에서 **Traces**를 클릭합니다.
2. Traces 테이블에서 내보내려는 트레이스를 선택합니다.
3. 테이블 툴바에서 **데이터셋에 추가**를 클릭합니다. 화면의 안내에 따라 추가를 완료합니다.
데이터셋 사용 방법에 대해 자세히 알아보려면 [데이터셋 수집 및 추적](/ko/weave/guides/core-types/datasets)을 참조하세요.
## 프로그래밍 방식으로 어노테이션에 액세스
어노테이션을 프로그래밍 방식으로 통합하려면 프로젝트 이름과 큐 ID를 알아야 합니다:
* **Project**: W\&B 프로젝트 이름입니다(`project` 또는 `team/project` 형식일 수 있음). W\&B 팀(예: "team/project")을 지정하지 않으면 기본 팀이 사용됩니다.
* **Queue ID**: 어노테이션 큐의 고유 식별자입니다.
큐 ID를 찾으려면:
1. **Annotation Queues** 테이블에서 큐 이름을 선택해 해당 항목을 엽니다.
2. 페이지 URL 끝부분의 ID를 복사합니다.
**예시**
```
https://wandb.ai/.../annotation-queues/019c0f63-7acb-7497-8f87-08873368fcd4
```
이 예제에서 큐 ID는 다음과 같습니다.
019c0f63-7acb-7497-8f87-08873368fcd4
다음 코드를 사용하면 큐에 있는 트레이스(call)를 순회할 수 있습니다.
```python lines theme={null}
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)
# 큐에 있는 calls에서 call ID를 조회합니다.
calls = client.server.annotation_queue_items_query(
AnnotationQueueItemsQueryReq(
project_id=PROJECT,
queue_id=QUEUE_ID,
)
)
# calls를 순회하며 피드백을 조회합니다.
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("항목에 대한 피드백 없음")
continue
# 첫 번째 annotation 값을 조회합니다.
# 필드 annotation은 고정된 순서로 추가되지 않으므로 첫 번째 필드는 달라질 수 있습니다.
field_name = next(iter(feedback))
field_value = feedback[0]
print(f" {field_name}: {field_value}")
```
다음 Google Colab 노트북은 프로그래밍 방식으로 annotation 데이터에 접근하고 분석 리포트를 수집하는 자세한 예제를 제공합니다:
어노테이션의 일관성을 보장하기 위해 필드는 생성 후 수정할 수 없습니다.
주석 큐를 만들면 평가에 사용할 필드와 가이드라인이 정의되지만, 어떤 데이터를 평가할지 파악하려면 여전히 큐에 트레이스를 추가해야 합니다.
5. **Add to annotation queue** 모달 대화상자에서 다음을 설정합니다.
* **Queue Name**: 목록에서 이 트레이스를 추가할 기존 큐의 이름을 선택합니다.
* **Select trace data to display**: annotator가 결과를 평가할 때 표시할 Weave 트레이스 데이터 요소를 선택합니다.
* **Inputs**: annotation 중에 표시할 트레이스 입력 필드를 선택합니다.
* **Outputs**: annotation 중에 표시할 트레이스 출력 필드를 선택합니다.
6. **Add ***\[Count]*** traces to annotation queue**를 클릭하여 이 트레이스를 annotation queue 검토의 일부로 할당합니다.
트레이스를 추가할 때는 검토할 트레이스 입력과 출력 또는 모델 응답을 제어할 수 있습니다. 이렇게 하면 annotator가 정확한 판단을 내리는 데 필요한 맥락만 제시할 수 있습니다.
Annotation Queues 테이블에서 **State** 열은 검토 진행 상황을 나타냅니다.
* **Not started**: 큐에 항목은 있지만 제출된 annotation은 없습니다.
* **In progress**: 하나 이상의 항목이 검토되었습니다.
* **Completed**: 모든 항목이 검토되었습니다.
Annotation Queues 테이블에서 **Calls with responses** 열은 제출된 검토가 하나 이상 있는 항목의 비율(전체 **Calls** 수 기준)을 나타냅니다.
4. 필터 행은 자동으로 적용됩니다. 필터 항목을 닫으려면 페이지의 다른 곳을 클릭합니다.
5. (선택 사항) 빠르게 액세스할 수 있도록 뷰로 저장합니다. Traces 테이블 헤더에서 **Save View**를 클릭합니다.