故障排除

有时会发生错误，但我们会为您提供帮助！本指南涵盖了一些我们遇到的最常见问题以及如何解决它们。但是，本指南并不旨在成为 🤗 Transformers 所有问题的全面集合。有关排除故障的更多帮助，请尝试：

在论坛上寻求帮助。您可以将问题发布到特定类别，例如初学者或 🤗 Transformers。请确保您撰写一个描述性的论坛帖子，并附带一些可重现的代码，以最大程度地提高解决问题的可能性！

如果问题与库有关，请在 🤗 Transformers 存储库上创建一个 Issue。请尽量提供尽可能多的信息来描述问题，以帮助我们更好地了解问题所在以及如何解决它。
如果您使用的是旧版本的 🤗 Transformers，请查看迁移指南，因为不同版本之间已引入一些重要更改。

有关故障排除和获取帮助的更多详细信息，请查看 Hugging Face 课程的第 8 章。

防火墙环境

云和内网设置中的某些 GPU 实例受到防火墙限制，无法进行外部连接，从而导致连接错误。当您的脚本尝试下载模型权重或数据集时，下载会挂起，然后超时并显示以下消息：

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，以避免连接错误。

CUDA 内存不足

在没有适当硬件的情况下，训练数百万参数的大型模型可能具有挑战性。当 GPU 内存不足时，您可能会遇到一个常见错误：

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)

以下是一些可以尝试减少内存使用的潜在解决方案：

在 TrainingArguments 中减小 per_device_train_batch_size 值。
尝试在 TrainingArguments 中使用 gradient_accumulation_steps 来有效增加总批次大小。

有关节省内存技术的更多详细信息，请参阅性能指南。

导入错误

您可能会遇到的另一个常见错误，特别是对于新发布的模型，是 ImportError。

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

对于这些类型的错误，请检查您是否安装了最新版本的 🤗 Transformers 以访问最新的模型。

pip install transformers --upgrade

CUDA 错误：设备端断言触发

有时您可能会遇到一个通用的 CUDA 错误，关于设备代码中的错误。

RuntimeError: CUDA error: device-side assert triggered

您应该尝试先在 CPU 上运行代码，以获得更具描述性的错误消息。在代码开头添加以下环境变量以切换到 CPU：

>>> import os

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

另一个选择是获取更好的 GPU traceback。在代码开头添加以下环境变量，以使 traceback 指向错误的源头：

>>> import os

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

填充标记未被屏蔽时的错误输出

在某些情况下，如果 input_ids 包含填充标记，输出 hidden_state 可能会不正确。为此，请加载模型和分词器。您可以访问模型的 pad_token_id 来查看其值。对于某些模型，pad_token_id 可能为 None，但您可以始终手动设置它。

>>> from transformers import AutoModelForSequenceClassification
>>> import torch

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

以下示例显示了未屏蔽填充标记时的输出：

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

这是第二个序列的实际输出：

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

大多数情况下，您应该向模型提供 attention_mask 来忽略填充标记，以避免这种静默错误。现在第二个序列的输出与其实际输出匹配：

默认情况下，分词器会根据您特定的分词器默认值自动为您创建一个 attention_mask。

>>> 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：无法为这种 AutoModel 识别配置类 XYZ

通常，我们建议使用 AutoModel 类来加载模型的预训练实例。此类可以根据配置自动推断并加载给定检查点的正确架构。如果您在从检查点加载模型时看到此 ValueError，则意味着 Auto 类未能找到给定检查点中的配置与您尝试加载的模型类型之间的映射。最常见的情况是，当检查点不支持给定任务时会发生这种情况。例如，在以下示例中，您会看到此错误，因为没有用于问答的 GPT2。

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

在 GitHub 上更新