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 un fichier. Un seul des ensembles suivants suffit :
curl, accompagné dejq.- 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.
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 éventuelstools, tool_choice et response_format, en tant qu’entrée, et le dernier message de l’assistant en tant que sortie.
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 lerow_idexiste déjà dans le dataset.upsertremplace l’entrée existante. Si la nouvelle ligne ne renseigne pasgroup_id,split,metadataouprovenance, la valeur stockée est conservée. Les sorties réétiquetées d’une entrée remplacée sont supprimées.
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. Sansparams, la requête crée un dataset vide, prêt immédiatement, et la réponse renvoyée est 201 Created :
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, avecContent-Type: application/x-ndjson :
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 seulPUT, 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.
- curl
- Python
- JavaScript
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éversementfailed 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 avecline,codeetmessage.linevautnullpour un problème qui concerne l’ensemble du téléversement, comme un conflit d’enregistrement.errors_truncatedvauttruelorsque la liste n’affiche pas tous les problèmes détectés.
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 est204 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.
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 valeursplit 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 :
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 :
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 :
- Créer un dataset
- Ajouter ou remplacer des entrées de dataset
- Déplacer des entrées de dataset vers un split
- Démarrer un téléversement JSONL dans un dataset
- Obtenir un téléversement de dataset
- Finaliser un téléversement de dataset
- Annuler un téléversement 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.