# カーネルの読み込み

カーネルは、標準的な PyTorch 操作のドロップイン代替として機能します。モデルコードを壊すことなく、`forward` メソッドを最適化されたカーネル実装に置き換えます。

このガイドでは、推論を高速化するためにカーネルを読み込む方法を示します。

サポートされているバージョンの[kernels](https://github.com/huggingface/kernels)パッケージとともにTransformersをインストールします。

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

`use_kernels=True` を [from_pretrained()](/docs/transformers/main/ja/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 embeddings | `kernels-community/rotary` | `kernels-community/aiter-rope` | `kernels-community/rotary` |
| 因果言語モデルの損失 | `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"
)
```

アテンションカーネルについては、`kernels-community` リポジトリ（信頼できるリポジトリであり、将来的により多くの信頼できるリポジトリを追加する可能性があります）の一部でないものは、追加の `allow_all_kernels=True` キーワード引数の使用が必要になります（HF 以外のモデルにおける `trust_remote_code=True` キーワード引数と同様です）。これは、カーネルの読み込みがホストマシン上で任意のコードの実行につながる可能性があるため、すべてのリポジトリを検証できないため、明示的に許可する必要があるためです。

```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` 状態に基づいて、[学習](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.train)モードと[推論](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/ja/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/ja/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/ja/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` クラスを伴うクラスをカーネルのリポジトリで提供する必要があります。実装方法については、[カーネルの作成](./writing_kernels) ガイドを参照してください。

## ローカルカーネル

`use_local_kernel=True` を [KernelConfig](/docs/transformers/main/ja/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
```

## トラブルシューティング

カーネル統合は、ハードウェア、ドライバー、パッケージのバージョンが互いに正常に動作していることに依存します。以下のセクションでは、一般的な失敗例について説明します。

### インストールの問題

インポートエラーは、kernels パッケージが欠落しているか、そのバージョンが Transformers がサポートする範囲外であることを示しています。互換性のあるバージョンを取得するには、extra を通じて再インストールしてください。

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

### カーネルの読み込み失敗

特定のカーネルの読み込みに失敗した場合は、以下の手順をお試しください。

- カーネルの要件に対するハードウェアの互換性を確認してください。
- 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) 組織でカーネルを発見