Uzmanlar arka uçları

Tüm Mixture-of-Experts (MoE) uygulamaları aynı yüksek düzeyde hesaplama işlemini gerçekleştirir. Her token için bir yönlendirici (router) k uzman seçer. Token gizli durumu (hidden state), ardından seçilen uzmanların parametreleri üzerinden projekte edilir ve yönlendirme ağırlıklarıyla birleştirilir. Uzman arka uçları arasındaki fark, bu uzman matris çarpımlarının nasıl yürütüldüğüdür.

ExpertsInterface, optimize edilmiş uzman (experts) arka uçlarını sağlar. Uzman uygulamasını model kodundan ayırarak farklı işlevlerle deney yapmayı kolaylaştırır. Yeni arka uçları aynı arayüz üzerinden ekleyin.

"batched_mm" ve "grouped_mm" arka uçları da FP8 ve FP4 (int8-paketli) kuantize uzmanları, float32 veya UE8M0 ölçeklerini okuyarak Triton finegrained-fp8 çekirdeği üzerinden çalıştırır. "deepgemm" arka ucu kullanılamadığında kuantize kontrol noktaları için yedek (fallback) olarak görev yaparlar.

Çözme aşaması geçişi

GPU üzerinde, experts_implementation="grouped_mm" ile yüklenen bir model, üretim sürecinin decode aşamasında otomatik olarak "batched_mm" moduna geçer; bu mod, düşük token sayılarında belirgin şekilde daha hızlıdır. Üretim tamamlandığında orijinal backend geri yüklenir. CPU üzerinde ise grouped_mm, her giriş boyutunda daha verimli olduğu için üretim boyunca etkin kalır.

Anahtar, üst düzey modeldeki ve bir görme-dil modelinin text_config gibi herhangi bir alt yapılandırma omurgasındaki MoE katmanlarına ulaşır. Yalnızca grouped_mm girdileri batched_mm olarak değiştirilir. Başka bir arka uç kullanan uzmanlar mevcut arka uçlarını korur.

Uzmanlar için bir arka uç ayarlayın

Belirli bir uzmanlar (experts) arka ucuna sahip bir model oluşturmak için from_pretrained() içinde experts_implementation argümanını kullanın.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen1.5-MoE-A2.7B",
    dtype="bfloat16",
    experts_implementation="batched_mm",
)

Modeli yeniden yüklemeye gerek kalmadan çalışma zamanında uzman arka uçları arasında geçiş yapmak için set_experts_implementation() kullanın.

model.set_experts_implementation("eager")

Şu anda çalışan backend'i get_experts_implementation() ile okuyun. Model için bir giriş ve her alt yapılandırma için bir giriş içeren bir dict döndürür.

model.get_experts_implementation()
# {"": "grouped_mm", "text_config": "grouped_mm", "vision_config": "eager"}

Backbone'a özgü uzmanlar backend'i

Çok modlu modeller birden fazla alt yapılandırmaya sahip olabilir (örneğin, farklı omurga mimarileri). Yüklenme sırasında experts_implementation parametresine dict geçirerek her alt yapılandırma için farklı bir uzmanlar arka ucu ayarlayabilirsiniz.

Haritalamadaki anahtarlar, alt yapılandırma adlarıyla eşleşmelidir.

from transformers import AutoModelForImageTextToText

experts_implementation_per_backbone = {
    "text_config": "grouped_mm",
    "vision_config": "eager",
}

model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen3-VL-Moe",
    experts_implementation=experts_implementation_per_backbone,
)

Uzmanlar arka planını boş bir anahtarla küresel olarak ayarlayın.

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen1.5-MoE-A2.7B",
    experts_implementation={"": "batched_mm"},
)

DeepGEMM

"deepgemm" arka ucu, uzman matmullarını kernels-community/deep-gemm tarafından dağıtılan DeepGEMM çekirdekleri üzerinden yönlendirir. Kuantize edilmemiş bfloat16 uzmanlarla ve Fine-grained FP8 üzerinden yüklenen FP8/FP4 kuantize uzmanlarla çalışır.

"deepgemm" arka ucu için şunlar gereklidir:

• Hesaplama yeteneği ≥ 9.0 olan bir CUDA GPU (Hopper veya daha yeni).
• Çekirdeğin JIT derlemesi için nvcc içeren, Hopper üzerinde 12.3 veya üzeri, Blackwell üzerinde 12.9 veya üzeri sürümde tam bir CUDA araç seti. Yalnızca çalışma zamanı kurulumunda nvcc bulunmaz ve reddedilir. Transformers, araç setini CUDA_HOME, CUDA_PATH, PATH üzerindeki nvcc ve ardından /usr/local/cuda yoluyla bulur.
• kernels paketi.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-V3",
    dtype="bfloat16",
    experts_implementation="deepgemm",
)

Çekirdek, ilk ileri geçişte tembel olarak yüklenir.

FP8 ve FP4 kuantize uzmanlar

DeepSeek tarzı checkpoint'ler genellikle önceden kuantize edilmiş gelir ve kendi kuantizasyon yapılandırmalarını taşır, bu nedenle bir FineGrainedFP8Config iletmenize gerek yoktur. "deepgemm" arka ucu, FP8 (veya Blackwell'de FP4) grouped-GEMM çekirdeğini otomatik olarak seçer. DeepGEMM, dinamik satır bazlı aktivasyon ölçeklerini (activation_scheme="dynamic") gerektirir ve statik (tensor bazlı) aktivasyon kuantizasyonunu reddeder.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-V3",
    experts_implementation="deepgemm",
)

FP4 paketlenmiş uzman ağırlıkları (DeepSeek V4 tarzı) için GPU'nun SM100+ (Blackwell) olması gerekir. Kontrol noktası yapılandırması genellikle expert_dtype="fp4" ve scale_fmt="ue8m0" olarak ayarlanır.

Blackwell (SM100+) üzerinde "deepgemm" ve "deepgemm_megamoe" uzman çekirdekleri, ikiyin üsü UE8M0 uzman ölçekleri gerektirir. Sadece float32 ölçekleriyle (scale_fmt="float") kuantize edilmiş bir kontrol noktası, çıktıyı sessizce bozmak yerine ilk ileri geçişte bir ValueError yükseltir. scale_fmt="ue8m0" ile kuantize edilmiş bir kontrol noktası yükleyin veya float32 blok ölçeklerini doğrudan tüketen grouped_mm veya batched_mm yöntemine geçin. Hopper (SM90+), DeepGEMM yolunda dönüştürme olmadan float32 ölçeklerini tüketir.

Önceden kantlanmış bir kontrol noktası için FineGrainedFP8Config geçilmesinin ana nedeni, onu bfloat16 formatına geri kantlamaktır; bu durumda uzmanlar FP8/FP4 DeepGEMM yolu yerine bfloat16 üzerinde çalışır.

from transformers import AutoModelForCausalLM, FineGrainedFP8Config

model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-V3",
    quantization_config=FineGrainedFP8Config(dequantize=True),
    experts_implementation="deepgemm",
)

Blackwell üzerinde Fused Mega MoE

Blackwell (SM100+) üzerinde, uzman paralel dağıtımını, yukarı projeksiyonu, SwiGLU'yu, aşağı projeksiyonunu ve EP birleştirmesini birleştiren tek bir füzyonlu çekirdeği çalıştırmak için experts_implementation="deepgemm_megamoe" değerini ayarlayın; bu sayede NVLink aktarımları, tensor çekirdeği hesaplamalarıyla üst üste bindirilir.

Bu arka uç şunları gerektirir:

• CUDA araç seti (nvcc) 12.9 veya daha yeni bir sürüme sahip, hesaplama yeteneği ≥ 10.0 olan bir Blackwell GPU.
• UE8M0 ağırlık ölçekleriyle eşleştirilmiş FP4 paketli uzman ağırlıkları (önceden kuantize edilmiş kontrol noktası, yapılandırmasında genellikle expert_dtype="fp4" ve scale_fmt="ue8m0" belirtir).
• Uzman paralel grubu için bir torch.distributed işlem grubu; uzman paralel sarmalama, ep_size > 1 olduğunda bunu otomatik olarak sağlar.

import os

from transformers import AutoModelForCausalLM, DistributedConfig

distributed_config = DistributedConfig(
    tp_size=int(os.environ["WORLD_SIZE"]),
    ep_size=int(os.environ["WORLD_SIZE"]),
)
model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-V4",
    experts_implementation="deepgemm_megamoe",
    distributed_config=distributed_config,
)

SonicMoE

"sonicmoe" arka ucu, yönlendirilmiş MoE ileri geçişini (yönlendirme, kapılı yukarı projeksiyon, aktivasyon, aşağı projeksiyon) quack kütüphanesi üzerine inşa edilmiş ve kernels-community/sonic-moe tarafından dağıtılan, yüksek düzeyde optimize edilmiş CuteDSL gruplu-GEMM çekirdekleri kümesine birleştirir.

"sonicmoe" arka ucu için şunlar gereklidir:

• Hesaplama yeteneği ≥ 9.0 olan bir CUDA GPU (Hopper veya daha yeni).
• kernels paketi ve nvidia-cutlass-dsl paketi.
• Kapılı bir aktivasyona (silu, gelu veya relu, sırasıyla SwiGLU/GeGLU/ReGLU'ya eşlenir) sahip uzmanlar.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen1.5-MoE-A2.7B",
    dtype="bfloat16",
    experts_implementation="sonicmoe",
)

Gereksinimler karşılanmıyorsa, forward ImportError fırlatır ve farklı bir experts_implementation seçmeniz gerekir.

torch.compile

"eager", "batched_mm" ve "grouped_mm" arka uçları, torch.compile ile farklı derecelerde uyumludur. Aşağıdaki tablo bu uyumluluğu özetler. "deepgemm", "deepgemm_megamoe" ve "sonicmoe" arka uçları harici CUDA çekirdekleri üzerinden yönlendirilir ve bu tablo kapsamına girmez.

Notlar:

• grouped_mm uzmanları arka ucu, torch.compile ile derlendiğinde şu anda yalnızca bfloat16 destekler. Ayrıca CUDA grafikleriyle uyumlu değildir, bu nedenle derleme sırasında mode=None veya mode="max-autotune-no-cudagraphs" kullanmanız gerekir.
• eager uzmanlar arka ucu, bir ileri geçişte hangi uzmanların kullanıldığını bulmak için veriye bağımlı bir işlem kullanır. Bu işlem, tam grafik derlemesiyle (fullgraph=True) uyumlu değildir.

import torch
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen1.5-MoE-A2.7B",
    dtype="bfloat16",
    experts_implementation="grouped_mm",
    device_map="auto",
).eval()

# Works for grouped_mm (no CUDA graphs)
model.forward = torch.compile(model.forward, mode="max-autotune-no-cudagraphs")

Benchmarks

Bu benchmark, farklı giriş boyutlarını ve torch.compile ile ve olmadan uzman uygulamalarını karşılaştırır.