Memuat kernel

Kernel berfungsi sebagai pengganti langsung untuk operasi PyTorch standar. Kernel mengganti metode forward dengan implementasi kernel yang dioptimalkan tanpa merusak kode model.

Panduan ini menunjukkan cara memuat kernel untuk mempercepat inferensi.

Instal Transformers dengan versi kernels yang didukung.

pip install -U "transformers[kernels]"

Set use_kernels=True di from_pretrained() untuk memuat kernel paling performan yang tersedia di Hub untuk perangkat Anda. Ini menggantikan operasi PyTorch yang didukung dengan implementasi kernel.

from transformers import AutoModelForCausalLM

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

Pemetaan default bergantung pada model, perangkat, dan mode eksekusi. Tabel di bawah ini mencantumkan repositori Hub umum untuk perangkat yang ditampilkan. Ketika tidak ada kernel yang terdaftar untuk kombinasi tertentu, operasi akan kembali ke PyTorch standar.

Tabel ini tidak bersifat lengkap. Model dapat mendaftarkan lapisan dan fungsi tambahan, dan beberapa pemetaan hanya tersedia untuk mode eksekusi tertentu.

GPU AMD melaporkan tipe perangkatnya sebagai cuda di PyTorch. Transformers mendeteksi ROCm saat runtime dan mengarahkan operasi yang didukung ke kernel AMD di atas, termasuk build AITER seperti kernels-community/aiter-rope. Anda tidak perlu mengatur tipe perangkat secara manual.

Jelajahi kernel yang tersedia di organisasi kernels-community.

Kernel perhatian

Muat kernel perhatian dari Hub dengan argumen attn_implementation.

from transformers import AutoModelForCausalLM

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

Perhatikan bahwa untuk kernel attention, apa pun yang bukan bagian dari repositori kernels-community (yang tepercaya - kami mungkin akan menambahkan lebih banyak repositori tepercaya di masa depan) akan memerlukan penggunaan kwarg tambahan allow_all_kernels=True (mirip dengan kwarg trust_remote_code=True untuk model non-HF). Hal ini karena memuat kernel dapat menyebabkan eksekusi kode arbitrer pada mesin host, dan kami tidak dapat memverifikasi setiap repositori, sehingga Anda perlu mengizinkannya secara eksplisit.

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"
)

Kernel tertentu, seperti attention, menerima beberapa format.

• @v2.1.0 mengunci ke tag atau cabang tertentu.
• @>=2.0,<3.0 mengatur batasan semantic versioning.

from transformers import AutoModelForCausalLM

# pin to a specific version
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/[email protected]",
    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"
)

Fallback FlashAttention

Permintaan attn_implementation="flash_attention_2", "flash_attention_3", atau "flash_attention_4" akan kembali ke kernel Hub yang sesuai jika paket flash-attn yang dikompilasi tidak terpasang atau perangkat Anda bukan CUDA.

Dukungan untuk FlashAttention-4 masih dalam tahap beta. API dan perilaku dapat berubah.

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",
)

Kesadaran terhadap mode

Kernels secara otomatis beradaptasi dengan mode pelatihan dan inferensi berdasarkan status model.training PyTorch.

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()

Aktifkan mode pelatihan dan inferensi secara eksplisit dengan argumen mode pada fungsi kernelize(). Mode pelatihan juga mendukung mode torch.compile tambahan.

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 menyesuaikan kernel mana yang digunakan dalam sebuah model.

Kunci kernel_mapping adalah nama yang didaftarkan oleh model. Mereka dapat merujuk ke lapisan, seperti "RMSNorm", atau fungsi yang didaftarkan, seperti "rotary_pos_emb". Pemisah : menamai entri kernel tertentu di dalam repositori dan memetakannya ke lapisan atau fungsi tersebut.

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"
)

Tentukan implementasi kernel yang berbeda untuk setiap tipe perangkat.

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"
        }
    }
)

Metadata kernel

Tambahkan dict metadata untuk mengontrol kernel build mana yang dimuat.

from transformers import KernelConfig

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

Cabang lama dari repositori kernel mungkin tidak memiliki build untuk versi PyTorch dan CUDA Anda. Jika kernel gagal dimuat, coba versi version yang lebih baru sebelum menyimpulkan bahwa perangkat keras Anda tidak didukung.

Pemetaan yang diwariskan

Sebuah KernelConfig mewarisi pemetaan kernel Transformers default untuk kernel Hub, dan entri dalam kernel_mapping menimpa default untuk lapisan dan fungsi yang sesuai. Atur inherit_mapping=False untuk hanya menggunakan entri dalam kernel_mapping. Segala sesuatu yang Anda tinggalkan akan kembali ke PyTorch standar. Ini berguna saat melakukan benchmarking kernel tertentu atau menguji implementasi kustom tanpa menerapkan default lainnya.

Konfigurasi di bawah memetakan fungsi rotary_pos_emb ke kernel RoPE dan membiarkan setiap operasi lainnya tetap di PyTorch. Nama fungsi harus didaftarkan oleh model.

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",
)

Fusi modul

Fuse modul yang bersebelahan menjadi satu kernel dengan meneruskan tuple pasangan (class_name, path_pattern) sebagai kunci di KernelConfig. Semua pola harus berbagi modul induk yang sama. * mencocokkan satu segmen path apa pun.

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 memerlukan repo kernel untuk menyediakan kelas pendamping KernelNameLayout di samping kelas KernelName. Lihat panduan Menulis kernel untuk cara mengimplementasikannya.

Kernel lokal

Muat kernel dari jalur file lokal dengan use_local_kernel=True di KernelConfig. Ini memuat dari jalur sistem file lokal, bukan dari repositori Hub.

Kernel lokal menggunakan /abs/path:layer_name alih-alih format Hub org/repo:layer_name.

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
)

Nonaktifkan kernel secara global

Setel variabel lingkungan USE_HUB_KERNELS untuk menonaktifkan kernel Hub di mana pun tanpa mengubah kode Anda.

export USE_HUB_KERNELS=0  # or OFF or NO

Pemecahan Masalah

Integrasi kernel bergantung pada kerja sama antara perangkat keras, driver, dan versi paket. Bagian-bagian berikut membahas kegagalan yang umum terjadi.

Masalah instalasi

Kesalahan impor berarti paket kernels tidak ada atau versinya berada di luar rentang yang didukung oleh Transformers. Instal ulang melalui extra untuk mendapatkan versi yang kompatibel.

pip install -U "transformers[kernels]"

Gagal memuat kernel

Jika kernel tertentu gagal dimuat, coba langkah-langkah berikut.

• Periksa kompatibilitas perangkat keras Anda dengan persyaratan kernel.
• Periksa apakah driver CUDA/ROCm/Metal Anda sudah diperbarui.
• Konsultasikan dokumentasi repositori kernel untuk masalah yang diketahui.

Kompatibilitas perangkat

Tidak semua kernel mendukung semua perangkat. Perpustakaan akan kembali ke operasi PyTorch standar jika kernel tidak tersedia untuk perangkat keras Anda. Periksa dokumentasi repositori kernel untuk dukungan perangkat tertentu.

Sumber daya

• repository Kernels
• artikel blog Perkuat Model Anda dalam 5 Menit dengan Hugging Face Kernel Hub
• Temukan kernel di org kernels-community