# Dépannage

Des erreurs peuvent survenir, mais nous sommes là pour vous aider ! Ce guide aborde certains des problèmes les plus courants que nous avons rencontrés et comment vous pouvez les résoudre. Toutefois, ce guide ne prétend pas être une collection exhaustive de tous les problèmes de 🤗 Transformers. Pour obtenir plus d'aide dans le dépannage de votre problème, essayez :

1. Demander de l'aide sur les [forums](/static-proxy?url=https%3A%2F%2Fdiscuss.huggingface.co%2F). Il existe des catégories spécifiques auxquelles vous pouvez poster votre question, comme [Beginners](/static-proxy?url=https%3A%2F%2Fdiscuss.huggingface.co%2Fc%2Fbeginners%2F5) ou [🤗 Transformers](/static-proxy?url=https%3A%2F%2Fdiscuss.huggingface.co%2Fc%2Ftransformers%2F9). Veillez à rédiger un message de forum descriptif et à inclure du code reproductible afin de maximiser les chances que votre problème soit résolu !

2. Créez une [Issue](https://github.com/huggingface/transformers/issues/new/choose) sur le dépôt 🤗 Transformers s'il s'agit d'un bug lié à la bibliothèque. Essayez d'inclure un maximum d'informations décrivant le bug afin de nous aider à mieux comprendre ce qui ne va pas et à trouver une solution.

3. Consultez le guide [Migration](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md) si vous utilisez une ancienne version de 🤗 Transformers, car des modifications importantes ont été introduites entre les versions.

Pour plus de détails sur le dépannage et l'obtention d'aide, consultez le [chapitre 8](https://huggingface.co/course/chapter8/1?fw=pt) du cours Hugging Face.

## Environnements cloisonnés

Certain instances GPU dans les environnements cloud et intranet sont protégées par un pare-feu contre les connexions externes, ce qui provoque une erreur de connexion. Lorsque votre script tente de télécharger des poids de modèle ou des jeux de données, le téléchargement reste suspendu puis expire avec le message suivant :

```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.
```

Dans ce cas, vous devriez essayer d'exécuter 🤗 Transformers en [mode hors ligne](installation#offline-mode) pour éviter l'erreur de connexion.

## CUDA hors mémoire

L’entraînement de grands modèles comptant des millions de paramètres peut s’avérer difficile sans le matériel approprié. Une erreur courante que vous pouvez rencontrer lorsque la mémoire de la GPU est épuisée est la suivante :

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

Voici quelques solutions potentielles que vous pouvez essayer pour réduire l'utilisation de la mémoire :

- Réduisez la valeur de [per_device_train_batch_size](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments.per_device_train_batch_size) dans [TrainingArguments](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments).
- Essayez d’utiliser [gradient_accumulation_steps](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments.gradient_accumulation_steps) dans [TrainingArguments](/docs/transformers/v5.23.0/fr/main_classes/trainer#transformers.TrainingArguments) pour augmenter efficacement la taille globale du lot.

Reportez-vous à la [vue d’ensemble de l’optimisation](optimization_overview) pour plus de détails sur les techniques d’économie de mémoire.

## ImportError

Une autre erreur courante que vous pouvez rencontrer, en particulier s'il s'agit d'un modèle récemment publié, est `ImportError` :

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

Pour ces types d’erreurs, vérifiez que vous avez bien installé la dernière version de 🤗 Transformers afin d’accéder aux modèles les plus récents :

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

## Erreur CUDA : une assertion côté appareil a été déclenchée

Il peut arriver que vous rencontriez une erreur CUDA générique signalant une erreur dans le code de l’appareil.

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

Vous devriez d’abord essayer d’exécuter le code sur un CPU afin d’obtenir un message d’erreur plus descriptif. Ajoutez la variable d’environnement suivante au début de votre code pour basculer sur un CPU :

```py
>>> import os

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

Une autre option consiste à obtenir une meilleure trace d’erreur depuis le GPU. Ajoutez la variable d’environnement suivante au début de votre code pour que la trace d’erreur pointe vers l’origine de l’erreur :

```py
>>> import os

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

## Sortie incorrecte lorsque les jetons de bourrage ne sont pas masqués

Dans certains cas, la sortie `hidden_state` peut être incorrecte si les `input_ids` incluent des jetons de bourrage. Pour le démontrer, chargez un modèle et un tokeniseur. Vous pouvez accéder au `pad_token_id` d'un modèle pour voir sa valeur. Le `pad_token_id` peut être `None` pour certains modèles, mais vous pouvez toujours le définir manuellement.

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

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

L'exemple suivant montre la sortie sans masquage des jetons de bourrage :

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

Voici la sortie réelle de la deuxième séquence :

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

La plupart du temps, vous devez fournir un `attention_mask` à votre modèle afin d’ignorer les jetons de bourrage et d’éviter cette erreur silencieuse. La sortie de la deuxième séquence correspond désormais à sa sortie réelle :

Par défaut, le tokenizer crée un `attention_mask` pour vous en fonction des valeurs par défaut de votre tokenizer spécifique.

```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 ne crée pas automatiquement un `attention_mask` pour masquer un jeton de bourrage s'il est fourni, car :

- Certains modèles ne disposent pas de jeton de bourrage.
- Pour certains cas d'utilisation, les utilisateurs souhaitent qu'un modèle prenne en compte un jeton de bourrage.

## ValueError: Classe de configuration XYZ non reconnue pour ce type d'AutoModel

En général, nous recommandons d'utiliser la classe [AutoModel](/docs/transformers/v5.23.0/fr/model_doc/auto#transformers.AutoModel) pour charger des instances préentraînées de modèles. Cette classe peut inférer et charger automatiquement l'architecture correcte à partir d'un point de contrôle donné, en se basant sur la configuration. Si vous voyez cette `ValueError` lors du chargement d'un modèle à partir d'un point de contrôle, cela signifie que la classe Auto n'a pas pu trouver de correspondance entre la configuration du point de contrôle donné et le type de modèle que vous essayez de charger. Le plus souvent, cela se produit lorsqu'un point de contrôle ne prend pas en charge une tâche donnée. Par exemple, vous verrez cette erreur dans l'exemple suivant car il n'existe pas de GPT2 pour la réponse à des questions :

```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, ...
```

