Utilitários de incorporações rotativas

Esta página explica como o Rotary Embedding é calculado e aplicado no Transformers e quais tipos de RoPE são suportados.

Visão geral

Rotary Position Embeddings é uma técnica utilizada para injetar informações posicionais em mecanismos de atenção sem depender de codificações de posição explícitas.
Em vez de adicionar vetores de posição aos embeddings de tokens, o RoPE rotaciona os vetores de query e key no plano complexo de acordo com suas posições, permitindo a percepção de posições relativas e uma melhor extrapolação para comprimentos de sequência não vistos.

A biblioteca Transformers fornece uma implementação flexível e extensível dos vários tipos de RoPE definidos em ~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS, incluindo as variantes padrão e escalonadas:

Tipo de Rope	Descrição
`"default"`	Incorporação rotacional padrão, como em LLaMA.
`"linear"`	RoPE com escala linear, que permite janelas de contexto mais longas.
`"dynamic"`	Escala com consciência de NTK calculada por reescalar a base de frequência (`θ`) para contextos mais longos.
`"yarn"`	Variante de escalonamento YaRN que fornece extrapolação mais suave e estabilidade.
`"longrope"`	Escala LongRoPE conforme a série de modelos Phi-2.
`"llama3"`	Escala de RoPE como em Llama3.1.

Configuração nos Model Configs

Para habilitar e personalizar os embeddings rotativos, adicione um campo rope_parameters ao arquivo de configuração do seu modelo (config.json). Este campo controla o comportamento do RoPE entre as camadas do modelo. Observe que cada variante do RoPE define seu próprio conjunto de chaves esperadas e chaves ausentes causarão um erro. Veja o exemplo abaixo, que cria uma configuração llama com parâmetros padrão do RoPE:

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
}

Configuração de RoPE por tipo de camada

Alguns modelos, como o Gemma-3, utilizam diferentes tipos de camadas com mecanismos de atenção distintos, ou seja, “atenção completa” em alguns blocos e “atenção de janela deslizante” em outros. O Transformers suporta a especificação de parâmetros RoPE distintos por tipo de camada para esses modelos. Nesse caso, rope_parameters deve ser um dicionário aninhado, em que as chaves de nível superior correspondem a config.layer_types e os valores são os parâmetros RoPE por tipo. Durante a inicialização do modelo, cada camada decodificadora consultará automaticamente a configuração RoPE correspondente com base no tipo de camada 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 é um tipo de rotação aplicado em modelos multimodais e definido por mrope_section. Não é uma entrada separada na tabela rope_type. Ainda é possível aplicar o escalonamento de rope (linear, dynamic) com ele.

mrope_section dimensiona as faixas de frequência contíguas para os eixos temporal, de altura e de largura (esses tamanhos somam head_dim // 2). Em seguida, as frequências são repetidas para que o embedding cubra todo o head_dim. Para entradas multimodais (geralmente visão), o RoPE é aplicado de uma só vez (matmul ou multiplicação elementar das frequências com as posições). mrope_section apenas reordena essas frequências ao longo de (t, h, w) primeiro, como no recomposition_frequencies do Qwen2-VL. O texto do prompt e os tokens gerados mantêm o RoPE 1D normal ao usar ids de posição idênticos em todas as três grades 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
}

O Qwen2-VL usa mrope_section = [16, 24, 24] (16 temporal, 24 altura, 24 largura quando head_dim é 128). Modelos multimodais frequentemente usam esse layout no backbone de texto (Qwen2-VL, GLM-4V). Alguns VLMs não usam MRoPE e permanecem com o RoPE de texto 2D normal. Verifique mrope_section na configuração de texto.

RoPE Axial

Separadamente, "axial" é um rope_type registrado para modelos de visão, mas não está listado em ROPE_INIT_FUNCTIONS. A configuração das frequências permanece no modelo. Ele geralmente aplica as mesmas frequências (head_dim // 4 por eixo espacial) para as posições de altura e largura e não permite escalonamento adicional. Exemplos incluem o modelo de visão Qwen2-VL e outros pilares de visão, como o Pixtral.

Utilitários

classe transformers.RopeParameters

< source >

( )

Parâmetros

rope_theta (float, opcional, padrão RotaryEmbeddingConfigMixin.default_theta) — O período base dos embeddings RoPE. Opcional em configurações serializadas — se omitido, o default_theta do modelo (geralmente 10000.0) é utilizado.
rope_type (str, opcional, padrão “default”) — A subvariante de RoPE a ser utilizada. Pode ser uma de [‘default’, ‘linear’, ‘dynamic’, ‘yarn’, ‘longrope’, ‘llama3’, ‘proportional’, ‘axial’], sendo ‘default’ a implementação original de RoPE.
partial_rotary_factor (float, opcional) — A porcentagem do embedding dos cabeçalhos de query e key sobre a qual o RoPE será aplicado.
factor (float, opcional) — Usado com todos os tipos de rope, exceto ‘default’. O fator de escala a ser aplicado aos embeddings RoPE. Na maioria dos tipos de escala, um factor de x permitirá que o modelo processe sequências de comprimento x * comprimento máximo original pré-treinado.
original_max_position_embeddings (int, opcional) — Usado com ‘yarn’, ‘longrope’ e ‘llama3’. As embeddings de posição máximas originais usadas durante o pré-treinamento.
attention_factor (float, opcional) — Usado com ‘yarn’ e ‘longrope’. O fator de escala a ser aplicado no cálculo da atenção. Se não for especificado, o valor padrão é o recomendado pela implementação, usando o campo factor para inferir o valor sugerido.
beta_fast (float, opcional) — Usado apenas com ‘yarn’. Parâmetro para definir o limite para extrapolação (somente) na função de rampa linear. Se não for especificado, o valor padrão é 32.
beta_slow (float, opcional) — Usado apenas com ‘yarn’. Parâmetro para definir o limite da interpolação (somente) na função de rampa linear. Se não for especificado, o valor padrão é 1.
short_factor (list[float], opcional) — Usado apenas com ‘longrope’. O fator de escala a ser aplicado a contextos curtos (< original_max_position_embeddings). Deve ser uma lista de números com o mesmo comprimento que o tamanho oculto dividido pelo número de cabeças de atenção dividido por 2
long_factor (list[float], opcional) — Usado apenas com ‘longrope’. O fator de escala a ser aplicado a contextos longos (< original_max_position_embeddings). Deve ser uma lista de números com o mesmo comprimento que o tamanho oculto dividido pelo número de cabeças de atenção dividido por 2
low_freq_factor (float, opcional) — Usado apenas com ‘llama3’. Fator de escala aplicado aos componentes de baixa frequência do RoPE
high_freq_factor (float, opcional) — Usado apenas com ‘llama3’. Fator de escala aplicado aos componentes de alta frequência do RoPE
mscale (float, opcional) — Usado apenas com ‘yarn’. Se attention_factor for None e ambos mscale e mscale_all_dim forem fornecidos, mscale atua como um escalar que aumenta log(factor) ao calcular o numerador para o valor inferido de attention_factor. Se não for fornecido, attention_factor será calculado com base apenas em factor.
mscale_all_dim (float, opcional) — Usado apenas com ‘yarn’. Se attention_factor for None e ambos mscale e mscale_all_dim forem fornecidos, mscale_all_dim atua como um escalar que aumenta log(factor) ao calcular o denominador para o valor inferido de attention_factor. Se não for fornecido, attention_factor será calculado com base apenas em factor.
truncate (bool, opcional) — Usado apenas com ‘yarn’. Indica se a faixa de correção deve ser truncada usando math.floor e math.ceil. Se não for especificado, o valor padrão é True.
mrope_section (list[int], opcional) — Usado com Multimodal RoPE (MRoPE). Tamanhos das bandas de frequência contínuas para os eixos multimodais (tipicamente temporal, altura e largura, cuja soma é igual a head_dim // 2).

classe .dict

( )

dict() -> novo dicionário vazio dict(mapping) -> novo dicionário inicializado a partir dos pares (chave, valor) de um objeto de mapeamento dict(iterable) -> novo dicionário inicializado como se fosse: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> novo dicionário inicializado com os pares nome=valor na lista de argumentos de palavra-chave. Por exemplo: dict(one=1, two=2)

Update on GitHub