어노테이션 큐 사용하기

*어노테이션 큐(annotation queue)*는 특정 런이나 스레드에 피드백을 다는 사람 검토자 전용 워크플로우를 제공해요. 트레이스를 인라인으로 어노테이션할 수도 있지만, 어노테이션 큐를 쓰면 런과 스레드를 함께 묶고, 루브릭을 지정하고, 검토자의 진행 상황을 추적할 수 있답니다. 전체 스레드를 검토하면 다회차 대화 전체를 평가할 수 있어, 단일 런으로는 잡을 수 없는 품질 신호를 포착할 수 있어요.

출처: 문서

본문

어노테이션 큐는 인간 검토자가 특정 런 또는 스레드에 피드백을 연결하는 데 집중할 수 있는 워크플로우를 제공합니다. 트레이스를 항상 인라인으로 어노테이션할 수 있지만, 어노테이션 큐를 사용하면 런과 스레드를 함께 그룹화하고, 루브릭을 지정하고, 검토자 진행 상황을 추적할 수 있습니다. 전체 스레드를 검토하면 다회차 대화 전체를 평가하여 단일 런으로는 포착할 수 없는 품질 신호를 얻을 수 있습니다.

참고: SDK로 어노테이션 큐와 피드백 구성을 프로그래매틱하게 관리할 수도 있습니다. 피드백 및 어노테이션 큐를 프로그래매틱하게 관리하기를 참고하세요.

검토 중 런 출력이 표시되는 방식을 커스터마이즈하려면 어노테이션 큐용 커스텀 출력 렌더링 구성을 참고하세요.

LangSmith는 두 가지 큐 스타일을 지원합니다:

단일 런 어노테이션 큐 — 한 번에 하나의 큐 항목(런 또는 스레드)을 보여주며, 검토자는 구성한 루브릭 피드백을 제출할 수 있습니다. 런 항목의 경우 단일 런 큐는 오프라인 평가를 위한 수용 기준을 포착하는 assertions도 지원합니다.
짝 비교 어노테이션 큐 (PAQ) — 두 개의 런을 나란히 보여줘, 검토자가 정의한 루브릭 항목에 대해 어느 출력이 더 좋은지 (또는 동등한지) 빠르게 결정하게 해줍니다.

팁: 어노테이션 큐 사용 데모는 어노테이션 큐 시작하기 비디오 가이드를 시청하세요.

단일 런 어노테이션 큐

단일 런 큐는 한 번에 하나의 항목을 보여주며, 검토자가 구성한 루브릭 피드백을 제출할 수 있게 합니다. LangSmith UI의 Annotation queues 섹션에서 직접 만들 수 있습니다. 큐에는 런 항목과 스레드 항목이 섞여 있을 수 있습니다. 스레드 항목은 전체 대화를 나타내며, 런 항목과 동일한 루브릭으로 검토됩니다.

런 항목과 스레드 항목은 서로 다른 기능을 지원합니다:

기능	런 항목	스레드 항목
루브릭 피드백	예	예
검토자 메모	예	아니요
Assertions	예	아니요
데이터셋에 추가	예	예
기본 데이터셋	예	아니요
자동화 규칙	예	예

단일 런 큐 만들기

왼쪽 내비게이션에서 Annotation Queues로 이동합니다.
왼쪽 상단의 + Annotation Queue를 클릭해 Create Annotation Queue 패널을 엽니다.

기본 정보 (Basic details)

큐의 이름(Name) 과 설명(Description) 을 입력합니다.
선택적으로 Application을 선택합니다.
선택적으로 LangSmith 워크스페이스의 데이터셋으로 검토된 런을 내보내기 쉽게 하려면 기본 데이터셋(Select a default dataset) 을 선택합니다. 기본 데이터셋은 런 항목에 Add to Dataset을 사용할 때 적용됩니다. 스레드 항목은 기본 데이터셋을 지원하지 않습니다.

어노테이션 루브릭 (Annotation rubric)

어노테이터를 위한 Instructions를 몇 개 초안으로 작성합니다. 모든 항목의 사이드바에 표시됩니다.
+ Add a feedback rubric을 클릭해 어노테이션 큐에 피드백 키를 추가합니다. 어노테이터는 각 항목에서 이 피드백 키들을 보게 됩니다.
각각에 대한 설명과, 피드백 유형이 범주형(categorical)이면 각 범주에 대한 짧은 설명을 추가합니다.

검토자는 UI 오른쪽 패널에서 Instructions와 Feedback 세부 정보를 봅니다.

협업자 설정 (Collaborator settings)

항목을 협업자에게 예약할 검토자 수 또는 최대 시간을 설정합니다. 항목에 어노테이터가 여러 명일 때, 모든 검토자가 Done으로 표시할 때까지 항목을 큐에 유지하도록 선택할 수 있습니다. 이 설정에서 "run"은 스레드 항목을 포함한 모든 큐 항목을 가리킵니다. 설정은 다음과 같습니다:

All workspace members review each run: 활성화하면 모든 워크스페이스 멤버가 검토를 Done으로 표시할 때까지 항목이 큐에 남습니다.
Enable reservations on runs: 항목을 예약하면 설정된 시간 동안 검토용으로 잠깁니다. 항목이 예약된 동안 다른 검토자는 볼 수는 있지만 피드백이나 메모를 추가할 수는 없습니다. 모든 워크스페이스 멤버가 각 런을 검토하면 예약이 비활성화됩니다.

검토자가 항목을 봤는데 Done으로 표시하지 않고 떠나면, 지정된 Reservation length 이후 예약이 만료됩니다. 그러면 항목이 큐로 다시 풀려나 다른 검토자가 예약할 수 있습니다.

참고: 항목의 어노테이션에 대해 Requeue를 클릭하면 현재 항목을 현재 사용자의 큐 끝으로만 옮깁니다. 다른 사용자의 큐 순서에는 영향이 없습니다. 또한 현재 사용자가 그 항목에 걸어둔 예약도 해제합니다.
Number of reviewers per run: 항목이 큐에서 제거되기 위해 Done으로 표시해야 하는 검토자 수를 결정합니다.
- 검토자는 다른 검토자가 남긴 피드백을 볼 수 없습니다.
- 항목에 대한 주석은 모든 검토자가 볼 수 있습니다.
참고: Use assigned reviewers가 활성화되면 Number of reviewers per run 설정이 숨겨집니다 (아래 참고).
Use assigned reviewers: 개수 기반 임계값 대신 특정 워크스페이스 멤버를 사용하려면 이 토글을 활성화합니다. 활성화하면:
- 특정 워크스페이스 멤버를 할당 검토자로 선택할 수 있는 다중 선택 사용자 선택기가 나타납니다.
- 모든 할당 검토자가 검토를 제출했을 때만 항목이 Completed로 표시됩니다. 큐 항목은 세 가지 상태(Needs Review, Needs Others' Review, Completed)를 거칩니다.
- 할당되지 않은 워크스페이스 멤버도 항목을 어노테이션할 수 있지만, 그 제출은 완료에 포함되지 않습니다.
- 아무 워크스페이스 멤버나 큐 설정에서 할당 검토자 목록을 편집할 수 있습니다.
참고: 이미 완료된 항목이 있는 큐에 새 할당 검토자를 추가해도 해당 항목이 보류 상태로 되돌아가지 않습니다. 할당 검토자를 제거하면, 그가 아직 검토하지 않은 항목의 완료 상태가 다시 계산됩니다.

이 설정들 때문에 각 검토자에게 보이는 항목 수는 총 큐 크기와 다를 수 있습니다.

큐 설정 편집하기

편집하려는 어노테이션 큐에 대해 Edit Annotation Queue 패널을 엽니다. 이 패널에는 두 가지 방법으로 접근할 수 있습니다:
- Annotation queues 목록에서 큐 행 오른쪽의 Actions 아이콘을 클릭하고, 드롭다운에서 Edit을 선택합니다.
- 어노테이션 큐 뷰에서 오른쪽 상단의 Settings 아이콘을 클릭합니다.
Edit Annotation Queue 패널에서 큐 생성 시 구성한 설정을 수정하고 Save를 클릭합니다.

단일 런 큐에 런과 스레드 할당하기

단일 런 큐에 항목을 채우는 방법은 여러 가지가 있습니다:

Details 뷰에서: 트레이싱 프로젝트에서 아무 행이나 클릭해 Details 뷰의 사이드 패널을 엽니다. 패널은 각각 고정된 범위를 가진 두 가지 작업을 제공합니다:
- Add to : 런 헤더에서 이 메뉴를 열고 Add to Annotation Queue를 선택합니다. 이렇게 하면 선택한 런이 런 항목으로 추가됩니다.
- Add thread to annotation queue : Trajectory, Turns, Details 탭 옆의 아이콘을 클릭합니다. 이렇게 하면 전체 스레드가 스레드 항목으로 추가됩니다.
두 작업 모두 기존 큐를 선택하거나 새 큐를 만들 수 있는 팝오버를 엽니다.

참고: 스레드 작업은 thread_id / session_id 메타데이터로 계측된 런에만 나타납니다. 해당 메타데이터가 없으면 패널은 런을 독립적으로 열고 런 작업만 사용 가능합니다.
Traces 또는 Runs 탭에서: 트레이싱 프로젝트에서 Traces 또는 Runs 탭을 선택합니다. 행 체크박스로 하나 이상의 항목을 선택하고, 페이지 하단의 Add to Annotation Queue를 클릭합니다. What to add를 사용해 각 선택 항목을 Selected run 또는 Entire thread로 큐에 넣습니다.
Threads 탭에서: 트레이싱 프로젝트에서 Threads 탭을 선택합니다. 행 체크박스로 하나 이상의 항목을 선택하고, 페이지 하단의 Add to Annotation Queue를 클릭합니다. 선택된 스레드는 스레드 항목으로 추가됩니다.
자동화 규칙: 규칙을 설정하여 필터와 일치하는(예: 오류 또는 낮은 사용자 점수) 런 또는 스레드를 큐에 자동으로 할당합니다.

참고: 규칙이 무엇을 큐에 넣는지는 항목 유형에 따라 달라집니다. 항목 유형이 Runs인 규칙은 런 항목을 큐에 넣습니다. 항목 유형이 Threads인 규칙은 스레드가 유휴 상태가 되면 전체 대화를 스레드 항목으로 큐에 넣습니다.
데이터셋 및 실험: 데이터셋 내에서 하나 이상의 실험을 선택하고 Annotate를 클릭합니다. Add to Annotation Queue를 선택한 다음 기존 큐를 선택하거나 새 큐를 만듭니다. 실험 어노테이션 흐름은 런 항목을 추가합니다.

참고: 한 번의 동작으로 어노테이션 큐에 최대 100개의 런 또는 스레드를 추가할 수 있습니다. 더 추가하려면 100개 이하 배치로 추가 흐름을 반복하세요.

어노테이션 큐에 런이나 스레드를 수동으로 추가하는 것은 기본적으로 트레이스 보존 기간을 변경하지 않습니다. 다른 작업으로 명시적으로 보존 기간을 연장하지 않는 한, 트레이스는 해당 프로젝트에 구성된 보존 기간을 유지합니다. 자동화 규칙에 의한 추가는 다릅니다: 규칙의 Extend Data Retention 토글이 어노테이션 큐 동작에 대해 기본적으로 활성화되어 있습니다. 런 규칙은 일치하는 각 런을 포함하는 전체 트레이스를 업그레이드하고, 스레드 규칙은 일치하는 스레드의 모든 트레이스를 업그레이드합니다. 전체 보존 모델은 데이터 보존 자동 업그레이드를 참고하세요.

단일 런 큐 검토하기

왼쪽 내비게이션 바를 통해 Annotation Queues 섹션으로 이동합니다.

큐 목록에는 각 큐에 어떤 검토자가 할당되었는지 보여주는 Assigned Reviewers 열이 포함됩니다. 자신에게 할당된 큐만 보려면 목록 상단의 Assigned to me 필터를 클릭합니다.
검토하려는 큐를 클릭합니다. 그러면 검토가 필요한 큐 항목의 집중형 순환 뷰로 이동합니다. 왼쪽 사이드 패널은 큐 항목(런 및 스레드)을 나열하고 각 상태(Needs Review, Needs Others' Review, Completed)를 보여줍니다. View all items를 사용해 전체 큐 목록을 엽니다.
현재 항목을 검토합니다:
- 런 항목: 가운데 패널에서 입력과 출력을 검사합니다. Reviewer Notes를 추가하고 Feedback 기준에 점수를 매기거나, 항목을 검토됨으로 표시합니다. 데이터셋을 만들려면 런의 입력과 출력을 편집해 수정된 기준 예제를 만들고 Add to Dataset을 클릭합니다. 수정된 기준 출력을 손으로 만들 필요 없이, 검토 사이드 패널에 Assertions을 직접 작성해 예제의 기대 출력으로 저장할 수 있습니다.
- 스레드 항목: 가운데 패널에 스레드의 대화 대화록(transcript)이 표시됩니다. 대화록을 읽고 루브릭 Feedback 기준에 점수를 매깁니다. View item을 클릭해 대화창(conversation peek)에서 스레드를 엽니다. 전체 대화를 한 예제로 데이터셋에 추가하려면 Add to Dataset을 클릭한 다음 데이터셋을 선택합니다. 선택기에서 데이터셋을 만들려면 New Dataset을 클릭합니다. 스레드 예제에 무엇이 포함되는지 알아보려면 UI에서 데이터셋 생성 및 관리를 참고하세요.
Delete를 클릭하면 현재 예약이나 큐 설정과 관계없이 모든 사용자에 대해 항목이 큐에서 제거됩니다.

참고: 스레드 항목의 경우 루브릭 피드백 제출과 Add to Dataset 사용이 가능합니다. 검토자 메모와 assertions는 사용할 수 없습니다. 런/스레드 항목 기능 비교는 기능 표를 참고하세요.

어노테이션 큐를 검토하면서 제출한 피드백과 메모는 트레이스의 보존 등급을 변경하지 않습니다.

팁: 각 옵션 옆의 키보드 단축키를 사용하면 더 빠르게 검토할 수 있습니다.

짝 비교 어노테이션 큐

짝 비교 어노테이션 큐(PAQ)는 두 개의 런을 나란히 보여줘, 검토자가 정의한 루브릭 항목에 대해 어느 출력이 더 좋은지(또는 동등한지) 빠르게 결정하게 해줍니다. 두 실험(종종 기준선 vs. 후보 모델) 간의 빠른 A/B 비교를 위해 설계되었으며, Datasets & Experiments 페이지에서만 만들 수 있습니다. 짝 비교 큐는 런 비교만 사용하며, 스레드 항목은 큐에 넣지 않습니다.

짝 비교 큐 만들기

Datasets & Experiments로 이동해 데이터셋을 열고, 비교할 정확히 두 개의 실험을 선택합니다.
Annotate를 클릭합니다. 팝오버에서 Add to Pairwise Annotation Queue를 선택합니다. (버튼은 정확히 두 실험을 선택하기 전까지 비활성화됩니다.)
실험을 기존 짝 비교 큐로 보낼지 새로 만들지를 결정합니다.
큐 세부 정보를 제공합니다:
- 기본 정보 (이름과 설명)
- 짝 비교 점수에 맞춘 Instructions & rubrics
- 협업자 설정 (검토자 수, 예약, 예약 길이)
양식을 제출해 큐를 만듭니다. LangSmith는 즉시 두 실험의 런을 짝지어 큐를 채웁니다.

짝 비교 어노테이션 큐를 만들거나 채우는 것은 기본적으로 트레이스 보존 기간을 변경하지 않습니다. 런은 큐에 추가되기 전의 보존 등급을 유지합니다.

PAQ의 주요 차이점:

실험: 사전에 두 개의 실험 세션을 제공해야 합니다. LangSmith는 생성 중에 그 런들을 시간순으로 자동 짝지어 큐를 채웁니다.
루브릭: 짝 비교 루브릭 항목은 피드백 키와 (선택적으로) 설명만 필요합니다. 어노테이터는 각 루브릭 항목에 대해 Run A, Run B, 또는 둘 다가 더 나은지 결정합니다.
데이터셋: 짝 비교 큐는 비교가 두 실험에 걸쳐 있으므로 기본 데이터셋을 사용하지 않습니다.
예약 및 검토자: 동일한 협업자 컨트롤이 적용됩니다. 예약은 두 사람이 동시에 같은 비교를 평가하지 못하게 방지합니다.

짝 비교 큐에 비교 항목 더 추가하기

나중에 비교 항목을 더 추가해야 한다면 Datasets & Experiments로 돌아가 두 실험을 다시 선택하고 Add to Pairwise Annotation Queue를 선택해 새 쌍을 추가합니다.

두 실험을 선택하고 PAQ를 만들면 런이 자동으로 짝지어집니다. 기존 PAQ를 확장할 때 LangSmith는 기존 비교를 보존하고 새 쌍을 큐에 추가합니다.

짝 비교 큐 검토하기

Annotation queues에서 검토할 짝 비교 큐를 선택합니다.
각 큐 항목은 왼쪽에 Run A, 오른쪽에 Run B와 함께 루브릭을 보여줍니다.
모든 루브릭 항목에 대해:
- A is better, B is better, 또는 Equal을 선택합니다. UI는 백그라운드에서 두 런 모두에 이진 피드백을 기록합니다.
- A, B, 또는 E 핫키를 사용해 선택을 확정합니다.
모든 루브릭 항목을 마치면 Done을 누르거나(마지막 루브릭 항목에서 Enter) 다음 비교로 진행합니다.
선택적 작업:
- 어느 런에든 연결된 주석을 남깁니다.
- 나중에 다시 방문해야 한다면 비교를 큐에 다시 넣습니다(Requeue).
- 더 깊은 디버깅을 위해 Details 뷰를 엽니다.

예약, 검토자 임계값, 주석은 단일 런 큐와 동일하게 동작하므로, 팀이 기존 워크플로우를 수정하지 않고도 다른 큐 유형을 사용할 수 있습니다.

확인: 이미 사용자 피드백(예: 엄지 내리기)이 있는 런을 분류를 위해 단일 런 큐로 보내고, 더 강한 기준선에 대한 정면 비교를 위해 짝 비교 큐로 보내는 것을 고려하세요. 이렇게 하면 회귀를 빠르게 식별하는 데 도움이 됩니다. LLM 애플리케이션에서 사용자 피드백을 수집하는 방법은 사용자 피드백 연결 가이드를 참고하세요.

비디오 가이드

더 알아보기

SDK로 어노테이션 큐를 관리하는 방법은 Manage feedback & annotation queues programmatically 문서를 참고하세요.
사용자 피드백 수집 방법은 Attach user feedback 문서를 확인해 보세요.