Transformers documentation
Écriture de noyaux
Écriture de noyaux
Ce guide explique comment écrire des noyaux qui vont au-delà d'un remplacement sans état de forward. Il couvre deux fonctionnalités prises en charge par l'API étendue KernelConfig :
- Transformation des paramètres : le noyau s'attend à ce que les poids soient disposés différemment de ceux du modèle d'origine (par exemple, des paramètres renommés ou fusionnés).
- Fusion de modules : le noyau remplace plusieurs modules adjacents par une seule implémentation fusionnée.
Pour les noyaux de base (remplacements sans état de forward sans modification de paramètres), consultez la documentation de la bibliothèque kernels.
Motif à deux classes
Tout noyau qui porte ses propres paramètres suit un schéma à deux classes.
KernelName: ne contient que le passageforward. La bibliothèquekernelsutilise cette classe pour kerneliser le modèle, car elle n’autorise pas les classes avec état.KernelNameLayout: unnn.Modulequi contient les paramètres et applique un monkey-patch au module d’origine avant le chargement du checkpoint. À l’exécution,kernelizeremplace sonforwardpar leforwarddeKernelName. Vous n’avez pas besoin de définirforward. Transformers en injecte un automatiquement avec la même signature queKernelName.forward.
La convention de nommage est stricte. La classe de disposition doit être nommée
{KernelName}Layoutet définie dans le même module queKernelName.
Transformation des paramètres
Utilisez ce motif lorsque le noyau s’attend à des poids sous des noms différents ou avec une forme différente de celle du point de contrôle du modèle d’origine.
La classe KernelNameLayout possède la même signature __init__ que le module qu'elle remplace et déclare un attribut de classe conversion_mapping qui indique à Transformers comment remapper les clés du checkpoint vers les nouveaux noms de paramètres (voir Chargement dynamique des poids pour plus de détails).
# layers.py
try:
from transformers import Concatenate, WeightConverter
from transformers.conversion_mapping import WeightRenaming
except ImportError:
Concatenate = WeightConverter = WeightRenaming = None
import torch
import torch.nn as nn
class CustomRMSNormLayout(nn.Module):
conversion_mapping = [...] # rules that remap checkpoint keys to the new parameter names
def __init__(self, hidden_size: int, eps: float = 1e-6):
super().__init__()
self.scale = nn.Parameter(torch.ones(hidden_size))
self.variance_epsilon = eps
class CustomRMSNorm(nn.Module):
def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
input_dtype = hidden_states.dtype
hidden_states = hidden_states.to(torch.float32)
variance = hidden_states.pow(2).mean(-1, keepdim=True)
hidden_states = hidden_states * torch.rsqrt(variance + self.variance_epsilon)
return self.scale * hidden_states.to(input_dtype)# __init__.py
from . import layersLa bibliothèque
kernelsdétecte les classes de noyaux via un modulelayers(soitlayers.py, soitlayers/__init__.py). Définissez à la fois les classes de noyau et de disposition directement danslayers.py, et exposez le modulelayersdepuis le__init__.pydu package. Transformers trouveCustomRMSNormLayoutdans le même module queCustomRMSNorm.Protégez les imports spécifiques à Transformers (
WeightConverter,Concatenate,WeightRenaming) danslayers.pyafin que le noyau puisse également être importé dans des environnements où Transformers n’est pas installé.
Chargez ce noyau en passant le dépôt et le nom de la classe à KernelConfig. La clé est le nom de la classe de module d'origine du modèle. La valeur pointe vers la classe KernelName (et non Layout) dans le dépôt.
La valeur est soit une chaîne "owner/repo:ClassName", soit un tuple (repo_string, metadata). Dans le cas du tuple, passez version ou revision (au moins l'un des deux), et éventuellement trust_remote_code. Utilisez version pour une version majeure du noyau ou revision pour un tag, une branche ou un commit. Définissez trust_remote_code=True pour charger depuis l'extérieur de l'organisation de confiance kernels-community. Une chaîne simple implique par défaut version=1 et trust_remode_code=False.
from transformers import AutoModelForCausalLM, KernelConfig
kernel_config = KernelConfig({"RMSNorm": ("owner/my-kernel:CustomRMSNorm", {"trust_remote_code": True, "version": 1})})
model = AutoModelForCausalLM.from_pretrained(
"Qwen/Qwen3-0.6B",
use_kernels=True,
kernel_config=kernel_config,
device_map="auto",
)Lors du chargement du modèle, Transformers :
- Charge
CustomRMSNormdepuis le dépôt et rechercheCustomRMSNormLayoutdans le même module. - Applique un monkey-patch à chaque
RMSNormdu modèle avecCustomRMSNormLayout. - Reconstruit les poids du point de contrôle à l'aide de
conversion_mappingafin qu'ils soient chargés avec les nouveaux noms de paramètres. - Appelle
kernelize, qui remplaceCustomRMSNormLayout.forwardparCustomRMSNorm.forward.
Fusion de modules
Utilisez ce motif lorsqu’un noyau remplace plusieurs modules adjacents par une seule implémentation fusionnée. Comme le module fusionné combine les paramètres de plusieurs modules d’origine, le KernelNameLayout.__init__ reçoit les modules enfants instanciés plutôt que leurs arguments de constructeur.
# layers.py
try:
from transformers import Concatenate, WeightConverter
from transformers.conversion_mapping import WeightRenaming
except ImportError:
Concatenate = WeightConverter = WeightRenaming = None
import torch
import torch.nn as nn
class RMSNormMLPLayout(nn.Module):
conversion_mapping = [...] # rules that remap checkpoint keys to the fused parameter names
def __init__(self, norm, mlp):
super().__init__()
self.variance_epsilon = norm.variance_epsilon
self.scale = nn.Parameter(torch.empty_like(norm.weight))
self.gate_up_proj = nn.Linear(
mlp.gate_proj.in_features,
mlp.gate_proj.out_features + mlp.up_proj.out_features,
bias=mlp.gate_proj.bias is not None,
device=mlp.gate_proj.weight.device,
dtype=mlp.gate_proj.weight.dtype,
)
self.down_proj = nn.Linear(
mlp.down_proj.in_features,
mlp.down_proj.out_features,
bias=mlp.down_proj.bias is not None,
device=mlp.down_proj.weight.device,
dtype=mlp.down_proj.weight.dtype,
)
self.act_fn = mlp.act_fn
class RMSNormMLP(nn.Module):
def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
input_dtype = hidden_states.dtype
hidden_states = hidden_states.to(torch.float32)
variance = hidden_states.pow(2).mean(-1, keepdim=True)
hidden_states = hidden_states * torch.rsqrt(variance + self.variance_epsilon)
hidden_states = self.scale * hidden_states.to(input_dtype)
gate, up = self.gate_up_proj(hidden_states).chunk(2, dim=-1)
return self.down_proj(self.act_fn(gate) * up)# __init__.py
from . import layersPour fusionner des modules, passez un tuple de paires (class_name, path_pattern) comme clé dans KernelConfig au lieu d'une simple chaîne de caractères. Tous les motifs doivent partager le même module parent (Transformers fusionne les enfants de ce parent). Le joker * correspond à n'importe quel segment de chemin unique.
from transformers import AutoModelForCausalLM, KernelConfig
kernel_config = KernelConfig(
{
(
("RMSNorm", "model.layers.*.post_attention_layernorm"),
("MLP", "model.layers.*.mlp"),
): ("owner/my-kernel:RMSNormMLP", {"trust_remote_code": True, "version": 1}),
}
)
model = AutoModelForCausalLM.from_pretrained(
"Qwen/Qwen3-0.6B",
use_kernels=True,
kernel_config=kernel_config,
device_map="auto",
)Lors du chargement du modèle, Transformers :
- Charge
RMSNormMLPdepuis le dépôt et trouveRMSNormMLPLayoutdans le même module. - Correspond à chaque couche décodeur située à
model.layers.*et construit une classe parente fusionnée dont__init__appelleRMSNormMLPLayout(post_attention_layernorm, mlp). - Remplace l'enfant restant (
mlp) parnn.Identity()afin de préserver l'interface du module parent. - Reconstruit les poids du point de contrôle à l'aide de
conversion_mapping. - Appelle
kernelize, qui remplaceRMSNormMLPLayout.forwardparRMSNormMLP.forward.
Update on GitHubL'ordre des paires dans le tuple de fusion détermine l'ordre des arguments transmis à
KernelNameLayout.__init__.