Skip to main content
원격 Scorer 시그널은 LLM judge 대신 사용자가 직접 호스팅하는 HTTP 엔드포인트를 사용해 완료된 각 에이전트 턴을 점수화합니다. 턴이 끝나면 W&B Weave 에이전트 점수화 워커가 해당 턴을 HTTP POST 요청으로 엔드포인트에 전송하고, 응답을 해당 턴의 피드백으로 기록합니다. 결과는 Agents view의 Signals 탭에 태그 또는 평점으로 표시됩니다. 이 페이지에서는 에이전트 턴용 원격 Scorer를 다룹니다. @weave.op로 트레이스된 Call을 점수화하려면 원격 Scorer로 Call 점수화하기를 참조하세요. 원격 Scorer는 Python SDK 또는 Weave UI에서 설정할 수 있습니다. TypeScript SDK에서는 RemoteScorer를 제공하지 않습니다.

에이전트 턴 점수화 작동 방식

에이전트 턴은 다음 순서로 점수화됩니다.
  1. 턴이 종료됩니다. 루트 span(부모가 없는 span)이 종료되면 Weave는 이를 완료된 턴으로 간주하고 weave.genai.turn_ended 이벤트를 발생시킵니다.
  2. 에이전트 점수화 워커는 프로젝트에서 weave.genai.turn_ended를 대상으로 하는 활성 시그널을 로드한 다음, 각 시그널의 필터와 샘플링 비율을 적용합니다.
  3. 조건에 일치하는 시그널의 각 RemoteScorer에 대해, 워커는 턴의 span을 바탕으로 메시지를 포함한 schema_version: 2 요청을 구성하고, Scorer의 자격 증명을 가져온 뒤, 엔드포인트 URL이 허용된 호스트에 해당하는지 확인하고 POST 요청을 전송합니다.
  4. 워커는 응답을 검증한 후 결과를 턴의 피드백으로 기록합니다. 태그와 평점은 Signals 탭에 표시됩니다.
Weave는 완료된 턴만 점수화합니다. 개별 LLM span과 도구 span, 그리고 대화 전체는 원격 점수화 대상이 아닙니다. 원격 Scorer 시그널은 UI에서 생성하든 SDK로 생성하든 op_names가 ["weave.genai.turn_ended"]인 Monitor입니다. 워커는 실패한 시도를 동일한 Idempotency-Key로 재시도하며, 첫 시도 후 30초 이내에 최대 세 번까지 시도합니다. 5xx, 408, 429 응답은 재시도 대상입니다. timeout이 발생하면 30초를 모두 소진하므로 시간이 초과된 요청은 재시도되지 않습니다. 그 외의 4xx 응답도 재시도되지 않습니다. 엔드포인트가 제한 시간 내에 턴을 점수화할 수 없다면, 요청이 timeout될 때까지 기다리지 말고 즉시 503을 반환하여 Weave가 재시도하도록 하세요. Weave는 태그와 평점을 유형이 지정된 피드백 열로 저장하므로, 에이전트 턴 점수화에는 구조화된 결과 형식을 사용해야 합니다.

원격 점수화 활성화

원격 점수화는 조직 또는 배포에서 활성화하기 전까지 꺼져 있으며, 점수화 워커는 호스트가 허용 목록에 있는 Scorer 엔드포인트만 호출합니다. 활성화 방법은 배포 유형에 따라 다릅니다. Multi-tenant Cloud 조직에서 원격 Scorer를 활성화하려면 조직 관리자 또는 청구 관리자가 다음 단계를 수행해야 합니다.
  1. https://wandb.ai/account-settings/[ORG]/settings 페이지를 여세요. [ORG]는 프로젝트를 소유한 조직 이름으로 바꾸세요.
  2. Remote scoring 탭을 선택하세요.
  3. Enable remote scoring을 켜세요.
  4. Allowed hosts 아래에서 Add host를 클릭하고 원격 Scorer가 호출할 수 있는 호스트를 각각 입력하세요. 원격 점수화를 활성화한 상태로 저장하려면 호스트를 하나 이상 추가해야 합니다. 해당 호스트의 모든 포트를 허용하려면 포트를 비워 두세요.
  5. Save settings를 클릭하세요.
Dedicated Cloud W&B에 배포의 원격 점수화 활성화와 허용 호스트 설정을 요청하세요. Self-Managed W&B Self-Managed 배포에서 W&B Weave를 실행하는 경우, 각 점수화 워커(온라인 평가 워커, Call 점수화 워커, 에이전트 점수화 워커)에 extraEnv를 사용하여 다음 환경 변수를 설정하세요. Weave UI에 원격 점수화 설정과 Scorer 옵션을 표시하려면 W&B 서버에 GORILLA_GATE_WEAVE_REMOTE_SCORING=true도 함께 설정하세요. 허용 호스트 규칙 점수화 워커는 모든 Scorer 엔드포인트 URL을 다음 규칙에 따라 검사합니다. Scorer가 OAuth를 사용하는 경우에는 OAuth 토큰 엔드포인트 URL도 별도로 검사합니다.
  • 항목은 정확히 일치하는 호스트와 매칭되며, 포트는 선택적으로 지정할 수 있습니다. 포트를 지정하지 않은 항목은 해당 호스트의 모든 포트를 허용합니다.
  • *.로 시작하는 항목은 깊이와 관계없이 모든 하위 도메인과 매칭되지만, 도메인 자체와는 매칭되지 않습니다. 예를 들어 *.corp.example.com은 a.corp.example.com 및 a.b.corp.example.com과는 매칭되지만 corp.example.com과는 매칭되지 않습니다. *. 뒤의 접미사에는 레이블이 두 개 이상 있어야 하므로 *.com은 거부됩니다. 와일드카드는 IP 주소와 함께 사용할 수 없습니다.
  • 운영자 허용 목록과 조직 허용 목록이 모두 있는 경우 URL은 두 목록을 모두 충족해야 합니다. 운영자 허용 목록이 비어 있으면 별도의 제한이 추가되지 않습니다. 허용 목록이 하나도 없으면 워커는 모든 호스트를 거부합니다.
  • 루프백, 비공개, 내부 및 클라우드 메타데이터 주소는 거부됩니다. 단, Self-Managed 환경에서는 WF_SCORING_WORKER_REMOTE_SCORER_ALLOWED_PRIVATE_CIDRS에 나열된 네트워크에 속한 비공개 주소가 허용됩니다.
  • 배포에서 안전하지 않은 HTTP를 허용하지 않는 한 HTTPS를 사용해야 합니다.
  • 리디렉션은 따라가지 않습니다.

Scorer 엔드포인트 구축하기

엔드포인트는 Weave에서 JSON POST 요청을 받아 JSON 형식의 점수를 반환합니다. 레퍼런스 구현은 샘플 코드를 참조하세요.

Request

Weave는 점수화 대상마다 scorer의 엔드포인트 URL로 HTTP POST 요청을 한 번씩 보내며, 이때 다음 헤더를 포함합니다. Weave는 동일한 점수화 시도를 두 번 이상 전달할 수 있습니다. 엔드포인트에 필요한 경우 Idempotency-Key를 사용해 중복 요청을 제거하세요. 이 키는 요청 버전별로 고정되므로, 동일한 Call에 대한 V1 요청과 V2 요청의 키는 서로 다릅니다. 모든 요청 본문에는 다음 최상위 필드가 포함됩니다. Weave는 값이 없는 선택 필드를 null로 보내지 않고 아예 생략합니다. 또한 버전 번호를 바꾸지 않고도 해당 버전에 선택 필드를 추가할 수 있으므로, 인식할 수 없는 필드는 무시하세요. 요청 본문과 응답 본문은 각각 최대 1 MiB이며 JSON 텍스트만 포함합니다. 이미지, 오디오, 비디오는 포함되지 않습니다. 이 제한을 초과하는 대상은 전송되지 않으므로 점수화되지 않습니다. 요청 하나에는 대상 하나만 포함됩니다. 에이전트 턴 요청에는 두 가지 버전 번호가 포함됩니다. 최상위 schema_version은 엔벌로프 버전이며, 에이전트 턴의 경우 2입니다. 점수화 대상 데이터는 scoring_target 아래에 있습니다. 이는 다음 세 필드로 구성된 태그된 유니언입니다.
  • type: 대상의 종류입니다. 턴의 경우 agent_turn입니다. 계약에는 call도 정의되어 있지만, 에이전트 턴 점수화에서는 이 값을 전송하지 않습니다.
  • schema_version: 해당 유형의 페이로드 버전입니다. 엔벌로프 버전과는 별개로 증가합니다. agent_turn 페이로드의 페이로드 버전은 1입니다.
  • payload: 해당 유형의 데이터입니다.
먼저 엔벌로프 버전을 확인한 다음, scoring_target.type과 scoring_target.schema_version을 함께 확인하여 페이로드의 점수화 방식을 결정하세요. 엔드포인트에서 처리하지 않는 조합에는 4xx를 반환하세요. 예를 들어 에이전트 턴만 점수화한다면 call이 여기에 해당합니다. 페이로드 버전 1의 agent_turn 페이로드에는 다음 필드가 포함됩니다. 명시적인 상태 없이 종료된 턴은 status.code가 UNSET으로 설정된 채 전달됩니다. UNSET은 정상적으로 완료된 턴으로, ERROR는 실패 시그널로 간주하세요. input과 output의 각 메시지에는 role, content, finish_reason이 있습니다. content는 일반 텍스트이며, 메시지에 도구 Call 같은 구조화된 콘텐츠가 포함된 경우에는 JSON으로 인코딩된 파트 배열입니다.
Weave는 페이로드 버전을 변경하지 않고 페이로드에 선택 필드를 추가합니다. 필드를 제거하거나 이름을 바꾸거나 의미를 변경할 때는 반드시 해당 유형의 새 페이로드 버전을 도입하며, 엔벨로프가 변경될 때는 새 엔벨로프 버전을 도입합니다. 새 대상 유형은 페이로드 버전 1로 V2 유니온에 추가됩니다.

응답

다음 두 필드를 포함한 JSON 객체와 함께 HTTP 200을 반환하세요.
  • schema_version: 요청의 schema_version과 동일한 정수입니다.
  • result: 점수 객체 하나, 점수 객체 목록 또는 {"scores": [...]} 형식의 객체입니다.
점수 객체에는 다음 필드가 있습니다. Weave는 200이 아닌 모든 응답을 Scorer 실패로 처리하며, 해당 시도에 대한 피드백을 기록하지 않습니다. Weave는 리디렉션을 따르지 않고 실패로 처리합니다. 또한 오류 응답의 본문은 파싱하지 않습니다. 엔드포인트에서 어떤 경우에도 수락하지 않는 요청에는 4xx를, 일시적인 문제에는 5xx를 반환하세요. 에이전트 턴 요청에 대한 응답의 schema_version은 2입니다. 다음 예시는 score 객체 하나를 반환합니다.
Weave는 결과에 포함된 태그와 사유를 저장하기 전에 정규화합니다. 자세한 내용은 Weave가 점수를 정규화하는 방법을 참조하세요.

Weave에서 보낸 요청 인증하기

Weave는 Bearer 토큰을 사용해 엔드포인트에 인증합니다. 요청에는 W&B 자격 증명이 포함되지 않습니다. 이 토큰은 요청이 Weave에서 보낸 것임을 엔드포인트에 증명하는 용도이며, 반대 방향으로는 증명하지 않습니다. 각 RemoteScorer는 다음 두 가지 모드 중 하나를 사용합니다. Scorer를 등록하기 전에 프로젝트를 소유한 팀의 시크릿 저장소에 클라이언트 시크릿 또는 Bearer 토큰을 저장하세요. RemoteScorer 설정에는 시크릿 이름만 저장되며, 실제 값은 점수화 워커가 점수화 시점에 조회합니다.

원격 Scorer 시그널 생성

Weave UI 또는 Python SDK에서 시그널을 생성하세요. 어느 방법을 사용하든 weave.genai.turn_ended를 대상으로 하는 모니터에 연결된 RemoteScorer가 생성됩니다.

Weave UI

Agents 뷰에서 시그널을 생성하세요.
  1. Weave 프로젝트 사이드바에서 Agents를 클릭하세요.
  2. 탭 바에서 Signals를 클릭하세요.
  3. New signal을 클릭한 다음 Remote scorer를 클릭하세요.
  4. Remote scorer 드로어에서 Scored by는 Remote scorer로 설정되어 있습니다. 다음 필드를 설정하세요.
    • Scorer name: Signals table의 Scorer 열에 표시되는 이름입니다. 최대 128자까지 입력할 수 있습니다.
    • Scoring endpoint URL: Weave가 POST 요청을 보낼 URL입니다.
    • Authentication: Static bearer 또는 OAuth client credentials 중에서 선택합니다. Static bearer를 선택한 경우 Bearer token secret name을 선택하거나 입력하세요. OAuth를 선택한 경우 Token endpoint URL, Client ID, Client secret name을 입력하고, 필요하면 Scope도 입력하세요. 시크릿 필드에는 시크릿 값이 아니라 팀 시크릿 이름을 입력합니다.
    • Config (JSON, optional): 엔드포인트에 scorer.config로 전달되는 JSON 객체입니다.
    • Only score turns matching (선택): Advanced를 펼친 다음 필터를 추가하여 시그널이 점수화할 턴을 제한하세요. 예를 들어 에이전트 이름, 에이전트 버전, 오퍼레이션 이름, 도구 이름, 상태 코드 등으로 제한할 수 있습니다. 모든 턴을 점수화하려면 비워 두세요. 필터를 여러 개 추가하면 Weave는 AND 논리로 결합합니다.
    • Sample rate (선택): Advanced를 펼친 다음 조건에 일치하는 턴 중 시그널이 점수화할 비율을 설정하세요.
  5. Create signal을 클릭하세요.
Remote scorer 양식에는 태그나 평점 필드가 없습니다. 무엇을 반환할지는 엔드포인트가 결정하며, Signals table에는 엔드포인트에서 받은 태그와 평점이 표시됩니다. Remote scorer 시그널은 Scorer 열에 웹훅 아이콘으로 표시됩니다.

Python SDK

RemoteScorer를 게시한 다음, scorers에 해당 Scorer를 포함하고 op_names에 weave.genai.turn_ended를 대상으로 지정한 Monitor를 활성화하세요.
OAuth 클라이언트 자격 증명을 사용하려면 대신 OAuthClientCredentialsConfig를 auth_config로 전달하세요.

샘플 코드

weave 저장소의 examples/remote_scorer 디렉터리는 이 계약의 레퍼런스 구현이자 샘플 코드의 기준 소스입니다. 이 샘플에서는 엔드포인트 하나로 V1 Call 요청, V2 Call 요청, V2 에이전트 턴 요청을 모두 처리합니다. 에이전트 턴에는 다음 파일이 사용됩니다.
  • remote_scorer_app.py: GET /health와 POST /score를 제공하는 FastAPI 앱입니다.
  • auth.py: REMOTE_SCORER_DEV_BEARER_TOKEN 환경 변수와 대조해 Bearer 토큰을 검사하는 개발 전용 코드입니다.
  • scoring_logic.py: extract_scoring_target으로 두 엔벌로프 중 어느 쪽이든 언래핑한 다음, 턴의 마지막 출력 메시지에 점수를 매깁니다.
  • sample_request_v2_agent_turn.json: 전체 V2 에이전트 턴 요청 예시입니다.
  • register_remote_scorer.py --agent-turn: RemoteScorer를 게시하고, 완료된 에이전트 턴을 대상으로 하는 모니터를 활성화합니다.
  • trigger_test_agent_turn.py: weave.conversation.log_turn으로 턴 하나를 로깅합니다.
Weave 없이 엔드포인트를 로컬에서 실행하고 V2 에이전트 턴 요청을 보내려면, 앱을 시작한 다음 샘플 요청을 보내세요.
이 샘플을 사용하려면 Weave 0.53.0 이상이 필요합니다. 로컬 run에서는 계약만 검증됩니다.

시그널 테스트하기

테스트하기 전에 허용된 호스트에 속한 HTTPS URL에 엔드포인트를 배포하고 등록하세요. 완료된 턴 하나를 로깅한 다음 Signals 탭을 확인하세요. 점수화는 비동기로 진행되므로 결과가 표시되기까지 시간이 조금 걸립니다.
엔드포인트는 scoring_target.type이 agent_turn으로 설정된 V2 요청을 받고, Weave는 그 결과를 해당 턴에 대한 피드백으로 기록합니다.

문제 해결