# Rotary embeddings ユーティリティ

このページでは、TransformersにおけるRotary Embeddingの計算方法と適用方法、およびサポートされているRoPEの種類について説明します。

## 概要

Rotary Position Embeddings（RoPE）は、明示的な位置エンコーディングに依存せずにアテンション機構に位置情報を注入するための技術です。トークン埋め込みに位置ベクトルを足し込む代わりに、RoPE はクエリとキーのベクトルを、その位置に応じて複素数平面上で回転させます。これにより、相対的な位置認識が可能になり、未見のシーケンス長への外挿性能が向上します。

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スケーリング。 |

## モデル設定ファイルでの設定

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` は、Qwen2-VL の `recomposition_frequencies` と同様に、まず `(t, h, w)` に沿ってそれらの周波数の順序を並べ替えるだけです。プロンプトのテキストと生成されたトークンは、3 つの THW グリッドすべてで同一の位置 ID を使用することで、通常の 1 次元 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` を確認してください。

## Axial 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]`、*optional*) : 'longrope' の使用時のみ適用されます。短いコンテキスト（< `original_max_position_embeddings`）に適用するスケーリング係数です。hidden size を attention heads の数で割り、さらに 2 で割った値と同じ長さの数値のリストである必要があります。

long_factor (`list[float]`、*optional*) : 'longrope'でのみ使用されます。長いコンテキスト（< `original_max_position_embeddings`）に適用するスケーリング係数です。hidden sizeをattention headの数で割り、さらに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]`, *任意*) : Multimodal RoPE (MRoPE) と併用します。マルチモーダル軸（通常は時間軸、高さ、幅で、その合計は `head_dim // 2` に等しい）における連続周波数バンドのサイズです。

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

dict() -> 空の新しい辞書 dict(mapping) -> mapping オブジェクトの (key, value) ペアから初期化された新しい辞書 dict(iterable) -> 以下の処理を行ったかのように初期化された新しい辞書: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> キーワード引数リストの name=value ペアで初期化された新しい辞書。 例: dict(one=1, two=2)