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.
RoPE, konum vektörlerini token gömme işlemlerine eklemek yerine, sorgu ve anahtar 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 dışa vurum (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 ö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:

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; örneğin bazı bloklarda “full attention”, diğerlerinde “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.

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ı boyutlandırır (bu boyutların toplamı head_dim // 2'dir). Ardından gömme, tam head_dim aralığını kapsayacak şekilde frekanslar 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.

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

sınıf transformers.RopeParameters

< source >

( )

Parametreler

rope_theta (float, isteğe bağlı, varsayılan RotaryEmbeddingConfigMixin.default_theta) — RoPE gömlemelerinin temel periyodu. Seriye alınmış 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, isteğe bağlı) — ‘default’ hariç tüm rope türleriyle kullanılır. RoPE gömlemelerine uygulanacak ölçekleme çarpanı. Çoğu ölçekleme türünde, factor değeri x olduğunda model, x * orijinal maksimum ön-eğitilmiş uzunluk uzunluğundaki dizileri işleyebilir hale gelir.
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, isteğe bağlı) — ‘yarn’ ve ‘longrope’ ile kullanılır. Dikkat (attention) hesabına uygulanacak ölçekleme faktörü. Belirtilmezse, önerilen değer, factor alanını kullanarak önerilen değeri çıkarmak için uygulamanın önerdiği değere ayarlanır.
beta_fast (float, isteğe bağlı) — Yalnızca ‘yarn’ ile kullanılır. Doğrusal rampa fonksiyonunda 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 faktörü. 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 faktörü. 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 faktörü
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 faktörü
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ırsa, mscale, attention_factor değeri çıkarılırken paydaşın hesaplanmasında log(factor) değerini 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 değeri çıkarılırken payda hesaplanırken log(factor) değerini artıran bir skaler olarak görev yapar. Sağlanmazsa, attention_factor yalnızca factor değerine dayanılarak 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ı belirtir. 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 eksenler için (genellikle zaman, yükseklik ve genişlik; toplamı head_dim // 2 değerine eşittir) ardışık frekans bantlarının boyutları.

sınıf .dict

( )

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ış gibi başlatılan 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)

Update on GitHub