🚀 在国内快速稳定下载 HuggingFace 模型的两种方法

随着大模型的广泛应用，很多开发者会直接从 Hugging Face Hub 下载模型进行推理、微调或部署。然而，在国内环境中，直接访问 HuggingFace 往往会遇到下载慢、失败率高、甚至连接不上的问题。

为了解决这个问题，HF-Mirror 提供了一个非常优秀的镜像服务，本文将介绍两种基于 HF-Mirror 的高效模型下载方案：

---

📌 方法一：使用 hfd.sh + aria2 —— 高速下载大模型利器

✅ 适用场景

• 下载大型模型（如 3GB+ 的 .safetensors 文件）
• 希望拥有多线程、高速、断点续传能力
• 能够安装 aria2 工具（如本地终端、部分云主机）

🔧 安装步骤

1. 安装 aria2

Ubuntu / Debian：

apt update && apt install -y aria2

CentOS / RHEL：

yum install -y aria2

macOS（使用 Homebrew）：

brew install aria2

💡 如果在容器中使用，直接执行 apt install -y aria2（无需 sudo）

2. 下载 hfd.sh 脚本

curl -L https://hf-mirror.com/hfd/hfd.sh -o hfd.sh
chmod +x hfd.sh

3. 使用 hfd 下载模型

./hfd.sh deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B

下载完成后，将模型文件保存在当前目录结构中，直接使用 Transformers 加载：

from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("./deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B", trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained("./deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B", trust_remote_code=True)

---

📌 方法二：使用 huggingface-cli + HF-Mirror —— 标准方式更易集成

✅ 适用场景

• 无法安装 aria2 或在受限环境中（如容器、CI/CD）
• 希望将下载过程融入 Python 项目或自动化流程
• 追求 Hugging Face 官方兼容性

🔧 使用步骤

1. 安装 CLI 工具

pip install -U huggingface_hub

2. 设置镜像源环境变量

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

建议写入 .bashrc 或 .zshrc 中：

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

3. 下载模型到本地

huggingface-cli download --resume-download deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --local-dir ./deepseek-model

4. 加载模型

from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("./deepseek-model", trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained("./deepseek-model", trust_remote_code=True)

---

✅ 方法对比总结

比较项	方法一：hfd + aria2	方法二：huggingface-cli
下载速度	⭐⭐⭐⭐（最快）	⭐⭐（中等）
安装复杂度	中（需安装 aria2）	低（纯 Python 工具）
对容器支持	需能装 aria2	✅ 非常友好
自动化脚本支持	一般（Shell）	✅ 非常适合
是否支持断点续传	✅ 支持	✅ 支持
是否支持镜像站	✅ HF-Mirror 推荐方式	✅ 通过 HF_ENDPOINT 配置
适合下载大型模型	✅ 强烈推荐	✅ 可用但速度较慢

---

📌 小结

• 如果你：追求下载速度、经常下载大模型、网络环境一般 → 优先使用方法一（hfd + aria2）
• 如果你：在云主机、Docker、CI/CD 中自动化部署 → 使用方法二（huggingface-cli）更灵活

---

🧠 附加建议

• 模型下载失败或中断时，建议使用 --resume-download 或重新下载
• 使用 trust_remote_code=True 来确保自定义模型类/Tokenizer 能正确加载
• 下载后可将模型打包为镜像或缓存到对象存储，方便部署

---

📚 参考链接

• HF-Mirror 官网
• HF-Mirror 使用教程
• huggingface_hub GitHub
• Transformers 文档

---

如果你觉得本文有帮助，欢迎收藏、分享或留言交流 🙌
如你有更多模型部署相关问题，也可以继续留言！