# 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 dalam 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](https://github.com/microsoft/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:

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

## Konfigurasi RoPE per Jenis Lapisan

Beberapa model seperti Gemma-3 menggunakan jenis lapisan yang berbeda dengan mekanisme perhatian yang berbeda, yaitu "full attention" pada beberapa blok dan "sliding-window attention" pada blok lainnya. Transformers mendukung penentuan parameter RoPE yang berbeda untuk setiap jenis 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 jenis. Selama inisialisasi model, setiap lapisan decoder akan secara otomatis mencari konfigurasi RoPE yang sesuai berdasarkan jenis lapisan yang dideklarasikan.

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

```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 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[[transformers.RopeParameters]]

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

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_rope_utils.py#L679)

**Parameter:**

rope_theta (`float`, *opsional*, defaultnya `RotaryEmbeddingConfigMixin.default_theta`) : Periode dasar dari embedding RoPE. Opsional dalam konfigurasi yang diserialisasi — jika diabaikan, `default_theta` dari model (biasanya 10000.0) akan digunakan.

rope_type (`str`, *opsional*, defaultnya "default") : Sub-variante 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 penskalaan yang diterapkan pada embedding RoPE. Pada sebagian besar tipe penskalaan, `factor` sebesar x akan memungkinkan model untuk menangani sekuens dengan panjang x * panjang maksimum pra-latihan asli.

original_max_position_embeddings (`int`, *opsional*) : Digunakan dengan 'yarn', 'longrope', dan 'llama3'. Max position embeddings asli yang digunakan selama pretraining.

attention_factor (`float`, *opsional*) : Digunakan dengan 'yarn' dan 'longrope'. Faktor penskalaan yang akan 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 ramp linear. 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 akan 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 akan 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`).

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

dict() -> kamus kosong baru dict(mapping) -> kamus baru yang diinisialisasi dari pasangan (key, value) objek mapping 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.  Contoh:  dict(one=1, two=2)