NVFLARE Convert PyTorch

Utiliser quand

Utiliser pour convertir un script d'entraînement PyTorch existant, un torch.nn.Module, une boucle d'entraînement manuelle, un workflow state_dict, un data loader, un checkpoint ou une boucle de métrique en un job d'entraînement fédéré NVFLARE. Supporte le FL horizontal, l'échange de modèle Client API avec FLModel, les hooks de recipe aggregator=, la validation et l'export.

Ne pas utiliser quand

Ne pas utiliser pour PyTorch Lightning (orienter vers nvflare-convert-lightning), Hugging Face Trainer (orienter vers nvflare-convert-huggingface), TensorFlow, XGBoost, scikit-learn, jobs échoués (orienter vers nvflare-diagnose-job), statistiques fédérées sans entraînement (orienter vers nvflare-fed-stats), ou débogage générique PyTorch sans intention FLARE. Hors scope : déploiement en production, Kubernetes, cycle de vie POC, conception de politique de confidentialité/sécurité, réécriture de controller/workflow en dehors des APIs recipe ou Job, recherche d'expériences et expériences de distribution de données au-delà de la validation minimale. Les demandes de protection de la vie privée — HE/agrégation chiffrée, confidentialité différentielle et filtres de confidentialité — nécessitent une politique de provisioning/déploiement ; orienter plutôt que de substituer une recipe non protégée ou d'ajouter seulement une mise en garde. Si une demande combine statistiques fédérées et conversion d'entraînement de modèle, traiter comme deux jobs et workflows indépendants : ne pas fusionner ou chaîner automatiquement, ne pas orienter la combinaison vers nvflare-orient, et demander quel workflow exécuter en premier avant de générer ou d'exécuter un job. Recommander nvflare-fed-stats en premier seulement si le but de l'utilisateur est de comprendre la distribution des données ; traiter la conversion plus tard comme une demande séparée.

Workflow

1. Charger ../nvflare-shared/references/conversion-common.md et l'appliquer pour toute la conversion ; ce SKILL.md énonce seulement les deltas spécifiques au framework. Charger ../nvflare-shared/references/conversion-workflow.md seulement pour un cas de réexécution non-standard, d'autorisation ou de sémantique manquante ; il ne contient plus les contrats de localisation de données ou de partitionnement, dont les invariants appartiennent à conversion-common.md. Charger ../nvflare-shared/references/site-data-and-paths.md pour les partitions générées, les chemins relatifs, ou les emplacements de données par site.
2. Inspecter avant édition avec nvflare agent inspect source <path> --format json plus lecture directe. L'extraction de faits est statique ; ne pas importer ou exécuter les modules d'entraînement de l'utilisateur pour découvrir des champs. Extraire : point d'entrée d'entraînement, chemin de classe de modèle et arguments du constructeur, comportement des checkpoints, fonctions train/eval, chargement des données, noms de métriques et dénominateurs, local epochs/steps, client et round counts demandés, split de données source ou evidence de partition, evidence de tracking, evidence de DDP, et toute intention d'agrégation personnalisée.
3. Appliquer la règle d'ordre d'installation des dépendances dans ../nvflare-shared/references/conversion-common.md avant toute commande Python important des modules utilisateur, PyTorch, NVFLARE ou des dépendances déclarées.
4. Sélectionner la recipe du workflow FL demandé, pas seulement de PyTorch. Pour le cas standard — l'utilisateur demande explicitement FedAvg et l'inspection identifie PyTorch — exécuter nvflare recipe show fedavg-pt --format json directement et la construire ; ne pas ajouter de config de recipe par site sauf si les sites diffèrent réellement. Charger ../nvflare-shared/references/pytorch-family-recipe-selection.md (découverte, guide d'algorithme, sélection basée sur le catalogue, règle HE-not-supported) seulement pour les algorithmes ambigus ou non-FedAvg, réservant nvflare recipe list pour ces cas. Utiliser le module, la classe et les paramètres retournés par recipe show pour la construction standard de job.py ; pour fedavg-pt, importer FedAvgRecipe de nvflare.app_opt.pt.recipes.fedavg, jamais de nvflare.recipe. Après chaque recipe show, charger ../nvflare-shared/references/pytorch-family-recipe-construction.md et en dériver les capacités de construction de la recipe. Charger references/recipe-selection.md seulement quand des détails non-FedAvg ou de mode d'exécution sont nécessaires.
5. Convertir l'entraînement et l'évaluation en tant que paire en utilisant references/pytorch-client-api-conversion.md : initialiser FLARE, recevoir un FLModel, charger params, évaluer le modèle global reçu, entraîner, et envoyer un FLModel avec params mis à jour, metrics, et le compte réel d'optimizer-steps locaux complétés dans NUM_STEPS_CURRENT_ROUND. Adapter le code d'évaluation de l'utilisateur dans le template d'évaluation fourni ; si l'évaluation est requise mais manquante, demander ou échouer en toute sécurité. Appliquer les règles de localisation de données de l'étape 1 à l'argument de données du client généré.
6. Ajouter ou mettre à jour job.py selon la règle de sérialisation-constructeur partagée : utiliser un class_path explicite (ou l'alias path documenté) plus des args complets chaque fois que la reconstruction a besoin de valeurs. Ajouter le câblage aggregator= demandé, métrique, transport de tenseur, server offload, et paramètres d'exécution dérivés du profil de construction PyTorch-family partagé.
7. Valider selon une échelle per ../nvflare-shared/references/validation-evidence.md : vérifications de compilation, construction de recipe, un chemin final complet d'exécution choisi par l'artefact en cours de validation, avec export et inspection de packaging seulement pour le chemin d'artefact exporté sélectionné. Pour une cible locale, inspecter les configs matérialisées et l'evidence de packaging après cette exécution. Utiliser references/job-validation.md pour les défaillances spécifiques à PyTorch. S'arrêter au premier échelon échoué et rapporter l'erreur du produit. Utiliser les mécanismes d'environnement et de permission fournis par l'hôte de l'agent ; ne pas inspecter ou appliquer sa limite de sécurité.
8. Rapporter la recipe, les fichiers modifiés, le statut de validation, les métriques et les chemins d'artefacts exacts. Charger ../nvflare-shared/references/metrics-and-artifact-reporting.md seulement quand les artefacts de métriques normaux sont absents ou incohérents.

Exigences

• Doit auditer les arguments du constructeur de modèle avant d'écrire job.py en lisant le __init__ du module de modèle et le paramètre model de la recipe sélectionnée depuis nvflare recipe show <recipe-name> --format json, et non en lisant la source de la bibliothèque NVFLARE. Émettre le class_path ou la clé path documentée de la recipe sélectionnée plus les args complets pour chaque valeur de constructeur requise ou écrasée ; un torch.nn.Module direct est permis seulement quand les valeurs par défaut d'argument zéro inchangées le reconstruisent. Les valeurs doivent être statiquement claires à partir de la source littérale, de la configuration, ou des métadonnées fournies. Sinon, poser une seule question sémantique quand un canal de réponse existe ou échouer en toute sécurité.
• Doit suivre ../nvflare-shared/references/pytorch-model-exchange.md et references/pytorch-client-api-conversion.md pour la payload plain-PyTorch canonique et le motif de boucle de round.
• Doit appliquer ../nvflare-shared/references/pytorch-family-recipe-construction.md après recipe show ; c'est la politique canonique pour les paramètres de recipe optionnels, la sélection de modèle, le transport de tenseur, le server disk offload, et le mode d'exécution. Ne jamais corriger un module runtime framework-neutre ou enregistrer des handlers FOBS dans client.py.
• Doit convertir l'évaluation source aux côtés de l'entraînement et retourner les métriques à travers FLModel.metrics ; ne doit pas synthétiser la sémantique des métriques sans evidence source.
• Doit compter les optimizer steps locaux complétés dans chaque round d'entraînement généré et envoyer cette valeur positive comme MetaKey.NUM_STEPS_CURRENT_ROUND. C'est le poids d'agrégation FedAvg ; ne pas l'omettre, réutiliser un compte cumulatif, ou inventer une valeur quand la boucle source ne peut pas l'établir.
• Doit charger les checkpoints avec torch.load(..., weights_only=True) ; un checkpoint qui a besoin d'unpickling complet est ask/fail, per references/pytorch-client-api-conversion.md.
• Ne doit pas faire charger les skills non-PyTorch-family ../nvflare-shared/references/pytorch-model-exchange.md ; cette référence est réservée aux échanges de modèle/state-dict plain PyTorch, PyTorch Lightning et Hugging Face Trainer seulement.
• Le partitionnement des sites, l'agrégation personnalisée, la Source Of Truth Boundary, et l'input/autorisation utilisateur suivent ../nvflare-shared/references/conversion-common.md.

Toujours lire ce SKILL.md du convertisseur ensemble avec ../nvflare-shared/references/conversion-common.md. Le chemin standard de routage, sélection de recipe et reporting est en ligne, donc le FedAvg commun ne charge pas de politique large ni de références de sélection d'algorithme. Charger le template client, la référence d'échange de modèle, la référence de validation et l'asset d'agrégateur seulement quand leur phase en a besoin. Charger les autres références détaillées seulement pour les exceptions :

• ../nvflare-shared/references/conversion-workflow.md pour le contrat de conversion complet quand un cas est non-standard ;
• ../nvflare-shared/references/site-data-and-paths.md seulement pour les partitions de site générées, la résolution de chemin relatif, ou les emplacements de données par site ;
• ../nvflare-shared/references/pytorch-family-recipe-selection.md seulement pour les algorithmes ambigus ou non-FedAvg, et references/recipe-selection.md seulement pour les détails de construction non-FedAvg ou de mode d'exécution non fournis par recipe show ;
• ../nvflare-shared/references/pytorch-family-recipe-construction.md après chaque recipe show ;
• ../nvflare-shared/references/dependency-install.md seulement quand une installation est nécessaire ;
• ../nvflare-shared/references/runtime-output-guidance.md seulement pour les racines source en lecture seule ou les destinations de sortie choisies par l'utilisateur ;
• ../nvflare-shared/references/metrics-and-artifact-reporting.md seulement quand les métriques sont absentes ou incohérentes ;
• ../nvflare-shared/references/validation-evidence.md avant la validation, et ../nvflare-shared/references/pytorch-model-exchange.md seulement pour l'échange PyTorch-family ;
• references/pytorch-client-api-conversion.md pour la conversion Client API, et references/job-validation.md pour les défaillances de validation spécifiques à PyTorch.

Ne pas charger chaque référence de façon préemptive, et ne pas dépendre de la présence d'exemples du repository NVFLARE dans l'environnement de l'utilisateur.