Çekirdeklerin yüklenmesi

Bir çekirdek, standart PyTorch işlemleri için doğrudan yer değiştirilebilir bir alternatif olarak çalışır. Model kodunu bozmadan forward yöntemini optimize edilmiş çekirdek uygulamasıyla değiştirir.

Bu kılavuz, çıkarımı hızlandırmak için çekirdeklerin nasıl yükleneceğini gösterir.

Transformers'ı kernels paketinin desteklenen sürümüyle yükleyin.

pip install -U "transformers[kernels]"

Cihazınız için Hub'da mevcut en yüksek performanslı çekirdekleri yüklemek için from_pretrained() içinde use_kernels=True ayarlayın. Bu, desteklenen PyTorch işlemlerini çekirdek uygulamasıyla değiştirir.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    device_map="auto"
)

Varsayılan eşleme, modele, cihaza ve çalışma moduna bağlıdır. Aşağıdaki tablo, gösterilen cihazlar için yaygın Hub depolarını listeler. Belirli bir kombinasyon için çekirdek kayıtlı değilse, işlem standart PyTorch’e geri düşer.

Tablo kapsamlı değildir. Modeller ek katmanlar ve işlevler kaydedebilir ve bazı eşlemeler yalnızca belirli çalışma modları için kullanılabilir.

AMD GPU'ler, PyTorch'ta cihaz türlerini cuda olarak raporlar. Transformers, çalışma zamanında ROCm'yi algılar ve kernels-community/aiter-rope gibi AITER derlemeleri dahil olmak üzere desteklenen işlemleri yukarıdaki AMD çekirdeklerine yönlendirir. Cihaz türünü kendiniz ayarlamanız gerekmez.

kernels-community kuruluşundaki kullanılabilir çekirdekleri görüntüleyin.

Dikkat çekirdekleri

Dikkat çekirdeklerini Hub'dan attn_implementation argümanı ile yükleyin.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/flash-attn2",
    device_map="auto"
)

Dikkat çekirdekleri için, kernels-community deposunun (güvenilir - gelecekte daha fazla güvenilir depo ekleyebiliriz) bir parçası olmayan her şey için, ek olarak allow_all_kernels=True anahtar kelime argümanının kullanılması gerekecektir (HF dışı modeller için trust_remote_code=True anahtar kelime argümanına benzer şekilde). Bunun nedeni, bir çekirdeğin yüklenmesinin ana makinede keyfi kod çalıştırılmasına yol açabilmesidir ve her depoyu doğrulayamayacağımız için bunu açıkça izin vermeniz gerekir.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="random-repo/random-attention",
    allow_all_kernels=True,
    device_map="auto"
)

Dikkat gibi belirli çekirdekler, birkaç formatı kabul eder.

• @v2.1.0, belirli bir etikete veya dalına sabitlenir.
• @>=2.0,<3.0 semantik sürümleme kısıtlamaları belirler.

from transformers import AutoModelForCausalLM

# pin to a specific version
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/flash-attn2@v2.1.0",
    device_map="auto"
)
# use semantic versioning constraints
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/flash-attn2@>=2.0,<3.0",
    device_map="auto"
)

FlashAttention yedeği

attn_implementation="flash_attention_2", "flash_attention_3" veya "flash_attention_4" istendiğinde, derlenmiş flash-attn paketi yüklü değilse veya cihazınız CUDA değilse, eşleşen Hub çekirdeğine geri düşülür.

FlashAttention-4 desteği beta aşamasındadır. API'ler ve davranışlar değişebilir.

from transformers import AutoModelForCausalLM

# uses the compiled flash-attn package if present, otherwise the kernels-community/flash-attn2 Hub kernel
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="flash_attention_2",
    device_map="auto",
)

Mod farkındalığı

Kernels, PyTorch'un model.training durumuna göre eğitim ve çıkarsama modlarına otomatik olarak uyarlanır.

import torch
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    device_map="auto"
)

# Switch to inference mode - uses inference-optimized kernels
model.eval()
with torch.no_grad():
    output = model.generate(input_ids, max_new_tokens=50)

# Switch to training mode - uses training-optimized kernels with gradient support
model.train()
loss = model(input_ids, labels=labels).loss
loss.backward()

kernelize() işlevinde mode argümanını kullanarak eğitim ve çıkarım modlarını açıkça etkinleştirin. Eğitim modu, ek olarak bir torch.compile modunu da destekler.

from kernels import Mode
from transformers import kernelize

# inference optimized kernels
kernelize(model, mode=Mode.INFERENCE)

# training optimized kernels
kernelize(model, mode=Mode.TRAINING)

# training and torch-compile friendly kernels
kernelize(model, mode=Mode.TRAINING | Mode.TORCH_COMPILE)

KernelConfig

KernelConfig, bir modelde hangi çekirdeklerin kullanılacağını özelleştirir.

kernel_mapping anahtarları, model tarafından kaydedilen adlardır. Bir katmana, örneğin "RMSNorm", veya kayıtlı bir işlev gibi "rotary_pos_emb" gibi bir şeye atıfta bulunabilirler. : ayıracı, depodaki belirli bir çekirdek girdisini adlandırır ve onu o katmana veya işleve eşler.

from transformers import AutoModelForCausalLM, KernelConfig

kernel_config = KernelConfig(
    kernel_mapping={
        "RMSNorm": "kernels-community/liger-kernels:LigerRMSNorm",
    }
)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/flash-attn2",
    use_kernels=True,
    kernel_config=kernel_config,
    device_map="auto"
)

Her cihaz türü için farklı çekirdek uygulamaları belirtin.

from transformers import KernelConfig

kernel_config = KernelConfig(
    kernel_mapping={
        "RMSNorm": {
            "cuda": "kernels-community/liger-kernels:LigerRMSNorm",
            "rocm": "kernels-community/liger-kernels:LigerRMSNorm",
            "xpu": "kernels-community/rmsnorm:RMSNorm"
        }
    }
)

Çekirdek meta verileri

Hangi kernel derlemesinin yükleneceğini kontrol etmek için bir metadata sözlüğü ekleyin.

from transformers import KernelConfig

kernel_config = KernelConfig(
    kernel_mapping={
        "RMSNorm": ("kernels-community/liger-kernels:LigerRMSNorm", {"version": 3}),
    }
)

Bir çekirdek deposunun eski dallarında, PyTorch ve CUDA sürümleriniz için derlemeler bulunmayabilir. Bir çekirdek yüklenemezse, donanımınızın desteklenmediği sonucuna varmadan önce daha yeni bir version denemek isteyin.

Devralınan eşlemeler

KernelConfig, Hub çekirdekleri için Transformers varsayılan çekirdek eşlemesini devralır ve kernel_mapping içindeki girdiler, ilgili katmanlar ve işlevler için varsayılanı geçersiz kılar. Yalnızca kernel_mapping içindeki girdileri kullanmak için inherit_mapping=False olarak ayarlayın. Atladığınız her şey standart PyTorch'e geri döner. Bu, diğer varsayılanları uygulamadan belirli bir çekirdeği ölçüm yaparken veya özel bir uygulamayı test ederken kullanışlıdır.

Aşağıdaki yapılandırma, rotary_pos_emb işlevini bir RoPE çekirdeğine eşler ve diğer tüm işlemleri PyTorch üzerinde bırakır. İşlev adı, model tarafından kaydedilmelidir.

from transformers import AutoModelForCausalLM, KernelConfig

kernel_config = KernelConfig(
    kernel_mapping={
        "rotary_pos_emb": (
            "kernels-community/rotary:apply_rotary_transformers",
            {"version": 2},
        ),
    },
    inherit_mapping=False,
)

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    kernel_config=kernel_config,
    device_map="auto",
)

Modül füzyonu

(class_name, path_pattern) çiftlerinin bir demetini KernelConfig içindeki anahtar olarak geçirerek bitişik modülleri tek bir çekirdeğe birleştirin. Tüm desenler aynı üst modülü paylaşmalıdır. * herhangi bir tek yol segmentini eşleştirir.

from transformers import AutoModelForCausalLM, KernelConfig

kernel_config = KernelConfig(
    {
        (
            ("RMSNorm", "model.layers.*.post_attention_layernorm"),
            ("MLP",     "model.layers.*.mlp"),
        ): "owner/fused-rmsnorm-mlp:RMSNormMLP",
    }
)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    kernel_config=kernel_config,
    device_map="auto",
)

Fusion, çekirdek deposunun KernelName sınıfının yanında bir KernelNameLayout sınıfı sağlamasını gerektirir. Bunu nasıl uygulayacağınızı görmek için Çekirdek yazma kılavuzuna bakın.

Yerel çekirdekler

KernelConfig içinde use_local_kernel=True kullanarak çekirdekleri yerel dosya yollarından yükleyin. Bu, çekirdekleri Hub deposu yerine yerel dosya sistemi yolundan yükler.

Yerel çekirdekler, Hub biçimi olan org/repo:layer_name yerine /abs/path:layer_name kullanır.

from transformers import KernelConfig, AutoModelForCausalLM

kernel_mapping = {
    "RMSNorm": "/path/to/liger-kernels:LigerRMSNorm",
}
kernel_config = KernelConfig(kernel_mapping, use_local_kernel=True)

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    dtype="auto",
    device_map="auto",
    use_kernels=True,
    kernel_config=kernel_config
)

Çekirdekleri küresel olarak devre dışı bırak

Kodunuzu değiştirmeden her yerde Hub çekirdeklerini devre dışı bırakmak için USE_HUB_KERNELS ortam değişkenini ayarlayın.

export USE_HUB_KERNELS=0  # or OFF or NO

Sorun Giderme

Kernel entegrasyonu, donanımın, sürücülerin ve paket sürümlerinin birlikte çalışmasına bağlıdır. Aşağıdaki bölümler yaygın hataları ele alır.

Yükleme sorunları

Import hataları, kernels paketinin eksik olduğunu veya sürümünün Transformers'ın desteklediği aralığın dışında kaldığını gösterir. Uygun bir sürümü almak için paketi extra üzerinden yeniden yükleyin.

pip install -U "transformers[kernels]"

Çekirdek yükleme hataları

Belirli çekirdekler yüklenemezse, aşağıdakileri deneyin.

• Çekirdek gereksinimleriyle donanım uyumluluğunuzu kontrol edin.
• CUDA/ROCm/Metal sürücülerinizin güncel olduğunu doğrulayın.
• Bilinen sorunlar için çekirdek deposu dokümantasyonuna başvurun.

Cihaz uyumluluğu

Tüm çekirdekler (kernels) tüm cihazları desteklemez. Cihazınız için bir çekirdek (kernel) kullanılamıyorsa, kütüphane standart PyTorch işlemlerine geri döner. Cihaza özgü destek için çekirdek (kernel) deposunun dokümantasyonunu kontrol edin.

Kaynaklar

• Kernels deposu
• Hugging Face Kernel Hub ile Modellerinizi 5 Dakikada Geliştirin blog yazısı
• kernels-community kuruluşunda çekirdekleri keşfedin