NVFLARE Convertir Hugging Face

À utiliser quand

À utiliser pour convertir du code d'entraînement construit autour de transformers.Trainer, Seq2SeqTrainer, TRL SFTTrainer, ou une autre sous-classe Trainer. Supporte l'ajustement du modèle complet et le fine-tuning PEFT/LoRA, datasets/tokenizers, callbacks et métriques Trainer, continuité des checkpoints, et entraînement torch.distributed répliqué.

À ne pas utiliser quand

À ne pas utiliser pour un AutoModel piloté par une boucle PyTorch manuelle sans Trainer Hugging Face (rediriger vers nvflare-convert-pytorch), PyTorch Lightning (rediriger vers nvflare-convert-lightning, y compris les modules Lightning contenant des modèles Transformers), pipelines d'inférence uniquement, service de modèles, jobs échoués (rediriger vers nvflare-diagnose-job), ou statistiques fédérées sans entraînement (rediriger vers nvflare-fed-stats). Rediriger un projet avec des points d'entrée Lightning et Hugging Face Trainer actifs vers nvflare-orient pour sélectionner un propriétaire de boucle d'entraînement ou des jobs séparés. Rediriger la propriété Trainer non résolue, comme une fabrique Trainer sans appel de propriétaire lié, vers nvflare-orient ; ne patcher aucun Trainer. Hors de portée : DeepSpeed, FSDP, déploiement production/POC, réécriture de contrôleur, recherche d'expériences, et demandes de protection de la vie privée telles que HE, agrégation chiffrée, confidentialité différentielle, ou filtres de confidentialité ; jamais substituer une recette non protégée ou présenter une clause de non-responsabilité comme implémentation. Si une demande combine statistiques fédérées et conversion d'entraînement de modèle, la traiter comme deux jobs et workflows indépendants : ne pas fusionner ni enchaîner automatiquement, ne pas rediriger la combinaison vers nvflare-orient, et demander quel workflow exécuter en premier avant de générer ou exécuter l'un ou l'autre job. Recommander nvflare-fed-stats en premier uniquement quand le but de l'utilisateur est de comprendre la distribution des données ; traiter la conversion plus tard comme une demande séparée.

Scripts disponibles

Utiliser run_script() uniquement pendant la phase de validation après avoir chargé references/huggingface-validation.md. Par exemple :

• run_script("scripts/resolve_model_snapshot.py", ["--source", "local", "--source-root", "<absolute-source-root>", "<configured-path>"])
• run_script("scripts/resolve_model_snapshot.py", ["--source", "hub", "<org/model>"])

Workflow

1. Charger ../nvflare-shared/references/conversion-common.md et l'appliquer pour la conversion entière ; ce SKILL.md énonce seulement les deltas propres au framework. Charger ../nvflare-shared/references/conversion-workflow.md uniquement pour une relance non standard, une autorisation, ou un cas sémantique manquant ; il ne possède plus les contrats de localisation des données ou de partitionnement, dont les invariants sont possédés par conversion-common.md. Charger ../nvflare-shared/references/site-data-and-paths.md pour les partitions générées, chemins relatifs, ou emplacements de données par site.
2. Inspecter avant édition avec nvflare agent inspect source <path> --format json plus lecture directe de source. Charger references/huggingface-detection.md pendant cette phase. Si inspect recommande nvflare-orient pour propriété Trainer non résolue ou propriétaires Lightning/Hugging Face actifs, arrêter avant d'éditer. Extraire le point d'entrée, la sous-classe Trainer, le constructeur de modèle, tokenizer ou processeur, datasets et collator, arguments Trainer, compute_metrics, callbacks, paramètres checkpoint et PEFT, précision, budget local, lanceur distribué, comptages site/round, localisation de données, et intention d'agrégation. Ne pas importer ou exécuter les modules d'entraînement utilisateur pour les découvrir.
3. Appliquer la règle de tri d'installation de dépendances dans ../nvflare-shared/references/conversion-common.md avant toute commande Python important les dépendances utilisateur, framework, NVFLARE, ou déclarées. Garder l'inventaire de dépendances d'un seul objectif : vérifier NVFLARE séparément, inventorier les paquets non-produit séparément, et ne pas ajouter de cache Hugging Face ou découverte de système de fichiers. Différer les vérifications de disponibilité de modèle et dataset au résolveur maintenu pendant la validation. Si un chemin optionnel doit être inspecté, l'exécuter séparément et signaler un répertoire manquant avec code de sortie zéro.
4. Sélectionner la recette à partir de l'intention FL. Pour FedAvg explicite, exécuter nvflare recipe show fedavg-pt --format json, puis charger immédiatement ../nvflare-shared/references/pytorch-family-recipe-construction.md et utiliser le module retourné, la classe, et les paramètres avec la forme de construction et exécution requise dans assets/job.py. Importer FedAvgRecipe depuis nvflare.app_opt.pt.recipes.fedavg, jamais depuis nvflare.recipe. Traiter class_path comme la clé de recette publique et path comme sa représentation exportée normalisée ; ne pas inspecter la source Recipe ou les signatures pour les réconcilier. Ne pas deviner les symboles adjacents ou ajouter de configuration de recette par site sauf si les sites diffèrent vraiment. Charger ../nvflare-shared/references/pytorch-family-recipe-selection.md uniquement pour demandes ambiguës, évaluation uniquement, ou non-FedAvg.
5. Convertir avec references/huggingface-conversion.md et adapter assets/client_with_eval.py plutôt que de rédiger une nouvelle boucle round. Préserver modèle, tokenizer/processeur, datasets, collator, arguments Trainer, callbacks, et métriques. Appliquer les règles de localisation de données de l'étape 1 à l'argument data du client. Importer l'API Client comme import nvflare.client.hf as flare, donc flare.init(), flare.patch(), et flare.is_running() résolvent à nvflare.client.hf. Garder flare.patch(trainer) simple avec params_scope="auto" inféré et encoder un budget par round dans les arguments Trainer : étapes demandées utilisent max_steps, epochs demandées utilisent num_train_epochs, et une invite silencieuse utilise la valeur par défaut rapportée max_steps=10 sauf si préservation du budget source a été demandée. Ne pas dupliquer le budget dans local_steps/local_epochs du patch. Quand le client utilise HfArgumentParser, le construire avec allow_abbrev=False.
6. Adapter assets/server_model.py et assets/job.py au lieu d'inventer serveur-modèle, empaquetage, export, ou câblage SimEnv. Garder les modules locaux au projet générés et empaquetés dans le même répertoire source inscriptible. Ne jamais utiliser .. dans train_script, add_server_file(), ou add_client_file() ; utiliser un chemin absolu résolu existant quand la co-localisation est impossible. Garder la fabrique de modèle et l'espace de clés d'échange du serveur et du Trainer identiques. Utiliser la clé class_path ou path documentée de la recette plus args complet pour les valeurs requises ou surchargées ; une instance directe sans argument ne doit pas utiliser from_pretrained(), téléchargements, ou chargement de checkpoint lors de la construction du job. Appliquer uniquement les options confirmées par la référence de construction. Préserver l'ordre recette-avant-parser de l'asset job, ArgumentParser(allow_abbrev=False), et parse_args() strict ; ne pas utiliser parse_known_args().
7. Seulement après l'existence des fichiers générés, charger ../nvflare-shared/references/validation-evidence.md et references/huggingface-validation.md. Suivre l'échelle partagée de compilation, construction, simulation, et preuve terminale. Inspecter l'export/preuve de package uniquement pour une cible finale exportée ; inspecter la preuve matérialisée d'une cible locale après son exécution. Appliquer uniquement les vérifications HF Trainer standard et arrêter au premier échelon échoué. Revoir et exercer les assets maintenus directement ; ne pas inspecter la source d'implémentation NVFLARE, improviser des sondes Recipe API, ou écrire des programmes AST ponctuels pour les re-prouver. Utiliser references/huggingface-state-and-distributed.md uniquement quand l'inspection a trouvé PEFT, DDP, checkpoint/restore overrides, modèles entraînables auxiliaires, ou un autre paramètre de patch non défaut.
8. Signaler la recette, les faits sources, l'étendue des paramètres, la partition de données, les fichiers modifiés, l'état de validation, et les chemins d'artefacts exacts. Quand la validation produit des métriques, charger ../nvflare-shared/references/metrics-and-artifact-reporting.md avant la réponse finale et signaler chaque scalaire primaire observé avec son nom de métrique, valeur numérique, et source d'artefact ou log borné.

Exigences

• Doit utiliser flare.patch(trainer) comme unique propriétaire d'échange de modèle. receive() à l'intérieur d'une boucle patchée peut inspecter uniquement les métadonnées de task ; elle ne doit pas charger une deuxième copie du modèle global.
• Doit suivre l'initialisation de l'API Client et le contrat de rang conditionnel dans ../nvflare-shared/references/conversion-common.md. Garder le client généré sans rang ; nvflare.client.hf.init() possède la résolution et le rejet du rang distribué. Charger references/huggingface-state-and-distributed.md uniquement pour un chemin source multi-processus distribué.
• Doit préserver l'évaluation source. Quand évaluation du modèle global par round est requise, appeler trainer.evaluate() avant trainer.train() sur chaque rang. Ne pas inventer compute_metrics, mappages de labels, dénominateurs de moyenne, ou direction de métrique.
• Doit suivre la politique Best-Model Metric dans ../nvflare-shared/references/pytorch-family-recipe-construction.md ; le delta Hugging Face est uniquement comment la clé livrée est nommée et produite. Doit préserver les noms de métriques sources quand pratique : si le trainer.evaluate() généré émet accuracy, définir key_metric="accuracy" ; si Trainer émet une clé préfixée telle que eval_accuracy, définir le serveur à cette clé exacte et signaler le mappage source-vers-serveur. Quand sélection du meilleur modèle est demandée, chaque métrique inférieure-est-meilleure, y compris Trainer-généré eval_loss, est livré comme compagnon explicitement nié et sélectionné par cette clé — jamais comme loss brut. Quand sélection n'est pas demandée, utiliser key_metric="" ; ne pas l'omettre et activer accidentellement la valeur par défaut de recette.
• Doit préserver la configuration PEFT exactement et vérifier la compatibilité des clés d'adapter entre le modèle serveur et le Trainer patché. Ne pas inférer les modules cibles LoRA, silencieusement basculer l'étendue adapter/modèle complet, ou résoudre les incompatibilités de clés avec chargement non strict.
• Doit vérifier que trainer.model possède tout l'état entraînable fédéré pour les sous-classes Trainer avec modèles référence, récompense, value-head, ou autres auxiliaires. Demander ou échouer fermé quand params_scope="auto" omettrait un état entraînable requis par l'algorithme.
• Doit préserver les valeurs du constructeur de modèle nécessaires sur le serveur et les clients par ../nvflare-shared/references/pytorch-model-exchange.md (State-Dict Compatibility). Demander une question sémantique ou échouer fermé quand les valeurs requises ne sont pas disponibles statiquement.
• Doit patcher uniquement un Trainer par processus Python. Préserver un cycle de vie Trainer unique à travers les rounds quand restore_state=True.
• Doit utiliser un budget TrainingArguments.max_steps positif pour un dataset d'entraînement itérable sans longueur et laisser flare.patch(trainer) l'inférer.
• Doit rejeter ou signaler DeepSpeed, FSDP, save_only_model=True avec restore_state=True, load_best_model_at_end=True, instances optimizer/scheduler prébuiltées avec restore_state=False, et chemins de checkpoint non visibles à chaque rang distribué. Ne pas réécrire ces paramètres silencieusement. launch_once est un paramètre de recette neutre au framework possédé par ../nvflare-shared/references/pytorch-family-recipe-construction.md ; le delta Hugging Face est uniquement que le produit rejette launch_once=False explicite ensemble avec restore_state=True.
• Doit initialiser torch.distributed avant de patcher quand les variables d'environnement de rang déclarent plusieurs rangs. Tous les rangs doivent appeler les méthodes Trainer patchées dans l'ordre identique.
• Doit utiliser le résolveur de validation HF maintenu avec une source locale/Hub explicite. Pour les téléchargements autorisés, il obtient ou valide une révision SHA de commit complet avant de télécharger. Doit ne pas le copier dans le code de job généré, définir trust_remote_code=True, télécharger des artefacts modèle/données sauf si demandé, ou récupérer d'un échec cache-only en allant en ligne. Les échecs de cache, les identifiants distants, et les demandes de validation n'autorisent pas les retries en ligne ; voir ../nvflare-shared/references/conversion-common.md.
• Partitionnement de site, agrégation personnalisée, la Source Of Truth Boundary, et entrée/autorisation utilisateur suivent ../nvflare-shared/references/conversion-common.md.

Toujours lire ce converteur SKILL.md ensemble avec ../nvflare-shared/references/conversion-common.md. Compléter chaque phase de workflow avant de charger la référence de la phase suivante. Ne pas précharger validation, state/DDP, workflow large, dépendance, ou références de rapport. Le chemin FedAvg standard charge, dans l'ordre : ../nvflare-shared/references/conversion-common.md, references/huggingface-detection.md, et ../nvflare-shared/references/site-data-and-paths.md uniquement pour ses déclencheurs déclarés ; ../nvflare-shared/references/pytorch-family-recipe-construction.md, references/huggingface-conversion.md, et ../nvflare-shared/references/pytorch-model-exchange.md ; puis ../nvflare-shared/references/validation-evidence.md et references/huggingface-validation.md ; charger references/huggingface-state-and-distributed.md et autres références partagées uniquement selon les déclencheurs ci-dessus. Ne pas dépendre des exemples du repository.