메타데이터와 트레이스

프록시 제어 옵션과 트레이스 속성은 표준 Chat Completion metadata 객체에 포함하세요. 이 페이지에서는 대화 ID를 유지하는 방법과 대화 전체를 샘플링하는 방법을 설명하고, 그 결과로 프로젝트에 생성되는 트레이스를 살펴봅니다.

예약된 메타데이터

키	유형	용도
`wandb.entity`	비어 있지 않은 `string`	프로젝트 또는 공급자를 소유한 팀 또는 개인 entity를 선택합니다
`wandb.thread_id`	비어 있지 않은 `string`	일관된 라우팅을 위한 권장 대화 식별자
`gen_ai.conversation.id`	비어 있지 않은 `string`	W&B 스레드 ID가 없을 때 사용되는 시맨틱 규칙(semantic convention) 기반 대화 식별자
`wandb.turn_index`	음수가 아닌 `integer`	재생 시 신뢰할 수 있는 원본 턴 인덱스를 유지합니다
`wandb.project`	`project` 또는 `entity/project`	이 대상으로 보내는 직접 공급자 호출에 대해 트레이싱을 활성화합니다
`wandb.trace_surface`	`spans`, `calls` 또는 `both`	트레이싱이 활성화된 직접 호출에 한해 트레이스 표면을 재정의합니다
`user.id`	비어 있지 않은 `string`	트레이스에 최종 사용자 ID를 연결합니다
`wandb.call_shadow`	`boolean`	프로젝트로 라우팅된 요청에 대해 Agent Span과 함께 Weave Call도 로깅합니다. 이 경우 트레이스가 중복 저장됩니다

wandb.* 키는 라우팅과 로깅을 제어합니다. 프록시는 요청을 공급자에게 보내기 전에 이 키를 제거하고, 그 외의 메타데이터는 공급자에게 그대로 전달합니다. 표현 가능한 경우에는 해당 메타데이터를 트레이스에도 추가합니다.

대화 식별자 우선순위

프록시는 사용 가능한 식별자 중 첫 번째 식별자를 선택합니다.

wandb.thread_id
gen_ai.conversation.id
Vapi call.id

애플리케이션에서 하나의 대화에 속하는 모든 공급자 호출에는 동일한 값을 사용하세요. 이렇게 하면 트레이스를 더 쉽게 탐색할 수 있고, 하나의 대화가 여러 데이터셋 분할에 나뉘어 들어가는 것을 방지할 수 있으며, 가중치 기반 라우팅도 안정적으로 동작합니다.

대화 전체 단위로 샘플링하기

대화 수준 트레이스 샘플링을 사용하면 대화가 중간에 잘리지 않도록 하면서 W&B Weave에 저장되는 프로젝트 트래픽의 양을 줄일 수 있습니다. 요청 단위 샘플링은 개별 턴만 남기고 앞뒤 컨텍스트를 버릴 수 있으므로, 저장된 데이터를 디버깅과 데이터셋 생성에 활용하기가 어려워집니다. 프로젝트의 샘플링을 설정하려면 다음을 수행하세요.

Model Distillation에서 프로젝트의 Routing 페이지를 엽니다.
Models and traffic에서 Weave trace sampling을 저장할 대화의 비율로 설정합니다.
Save routing을 선택합니다.

라우팅 설정을 저장하면 프록시는 선택한 비율에 따라 대화 수준 트레이스 샘플링을 수행합니다. 대화 ID가 있는 요청의 경우, 프록시는 W&B entity, Model Distillation 프로젝트, 대화 ID를 기준으로 해당 대화를 고정된 샘플링 그룹에 할당합니다. 기본 샘플링 비율은 100퍼센트입니다. 프록시는 동일한 ID를 가진 요청을 모두 저장하거나 모두 건너뜁니다. 샘플링 결정은 모델 선택 및 라우팅 리비전과 무관합니다. 트레이스를 건너뛰더라도 프록시의 추론 응답 제공에는 영향을 주지 않습니다. 대화 ID가 없는 요청은 프록시가 항상 저장합니다. 샘플링 비율을 변경하면 저장되는 대화가 달라질 수 있으므로, 진행 중인 대화가 유지되는 동안에는 샘플링 비율을 변경하지 마세요.

API: 대화 트레이스 샘플링 설정 (PUT /tasks/[PROXY-MODEL-NAME]/routing)

Model Distillation을 사용하지 않고 대화 수준 트레이스 샘플링을 설정하려면 라우팅 API를 사용하세요.[PROXY-MODEL-NAME]을 프록시 모델 이름으로, [WANDB-ENTITY]를 W&B entity로, [MODEL-REF]를 기존 타깃 모델 레퍼런스로 바꾸세요.trace_sampling_rate를 0에서 1 사이의 값으로 설정하세요. 라우팅을 업데이트하면 전체 설정이 대체되므로 요청에 기존 타깃을 모두 포함해야 합니다.

curl --request PUT \
  --url "https://distillation.training.wandb.ai/v1/tasks/[PROXY-MODEL-NAME]/routing" \
  --header "Authorization: Bearer $WANDB_API_KEY" \
  --header "Wandb-Entity: [WANDB-ENTITY]" \
  --header "Content-Type: application/json" \
  --data '{
    "trace_sampling_rate": 0.1,
    "targets": [
      {"model_ref": "[MODEL-REF]", "weight": 1}
    ]
  }'

다른 프로젝트 버전에 설정하려면 PUT /v1/tasks/[PROXY-MODEL-NAME]/versions/[PROJECT-VERSION]/routing을 사용하세요. [PROXY-MODEL-NAME]을 프록시 모델 이름으로, [PROJECT-VERSION]을 프로젝트 버전으로 바꾸세요. 새 라우팅 리비전에서 배포 상태가 Applied로 바뀐 후에 설정이 적용된 것으로 간주하세요.

프로젝트 트레이스 내용

프로젝트 트레이스는 다음과 같은 라우팅, 요청, 응답 및 메타데이터 세부 정보를 캡처합니다.

프로젝트 ID(UUID), 프록시 모델 이름, 버전
라우팅 리비전, 선택된 공급자 및 모델
프록시가 공급자에게 보내는 요청 원문과 프록시가 재구성한 응답
토큰 사용량, 종료 사유, 소요 시간, 오류 상태
응답이 정확 응답 캐시에서 재생되었는지 여부(cache_hit)
대화, 사용자, 시나리오 및 안전한 맞춤형 메타데이터
지원 문의 및 트레이스 출력 비교에 사용하는 프록시 요청 ID

표준 Agent Span에는 세부 정보를 보존하기 위해 요청과 응답의 원본 사본이 포함됩니다. 따라서 데이터셋을 재구성할 때 정규화된 표시 열에만 의존하지 않습니다.

메시지나 메타데이터에 자격 증명, 시크릿 또는 불필요한 개인 데이터를 넣지 마세요. 트레이스 데이터는 트레이닝 및 디버깅 입력으로 활용되도록 의도적으로 장기간 보존됩니다.

API: 대화 ID를 포함한 요청 보내기 (POST /chat/completions)

[PROXY-MODEL-NAME]은 프록시 모델 이름으로, [WANDB-ENTITY]는 W&B entity로, [CONVERSATION-ID]는 대화 식별자로 바꾸세요.하나의 대화에 속한 모든 턴에는 동일한 wandb.thread_id를 사용하세요.

curl --request POST \
  --url "https://proxy.training.wandb.ai/v1/chat/completions" \
  --header "Authorization: Bearer $WANDB_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "[PROXY-MODEL-NAME]",
    "messages": [{"role": "user", "content": "Classify this request"}],
    "metadata": {
      "wandb.entity": "[WANDB-ENTITY]",
      "wandb.thread_id": "[CONVERSATION-ID]"
    }
  }'

프록시는 공급자에게 요청을 보내기 전에 예약된 wandb.* 값을 제거합니다. 자세한 내용은 라우팅된 Chat Completion 생성을 참조하세요.

​예약된 메타데이터

​대화 식별자 우선순위

​대화 전체 단위로 샘플링하기

​프로젝트 트레이스 내용

예약된 메타데이터

대화 식별자 우선순위

대화 전체 단위로 샘플링하기

프로젝트 트레이스 내용