huggingface 镜像使用全攻略：国内用户如何高效下载模型与数据集？
HuggingFace 镜像站带来高速、便捷、稳定的下载新体验，解决国内开发者获取开源模型与数据集的痛点！本文深入解析主流 HuggingFace 镜像选择、加速工具组合、Token 权限难题及存储管理要点，辅以实操步骤、常见问题对照表和实用链接，助您快速部署 AI 研发环境。迈向高效模型下载新时代！
华语 AI 开发者福音：深度解析 huggingface 镜像加速方案
在 AI 模型开发浪潮中，HuggingFace 平台凭借其庞大开源模型和数据集资源，成为不可或缺的工具。但国内用户常遭遇官网连接不稳定、下载缓慢、甚至连接拒绝等困难。huggingface 镜像站应运而生，为开发者带来高速、便捷、稳定的新体验！
huggingface 镜像站点概览
镜像站的原理与优势
- 下载速度快，动辄数十 MB/s；
- 连接稳定，无国际网络瓶颈；
- 无需 VPN，直接高速访问。
主流 huggingface 镜像站对比表
| 镜像站名称 | 官网/主页 | Support Model | 支持数据集 | 是否同步官方 | 访问速度 | Token 支持 | Remark |
|---|---|---|---|---|---|---|---|
| hf-mirror.com | https://hf-mirror.com/ | √ | √ | 自动、较新 | 极快 | √ | hfd 下载工具 |
| 清华 Tuna 镜像 | 清华 | √ | √ | 自动更新 | 快 | part | 参考帮助文档 |
| 中国科大镜像 | USTC | √ | √ | 自动更新 | 快 | part | 支持 cache |
| BIT 镜像 | BIT | √ | √ | 自动 | 较快 | part | 活跃度一般 |
hf-mirror.com 支持官方授权 Token，可无缝下载 gated model！
国内下载 huggingface 面临的痛点
- 直连易超时/失败，大文件尤甚；
- 速率极慢，高峰期不足 100KB/s；
- 部分资源需 Token 授权，镜像多可绕过；
- 存储压力大，磁盘容易爆满；
- 大流量下易被限制，镜像可规避。
huggingface 镜像实操指南
浏览器/Web 直接下载
- access hf-mirror.com，搜索目标资源，网页直接复制下载链接。
命令行脚本批量下载（推荐）
方式一：hfd.sh（hf-mirror 官方）
- 安装 aria2：
apt update && apt install aria2 -y - wget 下载 hfd 脚本：
wget https://hf-mirror.com/hfd/hfd.sh && chmod +x hfd.sh - 设置环境变量：
export HF_ENDPOINT=https://hf-mirror.com - 下载模型：
./hfd.sh meta-llama/Meta-Llama-3-70B --hf_username your_hf_username --hf_token hf_xxx --tool aria2c -x 4
数据集用法类似，模型名换为数据集名即可。
方式二：huggingface-cli + 镜像
- 安装：
python3 -m pip install huggingface_hub - 设置镜像环境变量，下载模型：
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download google/t5-v1_1-xxl --local-dir ./google-t5-v1_1-xxl - 进阶：hf_transfer
python3 -m pip install huggingface_hub[hf_transfer]
export HF_HUB_ENABLE_HF_TRANSFER=1
HuggingFace Downloader（Python 脚本）
项目地址: LetheSec/HuggingFace-Download-Accelerator
支持 include/exclude 精选、自动镜像配置、Token 管理。
python hf_download.py --model lmsys/vicuna-7b-v1.5 --save_dir ./hf_models --token hf_xxx --use_mirror True
企业/团队分布式实践
- 共享高性能存储，各成员共用模型目录
- 大模型建议下载到大容量云盘或 NFS
- 用软链接重定向 cache 路径，灵活管控磁盘
镜像站进阶用法
- 支持模型/数据集切片节省带宽
- 命令行工具大多支持断点续传
- 可用 tmux/screen 后台保障不中断
快速查阅表：场景推荐下载工具
| 下载场景 | Recommended tools | 是否需要TOKEN | 环境变量 | 并发 | 断点续传 | Remark |
|---|---|---|---|---|---|---|
| 普通模型 | hfd.sh | 否 | must | support | support | 强烈推荐 |
| Gated/私有模型 | hfd.sh/hf_download.py | 是 | suggestion | support | support | 需 Token |
| 少量临时小文件 | 浏览器/Web | 否 | Optional | 否 | 否 | 手动为主 |
| 高并发批量数据集 | huggingface-cli | part | must | support | support | CLI 灵活 |
huggingface 镜像 Tips 与注意事项
令牌与隐私安全
- 下载 gating/private 模型需自建 TOKEN，点击生成，注意保密。
避免磁盘爆满
- 大模型推荐下载到大盘/挂载盘
- 定期清理无用缓存，rootfs 仅做小数据临时用途
镜像同步延迟
- 镜像同步有延迟，最新权重不及时可临时科学上网直连
- 清华/USTC/FDU 等高校同步频率低于 hf-mirror.com
模型 cache 管理
- 建议用软链接统一 cache，支持多应用/多账户高效使用
实用镜像工具/产品推荐链接一览
| Tool Name | Project address | Key Features |
|---|---|---|
| hf-mirror.com 镜像 | hf-mirror.com | 极速镜像、hfd.sh、多线程并发 |
| huggingface-cli | 官方文档 | 命令行官方标准工具 |
| huggingface_hub(Python) | GitHub | 自动化 Python 下载与交互 |
| hf_transfer | GitHub | 多线程断点续传 |
| HuggingFace-Download-Accelerator | LetheSec | 快速多选高阶批量下载脚本 |
| 清华 Tuna 镜像 | TUNA | 高教稳定镜像 |
| 中国科大/北京理工镜像 | USTC | 国产高速高校镜像 |
总结
近年来 huggingface 镜像为国内 AI 从业者带来极大便利！ 借助各类镜像及批量下载工具，不但模型/数据集下载极快，更有效规避原有网络瓶颈。未来，HuggingFace 镜像生态将带动国产 AI 基础设施升级 ——希望这份全攻略助力您高效迈向智能时代！
© Copyright notes
The copyright of the article belongs to the author, please do not reprint without permission.
Related posts
No comments...
