故障排除

本指南旨在为您提供解决一些常见问题所需的工具和知识。如果本指南中列出的建议未能涵盖您的具体情况，请参阅寻求帮助部分，了解如何针对您的特定问题获取帮助。

使用 push_to_hub 上传数据集时遇到的问题

身份验证问题

如果您在通过 Dataset.push_to_hub() 和 Hugging Face 访问令牌在 🤗 Hub 上共享数据集时遇到身份验证问题：

• 请确保您用于身份验证的 Hugging Face 令牌具有 write 权限。
• 在 OSX 上，使用 hf auth login 之前，建议先清理钥匙串访问中所有 huggingface.co 的密码，并重新配置 git config --global credential.helper osxkeychain。

或者，您可以使用 SSH 密钥进行身份验证 - 更多信息请参阅 🤗 Hub 文档。

上传大型数据集时连接丢失

将大型数据集上传到 Hub 时，如果数据集分片数量过多，可能会在短时间内为 Hub 创建过多的提交，从而导致连接错误。 连接错误也可能由 Hub 内部使用的 AWS S3 存储桶返回的 HTTP 500 错误引起。 在这两种情况下，都可以重新运行 Dataset.push_to_hub() 以继续上传数据集。Hub 会检查已上传分片的 SHA，以避免重复上传。 我们正在努力使上传过程对瞬时错误更具鲁棒性，因此始终建议更新到最新的库版本。

请求过多

通过 push_to_hub() 上传大型数据集时可能会导致错误：

HfHubHTTPError: 429 Client Error: Too Many Requests for url: ...
You have exceeded our hourly quotas for action: commit. We invite you to retry later.

如果遇到此问题，需要将 datasets 库升级到最新版本（或至少 2.15.0）。

从自定义数据创建数据集时遇到的问题

从文件夹加载图像和音频

从文件夹创建数据集时，最常见的问题之一是文件结构不符合预期格式，或者元数据文件存在问题。

有关所需文件夹结构的详细信息，请参阅相应的文档页面：

• AudioFolder
• ImageFolder

Pickling 问题

使用 Dataset.from_generator 时遇到的 Pickling 问题

When creating a dataset, IterableDataset.from_generator() and Dataset.from_generator() expect a “picklable” generator function. This is required to hash the function using pickle to be able to cache the dataset on disk.

虽然生成器函数通常是“可 pickle 的”，但请注意生成器对象不是。因此，如果您使用的是生成器对象， 将会遇到如下所示的 TypeError：

TypeError: cannot pickle 'generator' object

当使用生成器函数时，如果该函数引用了无法“pickle”序列化的全局对象（例如数据库连接），也可能出现此错误。在这种情况下，您可以直接在生成器函数内部初始化该对象，以避免此错误。

Dataset.map 的 Pickling 问题

在 Dataset.map() 的多进程处理中也可能出现 Pickling 错误——对象会被序列化（pickled）以便传递给子进程。 如果转换中使用的对象无法被序列化，则无法缓存 map 的结果，从而导致抛出错误。

以下是解决此问题的一些方法：

• 解决 pickle 问题的通用方法是手动确保对象（或生成器类）可被 pickle 序列化，即实现 __getstate__ / __setstate__ / __reduce__。
• 您也可以在 map 中通过 new_fingerprint 参数提供自己的唯一哈希值。
• 你还可以通过调用 datasets.disable_caching() 来禁用缓存，但这样做并不推荐 - 了解更多关于缓存重要性的内容

寻求帮助

如果上述故障排除建议未能帮助您解决问题，请向社区和团队寻求帮助。

论坛

在 Hugging Face 论坛上寻求帮助 - 将您的问题发布在 🤗Datasets 分类 中。请务必撰写描述清晰的帖子，并提供有关您环境的相关背景信息以及可复现的代码，以最大程度地提高问题得到解决的可能性！

Discord

在 Discord 上发布问题，让团队和社区来帮助你。

🤗 Hub 上的社区讨论

如果您在 Hub 上创建自定义数据集时遇到问题，可以在数据集的 Community 标签页中发起讨论，并使用以下消息向 Hugging Face 团队寻求帮助：

# Dataset rewiew request for <Dataset name>

## Description

<brief description of the dataset>

## Files to review

- file1
- file2
- ...

cc @lhoestq @albertvillanova

GitHub 问题

最后，如果您怀疑发现了与库本身相关的 bug，请在 🤗 Datasets 的 GitHub 仓库上创建一个 Issue。请提供有关该 bug 的上下文信息：用于复现的代码片段、关于您的环境和数据的详细信息等，以帮助我们查明问题所在以及如何修复。