Skip to main content
Si vos exemples d’entraînement existent déjà en dehors du projet, écrivez-les dans un dataset via la Management API plutôt que d’enregistrer le trafic via le proxy d’inférence. Comme tout autre dataset, le résultat peut servir au réétiquetage, au fine-tuning et aux évaluations. Le téléversement n’est possible que via la Management API. L’interface affiche le dataset obtenu, mais ne propose pas de sélecteur de fichiers. Cette page explique comment créer un dataset vide, y ajouter des lignes par lots ou sous la forme d’un seul fichier JSONL, et choisir les lignes à réserver pour l’évaluation.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :
  • Une clé API W&B associée à une équipe ayant accès à Model Distillation. Les exemples la lisent depuis la variable d’environnement WANDB_API_KEY, la transmettent dans l’en-tête Authorization et indiquent l’entity dans l’en-tête Wandb-Entity.
  • Un projet au sein de cette équipe. L’alias du projet figure dans chaque chemin de requête. Pour créer un projet, consultez le Démarrage rapide.
  • Les outils correspondant à l’onglet que vous comptez utiliser dans Téléverser un fichier. Un seul des ensembles suivants suffit :
    • curl, accompagné de jq.
    • Python 3.9 ou version ultérieure avec le package requests.
    • Node.js 18 ou version ultérieure, sans package supplémentaire.

Fonctionnement

Chaque téléversement s’effectue dans un dataset existant. Vous créez une seule fois un dataset vide, puis vous y ajoutez des lignes de l’une des deux manières suivantes :
  • Écrire des entrées envoie jusqu’à 5 000 lignes en une seule requête et renvoie immédiatement le résultat. Utilisez cette méthode pour les petits datasets et les ajouts incrémentiels.
  • Téléverser un fichier envoie un seul fichier JSONL (1 Gio et 100 000 lignes au maximum) directement vers le stockage d’objets. Model Distillation vérifie chaque ligne, puis enregistre toutes les lignes en une seule fois.
Les deux méthodes utilisent le même format de ligne et obéissent aux mêmes règles. Une écriture enregistre soit toutes les lignes, soit aucune, et chaque écriture réussie fait passer le dataset à une nouvelle révision. Les réétiquetages et évaluations déjà terminés sur ce dataset sont alors marqués comme obsolètes. Sauf indication contraire, les nouvelles lignes sont placées dans le split d’entraînement. Pour réserver des lignes à l’évaluation, définissez split sur chaque ligne, ou déplacez ensuite une partie des lignes. Voir Choisir les lignes de validation.

Préparer les lignes

Chaque ligne est une requête OpenAI Chat Completions dont le dernier message correspond à la réponse de l’assistant vers laquelle orienter l’entraînement. Model Distillation enregistre les messages précédents, ainsi que les éventuels tools, tool_choice et response_format, en tant qu’entrée, et le dernier message de l’assistant en tant que sortie.
Une ligne doit contenir au moins deux messages et peut en comporter jusqu’à 1 000. Les rôles des messages peuvent être system, developer, user, assistant ou tool, et le dernier message doit provenir de l’assistant. tools accepte jusqu’à 128 outils de type fonction et 1 Mio de JSON.

Champs facultatifs

Les lignes peuvent comporter les champs facultatifs suivants : Les lignes ne doivent contenir aucun autre champ de premier niveau.

Ajout ou upsert

Chaque écriture utilise l’un des deux modes suivants :
  • append, le mode par défaut, rejette toute ligne dont le row_id existe déjà dans le dataset.
  • upsert remplace l’entrée existante. Si la nouvelle ligne ne renseigne pas group_id, split, metadata ou provenance, la valeur stockée est conservée. Les sorties réétiquetées d’une entrée remplacée sont supprimées.
Quel que soit le mode, un row_id présent deux fois dans une même requête ou un même fichier est rejeté, et toute écriture qui placerait un même groupe dans les deux splits échoue avec l’erreur group_split_conflict.

Créer un dataset vide

Créez le dataset en envoyant uniquement un nom. Sans params, la requête crée un dataset vide, prêt immédiatement, et la réponse renvoyée est 201 Created :
Conservez l’id renvoyé dans la réponse. Les exemples suivants le désignent sous le nom DATASET_ID.

Écrire des entrées

Pour ajouter jusqu’à 5 000 lignes en une seule requête, envoyez-les au point de terminaison des entrées sous forme de tableau JSON. Vous pouvez également envoyer ces mêmes lignes au format NDJSON, à raison d’une ligne de données par ligne de texte, avec Content-Type: application/x-ndjson :
La réponse renvoie 200 OK avec created, updated, la nouvelle revision et entry_counts par split. Si une ligne n’est pas valide, la requête est rejetée et l’erreur indique l’index de la ligne concernée. En NDJSON, la ligne N correspond à l’index N - 1. Pour vérifier un lot sans modifier le dataset, ajoutez dry_run=true. Model Distillation valide les lignes, indique ce qui serait modifié, puis annule l’écriture.

Téléverser un fichier

Pour les fichiers dont la taille dépasse ce qu’autorise une seule requête, téléversez le fichier en quatre étapes : ouvrir un téléversement, envoyer le fichier avec un seul PUT, finaliser le téléversement, puis interroger l’état jusqu’à ce que les lignes soient enregistrées. Les onglets suivants présentent l’ensemble du processus sous la forme d’un script unique. Des commentaires numérotés signalent les étapes, et la section Fonctionnement du script détaille chacune d’elles. Les scripts utilisent l’alias de projet ticket-classifier et un fichier nommé tickets.jsonl, et lisent l’ID du dataset dans la variable d’environnement DATASET_ID. Avant d’exécuter un script, remplacez l’entity, l’alias et le nom de fichier par les vôtres, puis définissez WANDB_API_KEY et DATASET_ID dans votre environnement. Utilisez une nouvelle idempotency_key pour chaque téléversement distinct.

Fonctionnement du script

Les commentaires numérotés de chaque script correspondent aux étapes suivantes.
1

Ouvrir le téléversement

Le script envoie le nom du fichier, sa taille exacte en octets et le mode d’écriture. La requête exige également une idempotency_key, de sorte qu’une requête relancée renvoie le téléversement existant au lieu d’en ouvrir un second. Réutiliser une clé avec un corps de requête différent renvoie 409 Conflict avec le type idempotency_conflict.La réponse est 201 Created et contient le téléversement. upload.url est une URL signée pour le fichier, et upload.expires_at indique le moment où elle expire. L’extrait suivant présente ces champs :
2

Envoyer le fichier

Le script envoie l’intégralité du fichier en une seule requête PUT vers upload.url. L’URL est liée à la taille déclarée : le corps doit donc faire exactement file.size_bytes octets. Elle intègre sa propre autorisation, si bien que le script n’ajoute pas les en-têtes Authorization ou Wandb-Entity à cette requête.L’URL doit être utilisée dans un délai de 15 minutes. Si elle expire, lisez à nouveau le téléversement : tant que celui-ci est à l’état uploading, chaque lecture renvoie une nouvelle URL.
3

Finaliser le téléversement

Une fois le fichier stocké, le script finalise le téléversement. Model Distillation vérifie que le fichier stocké correspond à la taille déclarée et met la validation en file d’attente. La réponse est 202 Accepted.Si le fichier n’est pas arrivé, la réponse est 409 Conflict avec le type upload_incomplete. Si sa taille ne correspond pas, le type est upload_size_mismatch et le fichier stocké est supprimé. Dans les deux cas, le téléversement reste à l’état uploading : vous pouvez donc renvoyer le fichier, puis finaliser à nouveau le téléversement. Finaliser un téléversement déjà finalisé renvoie son état actuel, sans erreur.
4

Interroger jusqu'à l'enregistrement des lignes

Le script lit le téléversement toutes les 10 secondes jusqu’à ce qu’il atteigne un état final. Pendant la validation, validation.validated_lines et validation.validated_bytes indiquent la progression.Lorsque state vaut committed, counters indique rows, created, updated, la nouvelle revision et entry_counts par split. Si state vaut failed, consultez Lire les résultats de validation.Si un réétiquetage, une évaluation ou un fine-tuning est en cours sur le dataset, l’enregistrement attend qu’ils se terminent au lieu d’échouer.

États du téléversement

Un téléversement passe par les états suivants : Un téléversement encore à l’état uploading 24 heures après sa création ne peut plus être finalisé. Toute tentative de finalisation renvoie 410 Gone avec le type dataset_upload_expired, et un job exécuté toutes les heures le fait passer à l’état expired. Lorsqu’un téléversement se termine, quel que soit son état, le fichier stocké est supprimé.

Limites

Les fichiers et les téléversements doivent respecter les limites suivantes : Un entity correspond au compte d’équipe ou au compte personnel indiqué dans l’en-tête Wandb-Entity. Un téléversement est pris en compte dans les limites de l’entity tant que son état est uploading, queued ou validating. Toute requête qui dépasserait l’une ou l’autre de ces limites renvoie 429 Too Many Requests. Pour libérer de la capacité, annulez un téléversement dont vous n’avez plus besoin ou attendez qu’un téléversement en cours se termine.

Lire les résultats de validation

Un téléversement failed renvoie dans error une synthèse succincte, et validation fournit les détails :
  • error_count indique le nombre total de problèmes détectés.
  • errors répertorie jusqu’à 100 problèmes, triés par ligne, chacun avec line, code et message. line vaut null pour un problème qui concerne l’ensemble du téléversement, comme un conflit d’enregistrement.
  • errors_truncated vaut true lorsque la liste n’affiche pas tous les problèmes détectés.
Les codes au niveau de la ligne sont invalid_json, invalid_utf8, duplicate_json_key, json_too_deep, row_too_large, empty_line, duplicate_row_id, row_limit_exceeded et validation_failed, qui couvre les lignes non conformes au format attendu. Les codes au niveau du téléversement sont entry_exists, lorsqu’un téléversement append contient un row_id déjà présent dans le dataset, et group_split_conflict. Un téléversement en échec ne peut pas être rouvert. Corrigez le fichier, puis ouvrez un nouveau téléversement.

Annuler un téléversement

Pour abandonner un téléversement qui n’a pas encore été enregistré, supprimez-le. La réponse est 204 No Content, l’état passe à cancelled et le fichier stocké est supprimé. Si vous renvoyez la requête pour un téléversement déjà annulé, vous obtenez de nouveau 204 No Content.
Un téléversement déjà enregistré renvoie 409 Conflict avec le type dataset_upload_committed. Pour en supprimer les lignes, supprimez plutôt le dataset. Voir Supprimer un dataset.

Choisir les lignes de validation

Les lignes sans valeur split sont affectées à l’entraînement. Pour réserver une partie du dataset à l’évaluation une fois celui-ci téléversé, déplacez des entrées vers le split de validation :
La requête sélectionne les entrées à l’aide de filters, qui acceptent les mêmes filtres que la liste des entrées, y compris metadata, ainsi qu’à l’aide de row_ids. Si aucun des deux n’est fourni, elle sélectionne toutes les entrées. fraction ne déplace que cette proportion des groupes sélectionnés. Les groupes sont classés selon un digest de leur ID : un groupe n’est donc jamais scindé, et une requête ultérieure peut prélever sa part parmi les groupes restants. Pour mettre de côté une population entière, par exemple un client donné, filtrez plutôt sur les métadonnées. Les évaluations mesurent alors le modèle sur des utilisateurs qu’il n’a jamais vus pendant l’entraînement :
La réponse indique le nombre d’entrées et de groupes correspondants, le nombre d’entrées qui ont changé de split, la nouvelle revision ainsi que entry_counts. Ajoutez dry_run=true pour afficher le résultat sans modifier le dataset.

Erreurs

Les requêtes d’entrées et de téléversement peuvent renvoyer les erreurs suivantes. Pour les schémas de requête et de réponse, consultez les pages suivantes de la référence de la Management API :

Étapes suivantes

Réétiquetage

Demandez à un modèle plus performant de réécrire les réponses de l’assistant dans le dataset téléversé, sans modifier les lignes d’origine.

Fine-tuning

Entraînez un modèle de base pris en charge sur le dataset téléversé, à partir des sorties d’origine ou d’un ensemble de sorties réétiquetées.
Dernière modification le 8 octobre 2026