# Uzmanlar arka uçları

Tüm Mixture-of-Experts (MoE) uygulamaları aynı yüksek düzeyde hesaplamayı 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.

| experts arka ucu | açıklama | GPU | CPU |
| --- | --- | --- | --- |
| `"eager"` | Seçili uzmanlar üzerinde döngüye girip token'larına projeksiyonları uygulayan referans uygulama. | Derleme gerektirmeden makul bir temel performans. | `grouped_mm`'den yavaş ama `batched_mm`'den hızlı. |
| `"batched_mm"` | Seçilen uzman parametrelerini her token için çoğaltır ve tüm tokenları tek bir toplu GEMM'de [torch.bmm](https://docs.pytorch.org/docs/stable/generated/torch.bmm.html) kullanarak yansıtır. | Küçük girdiler için en hızlısıdır, özellikle derleme ile. Parametre kopyalama nedeniyle daha fazla bellek kullanır. | Önerilmez (diğer arka uçlardan önemli ölçüde yavaştır). |
| `"grouped_mm"` | Tokenları seçilen uzmanlara göre sıralar ve tüm tokenları tek bir gruplu GEMM ile projekte etmek için [torch.nn.functional.grouped_mm](https://docs.pytorch.org/docs/stable/generated/torch.nn.functional.grouped_mm.html) kullanır (PyTorch 2.9+ gerektirir). | Daha büyük girdiler için en iyisi ve uzman parametrelerini çoğaltmaktan kaçındığı için bellek açısından daha verimli. Derleme ile hızlıdır. | Tüm giriş boyutları için en verimli arka uç. |
| `"deepgemm"` | Seçilen uzmana göre jetonları sıralar ve [kernels-community/deep-gemm](https://huggingface.co/kernels-community/deep-gemm) içindeki [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM) çekirdeklerini kullanarak tüm jetonları tek bir TMA hizalı gruplu GEMM ile yansıtır. | Hopper (SM90+) ve Blackwell (SM100+) üzerinde DeepSeek modelleri için yerel backend; `bfloat16` ve FP8/FP4-kuantize uzmanları destekler. | Desteklenmiyor (yalnızca CUDA). |
| `"deepgemm_megamoe"` | Uzman paralel dağıtımını, kapılı MLP'yi (yukarı projeksiyon, SwiGLU, aşağı projeksiyon) ve EP birleştirmesini tek bir DeepGEMM Mega MoE çekirdeğinde birleştirir; NVLink aktarmalarını tensor çekirdeği hesaplamalarıyla üst üste bindirir. | Sadece Blackwell (SM100+), uzman paralelliği ile çalıştırılan FP4-kuantize uzmanlar için. | Desteklenmiyor (yalnızca CUDA). |
| `"sonicmoe"` | Rotalandırılmış `bfloat16` MoE ileri geçişini (router dağıtımı, kapılı yukarı projeksiyon, aktivasyon, aşağı projeksiyon), [kernels-community/sonic-moe](https://huggingface.co/kernels-community/sonic-moe) kaynaklı [quack](https://github.com/Dao-AILab/quack) kütüphanesinden CuteDSL gruplu-GEMM çekirdeklerine birleştirir. | `bfloat16` uzmanları için kapılı aktivasyon (SwiGLU/GeGLU/ReGLU) ile Hopper (SM90+) üzerinde en yüksek düzeyde (state-of-the-art) veri aktarım hızı (throughput), özellikle eğitim için. | Desteklenmiyor (yalnızca CUDA). |

`"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 yeniden etkinleştirilir. CPU tarafında ise `grouped_mm`, her giriş boyutunda daha verimli olduğu için üretim boyunca aktif 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()](/docs/transformers/main/tr/main_classes/model#transformers.PreTrainedModel.from_pretrained) içinde `experts_implementation` argümanını kullanın.

```py
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()](/docs/transformers/main/tr/main_classes/model#transformers.PreTrainedModel.set_experts_implementation) kullanın.

```py
model.set_experts_implementation("eager")
```

Şu anda çalışan backend'i [get_experts_implementation()](/docs/transformers/main/tr/main_classes/model#transformers.PreTrainedModel.get_experts_implementation) ile okuyun. Bu, model için bir giriş ve her alt yapılandırma için bir giriş içeren bir `dict` döndürür.

```py
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.

```py
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.

```py
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](https://huggingface.co/kernels-community/deep-gemm) tarafından dağıtılan [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM) çekirdekleri üzerinden yönlendirir. Kuantize edilmemiş `bfloat16` uzmanlarla ve [Fine-grained FP8](./quantization/finegrained_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).
- Kernelin JIT derlemesi için `nvcc` içeren, Hopper'da 12.3 veya üzeri, Blackwell'de 12.9 veya üzeri sürümde tam bir CUDA araç seti. Yalnızca çalışma zamanı kurulumunda `nvcc` bulunmaz ve bu kurulum reddedilir. Transformers, araç setini `CUDA_HOME`, `CUDA_PATH`, `PATH` üzerindeki `nvcc` ve ardından `/usr/local/cuda` yolu üzerinden bulur.
- [kernels](https://github.com/huggingface/kernels) paketi.

```py
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](/docs/transformers/main/tr/main_classes/quantization#transformers.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.

```py
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.

> [!NOTE]
> 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](/docs/transformers/main/tr/main_classes/quantization#transformers.FineGrainedFP8Config) geçilmesinin ana nedeni, onu `bfloat16` formatına geri kantlamaktır; bu durumda uzmanlar FP8/FP4 DeepGEMM yolu yerine `bfloat16` üzerinde çalışır.

```py
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.

```py
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](https://github.com/Dao-AILab/quack) kütüphanesi üzerine inşa edilmiş ve [kernels-community/sonic-moe](https://huggingface.co/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](https://github.com/huggingface/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.

```py
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 tablonun kapsamı dışında kalır.

| Uygulama          | derleme modları                    | dtypes                           | `fullgraph=True` |
| ----------------------- | ------------------------------------ | -------------------------------- | ---------------- |
| `grouped_mm`            | `None`, `max-autotune-no-cudagraphs` | `bfloat16`                       | Evet              |
| `grouped_mm` (yedek) | `None`, `max-autotune-no-cudagraphs` | `bfloat16`, `float16`, `float32` | Evet              |
| `batched_mm`            | tümü                                  | `bfloat16`, `float16`, `float32` | Evet              |
| `eager`                 | tümü                                  | `bfloat16`, `float16`, `float32` | Hayır               |

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.

```py
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](https://github.com/user-attachments/files/24125816/bench.py), farklı giriş boyutlarını ve `torch.compile` ile ve olmadan uzman uygulamalarını karşılaştırır.