Hugging Face 模型下载慢?用 hf-mirror 镜像加速

Hugging Face(huggingface.co)是最大的开源模型仓库,但在国内经常下载龟速、超时甚至连不上。最省事的解法是用镜像站 hf-mirror.com——它把 HF 的模型和数据集完整反代到国内可访问的节点。

核心就一件事

把下载入口从 huggingface.co 换成 hf-mirror.com,方法是设置环境变量 HF_ENDPOINT。绝大多数工具(transformers、datasets、huggingface-cli)都认这个变量。

方法一:设置 HF_ENDPOINT 环境变量(推荐)

Linux / macOS:

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

写进 ~/.bashrc / ~/.zshrc 即可长期生效。

Windows PowerShell:

$env:HF_ENDPOINT = "https://hf-mirror.com"

设置后,下面这些操作会自动走镜像:

# transformers 加载模型时自动走镜像
from transformers import AutoModel, AutoTokenizer
tok = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased")

Python 里也可以在代码开头设:import os; os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"(要在 import transformers 之前)。

方法二:huggingface-cli 下载

先装并确认 CLI:

pip install -U "huggingface_hub[cli]"

设置好 HF_ENDPOINT 后直接下载:

# 下载整个模型仓库到本地目录
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./Qwen2.5-7B

# 只下某几个文件
huggingface-cli download Qwen/Qwen2.5-7B-Instruct config.json model.safetensors --local-dir ./Qwen2.5-7B

新版 huggingface_hub 把命令简化为 hf,用法 hf download ...,详见 hf CLI 下载教程。

方法三:hfd 脚本(多线程,最快)

hfd 是社区常用的下载脚本,基于 aria2 多线程 + 断点续传,速度最快、断了能续。

# 1. 下载 hfd 脚本(从 hf-mirror 官网获取最新版)
wget https://hf-mirror.com/hfd/hfd.sh
chmod +x hfd.sh

# 2. 设置镜像
export HF_ENDPOINT=https://hf-mirror.com

# 3. 多线程下载模型(需先安装 aria2c)
./hfd.sh Qwen/Qwen2.5-7B-Instruct --tool aria2c -x 8

对几十 GB 的大模型,多线程效果最明显。

方法四:下载需要登录的模型(gated)

有些模型(如部分 Llama)需要在 HF 同意协议、并用 token 下载:

# 传入你的 HF token(在 hf-mirror / huggingface 账号生成)
huggingface-cli download meta-llama/Llama-3.1-8B --local-dir ./llama3 --token hf_xxx

部分 gated 模型镜像可能不同步,若拉不到,改用 ModelScope 魔搭 上的对应模型。

常见问题

Q:设了 HF_ENDPOINT 还是走 huggingface.co?

• 确认变量拼写正确、在当前终端生效(echo $HF_ENDPOINT)。
• Python 里要在 import transformers 之前设置。

Q:下载中断?

• 用方法三的 hfd + aria2,支持断点续传;或加 --resume-download。

Q:镜像上没有某个新模型?

• 镜像有同步延迟,新发布的模型可能滞后;可 走代理 直连 HF,或用 ModelScope。

小结

• 一招解决 90%:export HF_ENDPOINT=https://hf-mirror.com。
• 大模型用 hfd + aria2 多线程下载最快最稳。
• 镜像缺模型时,转 ModelScope 或 代理直连。

---

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