Transformers documentation
Chargement dynamique des poids
Chargement dynamique des poids
Les points de contrôle sont souvent sérialisés dans un format qui ne correspond pas à ce qu'un modèle attend lors de l'exécution. Les scénarios courants incluent :
- Poids fusionnés : les points de contrôle stockent des poids distincts
gate_projetup_proj, mais le modèle utilise ungate_up_projfusionné pour des raisons d'efficacité. - Consolidation des experts MoE : les poids des experts individuels (
experts.0.weight,experts.1.weight, …) doivent être empilés en un unique tenseur 3D. - Nommage ancien : les anciens points de contrôle utilisent des conventions de nommage différentes (par exemple,
LayerNorm.gammapar rapport àLayerNorm.weight). - Modèles composites : un modèle vision-langage contient deux sous-modules
PreTrainedModel, chacun ayant sa propre convention de point de contrôle. - Quantification : Les poids peuvent être stockés dans des formats quantifiés nécessitant une désérialisation.
Le chargement dynamique des poids traite ce problème en appliquant des opérations planifiées et réversibles aux tenseurs du point de contrôle au moment de leur chargement. Transformers expose cette fonctionnalité via WeightConverter et WeightRenaming, qui décrivent comment une ou plusieurs clés de point de contrôle correspondent à un ou plusieurs paramètres du modèle et quelles ConversionOps composables doivent être exécutées sur les tenseurs correspondants. Cette approche s'adapte aux nouvelles dispositions de poids, prend en charge les mélanges d'experts quantifiés (MoE) et s'intègre à la parallélisation de tenseurs.
Ce guide montre comment utiliser WeightConverter pour convertir des tenseurs. Les correspondances de conversion se trouvent dans conversion_mapping.py ; une correspondance enregistrée est indexée par une chaîne model_type (par ex. "mixtral") ou par un nom de classe (par ex. "LlavaModel").
Pipeline de chargement complet
Tous les modèles passent par le système de chargement dynamique des poids. La conversion par correspondance est une étape facultative au sein de ce système qui ne s'active que lorsque le modèle possède des entrées enregistrées pour son nom de classe ou son model_type.
Checkpoint File → from_pretrained() → convert_and_load_state_dict_in_model()
↓
┌───────────────────────────────────────────────────────────┐
│ For each weight in checkpoint: │
│ 1. Match renamed/processed source key to model parameter │
│ 2. Shard the weight and send to device (async) │
│ 3. Collect tensors with the same source_pattern together │
│ (e.g. MoE experts, gate_up_proj) │
│ 4. Apply dequantization/deserialization (if pre-quant) │
│ 5. Apply conversion (if defined) │
│ 6. Apply quantization (if enabled and step 4 not used) │
│ 7. Set parameter on model │
└───────────────────────────────────────────────────────────┘| Étape | Lorsqu'il s'active |
|---|---|
| Chargement dynamique | Toujours, pour tous les modèles |
| Cartographie de conversion | Uniquement lorsque la classe du modèle ou model_type est enregistrée dans _MODEL_TO_CONVERSION_PATTERN |
| Sharding TP | Uniquement lorsque DistributedConfig(tp_size=N) est utilisé et que le modèle possède base_model_tp_plan |
| Déquantification/désérialisation | Uniquement lors du chargement d'un point de contrôle pré-quantifié |
| Quantification | Uniquement lorsqu'une configuration de quantification est fournie et que les poids ne sont pas pré-quantifiés |
Modèles denses (par ex. Llama)
Pour la plupart des modèles denses, le format de point de contrôle correspond directement au format du modèle, de sorte qu’aucune conversion de correspondance n’est nécessaire. Certains modèles peuvent toutefois nécessiter un renommage (par exemple, des conventions de nommage obsolètes). Le fractionnement TP s’applique toujours lorsqu’il est activé.
Checkpoint: Model:
model.layers.0.self_attn.q_proj.weight → model.layers.0.self_attn.q_proj.weight
model.layers.0.self_attn.k_proj.weight → model.layers.0.self_attn.k_proj.weight
model.layers.0.mlp.gate_proj.weight → model.layers.0.mlp.gate_proj.weight
model.layers.0.mlp.up_proj.weight → model.layers.0.mlp.up_proj.weight
model.layers.0.mlp.down_proj.weight → model.layers.0.mlp.down_proj.weightLes points de contrôle hérités peuvent utiliser des conventions de nommage plus anciennes, gérées par des renommages intégrés appliqués à tous les modèles :
Checkpoint: Model:
LayerNorm.gamma → LayerNorm.weight
LayerNorm.beta → LayerNorm.biasModèles MoE (par ex. Mixtral)
Pour les modèles MoE, le format de point de contrôle diffère du format du modèle. La conversion par correspondance transforme les poids d’experts séparés en tenseurs 3D fusionnés, et le fractionnement TP s’applique après la conversion.
Checkpoint: Model:
experts.0.w1.weight ─┐
experts.1.w1.weight │ MergeModulelist
... ├───────────────→ experts.gate_up_proj (8, hidden, 2*intermediate)
experts.0.w3.weight │ + Concatenate
experts.1.w3.weight ─┘Modèles composites (par exemple, vision-langage)
Un PreTrainedModel peut contenir d'autres sous-modules PreTrainedModel. Chaque sous-modèle peut avoir sa propre correspondance de conversion, enregistrée par rapport à son nom de classe ou à son model_type. Lors du chargement du modèle parent, get_model_conversion_mapping parcourt les sous-modèles en profondeur, collecte leurs correspondances et scope automatiquement chaque transformation au chemin de son sous-module via scope_prefix.
Composite model: Per-submodel mappings (auto-scoped):
LlavaForConditionalGeneration
├── vision_model: SiglipVisionModel → SiglipVisionModel mapping (scope="vision_model")
└── language_model: LlamaForCausalLM → LlamaForCausalLM mapping (scope="language_model")scope_prefix est le chemin pointé du sous-module ("vision_model", "language_model.model", etc.). Une transformation scopée ne s’applique qu’aux clés commençant par f"{scope_prefix}." ; le préfixe est retiré avant l’appariement des motifs puis ré-ajouté après le remplacement, de sorte que la correspondance de chaque sous-modèle est écrite relativement au sous-modèle, exactement comme s’il s’agissait de la racine.
Architecture
Le système est construit autour de plusieurs composants clés définis dans core_model_loading.py :
Phase 1 — Traitement par clé (parcourt les clés du point de contrôle) :
- Parcourir la liste de transformations une seule fois. Chaque
WeightRenamingcorrespondant est appliqué (par ex.block_sparse_moe→mlp), et au plus un WeightConverter peut revendiquer la clé (par ex.experts.*.w1.weight). - Fragmenter (TP) et envoyer sur l'appareil de manière asynchrone via
ThreadPoolExecutor. - Collecter les tenseurs partageant le même
source_pattern(par exemple, tous les poids des experts MoE, les projections gate + up).
Phase 2 — Traitement par correspondance (parcourt les correspondances collectées) :
- Déquantiser/désérialiser (uniquement pour les points de contrôle pré-quantifiés).
- Appliquer la chaîne ConversionOps :
Chunk,Concatenate,MergeModulelist,Transpose, etc. - Quantifier à la volée (si non pré-quantifié).
- Définir le paramètre sur le modèle.
WeightTransform
La classe de base qui gère l’analyse de motifs et la collecte de tenseurs :
- Compilation de motifs : Les motifs source sont des expressions régulières complètes, évaluées à l'aide de
re.search(). Le joker*correspond à tout composant indexable et regroupe toutes les correspondances pour les opérations par lot. - Groupes de capture et références arrière : les groupes de capture des motifs source peuvent être référencés sous la forme
\1,\2, … dans les motifs cible afin de conserver les sous-chaînes (par exemple, les indices de couche) lors du renommage. - Portée :
scope_prefix(défini automatiquement pour chaque sous-modèle parget_model_conversion_mapping) restreint la transformation aux clés situées sous ce chemin. Le préfixe est retiré avant l'appariement puis réappliqué après le remplacement. - Renommage des clés :
rename_source_key()applique l'expression régulière (avec la gestion de l'étendue) et renvoie(renamed_key, source_pattern)afin que le chargeur sache quel convertisseur, le cas échéant, a revendiqué la clé. - Collecte de tenseurs :
add_tensor()accumule les tenseurs résolus (ou desFuture) sous leursource_patternafin que tous les tenseurs nécessaires à une seule conversion (par exemple, tous les poids d'experts MoE) soient regroupés avant l'exécution de la chaîne d'opérations. - Réversibilité :
reverse_transform()échange les motifs source ↔ cible et inverse chaque opération, de sorte que la même liste, parcourue à l'envers, pilote l'enregistrement. - Suivi :
was_used()indique si la transformation a réellement correspondu à une clé lors du chargement ; cela est nécessaire pour que les renommages non bijectifs (par ex.PrefixChangeajoutant un préfixe qui peut déjà être présent) puissent être réappliqués de manière symétrique lors de l'enregistrement.
WeightRenaming
WeightRenaming est un WeightTransform spécialisé dans le renommage pur des clés, sans opérations sur les tenseurs. Contrairement à WeightConverter, un WeightRenaming ne claim pas la clé, ce qui permet d’enchaîner librement plusieurs renommages. Sur le chemin de chargement, tous les renommages s’exécutent avant le convertisseur ; sur le chemin d’enregistrement (liste inversée), tous les renommages inversés s’exécutent après le convertisseur inversé — voir la règle d’ordre ci-dessus.
# Legacy checkpoint compatibility
WeightRenaming("LayerNorm.gamma", "LayerNorm.weight")
# Module path changes
WeightRenaming(".block_sparse_moe.", ".mlp.")PrefixChange est un wrapper de plus haut niveau autour de WeightRenaming pour le cas courant de suppression ou d’ajout d’un composant de chemin entier. Le paramètre facultatif model_prefix limite l’opération aux clés situées sous cet espace de noms :
# "model.layers.bad_prefix.weight" → "model.layers.weight"
PrefixChange(prefix_to_remove="bad_prefix", model_prefix="model.layers")
# "layers.0.weight" → "model.layers.0.weight"
PrefixChange(prefix_to_add="model")WeightConverter
WeightConverter étend WeightTransform avec une chaîne de ConversionOps qui agissent sur les tenseurs collectés. Les quatre cardinalités prises en charge sont :
| Cardinalité | Modèles de source | Motifs cibles | Fonctionnement typique |
|---|---|---|---|
| un-à-un | 1 | 1 | Transpose, PermuteForRope |
| un-à-plusieurs | 1 | >1 | Chunk (par exemple, dépaqueter qkv_proj) |
| plusieurs vers un | >1 | 1 | Concatener, MergeModulelist (par ex. fusionner les experts) |
| plusieurs-à-plusieurs | >1 | >1 | uniquement avec des opérations qui le prennent explicitement en charge (par ex. ErnieFuseAndSplitTextVisionExperts) |
WeightConverter(
source_patterns=[".experts.*.w1.weight", ".experts.*.w3.weight"],
target_patterns=".experts.gate_up_proj",
operations=[MergeModulelist(dim=0), Concatenate(dim=1)],
)Un WeightConverter est également réversible : reverse_transform() inverse source ↔ cible et remplace chaque opération par son reverse_op, de sorte qu’un mappage de conversion enregistré est bidirectionnel par construction (le chargement utilise la liste telle quelle, l’enregistrement l’utilise à l’envers).
Ordre des renommages et des convertisseurs
Placez les entrées WeightRenaming avant les entrées WeightConverter et gardez leurs feuilles disjointes : les renommages normalisent les clés consommées par les convertisseurs, mais ne ciblent jamais une feuille produite par un convertisseur. Le chemin de sauvegarde s’appuie sur ce principe pour inverser la correspondance en deux phases (inversion des convertisseurs, puis inversion des renommages).
La liste de transformations est parcourue dans l'ordre, une fois par clé de point de contrôle. Pour chaque clé :
- Chaque
WeightRenamingcorrespondant est déclenché ; plusieurs renommages peuvent s’enchaîner. - Le premier
WeightConverterqui correspond aux claims de la clé. Les convertisseurs suivants sont ignorés — cela garantit que le tenseur est acheminé vers un convertisseur unique pour l’étape de fusion/séparation, et c’est la raison pour laquelle deux convertisseurs aux intentions chevauchantes constitueraient une mauvaise configuration.
weight_mapping = [
WeightRenaming("^old_prefix", "encoder"), # rename runs always
WeightConverter( # converter claims the key
"attn.qkv_proj.weight",
["attn.q_proj.weight", "attn.k_proj.weight", "attn.v_proj.weight"],
operations=[Chunk(dim=0)],
),
]
# Load: "old_prefix.attn.qkv_proj.weight"
# → WeightRenaming → "encoder.attn.qkv_proj.weight"
# → WeightConverter → "encoder.attn.{q,k,v}_proj.weight"
#
# Save: list reversed, each transform inverted:
# → rev(WeightConverter) repacks QKV → "encoder.attn.qkv_proj.weight"
# → rev(WeightRenaming) fixes prefix → "old_prefix.attn.qkv_proj.weight"Opérations de conversion
La classe WeightConverter comporte plusieurs opérations exécutées lors de l’appel de from_pretrained() pour transformer les tenseurs sources du point de contrôle en tenseurs cibles du modèle.
Les opérations sont entièrement réversibles. L'enregistrement inverse les conversions et restitue le point de contrôle d'origine, ce qui vous permet de travailler facilement entre différents frameworks.
| Opération | Inverser |
|---|---|
Chunk(dim) | Concatenate(dim) |
Concatenate(dim) | Chunk(dim) |
MergeModulelist(dim) | SplitModulelist(dim) |
SplitModulelist(dim) | MergeModulelist(dim) |
Transpose(d0, d1) | Transpose(d1, d0) |
PermuteForRope() | PermuteForRope() |
Conv3dToLinear(...) | LinearToConv3d(...) |
Chunk
L'opération Chunk divise un tenseur en parties égales le long d'une dimension. Par exemple, si un modèle attend Q, K et V sous forme de trois tenseurs distincts plutôt que d'un tenseur unique.
WeightConverter(
"self_attn.qkv_proj",
["self_attn.q_proj", "self_attn.k_proj", "self_attn.v_proj"],
operations=[Chunk(dim=0)],
)Concaténer
L'opération Concatenate fusionne des tenseurs distincts en un tenseur unique. Par exemple, si un modèle attend Q, K et V sous forme d'un tenseur unique plutôt que de tenseurs séparés.
WeightConverter(
["self_attn.q_proj", "self_attn.k_proj", "self_attn.v_proj"],
"self_attn.qkv_proj",
operations=[Concatenate(dim=0)],
)MergeModulelist
MergeModulelist fusionne une liste de tenseurs 2D en un seul tenseur 3D. Par exemple, vous pouvez combiner MergeModulelist avec Concatenate pour empiler les experts d'un MoE et les regrouper dans un seul tenseur.
WeightConverter(
["block_sparse_moe.experts.*.w1.weight", "block_sparse_moe.experts.*.w3.weight"],
"mlp.experts.gate_up_proj",
operations=[MergeModulelist(dim=0), Concatenate(dim=1)],
)SplitModulelist
SplitModulelist divise un tenseur 3D en une liste de tenseurs 2D. Par exemple, vous pouvez diviser une pile d’experts en experts individuels.
WeightConverter(
"mlp.experts.down_proj",
"block_sparse_moe.experts.*.w2.weight",
operations=[SplitModulelist(dim=0)],
)PermuteForRope
PermuteForRope convertit les poids du format entrelacé vers le format sin/cos. Par exemple, vous pouvez composer Chunk avec PermuteForRope pour séparer un tenseur QKV fusionné et appliquer la permutation RoPE sin/cos à Q et K.
WeightConverter(
["model.layers.*.self_attn.qkv_proj.weight"],
[
"model.layers.*.self_attn.q_proj.weight",
"model.layers.*.self_attn.k_proj.weight",
"model.layers.*.self_attn.v_proj.weight",
],
operations=[Chunk(dim=0), PermuteForRope()],
)Transposer
Transpose échange les dimensions d'un tenseur. Utile pour convertir les dispositions des poids entre différentes conventions.
WeightConverter(
source_patterns="mlp.gate.weight",
target_patterns="mlp.text_moe.gate.weight",
operations=[Transpose(dim0=0, dim1=1)],
)Enchaînement des opérations
Les opérations peuvent être enchaînées pour effectuer des transformations complexes. Les opérations s’exécutent dans l’ordre, la sortie de chaque opération devenant l’entrée de l’opération suivante.
Exemple : conversion de Mixtral MoE
WeightConverter(
source_patterns=[
".experts.*.w1.weight", # gate_proj per expert
".experts.*.w3.weight", # up_proj per expert
],
target_patterns=".experts.gate_up_proj",
operations=[
MergeModulelist(dim=0), # Stack all experts: (n_experts, in, out)
Concatenate(dim=1), # Fuse gate+up: (n_experts, in, 2*out)
],
)Flux de données :
Input:
".experts.*.w1.weight": [tensor_0, tensor_1, ..., tensor_7] # 8 experts
".experts.*.w3.weight": [tensor_0, tensor_1, ..., tensor_7] # 8 experts
After MergeModulelist(dim=0):
".experts.*.w1.weight": (8, 4096, 14336) # stacked gate
".experts.*.w3.weight": (8, 4096, 14336) # stacked up
After Concatenate(dim=1):
".experts.gate_up_proj": (8, 4096, 28672) # fused gate_upRègles de correspondance de motifs
- Les motifs de source sont des expressions régulières complètes évaluées avec
re.search().^est ancré au début de la clé scoped (après le retrait descope_prefix). *est un joker par index qui regroupe tous les tenseurs correspondants sous le même motif source (en conservant l'ordre du point de contrôle pour une concaténation correcte).- Les groupes de capture dans les motifs source peuvent être référencés sous la forme
\1,\2, … dans les motifs cible afin de conserver certaines parties de la clé d’origine (par exemple, les indices de couche). - Les transformations à portée limitée (
scope_prefixdéfini) ne correspondent qu’aux clés commençant parf"{scope_prefix}.".
Enregistrement d'une correspondance de conversion
Une liste de conversion est enregistrée sous une clé de chaîne — soit un model_type (par ex. "mixtral"), soit un nom de classe (par ex. "LlavaModel") :
from transformers.conversion_mapping import register_checkpoint_conversion_mapping
register_checkpoint_conversion_mapping(
"my_model_type",
[
WeightRenaming(".old.", ".new."),
WeightConverter(
".experts.*.w1.weight",
".experts.gate_proj",
operations=[MergeModulelist(dim=0)],
),
],
)Règles de recherche
Lorsque get_model_conversion_mapping traite un PreTrainedModel, chaque sous-PreTrainedModel est visité dans l'ordre DFS (nn.Module.named_modules() filtré aux instances de PreTrainedModel). Chaque sous-modèle est résolu en deux étapes : un filtre de code personnalisé s'exécute d'abord, puis la correspondance enregistrée est recherchée.
Les modèles de code personnalisé sont ignorés avant toute recherche. Un sous-modèle est considéré comme du code personnalisé lorsque is_custom_code() renvoie True, ce qui couvre les modèles chargés depuis le Hub avec trust_remote_code=True ainsi que toute classe de modèle non présente dans Transformers. Les modèles de code personnalisé n’héritent pas d’un mappage de conversion, car leur nom de classe ou leur model_type pourrait entrer en collision avec un modèle natif. Par exemple, une architecture personnalisée qui définit model_type="mixtral" n’appliquera pas les transformations de fusion d’experts intégrées à Mixtral.
Enregistrez explicitement un modèle de code personnalisé avec
register_checkpoint_conversion_mappingpour appliquer une correspondance de conversion. L'enregistrement ajoute le nom de la classe oumodel_typeà l'ensemble des correspondances enregistrées par l'utilisateur, ce qui dispense le modèle de l'ignorance du code personnalisé et le fait passer par la recherche normale décrite ci-dessous.
Pour chaque sous-modèle qui passe le filtre de code personnalisé :
- La recherche par nom de classe est tentée en premier, puis
model_type. Si les deux sont enregistrés pour le même module, le mappage par nom de classe prend le pas et celui demodel_typeest ignoré pour ce module — ce qui permet à une tête de tâche (par ex.LlavaForConditionalGeneration) de remplacer la référence communemodel_type("llava"). - La sélection de correspondance a
scope_prefixdéfini sur le chemin pointé du sous-module (""pour la racine). - Ancestor-based deduplication décide s'il faut conserver la correspondance :
- Si un chemin ancêtre a déjà revendiqué le même identifiant (nom de classe ou
model_type), le sous-module est ignoré — la mapping non scopée ou de portée supérieure de l’ancêtre couvre déjà ce sous-arbre. - Si seul un frère l’a revendiqué, le sous-module est conservé avec son propre
scope_prefix. Chaque frère reçoit sa propre cartographie scopée.
- Si un chemin ancêtre a déjà revendiqué le même identifiant (nom de classe ou
Les listes de suivi des noms de classes et de model_type sont gérées séparément, avec une subtilité : lorsqu'un module est apparié via son nom de classe, son model_type n'est pas ajouté à la liste de suivi. Cela permet de conserver l'accessibilité, via la recherche par model_type, des autres modules partageant le même model_type mais ne disposant pas d'un mappage spécifique à la classe (par exemple DetrModel sous DetrForSegmentation).
Mappages basés sur des classes vs alias model_type
Les deux styles coexistent dans _MODEL_TO_CONVERSION_PATTERN :
_MODEL_TO_CONVERSION_PATTERN = {
# model_type aliases (lookup by config.model_type)
"minimax": "mixtral",
"qwen3_moe": "qwen2_moe",
"mistral3": "llava",
# class-name aliases (lookup by type(submodule).__name__)
"PaliGemmaModel": "LlavaModel",
"MaskFormerDetrDecoder": "DetrModel",
...
}Les clés de nom de classe sont préférées lorsque le model_type est partagé mais qu'une classe spécifique nécessite un comportement différent.
Intégration du parallélisme de tenseurs
Le système de chargement dynamique s’intègre à la parallélisation de tenseurs (TP) via la hiérarchie TensorParallelLayer définie dans src/transformers/integrations/tensor_parallel.py.
Lorsque le TP est activé, les tenseurs sont fractionnés durant la matérialisation, et non après. Cela signifie que chaque rang ne charge que la portion du tenseur dont il a besoin.
def spawn_tp_materialize(thread_pool, tensor, sharding_method, tensor_idx, device, dtype):
def _job():
return sharding_method.shard_tensor(tensor, tensor_idx=tensor_idx, device=device, dtype=dtype)
return thread_pool.submit(_job)Styles de parallélisme disponibles
| Style | Dimension des shards de poids | Description |
|---|---|---|
colwise | -2 | Par colonne : fonctionnalités de sortie fragmentées |
rowwise | -1 | Par ligne : fonctionnalités d'entrée fractionnées |
packed_colwise | -2 | Pour les poids fusionnés (gate_up_proj) |
packed_rowwise | -1 | Pour les poids fusionnés |
embedding_rowwise | 0 | Parallélisme du vocabulaire |
grouped_gemm | 0 | Parallélisme d'experts pour MoE |
sequence_parallel | Aucun | Aucun fractionnement des poids |
Gestion des poids empilés
Pour les poids fusionnés tels que gate_up_proj, une attention particulière est nécessaire pour les découper correctement :
def get_packed_weights(param, empty_param, device_mesh, rank, dim):
"""
Interleaves gate and up shards correctly.
Packed tensor: [G0 G1 G2 G3 | U0 U1 U2 U3]
With TP=2:
- Rank 0 gets: [G0 G1 | U0 U1]
- Rank 1 gets: [G2 G3 | U2 U3]
"""L'opération TP est stockée dans WeightTransform et appliquée après les opérations de conversion :
if matched_tp_pattern := tp_plan_alt.search(renamed_key):
tp_layer = ALL_PARALLEL_STYLES[model.tp_plan[matched_tp_pattern]]
mapping.distributed_operation = tp_layer(
device_mesh=device_mesh,
rank=device_mesh.get_local_rank(),
empty_param=empty_param.clone()
)Intégration de la quantification
La quantification s'intègre au pipeline de chargement de deux manières, selon que le point de contrôle est déjà quantisé ou non :
- Points de contrôle pré-quantifiés : le quantificateur fournit des instances WeightConverter (via
get_weight_conversions()) qui désérialisent les tenseurs quantifiés. Les dtypes des points de contrôle sont conservés afin d'éviter des conversions non souhaitées. - Quantification à la volée : le quantificateur fournit une opération de quantification appliquée après les opérations de conversion, qui quantifie les poids au fur et à mesure de leur chargement.
Le quantiseur peut également réécrire l’ensemble de la liste de conversions à la fin de get_model_conversion_mapping via update_weight_conversions(...) — par exemple, le déquantiseur FP8 insère une opération Fp8Dequantize au début de chaque convertisseur existant afin que les échelles par bloc soient appliquées avant que les opérations de fusion d’experts / concaténation n’applatissent la structure par expert.
Chargement de modèle rapide et efficace
Le chargement d'un modèle est plus rapide et utilise moins de mémoire, car le chargeur sait quels tenseurs sont nécessaires aux opérations et planifie leur matérialisation de manière paresseuse.
Le chargeur parcourt le point de contrôle une seule fois pour détecter les correspondances de motifs et collecter les tenseurs. Il les stocke sous forme d'objets Future et les soumet à un pool de threads pour un chargement asynchrone sans bloquer le GIL. Un paramètre commence à se charger dès qu'un thread lui devient disponible.
Si votre système exécute d’autres processus gourmands, plusieurs threads peuvent ralentir le chargement au lieu de l’accélérer. Dans ce cas, définissez la variable d’environnement HF_DEACTIVATE_ASYNC_LOAD=1 pour charger les poids de manière séquentielle.
La valeur par défaut est de 4 threads pour le chargement asynchrone des paramètres. Cela offre le meilleur compromis entre les différents scénarios de chargement et le matériel. Le travail est principalement limité par l’I/O, mais selon le matériel d’accélération et le
dtyperequis au moment du chargement, il peut devenir limité par le CPU/GPU si ledtypediffère de celui sérialisé (ce qui nécessite une opération de copie supplémentaire).
Chargement asynchrone vs synchrone
def spawn_materialize(thread_pool, tensor, device, dtype) -> Future | Callable:
def _job():
return _materialize_copy(tensor, device, dtype)
if thread_pool is not None:
return thread_pool.submit(_job) # Async: returns Future
else:
return _job # Sync: returns Callable (deferred execution)Le chargement synchrone est utilisé lorsque :
- la variable d'environnement
HF_DEACTIVATE_ASYNC_LOAD=1est définie. - Le déchargement sur disque est activé (les contraintes de mémoire imposent un chargement séquentiel).
- La quantification à la volée est activée (évite que les threads de travail ne dépassent l'étape de quantification).
Flux de matérialisation
1. Checkpoint iteration (Phase 1):
- For each key, walk the transform list once
- Submit materialization job to ThreadPoolExecutor
- Job returns Future (async) or Callable (sync)
- Collect into the matching WeightConverter / WeightRenaming
2. Per-mapping processing (Phase 2, one mapping at a time):
- materialize_tensors() waits for this mapping's Futures only
- Apply conversion operations chain (self.operations)
- Apply quantization operation (if on-the-fly)
- Set parameters on model
- Delete realized tensors immediately
3. Cleanup:
- Thread pool shutdown (with cancel_futures=True for interrupts)Efficacité mémoire
Lors de la conversion d’un poids, le convertisseur attend que tous les tenseurs requis soient matérialisés s’ils ne sont pas encore chargés. Par exemple, l’opération MergeModulelist exige que tous les poids de ModuleList soient chargés avant la fusion.
La concaténation de tenseurs nécessite une copie temporaire, de sorte que des opérations telles que MergeModulelist et Concatenate nécessitent deux fois la mémoire des tenseurs sous-jacents pendant la conversion. Une fois fusionnés, seul le tenseur résultant reste en mémoire. Le pic de mémoire théorique dans le pire des cas est la taille du modèle plus les tenseurs requis pour l’opération MergeModulelist ou Concatenate la plus volumineuse.
Ce cas de figure le plus défavorable ne se produit que lorsque tous les autres paramètres ont été chargés avant l’exécution de la conversion exigeante. Deux scénarios déclenchent ce comportement.
- Tous les paramètres sont chargés de manière asynchrone avant d'entrer dans la conversion exigeante (le pool de threads était plus rapide que la file de conversion).
- La conversion exigeante est la dernière.
Par exemple, pour un modèle MoE utilisant MergeModulelist pour les experts de chaque couche, le pic mémoire théorique dans le pire des cas correspond à la taille du modèle plus les experts d'une couche.
Ces scénarios de pire cas sont rares. Le pic de mémoire réel a tendance à rester proche de la taille du modèle.
Réversibilité
Le système prend en charge l’enregistrement des modèles avec les transformations inverses, permettant ainsi un aller-retour enregistrement/chargement. L’enregistrement s’effectue en deux phases : d’abord les convertisseurs inversés (chaque tenseur correspond à au plus un convertisseur), puis les renommages inversés, conformément à la règle d’ordre décrite ci-dessus.
def revert_weight_conversion(model, state_dict):
"""Applies reverse conversions for saving."""
weight_conversions = getattr(model, "_weight_conversions", None)
# Reverse all transforms
reverse_weight_conversion = [
conversion.reverse_transform() for conversion in weight_conversions
]
# Apply in reverse
for first_param_name, reversed_converter in conversion_mapping.items():
realized_value = reversed_converter.convert(first_param_name, model=model)La liste des transformations utilisées au moment du chargement est mise en cache sur le modèle sous _weight_conversions (seules les entrées réellement déclenchées sont conservées, de sorte que les renommages non bijectifs tels que PrefixChange sont correctement réappliqués de manière symétrique). Lorsque le modèle a été instancié sans from_pretrained (et n'a donc pas de _weight_conversions), revert_weight_conversion recourt au recalcul du mappage via get_model_conversion_mapping et supprime tout PrefixChange de celui-ci (nous ne pouvons pas déterminer si le point de contrôle d'origine contenait le préfixe).
Les motifs cibles peuvent contenir des éléments d'expression régulière qui nécessitent un traitement pour la direction inverse :
def process_target_pattern(pattern: str) -> tuple[str, str | None]:
"""
- Removes `^` and `$` anchors
- Removes negative lookahead/lookbehind
- Detects capturing groups, replaces with \1
"""Exemples concrets
MoE de type Mixtral
Format de point de contrôle :
model.layers.0.block_sparse_moe.experts.0.w1.weight # gate per expert
model.layers.0.block_sparse_moe.experts.0.w2.weight # down per expert
model.layers.0.block_sparse_moe.experts.0.w3.weight # up per expert
...
model.layers.0.block_sparse_moe.experts.7.w1.weightFormat du modèle :
model.layers.0.mlp.experts.gate_up_proj # (8, 4096, 28672)
model.layers.0.mlp.experts.down_proj # (8, 14336, 4096)Cartographie de conversion (depuis conversion_mapping.py) :
"mixtral": [
WeightRenaming(".block_sparse_moe.", ".mlp."),
WeightConverter(
source_patterns=[".experts.*.w1.weight", ".experts.*.w3.weight"],
target_patterns=".experts.gate_up_proj",
operations=[MergeModulelist(dim=0), Concatenate(dim=1)],
),
WeightConverter(
source_patterns=[".experts.*.w2.weight"],
target_patterns=".experts.down_proj",
operations=[MergeModulelist(dim=0)],
),
],Modèle composite vision-langage (Gemma3)
Gemma3 adopte la configuration canonique « logique de préfixe différente pour le modèle de tête par rapport au modèle de base ». Deux entrées sont enregistrées (ici via des alias pointant vers les listes partagées "llava" / "LlavaModel") :
# model_type: applies to Gemma3ForConditionalGeneration / Gemma3ForSequenceClassification
"gemma3": "llava" # → adds "model." in front of language_model / vision_tower / ...
# class: applies to the inner Gemma3Model only
"Gemma3Model": "LlavaModel" # → minimal rename inside the already-prefixed namespaceParcours DFS pour Gemma3ForConditionalGeneration :
- Root — l’absence de correspondance dans la recherche de classe (
Gemma3ForConditionalGenerationn’est pas enregistré), la correspondance dans la recherche de model_type ("gemma3") → les transformations de réécriture du préfixe"llava"sont ajoutées sans portée, plaçantlanguage_model,vision_tower,multi_modal_projectorsousmodel.*. - Modèle interne
model: Gemma3Model— correspondances de classe (Gemma3Model→LlavaModel) → seule la correspondanceLlavaModelest appliquée, limitée à"model". Les renommages de préfixe beaucoup plus larges"gemma3"(="llava") ne sont pas réappliqués ici, ce qui est exactement ce que vous souhaitez : le modèle interne se trouve dans un espace de noms où le préfixe est déjà correct.
La même forme de paire est utilisée par tous les VLM de la famille Llava (PaliGemma, InternVL, Mistral3, …). L’entrée model_type gère la chirurgie du préfixe du modèle de tête ; l’entrée class maintient la correspondance du modèle de base interne au minimum.
Nidification plus profonde avec une surcharge spécifique à la tête (DETR)
DetrForSegmentation montre une surcharge spécifique à la tête superposée à deux niveaux imbriqués :
DetrForSegmentation (class registered: segmentation-only renames)
├── detr: DetrForObjectDetection (no mapping; just walked through)
│ └── model: DetrModel (class registered: shared base transforms)
│ └── backbone, encoder, ...
└── mask_head, bbox_attention (head-specific weights)Deux correspondances sont impliquées (une par clé enregistrée) :
"DetrModel": [WeightRenaming("backbone.conv_encoder", "backbone"), ...] # shared base
"DetrForSegmentation": [WeightRenaming("mask_head.lay1", "mask_head.conv1.conv"), ...] # head-specificParcours en profondeur :
- La racine
DetrForSegmentationcorrespond par classe → les renommages de segmentation ajoutés unscoped. detr: DetrForObjectDetectionn'est pas enregistré → aucune transformation n'est ajoutée ; le DFS continue à l'intérieur.detr.model: DetrModelcorrespond par classe → les transformations de base sont ajoutées avecscope_prefix="detr.model".
C’est pourquoi DetrForObjectDetection n’a pas besoin de sa propre correspondance : la seule correspondance enregistrée dans son sous-arbre (DetrModel) est automatiquement limitée au bon chemin.
Les alias basés sur la classe réutilisent la correspondance de base sans enregistrement supplémentaire : "MaskFormerDetrDecoder": "DetrModel" permet à un décodeur MaskFormer d’appliquer les mêmes transformations sous son propre nom de classe.
Opérations personnalisées (ERNIE 4.5 VL MoE)
Lorsque les opérations intégrées ne suffisent pas, vous pouvez créer une sous-classe personnalisée de ConversionOps. Par exemple, ERNIE 4.5 VL MoE doit diviser une liste d'experts partagés entre les modalités texte et vision, ce qu'aucune opération intégrée unique ne permet. L'opération personnalisée ErnieFuseAndSplitTextVisionExperts divise et réempile les experts sur deux clés cibles :
"ernie4_5_vl_moe": [
WeightRenaming("vision_model", "vision_tower"),
WeightConverter(
source_patterns=["experts.*.down_proj.weight"],
target_patterns=[
"text_moe.experts.down_proj",
"vision_moe.experts.down_proj",
],
operations=[ErnieFuseAndSplitTextVisionExperts(stack_dim=0, concat_dim=1)],
),
],Les opérateurs personnalisés doivent implémenter convert() et la propriété reverse_op pour prendre en charge la sauvegarde et le chargement aller-retour.
Alias de type de modèle
De nombreux modèles partagent des schémas de conversion :
_MODEL_TO_CONVERSION_PATTERN = {
"mixtral": "mixtral",
"minimax": "mixtral",
"qwen2_moe": "qwen2_moe",
"deepseek_v2": "qwen2_moe",
"deepseek_v3": "qwen2_moe",
"qwen3_moe": "qwen2_moe",
"olmoe": "qwen2_moe",
...
}Réutilisation des briques de chargement dynamique
Le chargement dynamique des poids ne se limite pas aux points de contrôle de modèles complets. Les mêmes briques de base vous permettent de charger n'importe quel ensemble de poids, à condition de pouvoir décrire la correspondance entre les clés du point de contrôle et les paramètres, et de vous assurer que les modules cibles existent.
De manière générale, le contrat ressemble à ceci :
- Préparer l'espace de noms du modèle. Assurez-vous que les modules/paramètres que vous souhaitez charger sont présents et nommés de la manière visée par votre
mappage. Pour les adaptateurs, cela implique d'appeler
inject_adapter_in_model(...)afin que les modules d'adaptateur existent avant le chargement. Pour les têtes personnalisées ou les modules supplémentaires, instanciez-les d'abord sur le modèle. - Describe how to map weights. Construisez une liste de conversion/renommage (par exemple, dans un utilitaire tel que
_build_peft_weight_mapping(...)) en utilisant WeightConverter ouWeightRenaming. C'est ici que vous exprimez comment les clés du checkpoint doivent être converties, divisées, fusionnées ou renommées pour correspondre à l'espace de noms de votre modèle. Vous pouvez principalement faire trois choses :- ajouter des opérations à la liste des convertisseurs : elles seront appliquées à tous les poids, à l’exception de ceux collectés par l’un des
WeightConverter. Il s’agit en général d’opérations de typeWeightRenaming - ajouter des opérations à la liste des opérations de chaque convertisseur : c’est ce qui se passe pour
Quantization, où nous ajoutons simplement une opération de quantification après la liste des opérations de n’importe quelWeightConverter. - remplacer les opérations / map par vos opérations personnalisées : c’est ce qui se passe avec
peft. Nous remplaçons l’opérationConcatenatede, par exemple,mixtralparPeftConcatenate(définie dans PEFT). Ainsi, lorsque le point de contrôle de l’adaptateur est lu, les poids à concaténer sont collectés et correctement formatés pourpeft
- ajouter des opérations à la liste des convertisseurs : elles seront appliquées à tous les poids, à l’exception de ceux collectés par l’un des
- Load + finalize + report. Utilisez le chargeur principal pour effectuer la conversion et remplir les tenseurs, puis finalisez et journalisez les résultats. Concrètement, ce flux est le suivant :
LoadStateDictConfig(...)+_load_pretrained_model(...)pour charger et convertir._finalize_load_state_dict(...)pour déplacer les tenseurs manquants ou incohérents hors demeta, les initialiser et lier les poids.log_state_dict_report(...)pour signaler les clés manquantes/inattendues/non conformes (et les erreurs de conversion).
Ces API sont exposées pour vous permettre de gérer du code personnalisé et des formats de poids personnalisés, tout en vous assurant de bénéficier du chargement, du sharding et de la qualité de vie les plus efficaces de l'API transformers !
Référence des fichiers clés
| Fichier | Objectif |
|---|---|
src/transformers/core_model_loading.py | Logique de chargement principale, WeightConverter, WeightRenaming, ConversionOps |
src/transformers/conversion_mapping.py | Mappages intégrés et composition par sous-modèle (get_model_conversion_mapping) |
src/transformers/integrations/tensor_parallel.py | Classes et utilitaires de sharding TP |
src/transformers/quantizers/base.py | Crochets de quantification et classe de base |