# Устранение неполадок

Иногда возникают ошибки, но мы готовы помочь! В этом руководстве описаны некоторые из самых распространённых проблем, с которыми мы сталкивались, и способы их решения. Однако это руководство не является исчерпывающим списком всех проблем с 🤗 Transformers. Для дополнительной помощи в диагностике вашей проблемы попробуйте:

1. Обращение за помощью на [форумах](/static-proxy?url=https%3A%2F%2Fdiscuss.huggingface.co%2F). Существуют отдельные категории, в которые можно опубликовать свой вопрос, например [Beginners](/static-proxy?url=https%3A%2F%2Fdiscuss.huggingface.co%2Fc%2Fbeginners%2F5) или [🤗 Transformers](/static-proxy?url=https%3A%2F%2Fdiscuss.huggingface.co%2Fc%2Ftransformers%2F9). Убедитесь, что вы написали качественный описательный пост с воспроизводимым кодом, чтобы максимально повысить шансы на решение вашей проблемы!

2. Создайте [Issue](https://github.com/huggingface/transformers/issues/new/choose) в репозитории 🤗 Transformers, если это баг, связанный с библиотекой. Постарайтесь включить как можно больше информации, описывающей проблему, чтобы помочь нам лучше понять, что пошло не так, и как это исправить.

3. Если вы используете более старую версию 🤗 Transformers, обратитесь к [руководству по миграции](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md), так как между версиями были внесены важные изменения.

Для получения дополнительной информации об устранении неполадок и получении помощи обратитесь к [Главе 8](https://huggingface.co/course/chapter8/1?fw=pt) курса Hugging Face.

## Окружения с файрволом

Некоторые GPU-инстансы в облачных и корпоративных сетях изолированы от внешних подключений, что приводит к ошибке соединения. Когда ваш скрипт пытается скачать веса модели или датасеты, загрузка зависнет, а затем завершится по таймауту с следующим сообщением:

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

В этом случае попробуйте запустить 🤗 Transformers в [офлайн-режиме](installation#offline-mode), чтобы избежать ошибки подключения.

## Недостаточно памяти CUDA

Обучение больших моделей с миллионами параметров может быть сложным без соответствующего оборудования. Типичная ошибка, с которой вы можете столкнуться при нехватке памяти на GPU:

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

Вот несколько возможных решений, которые можно попробовать для снижения потребления памяти:

- Уменьшите значение [per_device_train_batch_size](/docs/transformers/v5.23.0/ru/main_classes/trainer#transformers.TrainingArguments.per_device_train_batch_size) в [TrainingArguments](/docs/transformers/v5.23.0/ru/main_classes/trainer#transformers.TrainingArguments).
- Попробуйте использовать [gradient_accumulation_steps](/docs/transformers/v5.23.0/ru/main_classes/trainer#transformers.TrainingArguments.gradient_accumulation_steps) в [TrainingArguments](/docs/transformers/v5.23.0/ru/main_classes/trainer#transformers.TrainingArguments), чтобы эффективно увеличить общий размер батча.

См. раздел [обзор оптимизации](optimization_overview) для получения дополнительной информации о техниках экономии памяти.

## ImportError

Другая распространённая ошибка, с которой вы можете столкнуться, особенно если модель только что вышла, — это `ImportError`:

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

Для этих типов ошибок убедитесь, что у вас установлена последняя версия 🤗 Transformers, чтобы иметь доступ к самым новым моделям:

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

## CUDA error: device-side assert triggered

Иногда вы можете столкнуться с общей ошибкой CUDA, связанной с ошибкой в коде устройства.

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

Сначала попробуйте выполнить код на CPU, чтобы получить более подробное сообщение об ошибке. Добавьте следующую переменную окружения в начало кода, чтобы переключиться на CPU:

```py
>>> import os

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

Другой вариант — получить более подробный traceback от GPU. Добавьте следующую переменную окружения в начало кода, чтобы traceback указывал на источник ошибки:

```py
>>> import os

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

## Некорректный вывод, если токены отступов не маскируются

В некоторых случаях выходной параметр `hidden_state` может быть неверным, если `input_ids` содержат токены отступов. Для демонстрации загрузите модель и токенизатор. Вы можете обратиться к `pad_token_id` модели, чтобы увидеть его значение. Для некоторых моделей `pad_token_id` может быть `None`, но вы всегда можете задать его вручную.

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

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

В следующем примере показан вывод без маскирования токенов отступов:

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

Вот фактический вывод второй последовательности:

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

В большинстве случаев вам следует передавать в модель `attention_mask`, чтобы игнорировать токены отступов и избежать этой скрытой ошибки. Теперь выход второго совпадает с его фактическим результатом:

По умолчанию токенизатор создаёт для вас `attention_mask` на основе значений по умолчанию конкретного токенизатора.

```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 не создаёт автоматически `attention_mask` для маскирования токена отступов, если он передан, потому что:

- Некоторые модели не имеют токена отступов.
- Для некоторых сценариев использования пользователям требуется, чтобы модель обращала внимание на токен отступов.

## ValueError: Нераспознанный класс конфигурации XYZ для этого типа AutoModel

Как правило, мы рекомендуем использовать класс [AutoModel](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoModel) для загрузки предобученных экземпляров моделей. Этот класс может автоматически определять и загружать правильную архитектуру из заданного контрольного пункта на основе конфигурации. Если при загрузке модели из контрольного пункта вы видите `ValueError`, это означает, что Auto-класс не смог найти соответствие между конфигурацией в данном контрольном пункте и типом модели, который вы пытаетесь загрузить. Чаще всего это происходит, когда контрольный пункт не поддерживает данную задачу. Например, в следующем примере вы увидите эту ошибку, так как для задачи question answering не существует GPT2:

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

