커널 로딩

커널은 표준 PyTorch 연산의 드롭인 대체재로 작동합니다. 모델 코드를 깨뜨리지 않으면서 forward 메서드를 최적화된 커널 구현으로 교체합니다.

이 가이드는 추론을 가속화하기 위해 커널을 로드하는 방법을 보여줍니다.

지원되는 버전의 kernels 패키지와 함께 Transformers를 설치합니다.

pip install -U "transformers[kernels]"

use_kernels=True를 from_pretrained()에 설정하여 Hub에서 해당 디바이스에 사용할 수 있는 가장 성능이 좋은 커널을 로드합니다. 이를 통해 지원되는 PyTorch 연산이 커널 구현으로 대체됩니다.

from transformers import AutoModelForCausalLM

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

기본 매핑은 모델, 장치 및 실행 모드에 따라 달라집니다. 아래 표에는 표시된 장치에 대한 일반적인 Hub 저장소가 나열되어 있습니다. 특정 조합에 대해 커널이 등록되지 않은 경우, 해당 연산은 표준 PyTorch로 폴백됩니다.

작업	NVIDIA (CUDA)	AMD (ROCm)	Intel (XPU)
RMSNorm	`kernels-community/liger-kernels`	`kernels-community/liger-kernels`	`kernels-community/rmsnorm`
MoE MLP	`kernels-community/megablocks`	`kernels-community/megablocks`	`kernels-community/megablocks`
MLP (SwiGLU, GeGLU)	`kernels-community/liger-kernels`	—	—
Linear	`kernels-community/liger-kernels`	—	—
활성화 함수(GELU 변형, SiLU)	`kernels-community/activation`	—	—
Rotary 임베딩	`kernels-community/rotary`	`kernels-community/aiter-rope`	`kernels-community/rotary`
Causal LM 손실	`kernels-community/liger-kernels`	—	—
Deformable attention	`kernels-community/deformable-detr`	—	—

이 표는 모든 항목을 포함하지 않습니다. 모델은 추가적인 레이어와 함수를 등록할 수 있으며, 일부 매핑은 특정 실행 모드에서만 사용할 수 있습니다.

AMD GPU는 PyTorch에서 장치 유형을 cuda로 보고합니다. Transformers는 런타임에 ROCm을 감지하여 kernels-community/aiter-rope와 같은 AITER 빌드를 포함한 위의 AMD 커널로 지원되는 연산을 라우팅합니다. 장치 유형을 직접 설정할 필요가 없습니다.

kernels-community 조직에서 사용 가능한 커널을 탐색하세요.

Attention 커널

attn_implementation 인수를 사용하여 Hub에서 어텐션 커널을 로드합니다.

from transformers import AutoModelForCausalLM

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

attention kernel의 경우, kernels-community 저장소(신뢰할 수 있는 저장소이며, 향후 더 많은 신뢰 저장소를 추가할 수 있음)에 속하지 않는 모든 항목은 추가적인 allow_all_kernels=True kwarg를 사용해야 합니다(비-HF 모델의 trust_remote_code=True kwarg와 유사합니다). 이는 커널 로딩이 호스트 머신에서 임의의 코드 실행으로 이어질 수 있고, 모든 저장소를 검증할 수 없기 때문에 명시적으로 허용해야 합니다.

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

attention과 같은 특정 커널은 여러 형식을 지원합니다.

@v2.1.0은 특정 태그나 브랜치를 고정합니다.
@>=2.0,<3.0은 시맨틱 버전 관리 제약 조건을 설정합니다.

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 폴백

attn_implementation="flash_attention_2", "flash_attention_3", 또는 "flash_attention_4"를 요청하면 컴파일된 flash-attn 패키지가 설치되어 있지 않거나 디바이스가 CUDA가 아닌 경우, 해당 Hub 커널로 폴백됩니다.

FlashAttention-4 지원은 베타 버전입니다. API 및 동작이 변경될 수 있습니다.

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

모드 인식

Kernels은 PyTorch의 model.training 상태에 따라 training 모드와 inference 모드를 자동으로 지원합니다.

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

mode 인수를 사용하여 kernelize() 함수에서 학습 모드와 추론 모드를 명시적으로 활성화합니다. 학습 모드에서는 추가적인 torch.compile 모드를 지원합니다.

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은 모델에서 사용할 커널을 사용자 지정합니다.

kernel_mapping의 키는 모델에 의해 등록된 이름입니다. "RMSNorm"과 같은 레이어나 "rotary_pos_emb"와 같은 등록된 함수를 가리킬 수 있습니다. : 구분자는 저장소 내의 특정 커널 항목을 지정하여 해당 레이어나 함수에 매핑합니다.

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

각 장치 유형별로 다른 커널 구현을 지정합니다.

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 딕셔너리를 추가하여 로드할 커널 빌드를 제어합니다.

옵션	설명	기본값
`version`	커널 저장소의 주요 버전입니다. `2`는 저장소의 `v2` 브랜치에서 최신 빌드를 로드합니다.	`1`
`revision`	버전 대신 로드할 정확한 태그, 브랜치 또는 커밋입니다.	---
`trust_remote_code`	신뢰할 수 있는 `kernels-community` 조직 외부의 저장소를 허용합니다. 커널을 로드하면 해당 저장소의 코드가 사용자의 머신에서 실행됩니다.	`False`

from transformers import KernelConfig

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

커널 저장소의 이전 브랜치에는 사용 중인 PyTorch 및 CUDA 버전에 대한 빌드가 없을 수 있습니다. 커널 로딩에 실패하면 하드웨어가 지원되지 않는다고 결론 내리기 전에 더 새로운 version을 시도해 보세요.

상속된 매핑

KernelConfig은 Hub 커널에 대한 Transformers의 기본 커널 매핑을 상속하며, kernel_mapping의 항목은 해당 레이어와 함수에 대해 기본값을 덮어씁니다. inherit_mapping=False로 설정하면 kernel_mapping의 항목만 사용합니다. 명시하지 않은 모든 항목은 표준 PyTorch로 폴백됩니다. 이는 다른 기본값을 적용하지 않고 특정 커널을 벤치마킹하거나 사용자 정의 구현을 테스트할 때 유용합니다.

아래 구성은 rotary_pos_emb 함수를 RoPE 커널에 매핑하고, 나머지 모든 연산은 PyTorch에서 수행하도록 합니다. 함수 이름은 모델에 의해 등록되어야 합니다.

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

모듈 융합

(class_name, path_pattern) 쌍의 튜플을 KernelConfig의 키로 전달하여 인접한 모듈을 단일 커널로 병합합니다. 모든 패턴은 동일한 부모 모듈을 공유해야 합니다. *는 단일 경로 세그먼트를 나타냅니다.

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은 KernelName 클래스와 함께 KernelNameLayout 클래스를 제공하도록 kernel repo를 요구합니다. 구현 방법은 Writing kernels 가이드를 참고하세요.

로컬 커널

use_local_kernel=True를 KernelConfig에 지정하여 로컬 파일 경로에서 커널을 로드합니다. 이렇게 하면 Hub 저장소가 아닌 로컬 파일 시스템 경로에서 로드됩니다.

로컬 커널은 Hub 형식인 org/repo:layer_name 대신 /abs/path: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
)

커널을 전역으로 비활성화

코드를 변경하지 않고 모든 곳에서 Hub 커널을 비활성화하려면 USE_HUB_KERNELS 환경 변수를 설정하세요.

export USE_HUB_KERNELS=0  # or OFF or NO

문제 해결

Kernel 통합은 하드웨어, 드라이버, 패키지 버전이 함께 작동하는지에 따라 달라집니다. 다음 섹션에서는 일반적인 실패 사례를 다룹니다.

설치 문제

Import 오류는 kernels 패키지가 누락되었거나 Transformers가 지원하는 버전 범위를 벗어났음을 의미합니다. extra를 통해 다시 설치하여 호환되는 버전을 받으세요.

pip install -U "transformers[kernels]"

커널 로딩 실패

특정 커널이 로드되지 않으면 다음을 시도해 보세요.

kernel 요구 사항에 대한 하드웨어 호환성을 확인하세요.
CUDA/ROCm/Metal 드라이버가 최신 상태인지 확인하세요.
알려진 문제에 대해서는 커널 저장소 문서를 참조하세요.

기기 호환성

모든 커널이 모든 장치를 지원하지는 않습니다. 하드웨어에서 특정 커널을 사용할 수 없는 경우 라이브러리는 표준 PyTorch 연산으로 대체합니다. 장치별 지원 사항은 커널 저장소 문서를 확인하세요.

리소스

Kernels 저장소
Hugging Face Kernel Hub로 5분 만에 모델을 향상시키세요 블로그 게시물
kernels-community 조직에서 커널을 찾아보세요

Update on GitHub