# 커널 로딩

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

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

지원되는 버전의 [kernels](https://github.com/huggingface/kernels) 패키지와 함께 Transformers를 설치합니다.

```bash
pip install -U "transformers[kernels]"
```

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

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

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

> [!NOTE]
> AMD GPU는 PyTorch에서 장치 유형을 `cuda`로 보고합니다. Transformers는 런타임에 ROCm을 감지하여 [AITER](https://github.com/ROCm/aiter) 빌드(예: `kernels-community/aiter-rope`)를 포함한 위의 AMD 커널로 지원되는 연산을 라우팅합니다. 장치 유형을 직접 설정할 필요가 없습니다.

[kernels-community](https://huggingface.co/kernels-community) 조직에서 사용 가능한 커널을 탐색하세요.

## Attention 커널

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

```py
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와 유사합니다). 이는 커널 로딩이 호스트 머신에서 임의의 코드 실행으로 이어질 수 있고, 모든 저장소를 검증할 수 없기 때문에 명시적으로 허용해야 합니다.

```py
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`은 시맨틱 버전 관리 제약 조건을 설정합니다.

```py
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 커널로 폴백됩니다.

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

```py
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](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.train) 모드와 [inference](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.eval) 모드로 자동으로 적응합니다.

```py
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()](/docs/transformers/main/ko/main_classes/kernels#transformers.kernelize) 함수에서 학습 모드와 추론 모드를 명시적으로 활성화합니다. 학습 모드에서는 추가적인 torch.compile 모드를 지원합니다.

```py
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](/docs/transformers/main/ko/main_classes/kernels#transformers.KernelConfig)은 모델에서 사용할 커널을 사용자 지정합니다.

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

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

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

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

```py
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에서 수행하도록 합니다. 함수 이름은 모델에 의해 등록되어야 합니다.

```py
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](/docs/transformers/main/ko/main_classes/kernels#transformers.KernelConfig)의 키로 전달하여 인접한 모듈을 단일 커널로 병합합니다. 모든 패턴은 동일한 부모 모듈을 공유해야 합니다. `*`는 단일 경로 세그먼트를 나타냅니다.

```python
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](./writing_kernels) 가이드를 참고하세요.

## 로컬 커널

`use_local_kernel=True`를 [KernelConfig](/docs/transformers/main/ko/main_classes/kernels#transformers.KernelConfig)에 지정하여 로컬 파일 경로에서 커널을 로드합니다. 이렇게 하면 Hub 저장소가 아닌 로컬 파일 시스템 경로에서 로드됩니다.

로컬 커널은 Hub 형식인 `org/repo:layer_name` 대신 `/abs/path:layer_name`를 사용합니다.

```py
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` 환경 변수를 설정하세요.

```bash
export USE_HUB_KERNELS=0  # or OFF or NO
```

## 문제 해결

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

### 설치 문제

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

```bash
pip install -U "transformers[kernels]"
```

### 커널 로딩 실패

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

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

### 기기 호환성

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

## 리소스

- [Kernels](https://github.com/huggingface/kernels) 저장소
- [Hugging Face Kernel Hub로 5분 만에 모델을 향상시키세요](https://huggingface.co/blog/hello-hf-kernels) 블로그 게시물
- [kernels-community](https://huggingface.co/kernels-community) 조직에서 커널을 찾아보세요