旋转嵌入工具

本页介绍了 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 缩放。
`"llama3"`	与 Llama3.1 相同的 RoPE 缩放。

模型配置中的配置

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

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 配置。

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。

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

< source >

( )

参数

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）的连续频率带大小。

class .dict

( )

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)

Update on GitHub