Experts 백엔드

모든 Mixture-of-Experts(MoE) 구현은 동일한 고수준 계산을 수행합니다. 각 토큰에 대해 라우터가 k개의 전문가를 선택합니다. 이후 토큰의 숨겨진 상태(hidden state)는 선택된 전문가의 파라미터를 통해 투사되고, 라우팅 가중치와 함께 집계됩니다. 전문가 백엔드 간의 차이는 이러한 전문가 행렬 곱셈이 어떻게 실행되는지에 있습니다.

ExpertsInterface는 최적화된 experts 백엔드를 제공합니다. experts 구현을 모델 코드와 분리하여 다양한 함수에 대한 실험을 단순화합니다. 동일한 인터페이스를 통해 새로운 백엔드를 추가할 수 있습니다.

"batched_mm" 및 "grouped_mm" 백엔드도 FP8 및 FP4(int8 패킹) 양자화 전문가를 Triton finegrained-fp8 커널을 통해 실행하며, float32 또는 UE8M0 스케일을 읽습니다. "deepgemm" 백엔드가 사용할 수 없는 경우 양자화 체크포인트의 폴백 역할을 수행합니다.

디코딩 단계 전환

GPU에서 experts_implementation="grouped_mm"로 로드된 모델은 생성의 디코딩 단계에서 "batched_mm"로 자동으로 전환됩니다. 이는 낮은 토큰 수에서 훨씬 빠릅니다. 생성이 완료되면 원래 백엔드로 복원됩니다. CPU에서는 모든 입력 크기에서 더 효율적이므로 grouped_mm가 생성 전체 동안 활성화된 상태로 유지됩니다.

스위치는 최상위 모델과 비전-언어 모델의 text_config과 같은 서브 구성 백본의 MoE 레이어까지 도달합니다. grouped_mm 항목만 batched_mm으로 전환됩니다. 다른 백엔드를 실행하는 전문가들은 이를 유지합니다.

experts 백엔드 설정

experts_implementation 인수를 from_pretrained()에 전달하여 특정 experts 백엔드를 사용하는 모델을 생성합니다.

from transformers import AutoModelForCausalLM

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

모델을 다시 로드하지 않고 런타임에서 set_experts_implementation()을 사용하여 전문가 백엔드 간을 전환할 수 있습니다.

model.set_experts_implementation("eager")

현재 실행 중인 백엔드를 get_experts_implementation()으로 읽습니다. 이 함수는 모델에 대한 항목 하나와 서브 구성별로 하나씩 항목을 포함하는 dict를 반환합니다.

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

백본별 전문가 백엔드

멀티모달 모델에는 여러 서브 구성(예: 서로 다른 백본)이 있을 수 있습니다. 로드 시 experts_implementation에 dict를 전달하여 서브 구성별로 다른 experts 백엔드를 설정할 수 있습니다.

매핑의 키는 서브 구성 이름과 일치해야 합니다.

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

빈 키를 사용하여 experts 백엔드를 전역으로 설정합니다.

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

DeepGEMM

"deepgemm" 백엔드는 kernels-community/deep-gemm에서 배포하는 DeepGEMM 커널을 통해 전문가 matmul을 라우팅합니다. 이는 양자화되지 않은 bfloat16 전문가와 Fine-grained FP8를 통해 로드된 FP8/FP4 양자화 전문가 모두와 함께 작동합니다.

"deepgemm" 백엔드는 다음을 요구합니다:

• Compute capability ≥ 9.0 (Hopper 또는 그 이상)을 지원하는 CUDA GPU
• 커널의 JIT 컴파일을 위한 nvcc가 포함된 완전한 CUDA 툴킷이 필요합니다. Hopper의 경우 버전 12.3 이상, Blackwell의 경우 12.9 이상이어야 합니다. 런타임 전용 설치에는 nvcc가 없으므로 거부됩니다. Transformers는 CUDA_HOME, CUDA_PATH, PATH에 있는 nvcc, 그리고 /usr/local/cuda 순서로 툴킷을 찾습니다.
• kernels 패키지.

from transformers import AutoModelForCausalLM

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

kernel은 첫 번째 forward 시점에 지연 로드됩니다.

FP8 및 FP4 양자화 전문가

DeepSeek 스타일의 체크포인트는 일반적으로 사전 양자화되어 있으며 자체 양자화 구성을 포함하므로 FineGrainedFP8Config를 전달할 필요가 없습니다. "deepgemm" 백엔드는 FP8(Blackwell의 경우 FP4) grouped-GEMM 커널을 자동으로 선택합니다. DeepGEMM은 동적 행별 활성화 스케일(activation_scheme="dynamic")을 요구하며 정적(텐서별) 활성화 양자화를 거부합니다.

from transformers import AutoModelForCausalLM

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

FP4-packed expert weights(DeepSeek V4 스타일)의 경우 GPU는 SM100+(Blackwell)이어야 합니다. 체크포인트 설정에는 일반적으로 expert_dtype="fp4"와 scale_fmt="ue8m0"가 지정되어 있습니다.

Blackwell(SM100+)에서 "deepgemm" 및 "deepgemm_megamoe" experts 커널은 2의 거듭제곱 UE8M0 expert scales가 필요합니다. 일반 float32 scales(scale_fmt="float")로 양자화된 체크포인트를 로드하면 출력이 조용히 손상되는 대신 첫 번째 forward에서 ValueError가 발생합니다. scale_fmt="ue8m0"로 양자화된 체크포인트를 로드하거나, float32 block scales를 직접 사용하는 grouped_mm 또는 batched_mm로 전환하세요. Hopper(SM90+)는 DeepGEMM 경로에서 변환 없이 float32 scales를 사용합니다.

사전 양자화 체크포인트에 FineGrainedFP8Config를 전달하는 주된 이유는 이를 bfloat16으로 역양자화하기 위해서이며, 이 경우 전문가들은 FP8/FP4 DeepGEMM 경로가 아닌 bfloat16로 실행됩니다.

from transformers import AutoModelForCausalLM, FineGrainedFP8Config

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

Blackwell의 Fused Mega MoE

Blackwell(SM100+)에서 experts_implementation="deepgemm_megamoe"를 설정하면 expert-parallel dispatch, up projection, SwiGLU, down projection, EP combine을 결합한 단일 fused kernel을 실행하여 NVLink 전송과 tensor-core 계산을 오버랩합니다.

이 백엔드는 다음을 요구합니다:

• CUDA 툴킷(nvcc) 12.9 이상을 갖춘 Blackwell GPU(컴퓨트 캐패빌리티 ≥ 10.0).
• UE8M0 가중치 스케일과 페어링된 FP4-packed expert 가중치(사전 양자화 체크포인트는 일반적으로 설정에서 expert_dtype="fp4" 및 scale_fmt="ue8m0"를 선언합니다).
• ep_size > 1일 때 expert-parallel 래핑이 자동으로 제공하는 expert-parallel 그룹용 torch.distributed 프로세스 그룹입니다.

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" 백엔드는 라우팅된 MoE 포워드(디스패치, 게이트드 업 투영, 활성화, 다운 투영)를 quack 라이브러리를 기반으로 kernels-community/sonic-moe에서 배포하는, 최적화가 잘된 CuteDSL 그룹 GEMM 커널 집합으로 융합합니다.

"sonicmoe" 백엔드는 다음을 요구합니다:

• Compute capability ≥ 9.0 (Hopper 또는 그 이상)을 지원하는 CUDA GPU
• kernels 패키지와 nvidia-cutlass-dsl 패키지.
• 게이트 활성화(silu, gelu, 또는 relu, 각각 SwiGLU/GeGLU/ReGLU로 매핑됨)를 사용하는 전문가(Experts).

from transformers import AutoModelForCausalLM

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

요건이 충족되지 않으면 forward가 ImportError를 발생시키며, 다른 experts_implementation을 선택해야 합니다.

torch.compile

"eager", "batched_mm", "grouped_mm" 백엔드는 torch.compile과 다양한 정도로 호환됩니다. 다음 표는 이러한 호환성을 요약합니다. "deepgemm", "deepgemm_megamoe", "sonicmoe" 백엔드는 외부 CUDA 커널을 통해 라우팅되며 이 표의 범위에 포함되지 않습니다.

참고:

• grouped_mm experts 백엔드는 현재 torch.compile로 컴파일할 때 bfloat16만 지원합니다. 또한 CUDA graphs와 호환되지 않으므로 컴파일 시 mode=None 또는 mode="max-autotune-no-cudagraphs"를 사용해야 합니다.
• eager experts 백엔드는 포워드 패스에서 어떤 experts가 사용되는지 찾기 위해 데이터 의존 연산을 사용합니다. 이 연산은 전체 그래프 컴파일(fullgraph=True)과 호환되지 않습니다.

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

벤치마크

이 벤치마크는 torch.compile을 사용하거나 사용하지 않는 다양한 입력 크기와 전문가(experts) 구현을 비교합니다.