🚀 Hugging Face 模型/数据集国内加速下载指南（ HF-Mirror 教程）

📅 更新时间：2025年6月
🧠 作者：@lijin6
🎯 关键词：huggingface、模型下载加速、HF-Mirror、hfd、huggingface-cli、国内AI开发者

---

🧩 为什么需要加速 Hugging Face 下载？

Hugging Face 是当前最受欢迎的 AI 模型平台，包含了诸如 LLaMA、GPT、SAM、Diffusers 等前沿模型。但由于其服务器在海外，国内下载 Huggingface 模型经常出现断连、超时、龟速等问题，严重影响开发效率。

为了解决这个痛点，开源社区开发了多种加速方案，尤其推荐 HF-Mirror 镜像站，本文将全面介绍其使用方式。

---

🌐 HF-Mirror 简介

官网地址： https://hf-mirror.com
这是一个由国内开发者维护的 公益 Hugging Face 镜像服务站，支持以下特性：

• ✅ 提供稳定、快速的模型与数据集下载；
• ✅ 支持 huggingface-cli 命令行；
• ✅ 支持环境变量无侵入式加速；
• ✅ 提供基于 aria2 的高速下载工具 hfd；
• ✅ 支持 Gated Repo 的 token 下载。

---

✅ 方法一：直接网页搜索下载

适用于模型数量少、不常更新时：

1. 打开 https://hf-mirror.com
2. 搜索你需要的模型，比如 gpt2
3. 点击 Files and versions，直接选择你需要的 .bin、.json 文件进行下载

---

✅ 方法二：huggingface-cli 命令行加速

1️⃣ 安装依赖：

pip install -U huggingface_hub

2️⃣ 设置环境变量：

• Linux/macOS：

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

• Windows PowerShell：

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

建议将其添加到你的 .bashrc 或 PowerShell 配置文件中。

---

3️⃣ 下载模型/数据集：

• 下载模型：

huggingface-cli download --resume-download gpt2 --local-dir gpt2

• 下载数据集：

huggingface-cli download --repo-type dataset --resume-download wikitext --local-dir wikitext

💡 使用 --local-dir-use-symlinks False 可禁用软链接，便于打包或直接部署。

---

✅ 方法三：使用 hfd 高速下载器（推荐）

hfd 是 HF-Mirror 提供的轻量级模型下载脚本，底层基于 aria2 支持断点续传和多线程，非常适合下载大模型。

1️⃣ 下载 hfd 工具：

wget https://hf-mirror.com/hfd/hfd.sh
chmod +x hfd.sh

2️⃣ 设置镜像地址：

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

3️⃣ 下载命令示例：

• 下载模型：

./hfd.sh gpt2

• 下载数据集：

./hfd.sh wikitext --dataset

🔐 下载需要授权的 Gated Repo：

./hfd.sh meta-llama/Llama-2-7b --hf_username YOUR_NAME --hf_token hf_***

---

✅ 方法四：非侵入式加速（代码中设置环境变量）

适用于已有代码框架、无法改写调用方式的情况：

HF_ENDPOINT=https://hf-mirror.com python your_script.py

如在 Transformers 中使用 from_pretrained() 时也会自动读取该变量。

---

❓ 常见问题解答

Q: 为什么有些模型提示没有权限？

A: Gated 模型（如 LLaMA、Stable Diffusion XL）需要在官网申请授权并登录，然后使用 access token 下载。

Q: 如何获取 token？

1. 登录 huggingface.co
2. 前往 https://huggingface.co/settings/tokens
3. 创建新的 Access Token

---

❤️ 最后

HF-Mirror 是一个非常棒的国内公益项目，极大提升了我们使用 Hugging Face 的效率。如果你觉得有帮助，欢迎前往官网左下角扫码支持一下维护者！

📢 项目地址： https://hf-mirror.com

---

📌 参考链接

• HF-Mirror 教程主页：https://hf-mirror.com
• huggingface-cli 官网文档：https://huggingface.co/docs/huggingface_hub
• Huggingface Datasets：https://huggingface.co/datasets

---

📬 如果这篇文章对你有帮助，欢迎点赞、收藏、评论支持我持续更新 AI 工具技巧！也欢迎留言分享你自己的加速经验 🚀