Utilitas embedding rotasi

Halaman ini menjelaskan bagaimana Rotary Embedding dihitung dan diterapkan dalam Transformers serta jenis-jenis RoPE yang didukung.

Ikhtisar

Rotary Position Embeddings adalah teknik yang digunakan untuk menyuntikkan informasi posisi ke dalam mekanisme perhatian tanpa bergantung pada enkoding posisi eksplisit.
Alih-alih menambahkan vektor posisi ke embedding token, RoPE memutar vektor query dan key di bidang kompleks sesuai dengan posisi mereka, sehingga memungkinkan kesadaran posisi relatif dan ekstrapolasi yang lebih baik ke panjang urutan yang belum pernah dilihat.

Perpustakaan Transformers menyediakan implementasi yang fleksibel dan dapat diperluas untuk berbagai tipe RoPE yang didefinisikan dalam ~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS, termasuk varian default dan varian berskala:

Jenis Rope	Deskripsi
`"default"`	Rotary embedding standar seperti pada LLaMA.
`"linear"`	RoPE berskala linear yang memungkinkan jendela konteks lebih panjang.
`"dynamic"`	Skala yang mempertimbangkan NTK dihitung dengan melakukan penskalaan ulang basis frekuensi (`θ`) untuk konteks yang lebih panjang.
`"yarn"`	Varian scaling YaRN yang menyediakan ekstrapolasi dan stabilitas yang lebih halus.
`"longrope"`	scaling LongRoPE seperti pada seri model Phi-2.
`"llama3"`	Skala RoPE seperti pada Llama3.1.

Konfigurasi dalam Konfigurasi Model

Untuk mengaktifkan dan menyesuaikan rotary embeddings, tambahkan field rope_parameters ke file konfigurasi model Anda (config.json). Field ini mengontrol perilaku RoPE di seluruh lapisan model. Perhatikan bahwa setiap varian RoPE mendefinisikan set kunci yang diharapkan, dan kunci yang hilang akan memicu error. Lihat contoh di bawah yang membuat konfigurasi llama dengan parameter RoPE default:

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
}

Konfigurasi RoPE per Jenis Lapisan

Beberapa model seperti Gemma-3 menggunakan tipe lapisan yang berbeda dengan mekanisme perhatian yang berbeda, yaitu “full attention” di beberapa blok dan “sliding-window attention” di blok lainnya. Transformers mendukung penentuan parameter RoPE yang berbeda untuk setiap tipe lapisan pada model-model ini. Dalam kasus ini, rope_parameters harus berupa kamus bersarang, di mana kunci tingkat atas sesuai dengan config.layer_types dan nilainya adalah parameter RoPE per tipe. Selama inisialisasi model, setiap lapisan decoder akan secara otomatis mencari konfigurasi RoPE yang cocok berdasarkan tipe lapisan yang dideklarasikannya.

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 adalah jenis rotasi yang diterapkan dalam model multimodal dan didefinisikan oleh mrope_section. Ini bukan entri terpisah dalam tabel rope_type. Anda tetap dapat menerapkan penskalaan rope (linear, dynamic) dengannya.

mrope_section menentukan ukuran pita frekuensi yang berurutan untuk sumbu temporal, tinggi, dan lebar (jumlah ukuran tersebut sama dengan head_dim // 2). Frekuensi kemudian diulang sehingga embedding mencakup seluruh head_dim. Untuk input multimodal (biasanya visi), RoPE diterapkan dalam satu langkah (matmul atau perkalian elementwise frekuensi dengan posisi). mrope_section hanya menyusun ulang frekuensi tersebut di sepanjang (t, h, w) terlebih dahulu, seperti pada recomposition_frequencies di Qwen2-VL. Teks prompt dan token yang dihasilkan tetap menggunakan RoPE 1D normal dengan menggunakan id posisi yang identik di ketiga grid THW.

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 menggunakan mrope_section = [16, 24, 24] (16 temporal, 24 tinggi, 24 lebar ketika head_dim adalah 128). Model multimodal sering menggunakan tata letak ini di backbone teks (Qwen2-VL, GLM-4V). Beberapa VLM tidak menggunakan MRoPE dan tetap menggunakan RoPE teks 2D biasa. Periksa mrope_section di konfigurasi teks.

Axial RoPE

Secara terpisah, "axial" adalah rope_type yang terdaftar untuk model visi, tetapi tidak tercantum dalam ROPE_INIT_FUNCTIONS. Pengaturan frekuensi tetap berada di model. Biasanya, ini menerapkan frekuensi yang sama (head_dim // 4 per sumbu spasial) untuk posisi tinggi dan lebar, dan tidak memungkinkan penskalaan di atasnya. Contoh termasuk model visi Qwen2-VL dan tumpukan visi lainnya seperti Pixtral.

Utilitas

kelas transformers.RopeParameters

< source >

( )

Parameter

rope_theta (float, opsional, defaultnya RotaryEmbeddingConfigMixin.default_theta) — Periode dasar dari embedding RoPE. Opsional dalam konfigurasi yang diserialisasi — jika diabaikan, default_theta model (biasanya 10000.0) akan digunakan.
rope_type (str, opsional, default “default”) — Sub-variant RoPE yang akan digunakan. Bisa berupa salah satu dari [‘default’, ‘linear’, ‘dynamic’, ‘yarn’, ‘longrope’, ‘llama3’, ‘proportional’, ‘axial’], dengan ‘default’ sebagai implementasi RoPE asli.
partial_rotary_factor (float, opsional) — Persentase dari embedding head query dan key yang akan diterapkan RoPE.
factor (float, opsional) — Digunakan dengan semua tipe rope kecuali ‘default’. Faktor skala yang diterapkan pada embedding RoPE. Pada sebagian besar tipe skala, factor sebesar x akan memungkinkan model untuk menangani sekuens dengan panjang x * panjang maksimum pra-latih asli.
original_max_position_embeddings (int, opsional) — Digunakan dengan ‘yarn’, ‘longrope’ dan ‘llama3’. Nilai max position embeddings asli yang digunakan selama pretraining.
attention_factor (float, opsional) — Digunakan dengan ‘yarn’ dan ‘longrope’. Faktor penskalaan yang diterapkan pada komputasi perhatian. Jika tidak ditentukan, nilainya secara default mengikuti rekomendasi dari implementasi, dengan menggunakan field factor untuk menyimpulkan nilai yang disarankan.
beta_fast (float, opsional) — Hanya digunakan dengan ‘yarn’. Parameter untuk mengatur batas ekstrapolasi (saja) dalam fungsi linear ramp. Jika tidak ditentukan, nilainya secara default adalah 32.
beta_slow (float, opsional) — Hanya digunakan dengan ‘yarn’. Parameter untuk mengatur batas interpolasi (saja) dalam fungsi linear ramp. Jika tidak ditentukan, nilainya secara default adalah 1.
short_factor (list[float], opsional) — Hanya digunakan dengan ‘longrope’. Faktor penskalaan yang diterapkan pada konteks pendek (< original_max_position_embeddings). Harus berupa daftar angka dengan panjang yang sama dengan ukuran tersembunyi dibagi jumlah kepala perhatian dibagi 2
long_factor (list[float], opsional) — Hanya digunakan dengan ‘longrope’. Faktor penskalaan yang diterapkan pada konteks panjang (< original_max_position_embeddings). Harus berupa daftar angka dengan panjang yang sama dengan ukuran tersembunyi dibagi jumlah kepala perhatian dibagi 2
low_freq_factor (float, opsional) — Hanya digunakan dengan ‘llama3’. Faktor penskalaan yang diterapkan pada komponen frekuensi rendah dari RoPE
high_freq_factor (float, opsional) — Hanya digunakan dengan ‘llama3’. Faktor penskalaan yang diterapkan pada komponen frekuensi tinggi dari RoPE
mscale (float, opsional) — Hanya digunakan dengan ‘yarn’. Jika attention_factor adalah None dan kedua mscale serta mscale_all_dim disediakan, mscale bertindak sebagai skalar yang memperkaya log(factor) saat menghitung pembilang untuk nilai attention_factor yang disimpulkan. Jika tidak disediakan, attention_factor akan dihitung berdasarkan factor saja.
mscale_all_dim (float, opsional) — Hanya digunakan dengan ‘yarn’. Jika attention_factor adalah None dan kedua mscale serta mscale_all_dim disediakan, mscale_all_dim bertindak sebagai skalar yang memperkaya log(factor) saat menghitung penyebut untuk nilai attention_factor yang disimpulkan. Jika tidak disediakan, attention_factor akan dihitung berdasarkan factor saja.
truncate (bool, opsional) — Hanya digunakan dengan ‘yarn’. Apakah akan memotong rentang koreksi menggunakan math.floor dan math.ceil. Jika tidak ditentukan, defaultnya adalah True.
mrope_section (list[int], opsional) — Digunakan dengan Multimodal RoPE (MRoPE). Ukuran pita frekuensi yang berurutan untuk sumbu multimodal (biasanya temporal, tinggi, dan lebar, yang jumlahnya sama dengan head_dim // 2).

kelas .dict

( )

dict() -> kamus kosong baru dict(mapping) -> kamus baru yang diinisialisasi dari pasangan (key, value) objek pemetaan dict(iterable) -> kamus baru yang diinisialisasi seolah-olah melalui: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> kamus baru yang diinisialisasi dengan pasangan name=value dalam daftar argumen kata kunci. Sebagai contoh: dict(one=1, two=2)

Update on GitHub