Transformers documentation

Écriture de noyaux

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

É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 :

  1. 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).
  2. 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 passage forward. La bibliothèque kernels utilise cette classe pour kerneliser le modèle, car elle n’autorise pas les classes avec état.
  • KernelNameLayout : un nn.Module qui contient les paramètres et applique un monkey-patch au module d’origine avant le chargement du checkpoint. À l’exécution, kernelize remplace son forward par le forward de KernelName. Vous n’avez pas besoin de définir forward. Transformers en injecte un automatiquement avec la même signature que KernelName.forward.

La convention de nommage est stricte. La classe de disposition doit être nommée {KernelName}Layout et définie dans le même module que KernelName.

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 layers

La bibliothèque kernels détecte les classes de noyaux via un module layers (soit layers.py, soit layers/__init__.py). Définissez à la fois les classes de noyau et de disposition directement dans layers.py, et exposez le module layers depuis le __init__.py du package. Transformers trouve CustomRMSNormLayout dans le même module que CustomRMSNorm.

Protégez les imports spécifiques à Transformers (WeightConverter, Concatenate, WeightRenaming) dans layers.py afin 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 :

  1. Charge CustomRMSNorm depuis le dépôt et recherche CustomRMSNormLayout dans le même module.
  2. Applique un monkey-patch à chaque RMSNorm du modèle avec CustomRMSNormLayout.
  3. Reconstruit les poids du point de contrôle à l'aide de conversion_mapping afin qu'ils soient chargés avec les nouveaux noms de paramètres.
  4. Appelle kernelize, qui remplace CustomRMSNormLayout.forward par CustomRMSNorm.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 layers

Pour 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 :

  1. Charge RMSNormMLP depuis le dépôt et trouve RMSNormMLPLayout dans le même module.
  2. Correspond à chaque couche décodeur située à model.layers.* et construit une classe parente fusionnée dont __init__ appelle RMSNormMLPLayout(post_attention_layernorm, mlp).
  3. Remplace l'enfant restant (mlp) par nn.Identity() afin de préserver l'interface du module parent.
  4. Reconstruit les poids du point de contrôle à l'aide de conversion_mapping.
  5. Appelle kernelize, qui remplace RMSNormMLPLayout.forward par RMSNormMLP.forward.

L'ordre des paires dans le tuple de fusion détermine l'ordre des arguments transmis à KernelNameLayout.__init__.

Update on GitHub