# 下载数据集

## 集成库

如果 Hub 上的数据集关联了某个[受支持的库](./datasets-libraries)，只需几行代码即可加载该数据集。有关访问数据集的信息，您可以点击数据集页面上的“使用此数据集”按钮来查看具体方法。例如，[`samsum`](https://huggingface.co/datasets/knkarthick/samsum?library=datasets) 在下方展示了如何使用 `datasets` 进行操作。

## 使用 Hugging Face 客户端库

您可以使用 [`huggingface_hub`](/docs/huggingface_hub) 库来创建、删除、更新和获取仓库信息。例如，要从命令行下载 `HuggingFaceH4/ultrachat_200k` 数据集，请运行

```bash
hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
```

有关更多信息，请参阅 [HF CLI 下载文档](https://huggingface.co/docs/huggingface_hub/en/guides/cli#download-a-dataset-a-space-or-a-kernel)。

你也可以将其集成到你自己的库中！例如，你可以使用 Pandas 通过几行代码快速加载 CSV 数据集。
```py
from huggingface_hub import hf_hub_download
import pandas as pd

REPO_ID = "YOUR_REPO_ID"
FILENAME = "data.csv"

dataset = pd.read_csv(
    hf_hub_download(repo_id=REPO_ID, filename=FILENAME, repo_type="dataset")
)
```

## 使用 Git

由于 Hub 上的所有数据集都是基于 Xet 的 Git 仓库，您可以通过[安装 git-xet](./xet/using-xet-storage#git-xet)并运行以下命令来在本地克隆数据集：

```bash
git xet install
git lfs install
git clone git@hf.co:datasets/<dataset ID> # example: git clone git@hf.co:datasets/allenai/c4
```

如果您对特定的数据集仓库具有写入权限，您还可以提交并推送该数据集的修订版本。

将您的 SSH 公钥添加到[用户设置](https://huggingface.co/settings/keys)中，以推送更改和/或访问私有仓库。

## 更快的下载速度

您可以在 [fast.hf.co](https://fast.hf.co) 上测试从 Hugging Face CDN 的下载速度。该工具会对最近的 HF 边缘服务器执行快速带宽测试，帮助您了解基线吞吐量。您也可以在终端中使用 [`hf-speedtest`](https://github.com/julien-c/hf-speedtest) CLI 扩展来测量下载速度：

```bash
hf extensions install julien-c/hf-speedtest
hf speedtest
```

为了获得更快的传输速度，Hub 使用了具有自适应并发功能的 [Xet 存储后端](https://huggingface.co/docs/hub/en/xet/index)，它会根据网络状况自动调整并行流。有关 `HF_XET_HIGH_PERFORMANCE=1` 等调优选项的详细信息，请参阅 [更快的模型下载](./models-downloading#faster-downloads)。

## 使用 hf-mount

对于大型数据集，你可以使用 [hf-mount](https://github.com/huggingface/hf-mount) 将仓库挂载为本地文件系统，而无需下载整个仓库。文件是按需获取的——只有代码实际读取的字节才会通过网络传输。当你的工作流期望使用本地文件路径（例如 `tarfile`、`zipfile`、`imagefolder`）而非 Python 迭代器时，这非常有用。

```bash
brew install hf-mount
hf-mount start repo datasets/stanfordnlp/imdb /tmp/imdb
```

仓库以只读方式挂载。有关完整的设置详情、后端选项和缓存，请参阅 [挂载为本地文件系统](./storage-buckets-access#mount-as-a-local-filesystem)。

## 在代理或防火墙后下载

如果您的网络通过防火墙或代理限制了出站流量，下载数据集所需的不仅仅是 `huggingface.co`。文件内容来自独立的存储和 CDN 主机名，如果这些主机名无法访问，即使 `huggingface.co` 本身已在白名单中，`load_dataset` / `hf download` 也会失败。

允许以下主机名（全部通过 HTTPS / 端口 443）：

| 主机名                     | 目的                                     |
|------------------------------|---------------------------------------------|
| `huggingface.co`             | Hub API、元数据和下载重定向   |
| `cas-server.xethub.hf.co`    | Xet 协议 API，下载和上传（美国） |
| `cas-server.xethub-eu.hf.co` | Xet 协议 API，下载和上传（欧盟） |
| `transfer.xethub.hf.co`      | Xet 存储下载 API（美国）              |
| `transfer.xethub-eu.hf.co`   | Xet 存储下载 API（欧盟）              |
| `us.aws.cdn.hf.co`           | CDN 边缘（美国）                               |
| `us.gcp.cdn.hf.co`           | CDN 边缘（美国）                               |
| `cdn-lfs-us-1.hf.co`         | LFS CDN（美国）                                |
| `cdn-lfs-eu-1.hf.co`         | LFS CDN（欧盟）                                |

> [!TIP]
> 下载会从 `huggingface.co` 通过 HTTP 重定向到这些主机名，因此仅将 `huggingface.co` 加入白名单是不够的。下载过程中出现 `ReadTimeoutError`（而非连接错误）通常意味着初始连接成功，但存储或 CDN 主机被阻止。

> [!TIP]
> 通配符的行为取决于您的代理如何匹配域名。许多企业代理将允许列表条目视为后缀匹配，可覆盖任意层级的子域名。如果您的代理如此，最简单的选项是将后缀 `hf.co` 和 `huggingface.co` 加入允许列表——这将覆盖所有当前及未来的存储和 CDN 端点。
>
> 如果您的代理仅支持单标签通配符（即 `*.hf.co` 可以匹配 `cdn-lfs-us-1.hf.co`，但无法匹配更深层的 `us.aws.cdn.hf.co` 或 `cas-server.xethub.hf.co`），请将上表中列出的显式主机名加入白名单。请注意，`*.xethub.hf.co` 并不涵盖 `xethub-eu.hf.co` 下的欧盟主机，且 `*.cdn.hf.co` 也不涵盖双标签的 `us.aws.cdn.hf.co` / `us.gcp.cdn.hf.co`。

> [!WARNING]
> 随着我们的存储和 CDN 基础设施不断演进，这些主机名可能会发生变化。如果您的安全策略允许，请将 `hf.co` 和 `huggingface.co` 后缀（所有子域名）加入允许列表，这样当特定端点变更时，您的规则就不会失效。

> [!NOTE]
> 使用 `hf_xet` 1.8.0 或更高版本上传时，也可以直接上传到 Amazon S3 主机名，这些主机名不属于 `hf.co` 或 `huggingface.co`。请参阅 [通过代理或防火墙上传](./xet/using-xet-storage#uploading-behind-a-proxy-or-firewall)。

### 机器可读列表

上述主机名也以 JSON 格式发布在 [`https://huggingface.co/.well-known/meta.json`](https://huggingface.co/.well-known/meta.json)，因此您可以基于它生成代理或防火墙规则，而无需手动复制表格。

> [!WARNING]
> 随着端点的添加和移除，该文件会发生变化。请在构建规则时获取该文件，而不是固定使用某个副本。