使用 Hugging Face 新版 CLI 工具 hf 下载数据集（国内镜像加速版）

在进行机器学习和深度学习项目时，我们经常需要从 Hugging Face Hub 下载公开的数据集。然而，由于网络原因，国内用户直接访问 Hugging Face 官方源时往往速度缓慢甚至无法连接。

第一个直觉其实是通过modelscope找替代方案

modelscope其实做得已经非常棒了！感谢他们的工作，modelscope还支持模型权重下载，支持cli，是我主要使用的一个下载工具，但是少数情况下，modescope也有更新不及时的时候，比如这次我们用到的quilt_vqa的数据集，甚至官网数据集地址还要写邮件申请access等等等。

这种情况下，还是绕不开hugging face

本文以下载病理图像数据集 Quilt_VQA 为例，介绍如何使用 Hugging Face 新版命令行工具 hf，并结合国内镜像站加速下载。

---

一、背景：从 huggingface-cli 到 hf

过去大家熟悉的下载命令是 huggingface-cli download ...。在新版 huggingface_hub 库中，官方提供了更简洁的命令行入口 hf，功能基本一致，但命令更短、使用更方便。

如果你之前习惯写：

huggingface-cli download wisdomik/Quilt_VQA --local-dir ./Quilt_VQA --repo-type dataset

现在只需把工具名替换成 hf 即可：

hf download wisdomik/Quilt_VQA --local-dir ./Quilt_VQA --repo-type dataset

参数保持一致，迁移成本几乎为零。

---

二、准备工作

在开始之前，请确保你已经安装了最新版的 huggingface_hub：

pip install -U huggingface_hub

安装完成后，可以用以下命令验证 hf 是否可用：

hf --help

如果提示找不到 hf 命令，说明你的 huggingface_hub 版本过旧，升级后即可。

---

三、配置国内镜像加速

Hugging Face 官方站点在国内访问常常不稳定。推荐使用镜像站 hf-mirror.com，只需设置一个环境变量即可生效：

export HF_ENDPOINT=https://hf-mirror.com

这条命令会让 hf 工具把所有请求自动转发到国内镜像，下载速度显著提升。

小提示：这个环境变量只在当前终端会话生效。如果希望长期使用，可以把它写入 ~/.bashrc 或 ~/.zshrc 配置文件。

---

四、完整下载命令

将环境变量配置与下载命令组合在一起，一行搞定：

export HF_ENDPOINT=https://hf-mirror.com && \
hf download wisdomik/Quilt_VQA --local-dir ./Quilt_VQA --repo-type dataset

参数含义说明：

• wisdomik/Quilt_VQA：数据集在 Hugging Face 上的仓库路径，格式为 用户名/仓库名。
• --local-dir ./Quilt_VQA：指定下载到当前目录下的 Quilt_VQA 文件夹。
• --repo-type dataset：声明这是一个数据集仓库（而不是模型仓库或 Space）。

---

结果显示access denied，被拒绝了，
这个时候你需要去你hf账户里生成一个token来认证

生成后，执行

hf auth login

然后把刚才复制的token贴进去，要注意，这里是不会明文显示的，你执行粘贴回车就好了，不要重复粘贴

一路通过，就可以正常下载了

五、常见问题排查

1. 提示找不到 --repo-type 参数

如果你使用的 hf 版本比较简化，不支持 --repo-type 参数，可以尝试最精简的写法：

hf download wisdomik/Quilt_VQA --local-dir ./Quilt_VQA

多数情况下 hf 会自动识别仓库类型。

2. 下载中断怎么办？

Quilt_VQA 数据集包含大量病理图像切片，体积较大，下载过程中可能会因为网络波动而中断。不用担心——只需重新执行相同的命令即可，hf 会自动检测已下载的部分并断点续传，无需从头再来。

3. 下载速度仍然很慢？

可以检查以下几点：

• 确认 HF_ENDPOINT 已正确设置，可通过 echo $HF_ENDPOINT 验证。
• 关闭可能干扰网络的 VPN 或代理。
• 如果仍有问题，可以尝试使用 hf download 自带的多线程参数（如 --max-workers）提高并发。

---

六、总结

使用 hf 工具下载 Hugging Face 数据集的三个关键点：

1. 工具升级：用更简洁的 hf 替代旧版 huggingface-cli，命令更短更好记。
2. 镜像加速：通过 export HF_ENDPOINT=https://hf-mirror.com 让流量走国内镜像。
3. 断点续传：大数据集中途掉线不用怕，重复执行命令即可续传。

掌握这套流程后，无论是下载数据集还是模型，你都能在国内网络环境下获得流畅、稳定的体验。祝你科研顺利！