ShadowPEFT dans PEFT : la carte de décision pour l'exportation des adaptateurs

Même API get_peft_model, contrat de déploiement différent

L'entraînement commence toujours avec get_peft_model. Cette familiarité est utile, mais elle peut aussi masquer la question de déploiement la plus importante : qu'allez-vous exactement livrer ?

Avec ShadowPEFT, la réponse n'est pas un modèle de base fusionné. L'inférence attachée garde le modèle de base dans la boucle. L'inférence détachée pour modèle de langage utilise un calcul différent. Les deux choix peuvent être légitimes, mais ils exigent un empaquetage différent, des tests différents et des preuves d'acceptation différentes.

Ce que change l'intégration du 15 septembre

L'annonce d'intégration du 15 septembre 2026 des auteurs indique que ShadowPEFT a été fusionné dans la branche principale de PEFT. Le papier d'avril donne un contexte utile, mais ce n'est pas un nouveau papier de septembre. Au moment de l'annonce, essayer l'intégration signifie installer PEFT depuis le code source ; la documentation principale sépare ce chemin du paquet stable. La date de l'annonce n'est pas une preuve indépendante de la date exacte de fusion.

Épinglez les révisions PEFT et Transformers que vous avez testées. Épinglez aussi les révisions du modèle de base et du modèle shadow. Une installation non épinglée de la branche principale n'est pas un plan de publication reproductible.

L'annonce explique la méthode et rapporte des expériences. La référence API documente les opérations. Cet article relie ces éléments à une décision de déploiement : quel artefact existe, quelles dépendances doivent être présentes et quelles preuves démontrent que l'artefact est prêt à être livré. C'est un guide de planification, pas une reproduction Optijara des résultats des auteurs.

Pourquoi une trajectoire shadow ne peut pas fusionner avec les poids de base

La documentation ShadowPEFT décrit une petite dorsale qui produit un état shadow initial. À travers des blocs décodeurs contigus, l'écart h-s passe par une correction de faible rang vers l'entrée de base. Des mises à jour contrôlées par porte font ensuite avancer l'état shadow avec les sorties des blocs. Une seule trajectoire d'adaptateur peut être active à la fois.

C'est un comportement dépendant de l'entrée. Ce n'est pas un delta fixe qui peut être intégré aux poids de base. Par conséquent, merge, merge_adapter et merge_and_unload lèvent des erreurs. Les méthodes PEFT familières de sauvegarde et de chargement ne suppriment pas cette restriction.

Gardez trois inventaires séparés : l'adaptateur sauvegardé, la configuration d'inférence attachée base plus shadow et le checkpoint complet du modèle de langage détaché. Ce ne sont pas trois noms de fichiers pour la même chose. Ce sont des produits différents.

La carte de décision pour l'exportation des adaptateurs : choisir l'artefact avant l'entraînement

Quatre routes de déploiement et leurs preuves d'acceptation

La carte de décision pour l'exportation des adaptateurs d'Optijara est une aide de planification originale pour cet article, pas un standard fournisseur. Commencez par la route dont vous avez besoin en production, puis choisissez les étapes d'entraînement, d'exportation et de validation qui peuvent vraiment la produire.

La route détachée mérite un examen attentif. Un petit fichier d'adaptateur n'est pas la même chose qu'un checkpoint avec une table d'embeddings, une projection, une dorsale, une tête de sortie, un tokenizer et une configuration. Notez quels composants la configuration choisie partage, entraîne et sauvegarde. Cet inventaire est aussi utile lors de l'examen des détails d'artefacts plutôt que des noms de fichiers, même si cet article ne prétend pas que ShadowPEFT prend en charge la conversion GGUF.

Pour Diffusers, la documentation sépare le backend d'architecture Flux2 enregistré d'un repli MLP résiduel token par token pour les architectures compatibles. Aucun des deux chemins ne prend en charge le déchargement autonome. Cette limite s'applique largement aux modèles Diffusers, pas seulement aux architectures sans backend enregistré.

L'entraînement, l'inférence attachée et l'exportation détachée sont des branches différentes

Les branches ci-dessous montrent les décisions ShadowPEFT et les contrôles qui leur sont associés. La branche Diffusers est explicitement non prise en charge. Elles ne décrivent pas un routeur edge-cloud implémenté.

Ce résumé compact est du JSON descriptif. Ce n'est pas une configuration PEFT et il n'effectue pas de contrôles de compatibilité.

{
  "framework": "Adapter Export Decision Map",
  "shadow_merge_supported": false,
  "attached_requires_base": true,
  "detached_lm_requires_separate_evaluation": true,
  "independent_export_copy": true,
  "diffusers_standalone_supported": false
}

Exporter un modèle de langage détaché sans perdre le contrat d'artefact

Entraîner délibérément le chemin autonome

Le calcul Transformers détaché documenté est head(projection(backbone(x))). Ce n'est pas l'état shadow inter-couches final sL, car sL dépend des interactions avec le décodeur de base. De bons résultats attachés ne prouvent donc pas la qualité de tâche détachée.

Traitez la qualité du prédicteur comme une question d'acceptation séparée. Une exportation peut être techniquement valide tout en restant le mauvais prédicteur pour la tâche. Une sauvegarde réussie ne tranche pas cette question.

La perte de tâche auxiliaire supervise l'état shadow initial s0, le chemin disponible sans ces interactions de base. La configuration documente auxiliary_loss_weight=0.05 comme valeur par défaut, avec la perte ajoutée lorsque des labels sont fournis. Vérifiez que le job d'entraînement fournit des labels et gère la tête de tâche comme prévu. Définir une valeur dans la configuration n'est pas la même chose que vérifier le chemin de perte.

Pour la modélisation causale du langage, la tête de sortie de base est réutilisée. Incluez modules_to_save=['lm_head'] lorsque cette tête doit être entraînée et sauvegardée via PEFT. Ne faites pas de l'entraînement de la tête un réflexe. Notez la taille du vocabulaire de la tête et sa relation avec le tokenizer et la table d'embeddings.

Utiliser unload_shadow(copy=True) pour une exportation indépendante

L'extrait suivant suit l'interface d'exportation documentée. Il est illustratif et n'est pas exécuté ici. peft_model signifie un modèle Transformers PEFT compatible et déjà entraîné, pas un pipeline Diffusers arbitraire.

# Illustration uniquement : non exécutée pour cet article.
detached_model = peft_model.base_model.unload_shadow(copy=True)
detached_model.save_pretrained("standalone-shadow")

Par défaut, copy=False partage des modules avec le modèle PEFT. Si le shadow utilise des embeddings d'entrée de base gelés via une référence externe à son arbre de sous-modules enregistré, la sauvegarde de cet objet détaché peut omettre la table d'embeddings. La documentation recommande copy=True lors de la sauvegarde ou de l'envoi d'un modèle indépendant, car ce paramètre attache une copie privée des embeddings. Le compromis est une mémoire supplémentaire pendant l'exportation.

Ce drapeau résout une dépendance de sérialisation. Il ne prouve pas que le tokenizer a été sauvegardé, que le chargeur est compatible ou que la qualité détachée répond à l'exigence de la tâche. Utilisez l'interface de chargement de l'implémentation épinglée. Ne déduisez pas la classe de rechargement à partir d'un nom commode.

Checklist de rechargement à froid, explicitement non exécutée ici

Utilisez cette checklist prospective avant d'appeler une exportation déployable. Optijara n'a pas entraîné, exporte, rechargé ni évalué le modèle pour cet article. La documentation et l'inspection du code source ne remplacent pas des preuves locales de test de sérialisation.

Conservez l'artefact attaché pendant que vous testez l'exportation. Un chargement propre ne doit pas remplacer automatiquement le candidat de déploiement attaché. Il valide seulement le contrôle de sérialisation. Rejetez les artefacts incomplets avant d'interpréter les différences de qualité, surtout lorsque des réglages de tokenizer ou des poids manquants peuvent expliquer le comportement.

Mesurer l'inférence attachée et détachée comme des produits séparés

Quatre bases de comparaison sur la même charge retenue

Planifiez une comparaison entre base seule, LoRA, Shadow attaché et Shadow détaché. Utilisez les mêmes tâches retenues, prompts, règles de notation et réglages de génération lorsque cela a du sens. Notez les différences de tokenizer, les tailles de modèle et les budgets d'entraînement. Une architecture détachée plus petite n'est pas identique à la base, et l'évaluation ne doit pas prétendre le contraire.

Fixez les seuils d'acceptation avant d'examiner les résultats. Une tâche hypothétique d'étiquetage de documents pourrait surtout privilégier l'exactitude des labels et la stabilité d'une sortie structurée. Un assistant interactif a aussi besoin de contrôles de latence. Ce sont des choix d'évaluation proposés, pas des résultats ShadowPEFT rapportés.

La taille de l'adaptateur n'est pas la mémoire de service

La génération attachée utilise des caches KV appariés pour la base et le shadow. La référence API décrit ShadowCache comme volontairement non compilable ; la conversion en tuple héritée n'est pas prise en charge. Ne promettez pas la prise en charge de torch.compile ou la compatibilité avec un moteur d'inférence simplement parce que generate() semble familier. L'implémentation du modèle définit séparément le chemin d'exportation autonome et sa restriction Diffusers.

Mesurez la croissance du cache sous la charge que vous comptez servir. Séparez les octets de l'adaptateur, les octets de l'exportation, les pics de chargement et la mémoire de service en régime stable. Suivez la même discipline que pour tester l'artefact exact sur le runtime et l'appareil cibles. Un téléchargement plus petit n'établit pas une exécution attachée plus petite.

Lire le benchmark des auteurs sans raccourci de coût

Le benchmark d'intégration des auteurs rapporte les résultats suivants d'entraînement MetaMathQA et d'évaluation GSM8K pour Llama 3.2 3B sur une NVIDIA A100 80GB. Leur tableau nomme la colonne de stockage "Checkpoint" ; ce sont des artefacts d'expérience rapportés, pas des exportations autonomes vérifiées.

Dans cette expérience, ShadowPEFT obtient un score plus élevé et un checkpoint plus petit, avec un pic mémoire plus élevé et un entraînement plus long. Inspectez la configuration Shadow et la configuration LoRA liées. L'annonce appelle ces réglages des valeurs par défaut, mais le fichier Shadow spécifie auxiliary_loss_weight=0.01 et shadow_alpha=0.5, plutôt que les valeurs par défaut API de 0.05 et 0.1. Utilisez les fichiers liés pour comprendre l'expérience ; ne supposez pas une recherche d'hyperparamètres égale. Un résultat rapporte sans incertitude n'établit pas une supériorité large. Il ne dit rien non plus, à lui seul, sur la mémoire de service détachée, la latence ou l'exactitude de l'inférence détachée.

Ce qu'il faut éviter dans un déploiement ShadowPEFT

Traiter chaque adaptateur PEFT comme fusionnable

Les points suivants sont des erreurs d'implémentation anticipées, pas des incidents issus de travaux clients d'Optijara. Un script de déploiement qui appelle merge_and_unload pour chaque type d'adaptateur a besoin d'une branche propre à la méthode. Remplacer cet appel par un déchargement shadow change aussi le prédicteur livré, donc l'ancien rapport d'acceptation ne peut pas simplement être réutilisé.

Les modes de défaillance possibles incluent le fait de traiter la taille du checkpoint comme un pic mémoire, d'attribuer des scores de benchmark attachés à un modèle détaché et de valider la sérialisation dans un processus ou la base d'origine reste disponible. Les modules partagés peuvent donner l'impression qu'une expérience en mémoire est complète tout en laissant une exportation indépendante non testée.

Confondre l'entraînement image auxiliaire avec un débruiteur détachable

Un chemin d'entraînement de débruitage auxiliaire ne crée pas un produit Diffusers autonome pris en charge. La prise en charge du backend Flux2 concerne la manière dont le calcul shadow est construit. Elle ne supprime pas le NotImplementedError lors du déchargement autonome.

Les auteurs rapportent aussi une comparaison de génération d'images utilisant un petit jeu DreamBooth à chat unique. Cette expérience propre à un modèle ne prouve pas la généralisation à tous les sujets, la qualité universelle des images ni la qualité d'un débruiteur autonome. Gardez ces affirmations hors d'une proposition de déploiement.

Pour les équipes qui passent d'un outil image à un autre, des contrôles familiers ne prouvent pas la parité d'exécution. La même logique s'applique ici. Les noms d'API partagés sont une ergonomie utile, pas la preuve que deux méthodes exportent des modèles équivalents.

Réserves avant d'adopter l'intégration de la branche principale

Compatibilité, coût d'implémentation et limites d'évaluation

Le comportement de la branche principale dépend de la révision. Notez l'architecture, le chargeur, les versions de dépendances et les restrictions d'exécution couvertes par vos tests. La description de prise en charge dans la documentation est le point de départ du travail. Ce n'est pas une certification pour chaque moteur de service.

Prévoyez un budget pour la vérification d'exportation, l'évaluation, le stockage et la maintenance en plus de l'entraînement. Le matériel, les prix fournisseur, la longueur de contexte, la concurrence et le choix du modèle influencent tous le résultat mesuré. Un adaptateur plus petit ne peut pas porter à lui seul une affirmation d'économies. Gardez l'incertitude visible dans les comparaisons, et relancez les contrôles pertinents après les changements de dépendances.

Les contrôles de confidentialité et de licence restent propres à chaque artefact

Examinez les conditions du modèle de base, du checkpoint shadow, du jeu de données, du tokenizer et de la tête de tâche avant toute distribution. Le checkpoint shadow Qwen projeté est une configuration concrète à inspecter, pas une permission générale pour chaque déploiement dérivé. Le détachement n'accorde pas de droits de redistribution et ne supprime pas les préoccupations de confidentialité liées aux données d'entraînement.

Choisissez une route prise en charge, conservez son inventaire de dépendances et évaluez l'artefact qui atteindra vraiment l'environnement cible. Laissez l'exportation Diffusers autonome non prise en charge hors du plan de publication jusqu'à ce que l'implémentation la prenne explicitement en charge.