Skip to main content
Si vos exemples d’entraînement existent déjà en dehors du projet, téléversez-les sous forme de fichier JSONL plutôt que d’enregistrer le trafic via le proxy d’inférence. Model Distillation valide le fichier, attribue les répartitions d’entraînement et de validation, puis crée un dataset qui, comme tout autre dataset, 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 ainsi qu’un panneau Uploaded source dans les paramètres du dataset, mais ne propose pas de sélecteur de fichiers. Cette page explique comment se déroule un téléversement, comment préparer le fichier, comment le téléverser en plusieurs parties et comment lire les résultats de validation.

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 le fichier. Un seul des ensembles suivants suffit :
    • curl, accompagné de jq et split.
    • Python 3.9 ou version ultérieure avec le package requests.
    • Node.js 18 ou version ultérieure, sans package supplémentaire.

Fonctionnement d’un téléversement

Un téléversement est une session d’importation limitée à un projet. Une session contient exactement un fichier JSONL, que vous envoyez directement vers le stockage d’objets en plusieurs parties. La session passe par les états suivants : Une session encore à l’état uploading 7 jours après sa création expire. Les requêtes de téléversement de parties et de finalisation qui lui sont adressées renvoient 410 Gone, puis une tâche exécutée toutes les heures la fait passer à l’état expired et supprime ses parties. Les objets téléversés et les téléversements multipart incomplets sont supprimés 8 jours après leur écriture, que la session ait été finalisée ou non. Une entity désigne le compte d’équipe ou personnel indiqué dans l’en-tête Wandb-Entity. Chaque entity peut avoir deux sessions en cours simultanément, pour une taille de fichier déclarée totale de 2 Gio au maximum. Une session est prise en compte dans ces deux limites dès sa création et jusqu’à ce qu’elle atteigne l’état ready, failed, cancelled ou expired. Toute requête qui dépasserait l’une de ces limites renvoie 429 Too Many Requests. Pour libérer de la capacité, annulez une session dont vous n’avez plus besoin ou attendez qu’une session en cours se termine.

Préparer le fichier

Avant de créer une session d’importation, assurez-vous que le fichier respecte le format de ligne et les limites décrites dans cette section. La validation ne s’exécute qu’une fois le téléversement terminé, et une session en échec ne peut pas être rouverte. Pour corriger un problème de format, créez une nouvelle session et téléversez de nouveau le fichier. Le fichier doit être au format JSONL encodé en UTF-8 : un objet JSON par ligne, sans clé en double au sein d’un même objet.

Format des 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. tools accepte jusqu’à 128 outils de type fonction et 1 Mio de JSON. Si le dernier message d’une ligne ne provient pas de l’assistant, la ligne échoue avec l’erreur missing_assistant_target.

Champs facultatifs

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

Limites

Les fichiers et les sessions d’importation doivent respecter les limites suivantes :

Téléverser le fichier

Le téléversement se déroule en plusieurs étapes : créer la session, téléverser le fichier par parties, finaliser le téléversement, puis interroger l’état jusqu’à ce que le dataset soit prêt. Les onglets suivants présentent l’ensemble du processus sous la forme d’un script unique en curl, Python et JavaScript. 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. 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 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

Créer la session d’importation

Le script envoie le nom du fichier et sa taille exacte en octets, la politique de répartition et, éventuellement, une politique de doublons. Pour en savoir plus sur le rôle de chaque politique, consultez Répartitions et doublons. La requête exige également une idempotency_key unique, afin qu’une requête relancée renvoie la session existante au lieu d’en créer une seconde.La réponse est 201 Created et contient la session. Le script en conserve les champs id, file.part_size_bytes et file.part_count. L’extrait suivant présente ces champs :
2

Demander les URL de téléversement

Le script demande une URL signée pour chaque numéro de partie, de 1 à file.part_count. La réponse liste chaque part_number avec son url, ainsi que expires_in_seconds. Chaque URL est valide pendant 15 minutes. Si les URL expirent avant que vous ne les utilisiez, demandez-en de nouvelles.
3

Téléverser les parties

Le script lit le fichier par blocs de file.part_size_bytes et envoie chaque bloc via une requête PUT à l’URL correspondant à son numéro de partie. Les numéros de partie commencent à 1 : le premier bloc est donc la partie 1. Chaque partie, à l’exception de la dernière, doit mesurer exactement file.part_size_bytes, la dernière contenant le reste. Vous pouvez envoyer les parties dans n’importe quel ordre, et en parallèle.Les URL signées intègrent leur propre autorisation : le script n’ajoute donc pas les en-têtes Authorization ou Wandb-Entity à ces requêtes.
4

Facultatif : vérifier les parties reçues

Pour reprendre après un transfert interrompu, lisez la session. file.parts liste chaque partie téléversée avec sa taille, et file.uploaded_bytes en indique le total. Demandez de nouvelles URL pour les parties manquantes, puis renvoyez-les. Les scripts Python et JavaScript calculent les numéros des parties manquantes, et le script curl affiche la liste des parties téléversées. Aucun des scripts ne renvoie les parties manquantes, car une exécution unique et sans interruption n’en laisse aucune.
5

Finaliser le téléversement

Lorsque toutes les parties sont présentes, le script finalise le téléversement. Model Distillation vérifie que les parties correspondent à la taille déclarée, calcule une empreinte, puis met en file d’attente la validation et la création du dataset.La réponse est 202 Accepted. Si une partie est manquante, la réponse est 409 Conflict avec le type upload_incomplete. Si une partie n’a pas la bonne taille, le type est upload_manifest_mismatch. Dans les deux cas, la session reste à l’état uploading : vous pouvez donc corriger les parties et relancer la finalisation. Si vous finalisez un téléversement déjà terminé, la requête renvoie la session actuelle sans erreur.
6

Interroger jusqu’à ce que le dataset soit prêt

Le script lit la session toutes les 10 secondes jusqu’à ce que state vaille ready ou failed. Pendant la validation, validation.validated_rows compte les lignes analysées, et counters indique staged_rows, rejected_rows et rows_by_split.Lorsque state vaut ready, dataset_id identifie le nouveau dataset. Utilisez-le pour le réétiquetage, le fine-tuning et les évaluations, ou ouvrez-le dans l’interface utilisateur. Si state vaut failed, consultez Lire les résultats de validation.

Répartitions et doublons

split_policy détermine la façon dont les lignes sont réparties entre l’entraînement et la validation :
  • preserve conserve la valeur split de chaque ligne. Une ligne sans split échoue à la validation avec l’erreur missing_split.
  • automatic ignore toute valeur split définie sur les lignes. Cette option calcule le hachage du group_id de chaque ligne (ou de l’identité de la ligne en l’absence de group_id) et attribue la fraction définie par val_fraction à la répartition de validation. La fraction par défaut est de 0,2. Les lignes qui partagent le même group_id sont toujours attribuées à la même répartition.
duplicate_policy.split_overlap détermine le comportement adopté lorsqu’une entrée identique figure dans les deux répartitions après l’attribution :
  • reject (valeur par défaut) enregistre une erreur de validation pour chaque ligne en double entre les deux ensembles, et l’importation échoue.
  • drop_train supprime les copies présentes dans l’ensemble d’entraînement et conserve celles de l’ensemble de validation.
Un row_id qui apparaît plusieurs fois dans le fichier échoue à la validation avec l’erreur duplicate_row_id, quelle que soit la politique choisie.

Lire les résultats de validation

Une session 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 physical_line, code et message.
  • errors_truncated vaut true lorsque la liste n’affiche pas tous les problèmes détectés.
Les codes les plus fréquents sont invalid_json, invalid_utf8, duplicate_json_key, row_too_large, missing_assistant_target, tools_too_large, missing_split et duplicate_row_id. Corrigez le fichier, puis créez une nouvelle session. Une session en échec ne peut pas être rouverte.

Annuler un téléversement

Pour abandonner une session, supprimez-la. L’annulation est possible dans tous les états sauf ready. Vous pouvez donc aussi abandonner une session en cours de validation ou en échec. La réponse est 204 No Content, l’état passe à cancelled, les parties déjà téléversées sont supprimées et tout dataset partiellement créé est retiré. Si vous renvoyez la requête sur une session annulée, vous obtenez de nouveau 204 No Content.
Une session ayant déjà atteint l’état ready renvoie 409 Conflict avec le type dataset_import_ready. Pour retirer le dataset qu’elle a créé, supprimez directement ce dataset. Voir Supprimer un dataset.

Erreurs

Les requêtes de session d’importation 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 30 septembre 2026