Transformers 常见问题与排错指南摘要

用途

这份文档汇总了 🤗 Transformers 使用中较常见的错误及初步处理方向，并提供获取进一步帮助的渠道（论坛、仓库 Issue、迁移指南和课程章节）。

常见问题与处理思路

• 防火墙或内网环境：脚本下载权重或数据集时可能连接失败并超时，报错提示无法在缓存路径找到文件。文档建议改用离线模式避免连接错误。
• CUDA 显存不足：可通过减小 per_device_train_batch_size，或使用梯度累积来等效增大批次；文档另指向优化概览了解更多省显存方法。
• ImportError：尤其是新发布模型相关导入失败时，文档建议确认已升级到最新版 Transformers。
• CUDA device-side assert triggered：文档建议先在 CPU 上运行以获取更明确的错误，或将 CUDA_VISIBLE_DEVICES 设为空；也可设置 CUDA_LAUNCH_BLOCKING=1 获得更准确的 GPU 回溯。
• padding token 未掩码导致输出异常：示例显示包含 padding 的序列若不加 attention_mask，其输出会偏离真实结果；文档说明 Transformers 不会自动为给定 padding token 创建掩码，因为部分模型无 padding token，且某些场景用户希望模型关注 padding。
• AutoModel 报“Unrecognized configuration class”：通常是检查点不支持目标任务，例如 GPT2 没有问答模型类；需选择与任务匹配的 AutoModel 类型。

限制与待核实事项

以上内容来自文档说明，未在本地环境复现验证；具体报错表现和可用解决方式可能随版本与硬件环境变化。