메타데이터와 트레이스

프록시 제어 옵션과 트레이스 속성은 표준 채팅 완성 metadata 객체에 포함하세요. 이 페이지에서는 대화 식별자를 유지하는 방법과 대화 전체를 샘플링하는 방법을 설명하고, 그 결과로 프로젝트에 생성되는 트레이스를 살펴봅니다. OpenAI SDK는 metadata를 기본 제공 요청 매개변수로 지원하므로 extra_body를 사용할 필요가 없습니다. 단, metadata 매개변수를 지원하지 않는 이전 릴리스의 openai Python 패키지에서는 여전히 extra_body={"metadata": {...}}를 사용해야 합니다.

예약된 메타데이터

키	유형	용도
`gen_ai.conversation.id`	비어 있지 않은 `string`	W&B Weave에서 고정 라우팅, 대화 샘플링, 대화 그룹화에 사용하는 대화 식별자
`forge.project_version`	`"2"`와 같은 `string` 또는 `integer`	프로젝트 버전을 선택합니다. `OpenAI-Project` 헤더가 필요합니다. 버전 1을 사용하려면 생략하세요
`forge.turn_index`	음수가 아닌 `integer`	재생 시 신뢰할 수 있는 소스의 턴 인덱스를 유지합니다
`user.id`	비어 있지 않은 `string`	트레이스에 최종 사용자 ID를 연결합니다
`forge.call_shadow`	`boolean`	프로젝트로 라우팅된 요청에 대해 Agent Span과 함께 Weave Call도 로깅합니다. 이 경우 트레이스 저장소 사용량이 중복됩니다

forge.* 및 wandb.* 키는 프록시 제어용으로 예약되어 있습니다. 프록시는 요청을 공급자에게 보내기 전에 이 키를 제거하며, 사용자 지정 트레이스 속성으로도 기록하지 않습니다. 그 외의 메타데이터는 프록시가 공급자에게 그대로 전달하며, 표현할 수 있는 경우 트레이스에도 추가합니다. forge. 또는 wandb.로 시작하는 메타데이터 키를 임의로 사용하지 마세요. 프록시가 이러한 키를 제어용 키로 처리합니다. 또한 routing_mode, task_version, alias처럼 프록시가 직접 기록하는 이름과 겹치는 사용자 지정 메타데이터는 트레이스에 기록되지 않습니다. Agent Span은 error.type 키와 gen_ai.conversation.id를 제외한 gen_ai.* 키도 건너뜁니다. 단, 프록시는 이러한 키도 공급자에게 전달합니다.

대화 식별자 우선순위

대화 식별자는 OpenTelemetry 표준 이름인 gen_ai.conversation.id로 전송하세요. 프록시는 사용 가능한 식별자 중 첫 번째 식별자를 선택합니다.

gen_ai.conversation.id
Vapi call.id

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

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

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

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

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

API: 대화 트레이스 샘플링 설정 (PUT /projects/[PROJECT-ALIAS]/routing)

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

curl --request PUT \
  --url "https://forge.coreweave.com/api/distillation/v1/projects/[PROJECT-ALIAS]/routing" \
  --header "Authorization: Bearer $WANDB_API_KEY" \
  --header "Forge-Entity: [WANDB-ENTITY]" \
  --header "Content-Type: application/json" \
  --data '{
    "trace_sampling_rate": 0.1,
    "targets": [
      {"model_ref": "[MODEL-REF]", "weight": 1}
    ]
  }'

다른 프로젝트 버전에 설정하려면 PUT /v1/projects/[PROJECT-ALIAS]/versions/[PROJECT-VERSION]/routing을 사용하세요. [PROJECT-ALIAS]를 프로젝트 별칭으로, [PROJECT-VERSION]을 프로젝트 버전으로 바꾸세요. 새 라우팅 리비전에서 배포 상태가 Applied로 바뀐 후에 설정이 적용된 것으로 간주하세요.

프로젝트 트레이스 내용

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

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

기준이 되는 Agent Span에는 세부 정보를 보존할 수 있도록 요청과 응답의 원본 사본이 포함됩니다. 따라서 데이터셋을 재구성할 때 정규화된 표시 열에만 의존하지 않습니다. 프록시는 프로젝트 요청마다 Agent Span을 하나씩 기록합니다. Weave의 Agents 뷰는 gen_ai.conversation.id를 기준으로 이러한 스팬을 대화별로 그룹화합니다. Weave의 Threads 뷰는 Call만 조회하므로, forge.call_shadow로 Call도 함께 기록하는 요청의 프로젝트 트래픽만 이 뷰에 표시됩니다. 모델 재정의도 프로젝트 트래픽에 해당하므로 프로젝트 트레이스로 만든 데이터셋에 포함될 수 있습니다. 데이터셋에서 재정의를 제외하려면 metadata: {"routing_mode": "weighted"}로 필터링하세요. 이 필터를 적용하면 프록시가 routing_mode를 기록하기 전에 작성된 트레이스도 함께 제외됩니다.

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

API: 대화 식별자를 포함하여 요청 보내기 (POST /chat/completions)

[WANDB-ENTITY]를 Weights & Biases entity로, [WANDB-PROJECT]를 프로젝트의 Weights & Biases 프로젝트 이름(별칭 아님)으로, [CONVERSATION-ID]를 대화 식별자로 바꾸세요.한 대화의 모든 턴에서 동일한 gen_ai.conversation.id를 사용하세요.

curl --request POST \
  --url "https://proxy.training.coreweave.com/v1/chat/completions" \
  --header "Authorization: Bearer $WANDB_API_KEY" \
  --header "OpenAI-Project: [WANDB-ENTITY]/[WANDB-PROJECT]" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "router",
    "messages": [{"role": "user", "content": "Classify this request"}],
    "metadata": {
      "gen_ai.conversation.id": "[CONVERSATION-ID]"
    }
  }'

버전 1이 아닌 다른 버전을 고정하려면 metadata에 "forge.project_version": "2"를 추가하세요. 프록시는 공급자에 요청을 보내기 전에 예약된 forge.* 값을 제거합니다. 자세한 내용은 라우팅된 채팅 완성 생성을 참조하세요.

​예약된 메타데이터

​대화 식별자 우선순위

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

​프로젝트 트레이스 내용

예약된 메타데이터

대화 식별자 우선순위

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

프로젝트 트레이스 내용