# 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](https://github.com/microsoft/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:

```python
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 do decoder localizará automaticamente a configuração RoPE correspondente com base no tipo de camada declarado.

```python
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` define os tamanhos das faixas de frequência contíguas para os eixos temporal, de altura e de largura (a soma desses tamanhos é `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 elemento a elemento 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, usando ids de posição idênticos nas três grades THW.

```python
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[[transformers.RopeParameters]]

#### transformers.RopeParameters[[transformers.RopeParameters]]

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_rope_utils.py#L678)

**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 dos embeddings de cabeçalho 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áxima 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, ele assume o valor 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 para 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'. Se deve truncar o intervalo de correção usando `math.floor` e `math.ceil`. Se não 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`).

#### dict[[transformers.RopeParameters.__call__]]

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)