Utilidades de incrustaciones rotatorias

Esta página explica cómo se calcula y aplica el Rotary Embedding en Transformers y qué tipos de RoPE se admiten.

Resumen

Los Rotary Position Embeddings son una técnica utilizada para inyectar información posicional en los mecanismos de atención sin depender de codificaciones de posición explícitas.
En lugar de sumar vectores de posición a las incrustaciones de tokens, RoPE rota los vectores de consulta y clave en el plano complejo según sus posiciones, lo que permite una conciencia posicional relativa y una mejor extrapolación a longitudes de secuencia no vistas.

La biblioteca Transformers ofrece una implementación flexible y extensible de varios tipos de RoPE definidos en ~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS, que incluye tanto las variantes predeterminadas como las escaladas:

Tipo de Rope	Descripción
`"default"`	Incrustado rotatorio estándar, como en LLaMA.
`"linear"`	RoPE con escala lineal que permite ventanas de contexto más largas.
`"dynamic"`	Escalar consciente de NTK calculado mediante el reescalado de la base de frecuencia (`θ`) para un contexto más largo.
`"yarn"`	Variante de escalado YaRN que proporciona una extrapolación más suave y estabilidad.
`"longrope"`	Escala de LongRoPE como en la serie de modelos Phi-2.
`"llama3"`	Escala de RoPE como en Llama3.1.

Configuración en Model Configs

Para habilitar y personalizar las incrustaciones rotativas, añade un campo rope_parameters al archivo de configuración de tu modelo (config.json). Este campo controla el comportamiento de RoPE en las capas del modelo. Ten en cuenta que cada variante de RoPE define su propio conjunto de claves esperadas y las claves faltantes provocarán un error. Consulta el ejemplo siguiente, que crea una configuración de llama con parámetros de RoPE predeterminados:

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
}

Configuración de RoPE por tipo de capa

Algunos modelos, como Gemma-3, utilizan diferentes tipos de capas con mecanismos de atención distintos, es decir, “full attention” en algunos bloques y “sliding-window attention” en otros. Transformers permite especificar parámetros de RoPE distintos por tipo de capa para estos modelos. En este caso, rope_parameters debe ser un diccionario anidado, donde las claves de nivel superior corresponden a config.layer_types y los valores son los parámetros de RoPE por tipo. Durante la inicialización del modelo, cada capa decodificadora buscará automáticamente la configuración de RoPE correspondiente según su tipo de capa declarado.

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 es un tipo de rotación aplicado en modelos multimodales y definido por mrope_section. No es una entrada separada en la tabla rope_type. Aún así, se puede aplicar el escalado de rope (linear, dynamic) con él.

mrope_section dimensiona las bandas de frecuencia contiguas para los ejes temporal, de altura y de ancho (esas dimensiones suman head_dim // 2). A continuación, las frecuencias se repiten para que el embedding abarque el head_dim completo. Para entradas multimodales (generalmente visión), RoPE se aplica de una sola vez (matmul o multiplicación elemento a elemento de frecuencias con posiciones). mrope_section solo reordena esas frecuencias a lo largo de (t, h, w) primero, tal como en recomposition_frequencies de Qwen2-VL. El texto del prompt y los tokens generados mantienen el RoPE 1D normal al usar ids de posición idénticos en las tres cuadrículas 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 usa mrope_section = [16, 24, 24] (16 temporal, 24 altura, 24 ancho cuando head_dim es 128). Los modelos multimodales suelen usar esta disposición en el backbone de texto (Qwen2-VL, GLM-4V). Algunos VLM no usan MRoPE y se quedan con el RoPE de texto 2D normal. Comprueba mrope_section en la configuración de texto.

RoPE axial

Por separado, "axial" es un rope_type registrado para modelos de visión, pero no aparece en ROPE_INIT_FUNCTIONS. La configuración de frecuencias queda a cargo del modelo. Por lo general, aplica las mismas frecuencias (head_dim // 4 por eje espacial) para las posiciones de altura y ancho, y no permite aplicar escalado adicional. Entre los ejemplos se encuentran el modelo de visión Qwen2-VL y otras pilas de visión como Pixtral.

Utilidades

clase transformers.RopeParameters

< source >

( )

Parámetros

rope_theta (float, opcional, valor predeterminado RotaryEmbeddingConfigMixin.default_theta) — El período base de las incrustaciones RoPE. Opcional en las configuraciones serializadas: si se omite, se utiliza el default_theta del modelo (típicamente 10000.0).
rope_type (str, opcional, valor predeterminado “default”) — La subvariante de RoPE a utilizar. Puede ser una de [‘default’, ‘linear’, ‘dynamic’, ‘yarn’, ‘longrope’, ‘llama3’, ‘proportional’, ‘axial’], siendo ‘default’ la implementación original de RoPE.
partial_rotary_factor (float, opcional) — El porcentaje de la incrustación de la cabeza de consulta y clave sobre la que se aplicará RoPE.
factor (float, opcional) — Se utiliza con todos los tipos de rope excepto ‘default’. El factor de escala que se aplica a las incrustaciones RoPE. En la mayoría de los tipos de escalado, un factor de x habilita que el modelo maneje secuencias de longitud x * longitud máxima original preentrenada.
original_max_position_embeddings (int, opcional) — Se usa con ‘yarn’, ‘longrope’ y ‘llama3’. Las embeddings de posición máximas originales utilizadas durante el preentrenamiento.
attention_factor (float, opcional) — Se utiliza con ‘yarn’ y ‘longrope’. Es el factor de escala que se aplica en el cálculo de la atención. Si no se especifica, toma por defecto el valor recomendado por la implementación, utilizando el campo factor para inferir el valor sugerido.
beta_fast (float, opcional) — Solo se usa con ‘yarn’. Parámetro para establecer el límite de la extrapolación (solo) en la función de rampa lineal. Si no se especifica, el valor predeterminado es 32.
beta_slow (float, opcional) — Solo se usa con ‘yarn’. Parámetro para establecer el límite de la interpolación (solo) en la función de rampa lineal. Si no se especifica, su valor predeterminado es 1.
short_factor (list[float], opcional) — Solo se usa con ‘longrope’. El factor de escalado que se debe aplicar a los contextos cortos (< original_max_position_embeddings). Debe ser una lista de números con la misma longitud que el tamaño oculto dividido por el número de cabezas de atención dividido por 2
long_factor (list[float], opcional) — Solo se usa con ‘longrope’. El factor de escalado que se debe aplicar a los contextos largos (< original_max_position_embeddings). Debe ser una lista de números con la misma longitud que el tamaño oculto dividido por el número de cabezas de atención dividido por 2
low_freq_factor (float, opcional) — Solo se usa con ‘llama3’. Factor de escala aplicado a las componentes de baja frecuencia del RoPE
high_freq_factor (float, opcional) — Solo se usa con ‘llama3’. Factor de escala aplicado a las componentes de alta frecuencia del RoPE
mscale (float, opcional) — Solo se usa con ‘yarn’. Si attention_factor es None y se proporcionan tanto mscale como mscale_all_dim, mscale actúa como un escalar que aumenta log(factor) al calcular el numerador para el valor inferido de attention_factor. Si no se proporciona, attention_factor se calculará en base únicamente a factor.
mscale_all_dim (float, opcional) — Solo se usa con ‘yarn’. Si attention_factor es None y se proporcionan tanto mscale como mscale_all_dim, mscale_all_dim actúa como un escalar que aumenta log(factor) al calcular el denominador para el valor inferido de attention_factor. Si no se proporciona, attention_factor se calculará basándose únicamente en factor.
truncate (bool, opcional) — Solo se usa con ‘yarn’. Indica si se debe truncar el rango de corrección usando math.floor y math.ceil. Si no se especifica, el valor predeterminado es True.
mrope_section (list[int], opcional) — Se utiliza con Multimodal RoPE (MRoPE). Tamaños de bandas de frecuencia contiguas para los ejes multimodales (típicamente temporal, altura y ancho, cuya suma es igual a head_dim // 2).

clase .dict

( )

dict() -> nuevo diccionario vacío dict(mapping) -> nuevo diccionario inicializado a partir de las pares (clave, valor) de un objeto de mapeo dict(iterable) -> nuevo diccionario inicializado como si se hiciera mediante: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> nuevo diccionario inicializado con los pares nombre=valor de la lista de argumentos de palabra clave. Por ejemplo: dict(one=1, two=2)

Update on GitHub