仓库限制和建议
在仓库中处理大量数据时，需要注意一些限制。由于数据流式传输需要时间，导致上传/推送在流程结束时失败或遇到体验下降（无论是在 hf.co 上还是在本地工作时），都可能非常令人恼火。
建议
我们收集了一份关于如何构建仓库的提示和建议列表。如果您正在寻找更多实用技巧，请查看 此指南，了解如何使用 Python 库上传大量数据。
| 特征 | 推荐 | 提示 |
|---|---|---|
| 仓库大小 | - | 对于大型仓库（TB 级数据），请联系我们 |
| 每个仓库的文件数 | <100k | 将数据合并到更少的文件中 |
| 每个文件夹的条目数 | <10k | 在仓库中使用子目录 |
| 文件大小 | <20GB | 将数据拆分为分块文件 |
| 提交大小 | <100 个文件* | 将文件分成多个提交上传 |
| 每个仓库的提交数 | - | 每个提交上传多个文件和/或压缩历史记录 |
* 直接使用 git CLI 时不相关
请阅读下一节以更好地了解这些限制以及如何处理它们。
解释
当我们说“大型上传”时，我们在谈论什么，以及它们相关的限制是什么？大型上传可以非常多样化，从包含几个大型文件的仓库（例如模型权重）到包含数千个小文件的仓库（例如图像数据集）。
在后台，Hub 使用 Git 对数据进行版本控制，这会对您在仓库中可以执行的操作产生结构性影响。如果您的仓库超过了上一节中提到的某些数字，**我们强烈建议您查看 git-sizer**，它提供了关于会影响您体验的不同因素的非常详细的文档。以下是需要考虑的因素的简要说明
- 仓库大小：您计划上传的数据的总大小。我们通常支持最多 300GB 的仓库。如果您想上传超过 300 GB（甚至 TB）的数据，则需要请求我们授予更多存储空间。为此，请发送包含项目详细信息的电子邮件至 [email protected]。
- 文件数量:
- 为了获得最佳体验，我们建议将文件总数保持在 100k 以下。如果您有更多文件，请尝试将数据合并到更少的文件中。例如，json 文件可以合并到单个 jsonl 文件中，或者大型数据集可以导出为 Parquet 文件或 WebDataset 格式。
- 每个文件夹的文件数不能超过每个文件夹 10k 个文件。一个简单的解决方案是创建一个使用子目录的仓库结构。例如，一个从
000/到999/的 1k 个文件夹的仓库，每个文件夹最多包含 1000 个文件，已经足够了。
- 文件大小：在上传大型文件（例如模型权重）的情况下，我们强烈建议将其拆分为大约 20GB 的块。这样做有几个原因
- 对于您和其他人来说，上传和下载较小的文件都更容易。在流式传输数据时，连接问题总是可能发生的，并且较小的文件可以避免在发生错误时从头开始恢复。
- 使用 CloudFront 向用户提供文件。根据我们的经验，此服务不会缓存大型文件，导致下载速度变慢。在任何情况下，单个 LFS 文件都不能大于 50GB。即 50GB 是单个文件大小的硬性限制。
- 提交数量：仓库历史记录的提交总数没有硬性限制。但是，根据我们的经验，在数千次提交后，Hub 上的用户体验开始下降。我们一直在努力改进服务，但必须始终记住，git 仓库并非旨在用作具有大量写入操作的数据库。如果您的仓库历史记录变得非常大，始终可以通过使用
huggingface_hub的super_squash_history将所有提交压缩来获得新的开始。请注意，这是一个不可逆的操作。 - 每个提交的操作数量：同样，这里没有硬性限制。当提交上传到 Hub 时，服务器会检查每个 git 操作（添加或删除）。当一次提交一百个 LFS 文件时，会单独检查每个文件以确保已正确上传。通过 HTTP 推送数据时，请求上设置了 60 秒的超时，这意味着如果该过程花费的时间超过此时间，则会引发错误。但是，可能会发生（在极少数情况下）即使客户端引发了超时，服务器端的过程仍在继续。这可以通过在 Hub 上浏览仓库手动检查。为了防止此超时，我们建议每个提交添加大约 50-100 个文件。
在 Hub 上共享大型数据集
Hugging Face 支持机器学习生态系统的一个关键方法是在 Hub 上托管数据集，包括非常大的数据集。但是，如果您的数据集大于 300GB，则需要请求我们授予更多存储空间。
在这种情况下，为了确保我们能够有效地支持开源生态系统，我们要求您通过 [email protected] 告知我们。
当您与我们联系时，请告知我们
- 数据集是什么，谁/什么可能对其有用？
- 数据集的大小。
- 您计划用于共享数据集的格式。
为了在 Hub 上托管大型数据集，我们要求您的数据集满足以下条件
- 数据集卡片：我们希望确保您的数据集可以被社区有效地使用，而实现这一目标的关键方法之一就是通过数据集卡片。此 指南 提供了有关如何编写数据集卡片的概述。
- 您共享数据集是为了使社区能够重复使用。如果您计划上传一个您预计不会被进一步重复使用的数据集，则其他平台可能更合适。
- 您必须遵守上面列出的仓库限制。
- 使用与 Hugging Face 生态系统良好集成的文件格式。我们对 Parquet 和 WebDataset 格式有良好的支持，它们通常是有效共享大型数据集的良好选择。这也将确保数据集查看器适用于您的数据集。
- 使用数据集时，请避免使用自定义加载脚本。根据我们的经验，需要自定义代码才能使用的数据集往往最终使用次数有限。
如果您由于数据类型或工作领域的原因难以满足这些要求，请与我们联系。
< > 在 GitHub 上更新