使用 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_hubpipinstall-Uhuggingface_hub安装完成后可以用以下命令验证hf是否可用hf--help如果提示找不到hf命令说明你的huggingface_hub版本过旧升级后即可。三、配置国内镜像加速Hugging Face 官方站点在国内访问常常不稳定。推荐使用镜像站 hf-mirror.com只需设置一个环境变量即可生效exportHF_ENDPOINThttps://hf-mirror.com这条命令会让hf工具把所有请求自动转发到国内镜像下载速度显著提升。小提示这个环境变量只在当前终端会话生效。如果希望长期使用可以把它写入~/.bashrc或~/.zshrc配置文件。四、完整下载命令将环境变量配置与下载命令组合在一起一行搞定exportHF_ENDPOINThttps://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 数据集的三个关键点工具升级用更简洁的hf替代旧版huggingface-cli命令更短更好记。镜像加速通过export HF_ENDPOINThttps://hf-mirror.com让流量走国内镜像。断点续传大数据集中途掉线不用怕重复执行命令即可续传。掌握这套流程后无论是下载数据集还是模型你都能在国内网络环境下获得流畅、稳定的体验。祝你科研顺利