Utilitaires d'incorporations rotationnelles

Cette page explique comment l’incorporation rotative est calculée et appliquée dans Transformers et quels types de RoPE sont pris en charge.

Aperçu

Les Rotary Position Embeddings sont une technique utilisée pour injecter des informations positionnelles dans les mécanismes d'attention sans recourir à des encodages de position explicites.
Au lieu d'ajouter des vecteurs de position aux embeddings de jetons, RoPE fait pivoter les vecteurs de requête et de clé dans le plan complexe en fonction de leurs positions, permettant ainsi une prise en compte relative des positions et une meilleure extrapolation vers des longueurs de séquence non vues.

La bibliothèque Transformers fournit une implémentation flexible et extensible des différents types de RoPE définis dans ~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS, incluant à la fois les variantes par défaut et celles mises à l'échelle :

Configuration dans les fichiers de configuration des modèles

Pour activer et personnaliser les embeddings rotatifs, ajoutez un champ rope_parameters au fichier de configuration de votre modèle (config.json). Ce champ contrôle le comportement de RoPE à travers les couches du modèle. Notez que chaque variante de RoPE définit son propre ensemble de clés attendues et les clés manquantes déclencheront une erreur. Consultez l’exemple ci-dessous qui crée une configuration llama avec des paramètres RoPE par défaut :

from transformers import LlamaConfig

config = LlamaConfig()
config.rope_parameters = {
    "rope_type": "default", # type of RoPE to use
    # rope_theta is optional — omitting it uses the model’s default_theta (typically 10000.0)
}

# If we want to apply a scaled RoPE type, we need to pass extra parameters
config.rope_parameters = {
    "rope_type": "linear",
    "rope_theta": 10000.0,  # can be omitted to fall back to default_theta
    "factor": 8.0  # scale factor for context extension
}

Configuration de RoPE par type de couche

Certains modèles, comme Gemma-3, utilisent différents types de couches avec des mécanismes d’attention distincts, c’est-à-dire une « attention complète » dans certains blocs et une « attention à fenêtre glissante » dans d’autres. Transformers permet de spécifier des paramètres RoPE distincts par type de couche pour ces modèles. Dans ce cas, rope_parameters doit être un dictionnaire imbriqué, où les clés de premier niveau correspondent à config.layer_types et les valeurs sont les paramètres RoPE par type. Lors de l’initialisation du modèle, chaque couche décodeur recherche automatiquement la configuration RoPE correspondante en fonction de son type de couche déclaré.

from transformers import Gemma3Config

config = Gemma3Config()
config.rope_parameters = {
    "full_attention": {
        "rope_type": "dynamic",
        "rope_theta": 1000000.0,
        "factor": 8.0,
        "original_max_position_embeddings": 8096,
    },
    "sliding_attention": {
        "rope_type": "default",
        "rope_theta": 10000.0,
    }
}

MRoPE

MRoPE est un type de rotation appliqué dans les modèles multimodaux et défini par mrope_section. Il ne constitue pas une entrée distincte dans le tableau rope_type. Il est toujours possible d’appliquer un redimensionnement de rope (linear, dynamic) avec celui-ci.

mrope_section définit les tailles des bandes de fréquences contiguës pour les axes temporel, hauteur et largeur (la somme de ces tailles est égale à head_dim // 2). Les fréquences sont ensuite répétées afin que l’embedding couvre la totalité de head_dim. Pour les entrées multimodales (généralement la vision), RoPE est appliqué en une seule passe (matmul ou multiplication élément par élément des fréquences avec les positions). mrope_section ne réordonne ces fréquences que le long de (t, h, w) en premier, comme dans recomposition_frequencies de Qwen2-VL. Le texte du prompt et les jetons générés conservent un RoPE 1D standard en utilisant des identifiants de position identiques sur les trois grilles THW.

from transformers import Qwen2VLConfig

config = Qwen2VLConfig()
config.text_config.rope_parameters = {
    "rope_type": "default",
    "rope_theta": 1000000.0,
    "mrope_section": [16, 24, 24],  # temporal, height, width frequency band sizes
}

Qwen2-VL utilise mrope_section = [16, 24, 24] (16 temporel, 24 hauteur, 24 largeur lorsque head_dim est 128). Les modèles multimodaux utilisent souvent cette disposition dans le tronc de texte (Qwen2-VL, GLM-4V). Certains VLM n’utilisent pas MRoPE et restent sur le RoPE de texte 2D standard. Vérifiez mrope_section dans la configuration du texte.

RoPE axial

Par ailleurs, "axial" est un rope_type enregistré pour les modèles de vision, mais il n'est pas répertorié dans ROPE_INIT_FUNCTIONS. La configuration des fréquences reste à la charge du modèle. Il applique généralement les mêmes fréquences (head_dim // 4 par axe spatial) pour les positions de hauteur et de largeur, et n'autorise pas de mise à l'échelle supplémentaire. Des exemples incluent le modèle de vision Qwen2-VL et d'autres piles de vision telles que Pixtral.

Utilitaires