> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 메타데이터와 트레이스

> W&B entity를 선택하고, 대화 ID를 유지하고, 검색 가능한 컨텍스트를 첨부하세요.

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

<h2 id="reserved-metadata">
  예약된 메타데이터
</h2>

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

<h2 id="conversation-precedence">
  대화 식별자 우선순위
</h2>

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

1. `wandb.thread_id`
2. `gen_ai.conversation.id`
3. Vapi `call.id`

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

<h2 id="sample-complete-conversations">
  대화 전체 단위로 샘플링하기
</h2>

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

프로젝트의 샘플링을 설정하려면 다음을 수행하세요.

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

라우팅 설정을 저장하면 프록시는 선택한 비율에 따라 대화 수준 트레이스 샘플링을 수행합니다.

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

대화 ID가 없는 요청은 프록시가 항상 저장합니다. 샘플링 비율을 변경하면 저장되는 대화가 달라질 수 있으므로, 진행 중인 대화가 유지되는 동안에는 샘플링 비율을 변경하지 마세요.

<Accordion title="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` 사이의 값으로 설정하세요. 라우팅을 업데이트하면 전체 설정이 대체되므로 요청에 기존 타깃을 모두 포함해야 합니다.

  ```bash theme={"system"}
  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**로 바뀐 후에 설정이 적용된 것으로 간주하세요.
</Accordion>

<h2 id="project-trace-contents">
  프로젝트 트레이스 내용
</h2>

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

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

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

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

<Accordion title="API: 대화 ID를 포함한 요청 보내기 (POST /chat/completions)">
  `[PROXY-MODEL-NAME]`은 프록시 모델 이름으로, `[WANDB-ENTITY]`는 W\&B entity로, `[CONVERSATION-ID]`는 대화 식별자로 바꾸세요.

  하나의 대화에 속한 모든 턴에는 동일한 `wandb.thread_id`를 사용하세요.

  ```bash theme={"system"}
  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 생성](/ko/model-distillation/reference/proxy/chat-completions/create-a-routed-chat-completion)을 참조하세요.
</Accordion>


## Related topics

- [PyTorch](/ko/products/wandb/integrations/pytorch.md)