Métadonnées et traces - CoreWeave Docs

Incluez les contrôles du proxy et les attributs de trace dans l’objet metadata standard de l’API Chat Completions. Cette page explique comment préserver l’identité de conversation, échantillonner des conversations complètes et interpréter les traces qui en résultent dans le projet. Les SDK d’OpenAI acceptent metadata comme paramètre de requête intégré : vous n’avez donc pas besoin de extra_body. Les anciennes versions du paquet Python openai dépourvues du paramètre metadata nécessitent toujours extra_body={"metadata": {...}}.

Métadonnées réservées

Clé	Type	Rôle
`gen_ai.conversation.id`	`string` non vide	Identifiant de conversation utilisé pour l’acheminement persistant, l’échantillonnage et le regroupement des conversations dans W&B Weave
`forge.project_version`	`string` (par exemple `"2"`) ou `integer`	Sélectionne une version de projet. Nécessite l’en-tête `OpenAI-Project`. À omettre pour la version 1
`forge.turn_index`	`integer` non négatif	Conserve un indice de Tour de conversation source fiable lors de la relecture
`user.id`	`string` non vide	Joint l’identité de l’utilisateur final à la trace
`forge.call_shadow`	`boolean`	Journalise également un Call Weave en plus de l’Agent Span pour une requête acheminée vers un projet, ce qui duplique le stockage des traces

Les clés forge.* et wandb.* sont réservées aux contrôles du proxy. Le proxy les supprime avant d’envoyer une requête au fournisseur et ne les enregistre pas comme attributs de trace personnalisés. Les autres métadonnées sont transmises au fournisseur et, lorsque leur format le permet, le proxy les ajoute également à la trace. N’utilisez pas de clés de métadonnées personnelles commençant par forge. ou wandb., car le proxy les traite comme des contrôles. La trace n’enregistre pas non plus les métadonnées personnalisées qui reprennent un nom déjà enregistré par le proxy lui-même, comme routing_mode, task_version ou alias. Les Agent Spans ignorent également error.type ainsi que les clés gen_ai.* autres que gen_ai.conversation.id. Le proxy transmet néanmoins ces clés au fournisseur.

Priorité des identifiants de conversation

Envoyez l’identifiant de conversation sous la forme gen_ai.conversation.id, le nom défini par OpenTelemetry. Le proxy choisit le premier identifiant disponible :

gen_ai.conversation.id
call.id de Vapi

Dans votre application, utilisez la même valeur pour tous les appels au fournisseur d’une même conversation. Cela facilite la navigation dans les traces, évite qu’une conversation ne soit répartie sur plusieurs splits du dataset et stabilise l’acheminement pondéré. L’identifiant de conversation ne modifie pas la clé du cache de réponses.

Échantillonner des conversations complètes

L’échantillonnage des traces au niveau des conversations réduit le volume de trafic du projet enregistré dans Weave, sans laisser de conversations partielles. L’échantillonnage par requête, lui, peut conserver des Tours de conversation isolés et en supprimer le contexte, ce qui rend les données enregistrées moins utiles pour le débogage et la création de datasets. Pour configurer l’échantillonnage d’un projet :

Dans Model Distillation, ouvrez la page Acheminement du projet.
Sous Models and traffic, définissez Weave trace sampling sur le pourcentage de conversations à enregistrer.
Sélectionnez Enregistrer l’acheminement.

Une fois la configuration d’acheminement enregistrée, le proxy applique le pourcentage sélectionné à l’échantillonnage des traces au niveau des conversations. Pour les requêtes associées à une identité de conversation, le proxy attribue la conversation à un groupe d’échantillonnage stable, basé sur l’entity Weights & Biases, le projet Model Distillation et l’ID de conversation. Le taux d’échantillonnage par défaut est de 100 %. Le proxy enregistre ou ignore l’ensemble des requêtes associées à cette identité. La décision d’échantillonnage ne dépend ni de la sélection du modèle ni des révisions d’acheminement. Les traces ignorées n’empêchent pas le proxy de fournir des réponses d’inférence. Le proxy enregistre toujours les requêtes dépourvues d’identité de conversation. Ne modifiez pas le pourcentage d’échantillonnage tant que des conversations sont actives, car toute modification peut changer les conversations enregistrées.

API : définir l’échantillonnage des traces de conversation (PUT /projects/[PROJECT-ALIAS]/routing)

Pour configurer l’échantillonnage des traces au niveau des conversations sans passer par Model Distillation, utilisez l’API d’acheminement.Remplacez [PROJECT-ALIAS] par l’alias du projet, [WANDB-ENTITY] par l’entity Weights & Biases et [MODEL-REF] par une référence de modèle cible existante.Définissez trace_sampling_rate sur une fraction comprise entre 0 et 1. Comme une mise à jour de l’acheminement remplace l’intégralité de la configuration, incluez toutes les cibles existantes dans la requête :

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}
    ]
  }'

Pour une autre version du projet, utilisez PUT /v1/projects/[PROJECT-ALIAS]/versions/[PROJECT-VERSION]/routing. Remplacez [PROJECT-ALIAS] par l’alias du projet et [PROJECT-VERSION] par la version du projet. Avant de considérer le paramètre comme actif, attendez que le statut du déploiement passe à Applied pour la nouvelle révision d’acheminement.

Contenu des traces de projet

Les traces de projet capturent les informations suivantes relatives à l’acheminement, à la requête, à la réponse et aux métadonnées :

ID du projet (UUID), alias du projet et version.
Révision d’acheminement, ainsi que le fournisseur et le modèle sélectionnés.
Le mode d’acheminement (routing_mode) : weighted lorsque le proxy a sélectionné une cible, ou override lorsque la requête a désigné un remplacement de modèle provider/model.
La requête exacte que le proxy envoie au fournisseur et la réponse que le proxy reconstruit.
L’utilisation des jetons, le motif de fin, la durée et le statut d’erreur.
Si la réponse a été restituée depuis le cache de réponses exactes (cache_hit).
La conversation, l’utilisateur, le scénario et les métadonnées personnalisées sûres.
Un ID de requête du proxy, utile pour l’assistance et la comparaison des sorties de traces.

L’Agent Span canonique contient une copie brute de la requête et de la réponse afin d’en préserver tous les détails. La reconstruction des datasets ne repose donc pas uniquement sur les colonnes d’affichage normalisées. Le proxy écrit un Agent Span pour chaque requête de projet. La vue Agents de Weave regroupe ces spans en conversations selon gen_ai.conversation.id. La vue Threads de Weave ne lit que les Calls : le trafic du projet n’y apparaît donc que pour les requêtes qui journalisent également un Call avec forge.call_shadow. Les remplacements de modèle font partie du trafic du projet : les datasets construits à partir des traces de projet peuvent donc les inclure. Pour exclure les remplacements d’un dataset, filtrez sur metadata: {"routing_mode": "weighted"}. Ce filtre exclut également les traces écrites avant que le proxy ne commence à enregistrer routing_mode.

N’incluez pas d’identifiants d’authentification, de secrets ou de données personnelles superflues dans les messages ou les métadonnées. Les données de trace sont délibérément conservées durablement pour servir d’entrée à l’entraînement et au débogage.

API : envoyer une requête avec une identité de conversation (POST /chat/completions)

Remplacez [WANDB-ENTITY] par l’entity Weights & Biases, [WANDB-PROJECT] par le nom du projet Weights & Biases associé au projet (et non son alias), et [CONVERSATION-ID] par un identifiant de conversation.Conservez le même gen_ai.conversation.id pour chaque Tour d’une même conversation :

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]"
    }
  }'

Pour épingler une version autre que la version 1, ajoutez "forge.project_version": "2" à metadata. Le proxy supprime les valeurs réservées forge.* avant d’envoyer la requête au fournisseur. Consultez Créer une complétion de conversation acheminée.

​Métadonnées réservées

​Priorité des identifiants de conversation

​Échantillonner des conversations complètes

​Contenu des traces de projet

Métadonnées réservées

Priorité des identifiants de conversation

Échantillonner des conversations complètes

Contenu des traces de projet