# Rotary gömme yardımcıları

Bu sayfa, Transformers içinde Döner Gömme (Rotary Embedding)'nin nasıl hesaplandığını ve uygulandığını ve hangi tür RoPE'lerin desteklendiğini açıklar.

## Genel Bakış

Rotary Position Embeddings, açık konum kodlamalarına dayanmadan dikkat mekanizmalarına konumsal bilgi enjekte etmek için kullanılan bir tekniktir. Konum vektörlerini token gömme (embedding) değerlerine eklemek yerine RoPE, sorgu (query) ve anahtar (key) vektörlerini konumlarına göre karmaşık düzlemde döndürerek göreli konumsal farkındalık sağlar ve görülmemiş dizi uzunluklarına daha iyi genelleme (extrapolation) yapılmasına olanak tanır.

Transformers kütüphanesi, ``~modeling_rope_utils.ROPE_VALIDATION_FUNCTIONS`` içinde tanımlanan çeşitli RoPE türlerinin esnek ve genişletilebilir bir uygulamasını sağlar; bunların hem varsayılan hem de ölçeklenmiş varyantlarını içerir:

| Rope Türü | Açıklama |
|------------|-------------|
| `"default"` | LLaMA'daki gibi standart döner gömme. |
| `"linear"` | Daha uzun bağlam pencerelerine izin veren doğrusal ölçekli RoPE. |
| `"dynamic"` | Daha uzun bağlam için frekans tabanının (`θ`) yeniden ölçeklenerek hesaplanan NTK-duyarlı ölçekleme. |
| `"yarn"` | Daha pürüzsüz dışa yayılım ve kararlılık sağlayan YaRN ölçeklendirme varyantı. |
| `"longrope"` | Phi-2 model serisindeki gibi [LongRoPE](https://github.com/microsoft/LongRoPE) ölçekleme. |
| `"llama3"` | Llama3.1'deki gibi RoPE ölçekleme. |

## Model Yapılandırmalarında Yapılandırma

Döner gömme (rotary embeddings) işlevini etkinleştirmek ve özelleştirmek için model yapılandırma dosyanıza (`config.json`) bir `rope_parameters` alanı ekleyin. Bu alan, model katmanları genelindeki RoPE davranışını kontrol eder. Her RoPE varyantının kendi beklenen anahtar kümesini tanımladığını ve eksik anahtarların bir hata oluşturacağını unutmayın. Varsayılan RoPE parametreleriyle bir llama yapılandırması oluşturan aşağıdaki örneğe bakın:

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

## Katman Tipine Göre RoPE Yapılandırması

Gemma-3 gibi bazı modeller, farklı dikkat mekanizmalarına sahip farklı katman türleri kullanır; yani bazı bloklarda "full attention", diğerlerinde ise "sliding-window attention" kullanılır. Transformers, bu modeller için katman türü başına ayrı RoPE parametreleri belirtmeyi destekler. Bu durumda `rope_parameters`, üst düzey anahtarların `config.layer_types` ile eşleştiği ve değerlerin tür başına RoPE parametrelerini içerdiği iç içe geçmiş bir sözlük olmalıdır. Model başlatma sırasında her decoder katmanı, beyan edilen katman türüne göre eşleşen RoPE yapılandırmasını otomatik olarak arar.

```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, multimodal modellerde uygulanan ve `mrope_section` tarafından tanımlanan bir dönüşüm türüdür. `rope_type` tablosunda ayrı bir giriş olarak yer almaz. Bununla birlikte, rope ölçekleme (`linear`, `dynamic`) yine uygulanabilir.

`mrope_section`, zaman, yükseklik ve genişlik eksenleri için ardışık frekans bantlarının boyutlarını belirler (bu boyutların toplamı `head_dim // 2`'dir). Ardından frekanslar, gömme (embedding) tam `head_dim` aralığını kapsayacak şekilde tekrarlanır. Çok modlu girdilerde (genellikle görü) RoPE tek seferde uygulanır (frekansların konumlarla matris çarpımı veya eleman bazlı çarpımı). `mrope_section`, Qwen2-VL'deki `recomposition_frequencies` gibi, bu frekansları önce `(t, h, w)` boyunca yeniden sıralar. İstem metni ve üretilen jetonlar, üç THW ızgarasında da aynı konum kimliklerini kullanarak normal 1B RoPE'yi korur.

```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, `head_dim` 128 olduğunda `mrope_section = [16, 24, 24]` kullanır (16 zamansal, 24 yükseklik, 24 genişlik). Çok modlu modeller genellikle metin omurgasında (Qwen2-VL, GLM-4V) bu yerleşimi kullanır. Bazı VLM'ler MRoPE kullanmaz ve bunun yerine normal 2B metin RoPE'sinde kalır. Metin yapılandırmasında `mrope_section` değerini kontrol edin.

## Aksiyel RoPE

Ayrı olarak, `"axial"` görme modelleri için kayıtlı bir `rope_type`'dır ancak `ROPE_INIT_FUNCTIONS` içinde listelenmez. Sıklık kurulumu modelde kalır. Genellikle yükseklik ve genişlik konumları için aynı sıklıkları (`head_dim // 4` / uzamsal eksen) uygular ve bunun üzerine ölçekleme yapmaya izin vermez. Örnekler arasında Qwen2-VL görme modeli ve Pixtral gibi diğer görme yığınları yer alır.

## Yardımcılar[[transformers.RopeParameters]]

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

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

**Parametreler:**

rope_theta (`float`, *isteğe bağlı*, varsayılan `RotaryEmbeddingConfigMixin.default_theta`) : RoPE gömmelemelerinin temel periyodu. Seri hale getirilmiş yapılandırmalarda isteğe bağlıdır — atlanırsa, modelin `default_theta` değeri (genellikle 10000.0) kullanılır.

rope_type (`str`, *isteğe bağlı*, varsayılan "default") : Kullanılacak RoPE alt-varyantı. ['default', 'linear', 'dynamic', 'yarn', 'longrope', 'llama3', 'proportional', 'axial'] değerlerinden biri olabilir; 'default', orijinal RoPE uygulamasıdır.

partial_rotary_factor (`float`, *isteğe bağlı*) : RoPE'nin uygulanacağı sorgu ve anahtar baş gömme oranı.

factor (`float`, *opsiyonel*) : 'default' hariç tüm rope türleriyle kullanılır. RoPE gömmelemelerine uygulanacak ölçekleme çarpanıdır. Çoğu ölçekleme türünde, x değerinde bir `factor`, modelin x * orijinal maksimum ön-eğitilmiş uzunlukta dizileri işlemesini sağlar.

original_max_position_embeddings (`int`, *isteğe bağlı*) : 'yarn', 'longrope' ve 'llama3' ile kullanılır. Ön eğitim sırasında kullanılan orijinal maksimum konum gömme değerleri.

attention_factor (`float`, *opsiyonel*) : 'yarn' ve 'longrope' ile kullanılır. Dikkat (attention) hesabına uygulanacak ölçekleme çarpanıdır. Belirtilmezse, önerilen değeri `factor` alanından çıkararak, uygulamanın önerdiği değere varsayılan olarak ayarlanır.

beta_fast (`float`, *isteğe bağlı*) : Yalnızca 'yarn' ile kullanılır. Doğrusal rampa işlevinde ekstrapolasyon (yalnızca) sınırı için ayarlanan parametre. Belirtilmezse, varsayılan değeri 32'dir.

beta_slow (`float`, *isteğe bağlı*) : Yalnızca 'yarn' ile kullanılır. Doğrusal rampa fonksiyonunda (yalnızca) interpolasyon sınırı için ayarlanan parametredir. Belirtilmezse, varsayılan değeri 1'dir.

short_factor (`list[float]`, *isteğe bağlı*) : Yalnızca 'longrope' ile kullanılır. Kısa bağlamlara (< `original_max_position_embeddings`) uygulanacak ölçekleme çarpanı. Gizli boyutun, dikkat başlarının sayısına bölünmüş halinin 2'ye bölünmüş değeriyle aynı uzunlukta sayılardan oluşan bir liste olmalıdır

long_factor (`list[float]`, *isteğe bağlı*) : Yalnızca 'longrope' ile kullanılır. Uzun bağlamlara (< `original_max_position_embeddings`) uygulanacak ölçekleme çarpanı. Gizli boyutun, dikkat başlarının sayısına bölünmüş halinin 2'ye bölünmüş değeriyle aynı uzunlukta sayılardan oluşan bir liste olmalıdır.

low_freq_factor (`float`, *isteğe bağlı*) : Yalnızca 'llama3' ile kullanılır. RoPE'nin düşük frekanslı bileşenlerine uygulanan ölçekleme çarpanı

high_freq_factor (`float`, *isteğe bağlı*) : Yalnızca 'llama3' ile kullanılır. RoPE'nin yüksek frekanslı bileşenlerine uygulanan ölçekleme çarpanı

mscale (`float`, *isteğe bağlı*) : Yalnızca 'yarn' ile kullanılır. `attention_factor` `None` ise ve hem `mscale` hem de `mscale_all_dim` sağlanıyorsa, `mscale`, `attention_factor`'in çıkarılan değeri için payı hesaplanırken `log(factor)`'i artıran bir skaler olarak görev yapar. Sağlanmazsa, `attention_factor` yalnızca `factor` değerine göre hesaplanır.

mscale_all_dim (`float`, *isteğe bağlı*) : Yalnızca 'yarn' ile kullanılır. `attention_factor` `None` ise ve hem `mscale` hem de `mscale_all_dim` sağlanırsa, `mscale_all_dim`, `attention_factor` için çıkarılan değerin paydasını hesaplarken `log(factor)` değerini ölçekleyen bir skaler olarak davranır. Sağlanmazsa, `attention_factor` yalnızca `factor` değerine dayanarak hesaplanır.

truncate (`bool`, *isteğe bağlı*) : Yalnızca 'yarn' ile kullanılır. Düzeltme aralığının `math.floor` ve `math.ceil` kullanılarak kırpılıp kırpılmayacağını belirler. Belirtilmezse varsayılan olarak `True` değerini alır.

mrope_section (`list[int]`, *isteğe bağlı*) : Multimodal RoPE (MRoPE) ile kullanılır. Multimodal eksenlerin (genellikle zaman, yükseklik ve genişlik; toplamı `head_dim // 2`'ye eşittir) ardışık frekans bantlarının boyutları.

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

dict() -> yeni boş sözlük dict(mapping) -> bir eşleme nesnesinin (anahtar, değer) çiftlerinden başlatılan yeni sözlük dict(iterable) -> aşağıdaki gibi başlatılmış yeni sözlük: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> anahtar kelime argüman listesindeki ad=değer çiftleriyle başlatılan yeni sözlük. Örneğin: dict(one=1, two=2)