# 故障排除

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

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

### 身份验证问题

如果您在通过 [Dataset.push_to_hub()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset.push_to_hub) 和 Hugging Face 访问令牌在 🤗 Hub 上共享数据集时遇到身份验证问题：

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

或者，您可以使用 SSH 密钥进行身份验证 - 更多信息请参阅 [🤗 Hub 文档](https://huggingface.co/docs/hub/security-git-ssh)。
 
### 上传大型数据集时连接丢失 

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

### `Too Many Requests`

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

```bash
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](https://huggingface.co/docs/datasets/audio_dataset#audiofolder)
* [ImageFolder](https://huggingface.co/docs/datasets/image_dataset#imagefolder)

### Pickling 问题 

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

When creating a dataset, [IterableDataset.from_generator()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.IterableDataset.from_generator) and [Dataset.from_generator()](/docs/datasets/v5.2.0/zh/package_reference/main_classes#datasets.Dataset.from_generator) expect a "picklable" generator function. This is required to hash the function using [`pickle`](https://docs.python.org/3/library/pickle.html) to be able to cache the dataset on disk.

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

```bash
TypeError: cannot pickle 'generator' object
```

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

#### `Dataset.map` 的序列化问题

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

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

## 寻求帮助

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

### 论坛 

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

### Discord

在 [Discord](http://hf.co/join/discord) 上发布问题，让团队和社区来帮助你。

### 🤗 Hub 上的社区讨论

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

```text
# Dataset rewiew request for <Dataset name>

## Description

<brief description of the dataset>

## Files to review

- file1
- file2
- ...

cc @lhoestq @albertvillanova
```

### GitHub 问题

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