Transformers documentation
Rotary embeddings ユーティリティ
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スケーリング。 |
"llama3" | Llama3.1と同様のRoPEスケーリング。 |
モデル設定ファイルでの設定
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 は、Qwen2-VL の recomposition_frequencies と同様に、まず (t, h, w) に沿ってそれらの周波数の順序を並べ替えるだけです。プロンプトのテキストと生成されたトークンは、3 つの THW グリッドすべてで同一の位置 ID を使用することで、通常の 1 次元 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 を確認してください。
Axial RoPE
別件として、"axial" はビジョンモデル用に登録された rope_type ですが、ROPE_INIT_FUNCTIONS にはリストされていません。周波数の設定はモデル側に委ねられます。通常、高さおよび幅の位置に対して同じ周波数（空間軸ごとに head_dim // 4）を適用し、その上でのスケーリングは許可されていません。例としては、Qwen2-VL ビジョンモデルや、Pixtral などの他のビジョンスタックが挙げられます。
ユーティリティ
class 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未満）に適用するスケーリング係数です。hidden sizeをattention headの数で割った値の2分の1と同じ長さの数値のリストである必要があります。 - long_factor (
list[float]、任意) — ‘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に等しくなります)の連続周波数バンドのサイズを指定します。