# Intel Gaudi

Os aceleradores Intel Gaudi executam o PyTorch no stack [Intel Gaudi](https://docs.habana.ai/en/latest/index.html), com a string de dispositivo `hpu`. O Gaudi executa o PyTorch em modo eager por padrão. O modo eager executa cada operação assim que ela é chamada, da mesma forma que o PyTorch é executado em uma CPU ou GPU, de modo que os modelos do Transformers rodam no Gaudi sem alterações específicas para o Gaudi. Para capturar o modelo em um grafo, [compile-o](#compile-the-model) com `torch.compile`.

## Instalação

Instale o software Intel Gaudi e seu pacote PyTorch (`habana-torch-plugin`, importado como `habana_frameworks`) com o [guia de instalação do Intel Gaudi](https://docs.habana.ai/en/latest/Installation_Guide/index.html), além do [Accelerate](https://huggingface.co/docs/accelerate/index) 1.5.0 ou posterior.

O Transformers usa tensores int64 para IDs de tokens, portanto, habilite o suporte a int64 no Gaudi. O CI do Gaudi do Transformers é executado com a mesma configuração.

```bash
export PT_ENABLE_INT64_SUPPORT=1
```

Verifique se o Transformers consegue ver o dispositivo.

```py
from transformers import is_torch_hpu_available

print(is_torch_hpu_available())
```

Ele imprime `True` quando o Gaudi está pronto para uso e `False` com o Accelerate anterior à versão 1.5.0, mesmo que um dispositivo Gaudi esteja presente.

## Selecione dispositivos

Escolha quais dispositivos Gaudi um contêiner Docker pode usar ao iniciá-lo. Defina `HABANA_VISIBLE_MODULES` para IDs de módulo, que permanecem os mesmos após reinicializações e reinstalações de drivers, ou `HABANA_VISIBLE_DEVICES` para índices de dispositivo, que podem mudar. Se você não definir nenhum dos dois, o PyTorch usará qualquer dispositivo Gaudi disponível no servidor.

```bash
docker run --runtime=habana -e HABANA_VISIBLE_MODULES=0,1,2,3 ...
```

Execute `hl-smi -Q index,module_id -f csv` para mapear os índices de dispositivos para os IDs de módulo. Para uma carga de trabalho distribuída em parte de um servidor, a Intel suporta apenas grupos de 2 e 4 dispositivos. Consulte [Vários Dockers, cada um com uma única carga de trabalho](https://docs.habana.ai/en/latest/Orchestration/Multiple_Tenants_on_HPU/Multiple_Dockers_each_with_Single_Workload.html) para as combinações de IDs de módulo suportadas.

## Executar inferência

Passe `device_map="hpu"` para [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained). O [pipeline()](/docs/transformers/main/pt/main_classes/pipelines#transformers.pipeline) seleciona o Gaudi automaticamente quando você não passa `device`.

```py
from transformers import AutoModelForCausalLM, AutoTokenizer

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

inputs = tokenizer("Intel Gaudi is", return_tensors="pt").to(model.device)
output = model.generate(**inputs, max_new_tokens=50, do_sample=False)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

## Quantizar modelos

[bitsandbytes](./quantization/bitsandbytes) quantiza modelos para 4 ou 8 bits no Gaudi 2 e no Gaudi 3. Quando você não passa `device_map`, ele coloca o modelo no dispositivo Gaudi atual.

Para ajustar um modelo que não cabe em um único dispositivo, carregue-o em 4 bits com bitsandbytes e treine adaptadores LoRA com [PEFT](./peft).

## Treinar com o Trainer

[TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) detecta o Gaudi e define o dispositivo como `hpu`, de modo que o `Trainer` treina nele sem nenhuma configuração de dispositivo. Todas as gerações do Gaudi suportam bf16.

```py
from transformers import TrainingArguments

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

Ele imprime um dispositivo `hpu` quando o `Trainer` treinará no Gaudi.

## Compilar o modelo

O Transformers encapsula `torch.compile` no Gaudi, de modo que qualquer chamada com um backend diferente de `hpu_backend` ou `eager`, incluindo um decorador `@torch.compile` no código de modelagem, alterna para `hpu_backend` e registra um aviso. O encapsulamento se aplica a todas as chamadas de `torch.compile`, seja para inferência ou treinamento.

Para compilar um modelo para treinamento, defina `torch_compile=True` em [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments), o que define `torch_compile_backend` como `"hpu_backend"`.

```py
from transformers import TrainingArguments

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

### Treinamento distribuído

O treinamento distribuído usa o backend coletivo [HCCL](https://docs.habana.ai/en/latest/API_Reference_Guides/HCCL_APIs/index.html). O Transformers o seleciona no Gaudi, e você também pode defini-lo explicitamente com `ddp_backend="hccl"`.

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

Inicie um processo por dispositivo Gaudi com `torchrun` ou `accelerate launch`, após [selecionar os dispositivos](#select-devices). O `accelerate launch` define o número de processos como o número de dispositivos Gaudi quando você não passa `--num_processes`.

```bash
accelerate launch train.py
```

## Próximas etapas

- Consulte a [documentação do Intel Gaudi](https://docs.habana.ai/en/latest/index.html) para obter detalhes sobre o hardware, a pilha de software e a [arquitetura do Gaudi](https://docs.habana.ai/en/latest/Gaudi_Overview/Gaudi_Architecture.html).
- Experimente o [Optimum for Intel Gaudi](https://huggingface.co/docs/optimum-habana/index) para implementações de modelos otimizadas para Gaudi, voltadas para treinamento e inferência.