Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / transformers /main /pt /kernel_doc /loading_kernels.md

mishig

3 days ago

preview code

download

raw

13.2 kB

# Carregando kernels

Um kernel funciona como uma substituição direta para as operações padrão do PyTorch. Ele substitui o método `forward` pela implementação otimizada do kernel sem quebrar o código do modelo.

Este guia mostra como carregar kernels para acelerar a inferência.

Instale o Transformers com a versão suportada do pacote [kernels](https://github.com/huggingface/kernels).

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

Defina `use_kernels=True` em [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os kernels mais performáticos disponíveis no Hub para o seu dispositivo. Isso substitui as operações suportadas do PyTorch pela implementação do kernel.

```py
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    device_map="auto"
)
```

O mapeamento padrão depende do modelo, do dispositivo e do modo de execução. A tabela abaixo lista os repositórios comuns do Hub para os dispositivos mostrados. Quando nenhum kernel está registrado para uma combinação específica, a operação recorre ao PyTorch padrão.

| Operação | NVIDIA (CUDA) | AMD (ROCm) | Intel (XPU) |
|---|---|---|---|
| RMSNorm | `kernels-community/liger-kernels` | `kernels-community/liger-kernels` | `kernels-community/rmsnorm` |
| MLP de MoE | `kernels-community/megablocks` | `kernels-community/megablocks` | `kernels-community/megablocks` |
| MLP (SwiGLU, GeGLU) | `kernels-community/liger-kernels` | — | — |
| Linear | `kernels-community/liger-kernels` | — | — |
| Ativações (variantes de GELU, SiLU) | `kernels-community/activation` | — | — |
| Incorporações rotativas | `kernels-community/rotary` | `kernels-community/aiter-rope` | `kernels-community/rotary` |
| Perda do LM causal | `kernels-community/liger-kernels` | — | — |
| Atenção deformável | `kernels-community/deformable-detr` | — | — |

A tabela não é exaustiva. Os modelos podem registrar camadas e funções adicionais, e alguns mapeamentos estão disponíveis apenas para modos de execução específicos.

> [!NOTE]
> GPUs da AMD relatam seu tipo de dispositivo como `cuda` no PyTorch. O Transformers detecta o ROCm em tempo de execução e direciona as operações suportadas para os kernels da AMD acima, incluindo builds do [AITER](https://github.com/ROCm/aiter), como `kernels-community/aiter-rope`. Você não precisa definir o tipo de dispositivo manualmente.

Navegue pelos kernels disponíveis na organização [kernels-community](https://huggingface.co/kernels-community).

## Kernels de atenção

Carregue kernels de atenção do Hub com o argumento `attn_implementation`.

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

Observe que, para kernels de atenção, qualquer coisa que não faça parte do repositório `kernels-community` (que é confiável – podemos adicionar mais repositórios confiáveis no futuro) exigirá o uso de um kwarg adicional `allow_all_kernels=True` (similar ao kwarg `trust_remote_code=True` para modelos não-HF). Isso ocorre porque o carregamento de um kernel pode levar à execução de código arbitrário na máquina host, e não podemos verificar todos os repositórios, portanto, você precisa permitir isso explicitamente.

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

Kernels específicos, como attention, aceitam vários formatos.

- `@v2.1.0` fixa uma tag ou branch específica.
- `@>=2.0,<3.0` define restrições de versionamento semântico.

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

### Fallback do FlashAttention

Solicitar `attn_implementation="flash_attention_2"`, `"flash_attention_3"` ou `"flash_attention_4"` recorre ao kernel correspondente do Hub quando o pacote `flash-attn` compilado não está instalado ou quando seu dispositivo não é CUDA.

> [!NOTE]
> O suporte ao FlashAttention-4 está em beta. As APIs e o comportamento podem mudar.

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

## Consciência do modo

Os kernels se adaptam automaticamente aos modos de [treinamento](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.train) e [inferência](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.eval) com base no estado `model.training` do PyTorch.

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

Ative explicitamente os modos de treinamento e inferência com o argumento `mode` na função [kernelize()](/docs/transformers/main/pt/main_classes/kernels#transformers.kernelize). O modo de treinamento também suporta um modo adicional do 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/pt/main_classes/kernels#transformers.KernelConfig) personaliza quais kernels são usados em um modelo.

As chaves de `kernel_mapping` são nomes registrados pelo modelo. Elas podem se referir a uma camada, como `"RMSNorm"`, ou a uma função registrada, como `"rotary_pos_emb"`. O separador `:` nomeia uma entrada de kernel específica dentro do repositório e a mapeia para aquela camada ou função.

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

Especifique diferentes implementações de kernel para cada tipo de dispositivo.

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

### Metadados do kernel

Adicione um dicionário de metadados para controlar qual build do kernel é carregada.

| Opção | Descrição | Padrão |
|---|---|---|
| `version` | Versão principal do repositório do kernel. `2` carrega o build mais recente no ramo `v2` do repositório. | `1` |
| `revision` | Tag, branch ou commit exato para carregar em vez de uma versão. | --- |
| `trust_remote_code` | Permite um repositório fora da organização confiável `kernels-community`. Carregar um kernel executa código desse repositório na sua máquina. | `False` |

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

Ramificações mais antigas de um repositório de kernel podem não ter builds para as suas versões de PyTorch e CUDA. Se um kernel falhar ao carregar, tente uma `version` mais recente antes de concluir que o seu hardware não é suportado.

### Mapeamentos herdados

Um `KernelConfig` herda o mapeamento padrão de kernels do Transformers para kernels do Hub, e as entradas em `kernel_mapping` substituem o padrão para as camadas e funções correspondentes. Defina `inherit_mapping=False` para usar apenas as entradas em `kernel_mapping`. Tudo o que você deixar de fora volta ao PyTorch padrão. Isso é útil ao fazer benchmark de um kernel específico ou testar uma implementação personalizada sem aplicar os outros padrões.

A configuração abaixo mapeia a função `rotary_pos_emb` para um kernel RoPE e mantém todas as outras operações no PyTorch. O nome da função deve ser registrado pelo modelo.

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

## Fusão de módulos

Fusione módulos adjacentes em um único kernel passando uma tupla de pares `(class_name, path_pattern)` como chave em [KernelConfig](/docs/transformers/main/pt/main_classes/kernels#transformers.KernelConfig). Todos os padrões devem compartilhar o mesmo módulo pai. `*` corresponde a qualquer segmento único de caminho.

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

O Fusion exige que o repositório do kernel forneça uma classe `KernelNameLayout` complementar junto com a classe `KernelName`. Consulte o guia [Writing kernels](./writing_kernels) para saber como implementar uma.

## Kernels locais

Carregue kernels a partir de caminhos de arquivo locais com `use_local_kernel=True` em [KernelConfig](/docs/transformers/main/pt/main_classes/kernels#transformers.KernelConfig). Isso carrega de um caminho do sistema de arquivos local em vez de um repositório do Hub.

Kernels locais usam `/abs/path:layer_name` em vez do formato do Hub `org/repo: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
)
```

## Desativar kernels globalmente

Defina a variável de ambiente `USE_HUB_KERNELS` para desativar os kernels do Hub em todos os lugares sem alterar seu código.

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

## Solução de problemas

A integração do kernel depende do funcionamento conjunto do hardware, dos drivers e das versões dos pacotes. As seções a seguir abordam falhas comuns.

### Problemas de instalação

Erros de importação indicam que o pacote de kernels está ausente ou que sua versão está fora da faixa suportada pelo Transformers. Reinstale por meio do extra para obter uma versão compatível.

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

### Falhas no carregamento de kernels

Se kernels específicos falharem ao carregar, tente o seguinte.

- Verifique a compatibilidade do seu hardware com os requisitos do kernel.
- Verifique se seus drivers CUDA/ROCm/Metal estão atualizados.
- Consulte a documentação do repositório do kernel para problemas conhecidos.

### Compatibilidade de dispositivos

Nem todos os kernels suportam todos os dispositivos. A biblioteca recorre às operações padrão do PyTorch quando um kernel não está disponível para o seu hardware. Consulte a documentação do repositório de kernels para verificar o suporte específico a cada dispositivo.

## Recursos

- repositório [Kernels](https://github.com/huggingface/kernels)
- post no blog [Reforce seus modelos em 5 minutos com o Hugging Face Kernel Hub](https://huggingface.co/blog/hello-hf-kernels)
- Descubra kernels na organização [kernels-community](https://huggingface.co/kernels-community)

Xet Storage Details

Size:: 13.2 kB
Xet hash:: 3d486b960baf4bc293eac1e07bcd694021bbd3233f5424f2a93657b6d7c73328

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# Carregando kernels

	Um kernel funciona como uma substituição direta para as operações padrão do PyTorch. Ele substitui o método `forward` pela implementação otimizada do kernel sem quebrar o código do modelo.

	Este guia mostra como carregar kernels para acelerar a inferência.

	Instale o Transformers com a versão suportada do pacote [kernels](https://github.com/huggingface/kernels).

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

	Defina `use_kernels=True` em [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os kernels mais performáticos disponíveis no Hub para o seu dispositivo. Isso substitui as operações suportadas do PyTorch pela implementação do kernel.

	```py
	from transformers import AutoModelForCausalLM

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

	O mapeamento padrão depende do modelo, do dispositivo e do modo de execução. A tabela abaixo lista os repositórios comuns do Hub para os dispositivos mostrados. Quando nenhum kernel está registrado para uma combinação específica, a operação recorre ao PyTorch padrão.

	\| Operação \| NVIDIA (CUDA) \| AMD (ROCm) \| Intel (XPU) \|
	\|---\|---\|---\|---\|
	\| RMSNorm \| `kernels-community/liger-kernels` \| `kernels-community/liger-kernels` \| `kernels-community/rmsnorm` \|
	\| MLP de MoE \| `kernels-community/megablocks` \| `kernels-community/megablocks` \| `kernels-community/megablocks` \|
	\| MLP (SwiGLU, GeGLU) \| `kernels-community/liger-kernels` \| — \| — \|
	\| Linear \| `kernels-community/liger-kernels` \| — \| — \|
	\| Ativações (variantes de GELU, SiLU) \| `kernels-community/activation` \| — \| — \|
	\| Incorporações rotativas \| `kernels-community/rotary` \| `kernels-community/aiter-rope` \| `kernels-community/rotary` \|
	\| Perda do LM causal \| `kernels-community/liger-kernels` \| — \| — \|
	\| Atenção deformável \| `kernels-community/deformable-detr` \| — \| — \|

	A tabela não é exaustiva. Os modelos podem registrar camadas e funções adicionais, e alguns mapeamentos estão disponíveis apenas para modos de execução específicos.

	> [!NOTE]
	> GPUs da AMD relatam seu tipo de dispositivo como `cuda` no PyTorch. O Transformers detecta o ROCm em tempo de execução e direciona as operações suportadas para os kernels da AMD acima, incluindo builds do [AITER](https://github.com/ROCm/aiter), como `kernels-community/aiter-rope`. Você não precisa definir o tipo de dispositivo manualmente.

	Navegue pelos kernels disponíveis na organização [kernels-community](https://huggingface.co/kernels-community).

	## Kernels de atenção

	Carregue kernels de atenção do Hub com o argumento `attn_implementation`.

	```py
	from transformers import AutoModelForCausalLM

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

	Observe que, para kernels de atenção, qualquer coisa que não faça parte do repositório `kernels-community` (que é confiável – podemos adicionar mais repositórios confiáveis no futuro) exigirá o uso de um kwarg adicional `allow_all_kernels=True` (similar ao kwarg `trust_remote_code=True` para modelos não-HF). Isso ocorre porque o carregamento de um kernel pode levar à execução de código arbitrário na máquina host, e não podemos verificar todos os repositórios, portanto, você precisa permitir isso explicitamente.

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

	Kernels específicos, como attention, aceitam vários formatos.

	- `@v2.1.0` fixa uma tag ou branch específica.
	- `@>=2.0,<3.0` define restrições de versionamento semântico.

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

	### Fallback do FlashAttention

	Solicitar `attn_implementation="flash_attention_2"`, `"flash_attention_3"` ou `"flash_attention_4"` recorre ao kernel correspondente do Hub quando o pacote `flash-attn` compilado não está instalado ou quando seu dispositivo não é CUDA.

	> [!NOTE]
	> O suporte ao FlashAttention-4 está em beta. As APIs e o comportamento podem mudar.

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

	## Consciência do modo

	Os kernels se adaptam automaticamente aos modos de [treinamento](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.train) e [inferência](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.eval) com base no estado `model.training` do PyTorch.

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

	Ative explicitamente os modos de treinamento e inferência com o argumento `mode` na função [kernelize()](/docs/transformers/main/pt/main_classes/kernels#transformers.kernelize). O modo de treinamento também suporta um modo adicional do 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/pt/main_classes/kernels#transformers.KernelConfig) personaliza quais kernels são usados em um modelo.

	As chaves de `kernel_mapping` são nomes registrados pelo modelo. Elas podem se referir a uma camada, como `"RMSNorm"`, ou a uma função registrada, como `"rotary_pos_emb"`. O separador `:` nomeia uma entrada de kernel específica dentro do repositório e a mapeia para aquela camada ou função.

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

	Especifique diferentes implementações de kernel para cada tipo de dispositivo.

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

	### Metadados do kernel

	Adicione um dicionário de metadados para controlar qual build do kernel é carregada.

	\| Opção \| Descrição \| Padrão \|
	\|---\|---\|---\|
	\| `version` \| Versão principal do repositório do kernel. `2` carrega o build mais recente no ramo `v2` do repositório. \| `1` \|
	\| `revision` \| Tag, branch ou commit exato para carregar em vez de uma versão. \| --- \|
	\| `trust_remote_code` \| Permite um repositório fora da organização confiável `kernels-community`. Carregar um kernel executa código desse repositório na sua máquina. \| `False` \|

	```py
	from transformers import KernelConfig

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

	Ramificações mais antigas de um repositório de kernel podem não ter builds para as suas versões de PyTorch e CUDA. Se um kernel falhar ao carregar, tente uma `version` mais recente antes de concluir que o seu hardware não é suportado.

	### Mapeamentos herdados

	Um `KernelConfig` herda o mapeamento padrão de kernels do Transformers para kernels do Hub, e as entradas em `kernel_mapping` substituem o padrão para as camadas e funções correspondentes. Defina `inherit_mapping=False` para usar apenas as entradas em `kernel_mapping`. Tudo o que você deixar de fora volta ao PyTorch padrão. Isso é útil ao fazer benchmark de um kernel específico ou testar uma implementação personalizada sem aplicar os outros padrões.

	A configuração abaixo mapeia a função `rotary_pos_emb` para um kernel RoPE e mantém todas as outras operações no PyTorch. O nome da função deve ser registrado pelo modelo.

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

	## Fusão de módulos

	Fusione módulos adjacentes em um único kernel passando uma tupla de pares `(class_name, path_pattern)` como chave em [KernelConfig](/docs/transformers/main/pt/main_classes/kernels#transformers.KernelConfig). Todos os padrões devem compartilhar o mesmo módulo pai. `*` corresponde a qualquer segmento único de caminho.

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

	O Fusion exige que o repositório do kernel forneça uma classe `KernelNameLayout` complementar junto com a classe `KernelName`. Consulte o guia [Writing kernels](./writing_kernels) para saber como implementar uma.

	## Kernels locais

	Carregue kernels a partir de caminhos de arquivo locais com `use_local_kernel=True` em [KernelConfig](/docs/transformers/main/pt/main_classes/kernels#transformers.KernelConfig). Isso carrega de um caminho do sistema de arquivos local em vez de um repositório do Hub.

	Kernels locais usam `/abs/path:layer_name` em vez do formato do Hub `org/repo: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
	)
	```

	## Desativar kernels globalmente

	Defina a variável de ambiente `USE_HUB_KERNELS` para desativar os kernels do Hub em todos os lugares sem alterar seu código.

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

	## Solução de problemas

	A integração do kernel depende do funcionamento conjunto do hardware, dos drivers e das versões dos pacotes. As seções a seguir abordam falhas comuns.

	### Problemas de instalação

	Erros de importação indicam que o pacote de kernels está ausente ou que sua versão está fora da faixa suportada pelo Transformers. Reinstale por meio do extra para obter uma versão compatível.

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

	### Falhas no carregamento de kernels

	Se kernels específicos falharem ao carregar, tente o seguinte.

	- Verifique a compatibilidade do seu hardware com os requisitos do kernel.
	- Verifique se seus drivers CUDA/ROCm/Metal estão atualizados.
	- Consulte a documentação do repositório do kernel para problemas conhecidos.

	### Compatibilidade de dispositivos

	Nem todos os kernels suportam todos os dispositivos. A biblioteca recorre às operações padrão do PyTorch quando um kernel não está disponível para o seu hardware. Consulte a documentação do repositório de kernels para verificar o suporte específico a cada dispositivo.

	## Recursos

	- repositório [Kernels](https://github.com/huggingface/kernels)
	- post no blog [Reforce seus modelos em 5 minutos com o Hugging Face Kernel Hub](https://huggingface.co/blog/hello-hf-kernels)
	- Descubra kernels na organização [kernels-community](https://huggingface.co/kernels-community)