NVFLARE Convert PyTorch Lightning

Utiliser quand

À utiliser uniquement quand l'utilisateur demande de convertir du code PyTorch Lightning en un job d'entraînement fédéré NVFLARE ; exiger à la fois l'intention de fédération et la propriété de Lightning. Traiter les demandes pour que plusieurs sites ou institutions s'entraînent collaborativement tandis que les données de chaque site restent locales comme intention de fédération, même quand la demande ne dit pas « fédéré » ou « NVFLARE ». Les preuves de source Lightning seules ne suffisent pas. La source pertinente peut contenir un LightningModule, un LightningDataModule, une boucle Trainer fit/validate/test, des callbacks Lightning, du checkpointing, ou des loggers. Supporté : la famille de recettes PyTorch avec flare.patch(trainer) comme intégration d'échange de modèle, l'évaluation native de Lightning, l'agrégation personnalisée via le hook aggregator= de la même recette, et la validation et l'export locaux.

Chemin standard

Lisez toujours ce SKILL.md du convertisseur avec ../nvflare-shared/references/conversion-common.md. Pour une conversion FedAvg explicite, chargez uniquement ces références, dans l'ordre du workflow :

Lors de l'inspection, references/lightning-detection.md.
Pour les divisions générées, les chemins relatifs, ou les emplacements de données par site, ../nvflare-shared/references/site-data-and-paths.md.
Après nvflare recipe show fedavg-pt --format json, ../nvflare-shared/references/pytorch-family-recipe-construction.md.
Lors de la conversion, references/lightning-conversion.md, puis ../nvflare-shared/references/pytorch-model-exchange.md.
Uniquement après l'existence des fichiers générés, ../nvflare-shared/references/validation-evidence.md, puis references/lightning-validation.md.

Complétez chaque phase du workflow avant de charger la référence de la phase suivante. N'énumérez pas les répertoires de références ni ne préchargez les références de validation, DDP/tracking, workflow général, dépendance, sortie runtime, ou reporting. Ne dépendez pas des exemples du repository NVFLARE.

Ne pas utiliser quand

Ne pas utiliser pour les modifications Lightning non-fédérées telles que la configuration DDP uniquement, le profilage, l'inference serving, les callbacks, l'arrêt anticipé, ou les schedulers ; ou pour les boucles d'entraînement manuel sans Lightning sur torch.nn.Module (orienter vers nvflare-convert-pytorch), Hugging Face Trainer (orienter vers nvflare-convert-huggingface), TensorFlow, XGBoost, scikit-learn, un job échoué (orienter vers nvflare-diagnose-job), des statistiques fédérées sans entraînement (orienter vers nvflare-fed-stats), ou un debugging Lightning générique sans intention FLARE ; quand le projet inspecté contient activement à la fois des points d'entrée Lightning et Hugging Face Trainer, orienter vers nvflare-orient. Hors du périmètre de conversion : déploiement en production, Kubernetes, cycle de vie POC, conception de politique de confidentialité/sécurité du déploiement, politiques de lancement distribué personnalisées non expressibles par les APIs du produit, refonte du tracking d'expérience, et recherche d'expérience entre recettes. Les demandes de protection de la confidentialité — chiffrement homomorphe (HE)/ agrégation chiffrée, confidentialité différentielle, et filtres de confidentialité — ne sont pas supportées : elles nécessitent un provisionnement ou une politique de déploiement au-delà du périmètre de conversion, donc signalez une telle demande comme non supportée et orienter vers provisionnement/déploiement, jamais en substituant une recette non protégée ou une clause de non-responsabilité. Si une demande combine conversion de statistiques fédérées et d'entraînement de modèle, traitez-la comme deux jobs et workflows indépendants : ne fusionnez pas ou ne chaînez pas automatiquement, n'orientez pas la combinaison vers nvflare-orient, et demandez quel workflow exécuter en premier avant de générer ou d'exécuter l'un ou l'autre job. Recommandez nvflare-fed-stats en premier uniquement quand le but de l'utilisateur est de comprendre la distribution des données ; traitez la conversion plus tard comme une demande séparée.

Workflow

Appliquez ../nvflare-shared/references/conversion-common.md pour la conversion entière ; ce SKILL.md énonce seulement les deltas spécifiques au framework.
Inspectez avant d'éditer avec nvflare agent inspect source <path> --format json plus la lecture directe ; l'extraction de faits est statique. Confirmez Lightning par rapport à PyTorch simple et transférez vers nvflare-convert-pytorch quand aucune preuve Lightning n'existe. Si l'inspection recommande nvflare-orient pour les propriétaires actifs Lightning et Hugging Face Trainer, arrêtez et transférez avant d'éditer.
Appliquez 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, Lightning, NVFLARE, ou de dépendance déclarés. Déterminez les dépendances applicables du chemin d'exécution sélectionné en premier. Si les artefacts de données requis existent déjà et que l'inspection statique montre que le chemin sélectionné n'atteindra pas un helper de téléchargement ou ses imports, traitez ses exigences de téléchargement uniquement comme inapplicables : ne les installez pas ou ne testez pas leurs imports. Testez uniquement les modules que la conversion générée et le chemin de validation sélectionné exécuteront, et gardez un test optionnel séparé et sortez avec zéro quand non disponible.
Identifiez le LightningModule existant, LightningDataModule, la construction du trainer, les callbacks, le checkpointing, validation_step/test_step et les dataloaders, les métriques, l'utilisation du logger, la preuve de partition source, la preuve de spawning de processus distribué, l'intention d'agrégation personnalisée, et les valeurs concrètes du constructeur de modèle que le serveur et les clients doivent partager.
Réutilisez la famille de recettes PyTorch ; Lightning n'est pas une famille de recettes séparée. Pour le cas standard — l'utilisateur demande explicitement FedAvg et l'inspection identifie Lightning — exécutez nvflare recipe show fedavg-pt --format json directement et construisez-le. Pour fedavg-pt, importez FedAvgRecipe uniquement depuis nvflare.app_opt.pt.recipes.fedavg, jamais depuis nvflare.recipe. Utilisez FedEval pour l'évaluation seule. Après chaque recipe show, dérivez les capacités de construction à partir de la référence de construction. Puis utilisez ce chemin documenté : n'exécutez pas d'imports NVFLARE exploratoires ou n'utilisez inspect, hasattr, la découverte de constante, les lectures de source/docstring SDK, ou les sondes de cycle de vie. Si un détail requis est absent, signalez une lacune de compétence ou échouez fermé plutôt que de deviner. Appelez recipe.execute(SimEnv(...)).
Convertissez le point d'entrée d'entraînement vers l'API Client Lightning : construisez le Trainer, appelez flare.patch(trainer), et laissez le trainer corrigé posséder l'échange de modèle. Gardez l'évaluation à l'intérieur de Lightning selon references/lightning-conversion.md et utilisez self.log. Dérivez evaluate_only=True uniquement pour FedEval ; omettez-le pour les recettes d'entraînement pour que son défaut reste False. Dérivez evaluate_before_train = recipe_algorithm != "cyclic" : Cyclic ne persiste que son modèle séquentiel final ; tous les autres algorithmes utilisent une validation explicite pour les métriques du serveur et, pour l'entraînement, la sélection du meilleur modèle. Vérifiez la clé dans la preuve du serveur ou échouez fermé.
Ajoutez ou mettez à jour job.py selon la règle de sérialisation du constructeur partagé. Utilisez la clé class_path ou path de la recette plus les args complètes quand des valeurs sont nécessaires ; une instance zéro-argument permise est le module complet. Ajoutez le câblage aggregator= demandé et la métrique, le transport tensoriel, le serveur offload, et les paramètres d'exécution dérivés du profil de construction PyTorch-family partagé. Si les sites ont besoin de train_args distincts, faites que chaque site override la chaîne d'arguments complète ; ne divisez jamais les arguments partagés et un chemin de données spécifique au site entre les valeurs au niveau de la recette et par site en attendant une fusion.
Immédiatement après l'existence des fichiers générés et avant toute vérification préalable, smoke test, nettoyage, validation, ou commande d'exécution, chargez les deux références de validation dans l'ordre du Chemin standard. Avant d'exécuter un run complet, sélectionnez et enregistrez exactement une cible de validation finale :
- pour une simulation locale demandée ou un premier run sans réclamation d'export, exécutez python job.py et n'exportez pas ou n'exécutez pas le dossier exporté avec le simulateur après ;
- pour un artefact demandé exporté/déployable, exportez d'abord et exécutez uniquement le dossier exporté avec le CLI simulateur ; n'exécutez pas d'abord python job.py. Si la cible de run complet sélectionnée échoue, diagnostiquez-la, appliquez un correctif ciblé, et réexécutez cette même cible. Changez les cibles uniquement quand la preuve montre que la cible d'origine ne représente pas l'artefact demandé, et enregistrez cette raison. L'inspection d'export appartient uniquement au chemin exporté. Gardez le nettoyage, l'export, et la simulation comme des appels d'outil séparés ; ne combinez jamais le nettoyage récursif avec l'exécution. Arrêtez au premier échelon de validation échoué avant de le diagnostiquer ; n'ajoutez pas de sondes de récupération spéculatives. Utilisez les mécanismes d'environnement et de permission fournis par l'hôte agent ; n'inspectez pas ou n'appliquez pas sa limite de sécurité.
Signalez la recette, les fichiers modifiés, la cible de validation sélectionnée, l'état de validation, les métriques, et les chemins d'artefact exacts.

Cas non-standard

Chargez uniquement la référence correspondant à un cas rencontré :

../nvflare-shared/references/conversion-workflow.md pour un cas non-standard non résolu de rerun, autorisation, ou sémantique manquante ; elle ne contient plus les contrats de localisation de données ou de partitionnement.
../nvflare-shared/references/pytorch-family-recipe-selection.md pour un algorithme ambigu ou non-FedAvg ; utilisez son catalogue pour FedAvg, FedOpt, FedProx, SCAFFOLD, Cyclic, Swarm, ou FedEval, et réservez nvflare recipe list pour ces cas.
../nvflare-shared/references/dependency-install.md quand une dépendance applicable est manquante.
../nvflare-shared/references/runtime-output-guidance.md pour une racine source en lecture seule ou une destination de sortie choisie par l'utilisateur.
references/lightning-ddp-and-tracking.md quand l'inspection trouve son déclencheur.
../nvflare-shared/references/metrics-and-artifact-reporting.md quand les artefacts de métrique normaux sont absents ou incohérents.

Exigences

Doit s'intégrer via flare.patch(trainer) et laisser le trainer corrigé posséder l'échange de modèle. Ne doit pas générer un chemin d'envoi/réception FLModel manuel comme l'échange Lightning par défaut, et ne doit pas passer le input_model reçu dans le Trainer.
Doit traiter flare.receive() à l'intérieur de la boucle corrigée comme accès optionnel aux métadonnées ou à la progression des tâches uniquement, pas comme un deuxième chemin de chargement de modèle.
Doit garder l'évaluation à l'intérieur de Lightning (trainer.validate/trainer.test, validation_step, self.log) ; ne doit pas générer une boucle PyTorch brute model.eval() pour la conversion Lightning ordinaire.
Sauf pour Cyclic, doit exécuter un trainer.validate(...) autonome explicite avant trainer.fit(...) et s'appuyer sur le callback corrigé pour attacher ses métriques scalaires finies ; ne doit jamais remplir model.__fl_meta__[MetaKey.INITIAL_METRICS]. La validation à l'intérieur de trainer.fit(...) n'est pas une métrique de modèle global reçu. Cyclic doit ignorer l'appel pré-fit et signaler son modèle final persisté, pas un meilleur modèle.
Doit auditer les arguments du constructeur de modèle avant d'écrire job.py en lisant la signature LightningModule.__init__ et le paramètre model de la recette sélectionnée depuis nvflare recipe show <recipe-name> --format json, pas en lisant la source de la bibliothèque NVFLARE. Émettez la clé class_path ou path documentée par la recette plus les args complètes pour chaque valeur requise ou surchargée. L'utilisation directe de LightningModule est permise uniquement quand les défauts zéro-argument inchangés la reconstruisent. Les valeurs doivent être claires à partir de la source, de la configuration, ou des métadonnées fournies. Sinon, posez une question sémantique quand un canal de réponse existe ou échouez fermé.
Doit utiliser la famille de recettes PyTorch ; ne doit pas inventer une recette Lightning uniquement. Appliquez la référence de construction après recipe show ; elle est canonique pour les paramètres de recette optionnels, la sélection de modèle, le transport tensoriel, l'offload disque du serveur, et le mode d'exécution.
Doit préserver le comportement local des callbacks et du logger où c'est sûr. Le tracking connecté au réseau existant, les callbacks d'upload, et les loggers personnalisés/inconnus sont une preuve, pas une demande de l'utilisateur : gardez-les désactivés lors de la validation sauf si explicitement demandé, et ne demandez pas uniquement pour les activer. Ceci affine references/lightning-conversion.md.
Ne doit pas faire charger les compétences non-PyTorch-family ../nvflare-shared/references/pytorch-model-exchange.md.
Le partitionnement du site, l'agrégation personnalisée, la Frontière Source de Vérité, et l'entrée/autorisation de l'utilisateur suivent ../nvflare-shared/references/conversion-common.md.

nvflare-convert-lightning