# 存储限制

在 Hugging Face，我们致力于为 AI 社区提供大量**面向公共仓库的免费存储空间**，如有需要，还可以选择购买更多存储空间。对于**私有仓库**，我们也会对其存储空间进行计费，但提供免费额度（详见下表）。

> [!TIP]
> Hub 上的所有类型仓库（模型、数据集、存储桶等）均适用存储限制和策略。

我们持续[优化基础设施](https://huggingface.co/blog/xethub-joins-hf)，以[扩展存储](https://x.com/julien_c/status/1821540661973160339)，满足未来几年人工智能和机器学习领域增长的需求。

我们已采取相应措施，以防止滥用免费公共存储。总体而言，我们要求用户和组织确保其上传的大型模型或数据集**尽可能对社区有用**（例如，以点赞数或下载数来衡量）。请升级至付费的组织或用户（PRO）账户，以解锁更高的使用限额。

## 存储计划

| 账户类型          | 公共存储                                                      | 私有存储              |
| ------------------------ | ------------------------------------------------------------------- | ---------------------------- |
| 免费用户或组织         | 尽力而为\*                                                        | 100GB                        |
| PRO                      | 最多包含 10TB\* + [附加组件](#public-storage-add-on) ✅ 为具有影响力的工作提供授权†  | 1TB + 按量付费          |
| 团队组织       | 12TB 基础 + 每个席位 1TB + [附加组件](#public-storage-add-on) ✅      | 每席位 1TB + 按量付费 |
| 企业组织 | 200TB 基础容量 + 每个席位 1TB + [附加容量](#public-storage-add-on) 🏆 大型合同最高可达 1,000TB | 每席位 1TB + 按量付费 |

💡 [团队或企业组织](https://huggingface.co/enterprise)的订阅中，每个席位包含 1TB 的私有存储空间：例如，如果您的组织有 40 名成员，则您拥有 40TB 的包含私有存储空间。

\* 我们致力于继续为 AI 社区提供慷慨的公共仓库免费存储空间。在最初的几个 GB 之外，请负责任地使用此资源，上传对其他用户具有真正价值的内容。如果您需要大量存储空间，则需要升级到 [PRO、Team 或 Enterprise](https://huggingface.co/pricing)。

† 在某些情况下，对于具有重大影响力且付费方案确实无法满足存储需求的开源项目，我们可提供额外的存储配额。请提供社区影响力证明（如点赞数、下载量、引用次数）与我们联系。

### 公共存储附加组件

使用付费套餐（PRO、Team 或 Enterprise）的用户可以订阅 **Public Storage add-on**，在套餐基础限额之上获得额外的公共存储空间。

| 存储附加组件 | 价格          | 每 TB           |
| -------------- | -------------- | ---------------- |
| 1 TB           | 每月 12 美元      | $12/TB/月     |
| 5 TB           | 每月 60 美元      | $12/TB/月     |
| 10 TB          | 每月 120 美元     | $12/TB/月     |
| 20 TB          | 每月 240 美元     | $12/TB/月     |
| 50 TB          | 每月 500 美元     | $10/TB/月     |

您可以从您的账户或组织的 **账单** 设置页面订阅或更改您的套餐等级。升级立即生效；降级将在下月初生效。如果您需要更多存储空间，可以 [联系我们](https://huggingface.co/contact/sales) 以享受 [自定义大规模定价](https://huggingface.co/pricing#storage)。

### 私有存储 按量付费

在 [PRO](https://huggingface.co/subscribe/pro) 和 [Team 或 Enterprise Organizations](https://huggingface.co/enterprise) 中包含的 1TB（或每席位 1TB）私有存储之外，额外私有存储将以按量付费模式计入您的付款方式，基础价格为 $18/TB/月。如需大规模容量，可通过我们的客户经理获取额外折扣：

| 卷 | 价格（私有仓库） |
| ------ | --------------------- |
| 基础   | $18/TB/月             |
| 50TB+  | $16/TB/月             |
| 200TB+ | $14/TB/月             |
| 500TB+ | $12/TB/月             |

有关更多详细信息，请参阅我们的[计费文档](./billing)，或前往[huggingface.co/pricing](https://huggingface.co/pricing#storage)查看最新定价。

## 仓库限制与建议

> [!NOTE]
> 本节不适用于[Storage Buckets](./storage-buckets)

除了账户（用户或组织）级别的存储限制外，在处理特定 Git 支持仓库中的大量数据时，还有一些限制需要注意。由于流式传输数据需要一定时间，如果在流程末尾上传/推送失败，或者在 hf.co 上或本地工作时遇到体验下降的情况，都会非常令人烦恼。在下一节中，我们将介绍如何最佳地组织大型仓库的建议。

### 建议

我们整理了一份关于如何组织仓库的提示和建议列表。如果您希望获取更多实用技巧，请查阅[此指南](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload#tips-and-tricks-for-large-uploads)，了解如何使用 Python 库上传大量数据。

| 特征     | 推荐        | 提示                                                   |
| ----------------   | ------------------ | ------------------------------------------------------ |
| 仓库大小          | -                  | 升级您的[存储计划](#storage-plans)，或联系我们处理大型仓库（TB 级数据） |
| 每个仓库的文件数     | <100k              | 将数据合并到更少的文件中                            |
| 每个文件夹中的条目 | <10k               | 在仓库中使用子目录                             |
| 文件大小          | <200GB             | 将数据拆分为分块文件                          |
| 提交大小        | <100 个文件*        | `upload_folder`/`hf upload` 自动将大型文件夹拆分为多个提交                       |
| 每个仓库的提交次数   | -                  | 每次提交上传多个文件和/或压缩历史记录 |

_\* 直接使用 `git` CLI 时不适用_

请阅读下一节，以更好地理解这些限制以及如何处理它们。

### 解释

当我们提到“大型上传”时，具体指的是什么？它们有哪些相关的限制？大型上传的形式可能非常多样，从包含少数几个超大文件（例如模型权重）的仓库，到包含数千个小文件（例如图像数据集）的仓库。

在底层，Hub 使用 Git 对数据进行版本控制，这会对您在仓库中可执行的操作产生结构性影响。如果您的仓库规模超过了上一节中提到的某些数值，**我们强烈建议您查看 [`git-sizer`](https://github.com/github/git-sizer)**，其中包含关于影响您使用体验的各种因素的非常详细的文档。以下是需要考虑的因素的简要总结：

- **仓库大小**：您计划上传的数据总大小。模型和数据集没有单个仓库的大小限制，但上传会占用您账户的总存储配额（参见上文中的 [存储套餐](#storage-plans)）。如果您需要更多存储空间，请 [升级您的套餐](https://huggingface.co/pricing) 或购买 [存储附加包](#public-storage-add-on)。
- **文件数量**：
    - 为了获得最佳体验，我们建议将文件总数保持在 100k 以下，最好远少于该数量。如果文件数量较多，请尝试将数据合并到更少的文件中。例如，可以将 json 文件合并为单个 jsonl 文件，或者将大型数据集导出为 Parquet 文件或 [WebDataset](https://github.com/webdataset/webdataset) 格式。
    - 每个文件夹中的文件数量不能超过 10k 个。一个简单的解决方案是创建一个使用子目录的仓库结构。例如，一个包含从 `000/` 到 `999/` 的 1k 个文件夹的仓库，每个文件夹最多包含 1000 个文件，就已经足够了。
- **文件大小**：在上传大文件（例如模型权重）时，我们强烈建议将其拆分为**每个小于 200GB 的块。**
原因有以下几点：
    - 上传和下载较小的文件对您和其他用户来说都更加便捷。在流式传输数据时，连接问题随时可能发生，而较小的文件可以避免在出现错误时从头开始重新传输。
    - 文件通过 CloudFront 向用户提供服务。根据我们的经验，该服务不会缓存超大文件，从而导致下载速度变慢。
在所有情况下，单个文件的大小都不会超过 500GB。也就是说，500GB 是单个文件大小的硬性上限。
- **提交次数**：仓库历史中的提交总数没有硬性限制。但是，从
根据我们的经验，当 Hub 上的提交数量达到数千次后，用户体验开始下降。我们一直在努力改进服务，但请务必记住，git 仓库并非设计为支持大量写入操作的数据库。如果您的仓库历史变得非常庞大，始终可以使用 `huggingface_hub` 的 [`super_squash_history`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.super_squash_history) 将所有提交压缩在一起，以重新开始。请注意，这是一个不可逆的操作。
- **每次提交的运算次数**：同样，这里没有硬性限制。当提交上传到 Hub 时，每个
服务器会检查 git 操作（添加或删除）。当一次性提交一百个 Large Files 时，每个文件都会单独检查，以确保其已正确上传。通过 HTTP 推送数据时，请求设置了 60 秒的超时时间，这意味着如果处理耗时超过该时间，就会引发错误。然而，在极少数情况下，即使客户端已触发超时，服务器端的处理仍可能完成。可以通过在 Hub 上浏览仓库来手动检查。[`upload_folder`](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload) 方法和 `hf upload` 命令会自动将大型文件夹拆分为多个提交，从而避免此问题。如果您手动提交，请保持每次提交约 50-100 个文件。

### 在 Hub 上共享大型数据集

Hugging Face 支持机器学习生态系统的核心方式之一是在 Hub 上托管数据集，包括非常大的数据集。大型数据集会计入您账户的总存储配额，因此上传前请确保您的 [存储计划](#storage-plans) 具有足够的容量。额外的公共存储可以作为 [附加组件](#public-storage-add-on) 购买。

要在 Hub 上托管大型数据集，我们需要满足以下要求：

- 数据集卡片：我们希望确保您的数据集能够被社区有效使用，而实现这一目标的关键方式之一就是通过数据集卡片。这份[指南](./datasets-cards)概述了如何撰写数据集卡片。
- 您共享数据集是为了方便社区复用。如果您计划上传一个预计不会再被复用的数据集，其他平台可能更合适。
- 您必须遵守上述列出的仓库限制。
- 使用与 Hugging Face 生态系统良好集成的文件格式。我们对 [Parquet](https://huggingface.co/docs/datasets/main/en/loading#parquet) 和 [WebDataset](https://huggingface.co/docs/datasets/main/en/loading#webdataset) 格式提供了良好的支持，它们通常是高效共享大型数据集的不错选择。这也将确保数据集查看器能够正常工作于您的数据集。
- 在使用 datasets 时，请避免使用自定义加载脚本。根据我们的经验，需要自定义代码才能使用的数据集往往复用性有限。

如果您因所处理的数据类型或领域而难以满足上述任何要求，请联系我们。

### 在 Hub 上共享大量模型

与数据集类似，大型模型或大量模型（例如数百个自动量化模型）会计入您账户的总存储配额。请确保您的[存储计划](#storage-plans)具有足够的容量，或购买[存储附加组件](#public-storage-add-on)。

### 面向研究团队和非营利组织的资助

我们建议学术和研究机构升级到 [Team、Enterprise 或 Academia Hub](https://huggingface.co/pricing)，以获得有保障的存储配额。在某些情况下，对于高影响力的开源项目，如果付费方案确实无法满足需求，可能会提供存储配额支持。此类申请将逐案评估，并要求提供可证明的社区影响力（如下载量、引用次数、社区采用情况等）。请通过 datasets@huggingface.co 或 models@huggingface.co 提交详细提案。

## 如何释放我的账户/组织中的存储空间？

有几种方法可以管理并释放账户或组织中的存储空间。首先，如果您需要更多存储空间，请升级到 PRO、Team 或 Enterprise 计划，以获得更高的存储上限。

⚠️ **重要**：删除大文件是一项不可撤销的破坏性操作。请确保在继续操作之前备份您的文件。

需要记住的关键要点：
- 仅删除 LFS 指针不会释放空间
- 如果您不重写 Git 历史记录，那么包含已删除 LFS 文件且存在 lfs 指针的分支/标签的后续检出将会失败（为避免错误，请在您的 `.gitconfig` 文件中添加以下行：`lfs.skipdownloaderrors=true`）

### 删除单个 LFS 文件

1. 导航至您的仓库的设置页面
2. 在“存储”部分中，点击“列出大文件”
3. 使用操作菜单删除特定文件

### 删除 Pull request refs

[Pull requests](./repositories-pull-requests-discussions) 会创建用于存储其提交的 git 引用。在关闭或合并 PR 后，你可以删除其引用以释放存储空间。这在以下情况下特别有用：
- PR 中包含从未合并的大文件
- 你压缩了主分支并随后删除了文件——即使这些文件并非由该 PR 本身添加，它们仍会保留在 PR 分支的历史记录中

要删除 PR ref，请打开已关闭或已合并的 PR，并在底部查找显示可释放的预估空间的存储通知。点击“Delete ref”将其永久删除。

> [!NOTE]
> 删除 PR ref 是不可逆的，并且会阻止任何人本地获取或检出这些提交。

### 使用 API 深度压缩你的仓库

super-squash 操作会将您的整个 Git 历史压缩为单个提交。当您需要回收未使用的旧 LFS 版本所占用的存储空间时，可以考虑使用 super-squash。此操作仅可通过 [Hub Python Library](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api#huggingface_hub.HfApi.super_squash_history) 或 API 使用。

⚠️ **重要**：这是一个不可撤销的破坏性操作，提交历史将被永久丢失，并且 **LFS 文件历史将被删除**

压缩操作对存储配额的影响不会立即生效，将在 36 小时内反映到您的配额中。

### 高级：跟踪 LFS 文件引用

当您在仓库的“列出大文件”中找到一个 LFS 文件，但不知道它的来源时，可以使用 git log 命令通过其 SHA-256 OID 来追溯其历史记录：

```bash
git log --all -p -S <SHA-256-OID>
```

例如：

```bash
git log --all -p -S 68d45e234eb4a928074dfd868cead0219ab85354cc53d20e772753c6bb9169d3

commit 5af368743e3f1d81c2a846f7c8d4a028ad9fb021
Date:   Sun Apr 28 02:01:18 2024 +0200

    Update LayerNorm tensor names to weight and bias

diff --git a/model.safetensors b/model.safetensors
index a090ee7..e79c80e 100644
--- a/model.safetensors
+++ b/model.safetensors
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:68d45e234eb4a928074dfd868cead0219ab85354cc53d20e772753c6bb9169d3
+oid sha256:0bb7a1683251b832d6f4644e523b325adcf485b7193379f5515e6083b5ed174b
 size 440449768

commit 0a6aa9128b6194f4f3c4db429b6cb4891cdb421b (origin/pr/28)
Date:   Wed Nov 16 15:15:39 2022 +0000

    Adding `safetensors` variant of this model (#15)
    
    
    - Adding `safetensors` variant of this model (18c87780b5e54825a2454d5855a354ad46c5b87e)
    
    
    Co-authored-by: Nicolas Patry <Narsil@users.noreply.huggingface.co>

diff --git a/model.safetensors b/model.safetensors
new file mode 100644
index 0000000..a090ee7
--- /dev/null
+++ b/model.safetensors
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:68d45e234eb4a928074dfd868cead0219ab85354cc53d20e772753c6bb9169d3
+size 440449768

commit 18c87780b5e54825a2454d5855a354ad46c5b87e (origin/pr/15)
Date:   Thu Nov 10 09:35:55 2022 +0000

    Adding `safetensors` variant of this model

diff --git a/model.safetensors b/model.safetensors
new file mode 100644
index 0000000..a090ee7
--- /dev/null
+++ b/model.safetensors
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:68d45e234eb4a928074dfd868cead0219ab85354cc53d20e772753c6bb9169d3
+size 440449768

```

