huggingface-cli / hf 命令行下载加速完整教程

huggingface-cli 是从 Hugging Face 下模型/数据集最规范的方式。配合 hf-mirror,命令行下载又快又可控。本文把常用姿势一次讲清。

一、安装与镜像设置

pip install -U "huggingface_hub[cli]"

# 走国内镜像(关键)
export HF_ENDPOINT=https://hf-mirror.com          # Linux/macOS
# $env:HF_ENDPOINT = "https://hf-mirror.com"      # Windows PowerShell

新版 huggingface_hub 提供了更短的 hf 命令,hf download ... 等价于 huggingface-cli download ...。下面以 huggingface-cli 为主,hf 用法相同。

二、下载整个模型仓库

huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./Qwen2.5-7B

• --local-dir:下载到指定目录(推荐,文件直观可见)。
• 不加 --local-dir 则存到 HF 缓存目录(~/.cache/huggingface)。

三、只下部分文件 / 按模式过滤

大仓库里往往有多种权重格式,只下你要的能省大量时间和空间:

# 只下指定文件
huggingface-cli download Qwen/Qwen2.5-7B-Instruct config.json tokenizer.json --local-dir ./q

# 只下 safetensors,排除 bin(用通配)
huggingface-cli download Qwen/Qwen2.5-7B-Instruct \
  --include "*.safetensors" "*.json" \
  --exclude "*.bin" \
  --local-dir ./q

四、下载数据集

huggingface-cli download --repo-type dataset \
  某组织/某数据集 --local-dir ./data

更多数据集加速见 👉 HF 数据集下载慢。

五、断点续传 & 加速传输

# 断点续传(默认开启;显式指定)
huggingface-cli download 模型ID --local-dir ./m --resume-download

# 启用 hf_transfer 高速下载后端(大文件更快)
pip install hf_transfer
export HF_HUB_ENABLE_HF_TRANSFER=1
huggingface-cli download 模型ID --local-dir ./m

hf_transfer 是 Rust 写的高速下载后端,对大文件提速明显,但出错信息较少;排查问题时可临时关掉。

六、下载 gated(需授权)模型

# 先登录(粘贴你的 token)
huggingface-cli login

# 或下载时直接带 token
huggingface-cli download meta-llama/Llama-3.1-8B --token hf_xxx --local-dir ./llama

常用参数速查

参数	作用
--local-dir	下载到指定目录
--include / --exclude	按通配符筛选文件
--repo-type	model(默认)/ dataset / space
--revision	指定分支 / tag / commit
--token	传入访问令牌(gated 模型)
--resume-download	断点续传

常见问题

Q:命令找不到 huggingface-cli? 确认装的是 huggingface_hub[cli],且 pip 的 bin 目录在 PATH 里。

Q:很快但半路报错? 可能是 hf_transfer 吞了错误信息,unset HF_HUB_ENABLE_HF_TRANSFER 后重试看详细报错。

Q:镜像上没有? 换 ModelScope 或 代理直连。

小结

• 固定套路:HF_ENDPOINT=hf-mirror + huggingface-cli download --local-dir。
• 用 --include/--exclude 只下需要的格式,省时省盘。
• 大文件开 hf_transfer 提速,配合断点续传防中断。

---

本文仅供技术学习与研究,请遵守所在国家/地区法律法规。