# Solução de problemas

Às vezes, erros ocorrem, mas estamos aqui para ajudar! Este guia aborda alguns dos problemas mais comuns que já vimos e como você pode resolvê-los. No entanto, este guia não pretende ser uma coleção abrangente de todos os problemas do 🤗 Transformers. Para mais ajuda na solução do seu problema, tente:

1. Pedir ajuda nos [fóruns](https://discuss.huggingface.co/). Existem categorias específicas para postar sua pergunta, como [Beginners](https://discuss.huggingface.co/c/beginners/5) ou [🤗 Transformers](https://discuss.huggingface.co/c/transformers/9). Certifique-se de escrever um post de fórum bem descritivo, com algum código reproduzível, para maximizar as chances de seu problema ser resolvido!

2. Crie um [Issue](https://github.com/huggingface/transformers/issues/new/choose) no repositório 🤗 Transformers se for um bug relacionado à biblioteca. Tente incluir o máximo de informações possível descrevendo o bug para nos ajudar a entender melhor o que está errado e como podemos corrigi-lo.

3. Consulte o guia de [Migração](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md) se você usa uma versão mais antiga do 🤗 Transformers, pois algumas mudanças importantes foram introduzidas entre as versões.

Para mais detalhes sobre solução de problemas e obtenção de ajuda, consulte o [Capítulo 8](https://huggingface.co/course/chapter8/1?fw=pt) do curso da Hugging Face.

## Ambientes com firewall

Algumas instâncias de GPU em configurações de nuvem e intranet são protegidas por firewall contra conexões externas, o que resulta em um erro de conexão. Quando seu script tenta baixar pesos de modelo ou conjuntos de dados, o download fica pendurado e, em seguida, expira com a seguinte mensagem:

```text
ValueError: Connection error, and we cannot find the requested files in the cached path.
Please try again or make sure your Internet connection is on.
```

Nesse caso, você deve tentar executar o 🤗 Transformers em [modo offline](installation#offline-mode) para evitar o erro de conexão.

## CUDA sem memória suficiente

Treinar modelos grandes com milhões de parâmetros pode ser desafiador sem o hardware adequado. Um erro comum que você pode encontrar quando a GPU fica sem memória é:

```text
CUDA out of memory. Tried to allocate 256.00 MiB (GPU 0; 11.17 GiB total capacity; 9.70 GiB already allocated; 179.81 MiB free; 9.85 GiB reserved in total by PyTorch)
```

Aqui estão algumas soluções potenciais que você pode tentar para reduzir o uso de memória:

- Reduza o valor de [per_device_train_batch_size](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments.per_device_train_batch_size) em [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments).
- Tente usar [gradient_accumulation_steps](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments.gradient_accumulation_steps) em [TrainingArguments](/docs/transformers/main/pt/main_classes/trainer#transformers.TrainingArguments) para aumentar efetivamente o tamanho total do lote.

Consulte a [visão geral da otimização](optimization_overview) para mais detalhes sobre técnicas de economia de memória.

## ImportError

Outro erro comum que você pode encontrar, especialmente se for um modelo recém-lançado, é `ImportError`:

```text
ImportError: cannot import name 'ImageGPTImageProcessor' from 'transformers' (unknown location)
```

Para esses tipos de erro, verifique se você tem a versão mais recente do 🤗 Transformers instalada para acessar os modelos mais recentes:

```bash
pip install transformers --upgrade
```

## Erro CUDA: assert do lado do dispositivo acionado

Às vezes, você pode se deparar com um erro genérico de CUDA relacionado a um erro no código do dispositivo.

```text
RuntimeError: CUDA error: device-side assert triggered
```

Você deve tentar executar o código em uma CPU primeiro para obter uma mensagem de erro mais descritiva. Adicione a seguinte variável de ambiente no início do seu código para alternar para uma CPU:

```py
>>> import os

>>> os.environ["CUDA_VISIBLE_DEVICES"] = ""
```

Outra opção é obter um traceback mais detalhado da GPU. Adicione a seguinte variável de ambiente no início do seu código para que o traceback aponte para a origem do erro:

```py
>>> import os

>>> os.environ["CUDA_LAUNCH_BLOCKING"] = "1"
```

## Saída incorreta quando os tokens de preenchimento não são mascarados

Em alguns casos, a saída `hidden_state` pode estar incorreta se os `input_ids` incluírem tokens de padding. Para demonstrar, carregue um modelo e um tokenizer. Você pode acessar o `pad_token_id` de um modelo para ver seu valor. O `pad_token_id` pode ser `None` para alguns modelos, mas você sempre pode defini-lo manualmente.

```py
>>> from transformers import AutoModelForSequenceClassification
>>> import torch

>>> model = AutoModelForSequenceClassification.from_pretrained("google-bert/bert-base-uncased")
>>> model.config.pad_token_id
0
```

O exemplo a seguir mostra a saída sem mascarar os tokens de preenchimento:

```py
>>> input_ids = torch.tensor([[7592, 2057, 2097, 2393, 9611, 2115], [7592, 0, 0, 0, 0, 0]])
>>> output = model(input_ids)
>>> print(output.logits)
tensor([[ 0.0082, -0.2307],
        [ 0.1317, -0.1683]], grad_fn=<AddmmBackward0>)
```

Aqui está a saída real da segunda sequência:

```py
>>> input_ids = torch.tensor([[7592]])
>>> output = model(input_ids)
>>> print(output.logits)
tensor([[-0.1008, -0.4061]], grad_fn=<AddmmBackward0>)
```

Na maioria dos casos, você deve fornecer um `attention_mask` ao seu modelo para ignorar os tokens de preenchimento e evitar esse erro silencioso. Agora, a saída da segunda sequência corresponde à sua saída real:

Por padrão, o tokenizer cria um `attention_mask` para você com base nos padrões específicos do seu tokenizer.

```py
>>> attention_mask = torch.tensor([[1, 1, 1, 1, 1, 1], [1, 0, 0, 0, 0, 0]])
>>> output = model(input_ids, attention_mask=attention_mask)
>>> print(output.logits)
tensor([[ 0.0082, -0.2307],
        [-0.1008, -0.4061]], grad_fn=<AddmmBackward0>)
```

🤗 Transformers não cria automaticamente uma `attention_mask` para mascarar um token de preenchimento, caso ele seja fornecido, porque:

- Alguns modelos não possuem um token de preenchimento.
- Para alguns casos de uso, os usuários desejam que o modelo preste atenção a um token de preenchimento.

## ValueError: Classe de configuração XYZ não reconhecida para este tipo de AutoModel

Em geral, recomendamos usar a classe [AutoModel](/docs/transformers/main/pt/model_doc/auto#transformers.AutoModel) para carregar instâncias pré-treinadas de modelos. Essa classe pode inferir e carregar automaticamente a arquitetura correta de um checkpoint específico com base na configuração. Se você vir esse `ValueError` ao carregar um modelo de um checkpoint, isso significa que a classe Auto não conseguiu encontrar um mapeamento da configuração no checkpoint fornecido para o tipo de modelo que você está tentando carregar. Mais comumente, isso acontece quando um checkpoint não suporta uma tarefa específica. Por exemplo, você verá esse erro no exemplo a seguir porque não existe um GPT2 para question answering:

```py
>>> from transformers import AutoProcessor, AutoModelForQuestionAnswering

>>> processor = AutoProcessor.from_pretrained("openai-community/gpt2-medium")
>>> model = AutoModelForQuestionAnswering.from_pretrained("openai-community/gpt2-medium")
ValueError: Unrecognized configuration class <class 'transformers.models.gpt2.configuration_gpt2.GPT2Config'> for this kind of AutoModel: AutoModelForQuestionAnswering.
Model type should be one of AlbertConfig, BartConfig, BertConfig, BigBirdConfig, BigBirdPegasusConfig, BloomConfig, ...
```