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êteAuthorizationet indiquent l’entity dans l’en-têteWandb-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é dejqetsplit.- 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 éventuelstools, tool_choice et response_format, en tant qu’entrée, et le dernier message de l’assistant en tant que sortie.
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 encurl, 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.
- curl
- Python
- JavaScript
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 :
preserveconserve la valeursplitde chaque ligne. Une ligne sanssplitéchoue à la validation avec l’erreurmissing_split.automaticignore toute valeursplitdéfinie sur les lignes. Cette option calcule le hachage dugroup_idde chaque ligne (ou de l’identité de la ligne en l’absence degroup_id) et attribue la fraction définie parval_fractionà la répartition de validation. La fraction par défaut est de 0,2. Les lignes qui partagent le mêmegroup_idsont 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_trainsupprime les copies présentes dans l’ensemble d’entraînement et conserve celles de l’ensemble de validation.
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 sessionfailed renvoie dans error une synthèse succincte, et validation fournit les détails :
error_countindique le nombre total de problèmes détectés.errorsrépertorie jusqu’à 100 problèmes, triés par ligne, chacun avecphysical_line,codeetmessage.errors_truncatedvauttruelorsque la liste n’affiche pas tous les problèmes détectés.
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 saufready. 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.
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 :
- Créer une session d’importation de dataset
- Créer des URL de téléversement pour les parties de fichier
- Obtenir une session d’importation de dataset
- Finaliser et valider une importation de dataset
- Annuler une importation de dataset
É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.