POST 요청으로 사용자의 HTTPS 엔드포인트에 전송하고, 받은 응답을 해당 Call의 피드백으로 기록합니다. 내부 데이터를 기준으로 한 정책 검사나 직접 호스팅하는 모델처럼 점수화 로직을 Weave에서 실행할 수 없을 때 원격 Scorer를 사용하세요.
이 페이지에서는 @weave.op으로 트레이스된 Call에 사용하는 원격 Scorer를 다룹니다. Agents 뷰에서 에이전트 턴을 점수화하려면 원격 Scorer로 에이전트 턴 점수화하기를 참조하세요. Call용 원격 Scorer는 Python SDK로 설정합니다. TypeScript SDK에는 RemoteScorer가 없습니다.
원격 점수화의 작동 방식
Call은 다음 순서로 점수화됩니다.- 모니터링 대상 Op에 대한 Call이 종료됩니다.
- 점수화 워커가 오퍼레이션에 해당 Op가 포함된 활성 모니터를 찾은 다음, 각 모니터의 필터와 샘플링 비율을 적용합니다.
- 조건에 맞는 모니터의 각
RemoteScorer에 대해 워커는 Call을 담은schema_version: 1요청을 구성하고, Scorer의 자격 증명을 확인하고, 엔드포인트 URL이 허용된 호스트에 속하는지 검사한 다음POST요청을 보냅니다. - 워커는 응답을 검증한 뒤 그 결과를 Call의 피드백으로 기록합니다. 또한 성공 여부와 관계없이 점수화 시도 자체도 Call로 기록합니다.
weave.Evaluation이나 call.apply_scorer()에서는 사용할 수 없습니다. 두 방법 모두 Scorer의 score() 메서드를 호출하는데, RemoteScorer는 점수화 워커만 요청을 보낼 수 있으므로 이 메서드에서 NotImplementedError 예외가 발생합니다. Weave UI의 Score calls 액션에서도 RemoteScorer requires a monitor 메시지와 함께 RemoteScorer가 거부됩니다. 선택한 Call마다 요청이 하나씩 생성되며, 각 요청은 한 번만 전송됩니다. 요청이 timeout되거나 응답이 없어도 Weave는 재시도하지 않습니다. 기본 timeout은 30초입니다.
원격 점수화 활성화
원격 점수화는 조직 또는 배포에서 활성화하기 전까지 꺼져 있으며, 점수화 워커는 호스트가 허용 목록에 있는 Scorer 엔드포인트만 호출합니다. 활성화 방법은 배포 유형에 따라 다릅니다. Multi-tenant Cloud 조직에서 원격 Scorer를 활성화하려면 조직 관리자 또는 청구 관리자가 다음 단계를 수행해야 합니다.https://wandb.ai/account-settings/[ORG]/settings페이지를 여세요.[ORG]는 프로젝트를 소유한 조직 이름으로 바꾸세요.- Remote scoring 탭을 선택하세요.
- Enable remote scoring을 켜세요.
- Allowed hosts 아래에서 Add host를 클릭하고 원격 Scorer가 호출할 수 있는 호스트를 각각 입력하세요. 원격 점수화를 활성화한 상태로 저장하려면 호스트를 하나 이상 추가해야 합니다. 해당 호스트의 모든 포트를 허용하려면 포트를 비워 두세요.
- Save settings를 클릭하세요.
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에서 보낸 JSONPOST 요청을 받아 JSON 형식의 점수를 반환합니다. 레퍼런스 구현은 샘플 코드를 참조하세요.
요청
Weave는 점수화 대상마다 scorer의 엔드포인트 URL로 HTTPPOST 요청을 한 번씩 보내며, 이때 다음 헤더를 포함합니다.
Weave는 동일한 점수화 시도를 두 번 이상 전달할 수 있습니다. 엔드포인트에 필요한 경우
Idempotency-Key를 사용해 중복 요청을 제거하세요. 이 키는 요청 버전별로 고정되므로, 동일한 Call에 대한 V1 요청과 V2 요청의 키는 서로 다릅니다.
모든 요청 본문에는 다음 최상위 필드가 포함됩니다.
Weave는 값이 없는 선택 필드를
null로 보내지 않고 아예 생략합니다. 또한 버전 번호를 바꾸지 않고도 해당 버전에 선택 필드를 추가할 수 있으므로, 인식할 수 없는 필드는 무시하세요.
요청 본문과 응답 본문은 각각 최대 1 MiB이며 JSON 텍스트만 포함합니다. 이미지, 오디오, 비디오는 포함되지 않습니다. 이 제한을 초과하는 대상은 전송되지 않으므로 점수화되지 않습니다. 요청 하나에는 대상 하나만 포함됩니다.
Call의 경우 schema_version은 1이며, 점수가 매겨진 Call은 최상위 수준의 original_call 아래에 있습니다.
응답
다음 두 필드를 포함한 JSON 객체와 함께 HTTP200을 반환하세요.
schema_version: 요청의schema_version과 동일한 정수입니다.result: 점수 객체 하나, 점수 객체 목록 또는{"scores": [...]}형식의 객체입니다.
Weave는
200이 아닌 모든 응답을 Scorer 실패로 처리하며, 해당 시도에 대한 피드백을 기록하지 않습니다. Weave는 리디렉션을 따르지 않고 실패로 처리합니다. 또한 오류 응답의 본문은 파싱하지 않습니다. 엔드포인트에서 어떤 경우에도 수락하지 않는 요청에는 4xx를, 일시적인 문제에는 5xx를 반환하세요.
Call 요청에 대한 응답의 schema_version은 1입니다. 이 응답은 평점 하나와 태그 하나를 반환합니다.
Weave에서 보낸 요청 인증하기
Weave는 Bearer 토큰을 사용해 엔드포인트에 인증합니다. 요청에는 W&B 자격 증명이 포함되지 않습니다. 이 토큰은 요청이 Weave에서 보낸 것임을 엔드포인트에 증명하는 용도이며, 반대 방향으로는 증명하지 않습니다. 각RemoteScorer는 다음 두 가지 모드 중 하나를 사용합니다.
Scorer를 등록하기 전에 프로젝트를 소유한 팀의 시크릿 저장소에 클라이언트 시크릿 또는 Bearer 토큰을 저장하세요.
RemoteScorer 설정에는 시크릿 이름만 저장되며, 실제 값은 점수화 워커가 점수화 시점에 조회합니다.
원격 Scorer 등록하기
원격 Scorer는 모니터에 연결된RemoteScorer 객체이며, Python SDK로 생성합니다.
RemoteScorer를 게시한 다음, scorers에 해당 Scorer를 포함하고 op_names에 평가할 Ops를 지정한 Monitor를 활성화하세요. endpoint_url은 필수이며, config와 auth_config는 선택 사항입니다.
monitor.activate()가 모니터를 활성 상태로 게시하고, 접두사 없는 Op 이름을 현재 프로젝트 기준의 전체 Op ref로 확장합니다.
샘플 코드
weave 저장소의 examples/remote_scorer 디렉터리는 이 페이지에서 설명하는 요청 및 응답 형식의 레퍼런스 구현입니다. Python과 FastAPI로 작성되었지만, 엔드포인트는 어떤 언어, 프레임워크, 호스트를 사용해도 됩니다. Call에는 다음 파일이 사용됩니다.
remote_scorer_app.py:GET /health및POST /score를 제공하는 FastAPI 앱입니다.scoring_logic.py: 프레임워크와 무관한 요청 파싱 및 점수화 로직으로, 자체 서비스에 그대로 복사해 쓸 수 있도록 작성되었습니다. Call의 경우inputs.message값을 점수화합니다.auth.py:REMOTE_SCORER_DEV_BEARER_TOKEN환경 변수와 비교하여 Bearer 토큰을 검사하는 개발 전용 모듈입니다.register_remote_scorer.py --op-name:RemoteScorer를 게시하고 Op에 대한Monitor를 활성화합니다.trigger_test_trace.py: 모니터가 선택할 수 있도록 트레이스된 Call을 생성합니다.sample_request.json: Call에 대한 전체 V1 요청 예시입니다.
0.53.0 이상이 필요합니다. 로컬 run으로는 엔드포인트에 정의한 요청-응답 동작만 검증할 수 있습니다. Weave 점수화 워커는 루프백 주소를 거부하며, 호스팅된 배포 환경에서는 안전하지 않은 HTTP를 허용하지 않습니다.
Scorer 테스트하기
테스트하기 전에 허용된 호스트에 속한 HTTPS URL에 엔드포인트를 배포한 후 등록하세요. 점수화 대상 Call을 트리거하고 결과를 확인하세요.- 모니터링 대상 Op를 한 번 이상 호출합니다.
- 엔드포인트에 요청이 수신되었는지 확인합니다. 점수화는 비동기로 수행되므로 요청은 Call이 종료된 후에 도착합니다.
- Traces 탭에서 Call을 열고 피드백을 확인합니다.
original_call 필드에 Call이 담긴 V1 요청을 수신하며, Weave는 그 결과를 해당 Call의 피드백으로 기록합니다.