어노테이션 큐 설정

어노테이션 큐를 생성하고, 트레이스를 도메인 전문가에게 라우팅하며, 구조화된 피드백을 내보냅니다.

​

개요

Annotation queue를 사용하면 선택한 trace를 도메인 전문가에게 전달하여, 전체 Weave UI를 탐색할 필요 없이 구조화된 검토를 진행할 수 있습니다. 수집할 피드백을 정의하고, 어떤 trace가 검토가 필요한지 선택한 뒤, 나중에 완료된 annotation을 내보내어 분석이나 데이터셋 생성을 수행할 수 있습니다. 주요 사용 사례는 다음과 같습니다:

• 수동 trace 스코어링: SME(Subject Matter Expert)가 모델 출력의 정확성, 품질, 스타일을 평가하도록 합니다.
• 실패 분석: hallucination, 거절, 루프와 같은 실패 모드를 annotation하여 모델에 어떤 문제가 발생하는지 파악합니다.
• 도메인 전문가 검토: 의료, 법률, 안전 전문가가 작업 중심 인터페이스로 콘텐츠를 검토할 수 있게 합니다.
• 데이터셋 생성: annotation된 trace를 평가 또는 트레이닝 데이터셋으로 변환합니다.

​

엔드 투 엔드 워크플로

다음 워크플로는 어노테이션 큐를 사용해 검토를 수행하는 전체 과정을 요약합니다.

1. 어노테이션 필드를 정의합니다.
2. 어노테이션 큐를 생성합니다.
3. 검토할 트레이스를 큐에 로드합니다.
4. 도메인 전문가가 검토를 완료하는 동안 진행 상황을 모니터링합니다.
5. 완료된 어노테이션을 필터링하고 내보냅니다.

​

애노테이션 필드 정의

애노테이션 큐를 생성하려면 먼저 애노테이션 필드를 정의해야 하며, 이렇게 정의한 필드는 큐 설정 시 선택할 수 있습니다. 애노테이션 필드는 애노테이터가 각 트레이스 항목에 대해 제공하는 피드백의 항목을 정의합니다. 필드는 여러 큐와 프로젝트에서 재사용할 수 있습니다.

필드 유형에는 다음이 포함됩니다:

• 정답 여부나 허용 가능성처럼 불리언 판단.
• 품질이나 신뢰도처럼 숫자(정수 포함) 값.
• 실패 모드나 의도처럼 범주형 레이블.
• 정성적 피드백을 위한 자유 형식 텍스트.

애노테이션 필드를 생성하려면:

1. 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 페이지에 나열됩니다.

주석 대기열을 생성하면 평가에 사용할 필드와 가이드라인이 정의되지만, 어떤 데이터를 평가할지 지정하려면 여전히 트레이스를 대기열에 추가해야 합니다.

​

트레이스를 큐에 추가하기

트레이스는 Traces 페이지에서 직접 어노테이션 큐에 추가할 수 있습니다.

트레이스를 어노테이션 큐에 추가하려면:

1. Weave 프로젝트 사이드바에서 Traces를 클릭합니다.
2. Traces 테이블 툴바에서 필요에 따라 트레이스를 필터링합니다(예: hallucination 점수, 실패 모드, 특정 op 등).
3. 테이블에서 어노테이션할 트레이스를 선택합니다.
4. 테이블의 작업 막대에서 Add to queue를 클릭하여 선택한 행을 어노테이션 큐에 추가합니다.

5. Add to annotation queue 모달 대화상자에서 다음을 설정합니다:
   • Queue Name: 목록에서 이 트레이스들을 추가할 기존 큐의 이름을 선택합니다.
   • Select trace data to display: 어노테이터가 결과를 평가할 때 표시할 Weave 트레이스 데이터 요소를 선택합니다.
     • Inputs: 어노테이션 중에 표시할 트레이스 입력 필드를 선택합니다.
     • Outputs: 어노테이션 중에 표시할 트레이스 출력 필드를 선택합니다.
6. **어노테이션 큐에 트레이스 ***[Count]*개 추가를 클릭하여 이 트레이스들을 어노테이션 큐 검토 항목으로 할당합니다.

트레이스를 추가할 때, 어떤 트레이스 입력과 어떤 출력 또는 모델 응답을 검토할지 제어할 수 있습니다. 이렇게 하면 어노테이터에게 정확한 판단을 내리는 데 필요한 컨텍스트만 제공할 수 있습니다.

​

검토 진행 상황 모니터링

annotation 큐를 생성하고 trace를 추가한 다음, 검토자가 검토를 시작할 수 있도록 큐 이름을 공유하세요. 검토 프로세스에 대한 자세한 내용은 annotation 큐에서 항목 검토하기를 참조하세요.

annotation 큐에 대한 직접 링크를 검토자와 공유하려면:

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는 완료된 어노테이션을 트레이스의 구조화된 메타데이터로 저장합니다.

다음을 수행할 수 있습니다:

• 큐 할당 상태와 어노테이션 완료 여부로 트레이스를 필터링합니다.
• 필터링된 보기를 저장해 다시 사용할 수 있습니다.
• 평가 또는 트레이닝 워크플로우를 위해 어노테이션된 트레이스를 데이터셋으로 내보냅니다.

이를 통해 전문가의 피드백을 모델 평가 및 반복 과정과 직접 연결할 수 있습니다.

​

주석이 달린 Trace 필터링

Traces 페이지의 필터 컨트롤을 사용해 주석이 달린 Trace만 표시할 수 있습니다.

주석이 달린 Trace만 보려면:

1. Weave 프로젝트 사이드바에서 Traces를 클릭합니다.
2. Traces 테이블 툴바에서 Filter를 클릭합니다.
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를 클릭합니다.

​

주석이 달린 트레이스를 데이터셋으로 내보내기

데이터 활용 방식에 따라 UI 또는 프로그래밍 방식으로 주석이 달린 트레이스를 내보낼 수 있습니다.

​

주석이 달린 트레이스를 데이터셋에 추가하기

주석이 달린 트레이스를 선택하고 Add to Dataset을 클릭하여 평가(eval) 또는 트레이닝 데이터에 전문가 레이블을 포함합니다.

주석이 달린 트레이스를 데이터셋에 추가하려면:

1. Weave 프로젝트 사이드바에서 Traces를 클릭합니다.
2. Traces 표에서 내보낼 트레이스를 선택합니다.
3. 표 도구 모음에서 Add to dataset을 클릭합니다. 화면의 안내에 따라 추가를 완료합니다.

데이터셋 사용 방법에 대한 자세한 내용은 데이터셋 수집 및 추적을 참고하세요.

​

애노테이션에 프로그래밍 방식으로 접근하기

애노테이션을 코드로 연동하려면 프로젝트 이름과 큐 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

다음 코드를 사용해 큐에 있는 트레이스(호출)를 순회할 수 있습니다.

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)

# 큐에 있는 호출에서 호출 ID를 가져옵니다.
calls = client.server.annotation_queue_items_query(
    AnnotationQueueItemsQueryReq(
        project_id=PROJECT,
        queue_id=QUEUE_ID,
    )
)

# 호출을 순회하며 피드백을 가져옵니다.
for i, item in enumerate(calls.items):
    call = client.get_call(call_id=item.call_id, include_feedback=True)
    feedback = call.feedback or {}

    # 호출에 대한 총 피드백 항목 수를 계산합니다.
    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 노트북은 주석 데이터에 프로그래밍 방식으로 접근하고 분석 리포트를 생성하는 방법을 자세한 예제로 보여줍니다:

Colab에서 실행해 보기GitHub 소스