# 旋转嵌入工具

本页介绍了 Transformers 中旋转位置编码（Rotary Embedding）的计算与应用方式，以及所支持的 RoPE 类型。

## 概述

旋转位置嵌入（Rotary Position Embeddings）是一种将位置信息注入注意力机制的技术，无需依赖显式的位置编码。与将位置向量加到词元嵌入上不同，RoPE 根据词元的位置在复平面上对查询（query）和键（key）向量进行旋转，从而实现相对位置感知，并更好地外推到未见过的序列长度。

Transformers 库提供了对 ``~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS`` 中定义的各种 RoPE 类型的灵活且可扩展的实现，包括默认变体和缩放变体：

| Rope 类型 | 描述 |
|------------|-------------|
| `"default"` | 与 LLaMA 中相同的标准旋转位置编码。 |
| `"linear"` | 线性缩放 RoPE，支持更长的上下文窗口。 |
| `"dynamic"` | 通过重新缩放频率基数（`θ`）来计算 NTK 感知缩放，以支持更长的上下文。 |
| `"yarn"` | YaRN 缩放变体，提供更平滑的外推和稳定性。 |
| `"longrope"` | 与 Phi-2 模型系列相同的 [LongRoPE](https://github.com/microsoft/LongRoPE) 缩放。 |
| `"llama3"` | 与 Llama3.1 相同的 RoPE 缩放。 |

## 模型配置中的配置

要启用并自定义旋转位置编码，请在模型的配置文件（`config.json`）中添加 `rope_parameters` 字段。该字段用于控制模型各层中 RoPE 的行为。请注意，每种 RoPE 变体都定义了各自的一组预期键，缺失的键会引发错误。以下示例展示了如何创建一个具有默认 RoPE 参数的 llama 配置：

```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
}
```

## 按层类型的 RoPE 配置

某些模型（例如 Gemma-3）使用具有不同注意力机制的不同层类型，即某些块使用“full attention”，而其他块使用“sliding-window attention”。Transformers 支持为这些模型按层类型指定不同的 RoPE 参数。在这种情况下，`rope_parameters` 应为一个嵌套字典，其中顶层键对应 `config.layer_types`，值为各类型的 RoPE 参数。在模型初始化期间，每个解码器层会根据其声明的层类型自动查找匹配的 RoPE 配置。

```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 是一种应用于多模态模型的旋转类型，由 `mrope_section` 定义。它并不是 `rope_type` 表中的独立条目。您仍然可以对其应用 rope 缩放（`linear`、`dynamic`）。

`mrope_section` 为时间、高度和宽度轴（这些尺寸之和为 `head_dim // 2`）划分连续的频率带。随后，频率会被重复，使得嵌入覆盖完整的 `head_dim`。对于多模态输入（通常是视觉），RoPE 会一次性应用（将频率与位置进行矩阵乘法或逐元素乘法）。`mrope_section` 首先仅沿 `(t, h, w)` 重新排列这些频率，类似于 Qwen2-VL 中的 `recomposition_frequencies`。提示文本和生成的 token 通过在三个 THW 网格上使用相同的位置 ID，保持常规的 1D RoPE。

```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
}
```

Qwen2-VL 使用 `mrope_section = [16, 24, 24]`（当 `head_dim` 为 128 时，分别对应 16 个时间维度、24 个高度维度和 24 个宽度维度）。多模态模型通常在文本主干中采用这种布局（如 Qwen2-VL、GLM-4V）。部分 VLM 不使用 MRoPE，而是沿用常规的 2D 文本 RoPE。请在文本配置中检查 `mrope_section`。

## 轴向 RoPE

另外，`"axial"` 是视觉模型中已注册的 `rope_type`，但它并未列在 `ROPE_INIT_FUNCTIONS` 中。频率的设置仍由模型负责。它通常对高度和宽度位置应用相同的频率（每个空间轴 `head_dim // 4`），并且不允许在此基础上进行缩放。示例包括 Qwen2-VL 视觉模型以及 Pixtral 等其他视觉模型。

## 实用工具[[transformers.RopeParameters]]

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

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

**参数：**

rope_theta (`float`，*可选*，默认为 `RotaryEmbeddingConfigMixin.default_theta`)：RoPE 嵌入的基础周期。在序列化配置中为可选项——如果省略，则使用模型的 `default_theta`（通常为 10000.0）。

rope_type (`str`，*可选*，默认为 "default")：要使用的 RoPE 子变体。可以是 ['default', 'linear', 'dynamic', 'yarn', 'longrope', 'llama3', 'proportional', 'axial'] 之一，其中 'default' 为原始 RoPE 实现。

partial_rotary_factor (`float`, *可选*) : 对查询和键头嵌入应用 RoPE 的百分比。

factor (`float`, *可选*) : 用于除 'default' 以外的所有 rope 类型。应用于 RoPE 嵌入的缩放因子。在大多数缩放类型中，`factor` 为 x 时，模型将能够处理长度为 x * 原始最大预训练长度的序列。

original_max_position_embeddings (`int`，*可选*)：与 'yarn'、'longrope' 和 'llama3' 配合使用。指预训练期间使用的原始最大位置嵌入。

attention_factor (`float`, *可选*) : 与 'yarn' 和 'longrope' 配合使用。应用于注意力计算的缩放因子。如果未指定，则默认使用实现所推荐的值，该值通过 `factor` 字段推断得出。

beta_fast (`float`, *可选*) : 仅在使用 'yarn' 时使用。用于设置线性斜坡函数中外推（仅外推）的边界参数。如果未指定，默认值为 32。

beta_slow (`float`, *可选*) : 仅在使用 'yarn' 时生效。用于设置线性斜坡函数中插值（仅插值）的边界参数。如果未指定，则默认为 1。

short_factor (`list[float]`, *可选*) : 仅在使用 'longrope' 时生效。应用于短上下文（< `original_max_position_embeddings`）的缩放因子。必须是一个数字列表，其长度等于隐藏层大小除以注意力头数再除以 2

long_factor (`list[float]`, *可选*) : 仅在使用 'longrope' 时生效。应用于长上下文（< `original_max_position_embeddings`）的缩放因子。必须是一个数字列表，其长度等于隐藏层大小除以注意力头数再除以 2

low_freq_factor (`float`, *可选*) : 仅在使用 'llama3' 时生效。应用于 RoPE 低频分量的缩放因子

high_freq_factor (`float`, *可选*) : 仅在使用 'llama3' 时生效。应用于 RoPE 高频分量的缩放因子

mscale (`float`, *可选*) : 仅在使用 'yarn' 时生效。如果 `attention_factor` 为 `None` 且同时提供了 `mscale` 和 `mscale_all_dim`，则 `mscale` 作为一个标量，用于在计算 `attention_factor` 的推断值的分子时增强 `log(factor)`。如果未提供，`attention_factor` 将仅基于 `factor` 进行计算。

mscale_all_dim (`float`, *可选*) : 仅在 'yarn' 中使用。如果 `attention_factor` 为 `None` 且同时提供了 `mscale` 和 `mscale_all_dim`，则 `mscale_all_dim` 会作为一个标量，在计算 `attention_factor` 的推断值分母时增强 `log(factor)`。如果未提供，`attention_factor` 将仅基于 `factor` 进行计算。

truncate (`bool`，*可选*)：仅在 'yarn' 中使用。是否使用 `math.floor` 和 `math.ceil` 截断校正范围。如果未指定，默认为 `True`。

mrope_section (`list[int]`, *可选*) : 与多模态 RoPE (MRoPE) 配合使用。多模态轴（通常为时间、高度和宽度，其总和等于 `head_dim // 2`）上连续频率带的大小。

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

dict() -> 新的空字典 dict(mapping) -> 从映射对象的 (key, value) 对初始化的新字典 dict(iterable) -> 如同通过以下方式初始化的新字典：d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> 使用关键字参数列表中的 name=value 对初始化的新字典。 例如： dict(one=1, two=2)