# GPU AMD

As GPUs [AMD Instinct](https://www.amd.com/en/products/accelerators/instinct.html) (séries MI200, MI300, MI350) e [Radeon](https://www.amd.com/en/products/graphics/desktops/radeon.html) executam o PyTorch por meio do [ROCm](https://rocm.docs.amd.com/), a pilha de software de GPU da AMD. A build do PyTorch para ROCm utiliza o [HIP](https://rocm.docs.amd.com/projects/HIP/en/latest/what_is_hip.html), a interface de programação semelhante à CUDA da AMD, para expor as GPUs AMD através da API `torch.cuda`. A string de dispositivo é `cuda`, de modo que o código escrito para GPUs NVIDIA é executado sem alterações. O Transformers verifica `torch.version.hip` em tempo de execução para distinguir as duas e direciona os kernels de atenção e do Hub para builds específicos da AMD.

## Instalação

Instale o ROCm a partir da imagem Docker [huggingface/transformers-pytorch-amd-gpu](https://hub.docker.com/r/huggingface/transformers-pytorch-amd-gpu). Ela inclui a build do PyTorch para ROCm, uma build do `flash-attn` para GPUs MI300 e MI350 (`gfx942` e `gfx950`) e o Transformers instalado a partir do código-fonte.

```bash
docker run -it --device=/dev/kfd --device=/dev/dri --group-add video \
    --ipc=host --shm-size 16G \
    huggingface/transformers-pytorch-amd-gpu
```

`--device=/dev/kfd` e `--device=/dev/dri` expõem as GPUs AMD para o container. Instale [kernels](https://github.com/huggingface/kernels) dentro do container para [usar kernels do Hub](#use-hub-kernels).

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

Para instalar no seu próprio sistema, selecione ROCm no [seletor de instalação do PyTorch](https://pytorch.org/get-started/locally/) e verifique se a versão do wheel do ROCm é suportada pelo seu driver.

Verifique se o PyTorch detecta as GPUs AMD.

```py
import torch

print(torch.version.hip, torch.cuda.is_available(), torch.cuda.device_count())
print(torch.cuda.get_device_properties(0).gcnArchName)
```

```txt
7.2.53211 True 2
gfx942:sramecc+:xnack-
```

`torch.version.hip` é `None` em uma build do PyTorch com CUDA. `gcnArchName` relata a arquitetura da GPU, por exemplo, `gfx942` para MI300, `gfx950` para MI350 e `gfx1151` para Ryzen AI Max (Strix Halo).

## Selecionar e ordenar GPUs

Use `HIP_VISIBLE_DEVICES` para selecionar as GPUs e definir a ordem delas. Defina-o na mesma linha de comando da execução.

```cli
HIP_VISIBLE_DEVICES=0,2 torchrun trainer-program.py ...
```

O PyTorch enxerga apenas as GPUs 0 e 2, que são mapeadas para `cuda:0` e `cuda:1`. `ROCR_VISIBLE_DEVICES` filtra as GPUs em um nível mais baixo da pilha e é comumente definido por agendadores de cluster. Se ambos estiverem definidos, `HIP_VISIBLE_DEVICES` indexa as GPUs que permanecem visíveis após a filtragem por `ROCR_VISIBLE_DEVICES`.

Use `rocm-smi` ou `amd-smi` para listar as GPUs e seus índices.

## Executar inferência

[Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) e `device_map="auto"` detectam GPUs AMD e colocam o modelo em `cuda` automaticamente. Você também pode passar explicitamente `device_map="cuda"` ou `device_map="cuda:1"`.

```py
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B", dtype="bfloat16", device_map="auto"
)

inputs = tokenizer("The French Bread Law states", return_tensors="pt").to(model.device)
output = model.generate(**inputs, do_sample=False, max_new_tokens=50)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

```txt
The French Bread Law states that the French government must provide a certain amount of bread for the citizens of the country. The law is passed by the French parliament. The French parliament is a body of the French government. The French government is a body of the French state. The
```

## Escolha um backend de atenção

Defina o backend de atenção com `attn_implementation` ao carregar um modelo, e ele será aplicado tanto para inferência quanto para treinamento. O SDPA é o padrão e funciona em todas as GPUs AMD suportadas pelo PyTorch. Duas opções de FlashAttention também estão disponíveis.

| `attn_implementation` | Requisitos | Observações |
|---|---|---|
| `"sdpa"` | – | Padrão. |
| `"flash_attention_2"` | [flash-attn](https://github.com/Dao-AILab/flash-attention#amd-rocm-support) construído para ROCm, ou [kernels](https://github.com/huggingface/kernels) | Utiliza o pacote `flash-attn` quando ele está instalado. Seu backend padrão Composable Kernel (CK) suporta GPUs MI200, MI300, MI355 e RDNA 3/4, e a [imagem Docker](#installation) o inclui em MI300 ou MI350. Caso contrário, carrega [amd/aiter-flash-attn](https://huggingface.co/kernels/amd/aiter-flash-attn) do Hub. |
| `"flash_attention_3"` | [kernels](https://github.com/huggingface/kernels) | Carrega o [amd/aiter-flash-attn](https://huggingface.co/kernels/amd/aiter-flash-attn), um kernel FlashAttention pré-compilado da biblioteca [AITER](https://github.com/ROCm/aiter) da AMD. Não requer compilação. |

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    dtype="bfloat16",
    device_map="auto",
    attn_implementation="flash_attention_3",
)
```

No ROCm, `flash_attention_3` é resolvido para o kernel AITER e registra o seguinte. O Transformers atualmente usa o alias `kernels-community/aiter-flash-attn`, que redireciona para `amd/aiter-flash-attn`. A mensagem se refere ao pacote FlashAttention-3, portanto, ela aparece mesmo quando `flash_attention_2` está instalado.

```txt
You do not have `flash_attn` installed, using `kernels-community/aiter-flash-attn` from the `kernels` library instead!
```

Você também pode passar o repositório do kernel diretamente com `attn_implementation="kernels-community/aiter-flash-attn"`. Consulte [Backends de atenção](./attention_interface) para saber como os backends são selecionados.

## Use kernels do Hub

Defina `use_kernels=True` em [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para substituir camadas compatíveis por kernels otimizados do Hub. O Transformers detecta o ROCm e seleciona o build da AMD para cada camada, como [amd/aiter-rope](https://huggingface.co/kernels/amd/aiter-rope) para embeddings rotativos e [kernels-community/liger-kernels](https://huggingface.co/kernels/kernels-community/liger-kernels) para RMSNorm. Ao escrever um [KernelConfig](/docs/transformers/main/pt/main_classes/kernels#transformers.KernelConfig) personalizado, use `"rocm"` como a chave de dispositivo para mapeamentos específicos da AMD.

```py
from transformers import AutoModelForCausalLM

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

Os kernels do Hub geralmente aceleram o prefill e lotes grandes. Faça o benchmark da sua própria carga de trabalho antes de ativá-los para decodificação em lotes pequenos. Consulte [Carregando kernels](./kernel_doc/loading_kernels) para o mapeamento completo.

## Quantizar modelos

Os métodos compatíveis com ROCm incluem [AWQ](./quantization/awq), [GPT-QModel](./quantization/gptq), [compressed-tensors](./quantization/compressed_tensors) e o [Quark](./quantization/quark) da AMD. O [bitsandbytes](./quantization/bitsandbytes) tem suporte parcial. As GPUs MI300 e mais novas suportam FP8 nativamente. Consulte a [tabela de compatibilidade](./quantization/overview) para a lista completa.

## Treinar com o Trainer

[TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) detecta GPUs AMD e define o dispositivo como `cuda` automaticamente.

```py
from transformers import TrainingArguments

training_args = TrainingArguments(
    output_dir="./outputs",
    bf16=True,
)
```

### Treinamento distribuído

A build do PyTorch para ROCm inclui o RCCL, a implementação da API NCCL da AMD, de modo que o backend `nccl`, o `torchrun`, o [FSDP](./fsdp), o [DeepSpeed](./main_classes/deepspeed) e a API distribuída do Transformers funcionam sem alterações.

```py
import torch
from transformers import AutoModelForCausalLM, DistributedConfig

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-1.7B",
    dtype=torch.bfloat16,
    distributed_config=DistributedConfig(tp_size=2, fsdp_size=4),
)
```

```bash
torchrun --nproc_per_node=8 train.py
```

Consulte [Paralelismo de tensor](./tensor_parallelism), [Paralelismo de especialista](./expert_parallelism) e [FSDP](./fsdp) para as opções disponíveis.

## Limitações

- `CodeCarbonCallback` não é compatível com ROCm. Defina `report_to` em [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) para excluir `codecarbon`.
- Os métodos de quantização marcados com 🔴 para ROCm na [tabela de compatibilidade](./quantization/overview) dependem de kernels exclusivos de CUDA e falham ao carregar em GPUs AMD.

## Próximas etapas

- Leia a [documentação do ROCm](https://rocm.docs.amd.com/) para a configuração do driver e do PyTorch.
- Navegue pelos builds do ROCm nas organizações [AMD](https://huggingface.co/amd) e [kernels-community](https://huggingface.co/kernels-community).
- Leia [Carregamento de kernels](./kernel_doc/loading_kernels) para personalizar quais kernels substituem quais camadas.