1. 为什么需要镜像下载Hugging Face模型
在国内直接访问Hugging Face下载模型时,经常会遇到速度极慢甚至连接超时的问题。这主要是因为:
- 物理距离导致的网络延迟:Hugging Face的服务器主要位于海外,数据需要经过多个国际网络节点传输
- 国际带宽限制:跨境网络连接通常存在带宽限制和流量管控
- 高峰期拥堵:全球用户同时访问时,服务器负载较高
以我最近下载7B参数的LLaMA模型为例,直接连接Hugging Face的速度仅为50KB/s,而通过镜像站可以达到10MB/s以上,下载时间从数小时缩短到几分钟。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与代理清理
2.1 检查当前代理设置
在开始之前,我们需要确保终端没有设置任何可能干扰下载的代理。运行以下命令查看当前代理设置:
bash复制env | grep -i proxy
如果输出中包含任何http_proxy、https_proxy等变量,就需要进行清理。
2.2 彻底清理代理配置
不同操作系统和终端环境下,代理设置可能以不同形式存在。最全面的清理方式是:
bash复制unset http_proxy
unset https_proxy
unset ftp_proxy
unset all_proxy
unset HTTP_PROXY
unset HTTPS_PROXY
unset FTP_PROXY
unset ALL_PROXY
注意:这些命令只会影响当前终端会话。如果你希望永久移除代理设置,需要检查并修改shell配置文件(如~/.bashrc、~/.zshrc等)。
3. 配置Hugging Face镜像
3.1 选择可靠的镜像站点
目前国内可用的Hugging Face镜像站包括:
- https://hf-mirror.com - 目前最稳定的选择
- https://huggingface.co - 官方域名(不推荐直接使用)
- 其他高校/机构搭建的镜像(时效性可能较差)
建议使用hf-mirror.com,这是我测试过速度和稳定性最好的镜像。
3.2 设置环境变量
在终端中执行:
bash复制export HF_ENDPOINT=https://hf-mirror.com
这个设置只在当前终端会话有效。如果希望永久生效,可以将这行添加到你的shell配置文件中:
bash复制echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc
4. 安装与使用huggingface_hub工具
4.1 安装Python包
Hugging Face官方提供了Python库来管理模型下载:
bash复制pip install -U huggingface_hub
提示:建议使用Python 3.8+环境,并确保pip是最新版本。如果遇到权限问题,可以添加
--user参数。
4.2 下载模型的基本命令
下载模型的基本语法是:
bash复制huggingface-cli download <repo_id> --local-dir <local_path>
例如下载DiffusionDriveV2模型:
bash复制huggingface-cli download hustvl/DiffusionDriveV2 --local-dir ./DiffusionDriveV2
4.3 高级下载选项
- 下载特定文件:
bash复制huggingface-cli download hustvl/DiffusionDriveV2 --filename config.json
- 排除某些文件:
bash复制huggingface-cli download hustvl/DiffusionDriveV2 --exclude "*.bin"
- 指定修订版本:
bash复制huggingface-cli download hustvl/DiffusionDriveV2 --revision v1.0
5. 实际下载案例演示
5.1 下载LLaMA-2 7B模型
bash复制huggingface-cli download meta-llama/Llama-2-7b --local-dir ./llama-2-7b
这个命令会下载约13GB的模型文件。通过镜像站,我的实测下载速度达到15MB/s,大约15分钟完成。
5.2 下载BERT-base模型
bash复制huggingface-cli download bert-base-uncased --local-dir ./bert-base
这个模型约440MB,正常情况下1分钟内可以下载完成。
6. 常见问题与解决方案
6.1 下载中断或失败
如果下载过程中断,可以尝试:
- 添加
--resume-download参数继续下载:
bash复制huggingface-cli download hustvl/DiffusionDriveV2 --local-dir ./DiffusionDriveV2 --resume-download
- 检查网络连接,确保可以访问镜像站:
bash复制curl -I https://hf-mirror.com
6.2 权限问题
如果遇到权限错误:
- 确保对目标目录有写入权限
- 尝试使用
sudo(不推荐)或更改目录权限 - 使用
--cache-dir参数指定可写入的缓存目录
6.3 磁盘空间不足
大型模型如LLaMA-65B需要超过100GB空间。下载前请检查:
bash复制df -h
可以使用--local-dir参数指定有足够空间的目录。
7. 性能优化技巧
- 使用
aria2加速下载(需要先安装aria2):
bash复制pip install -U huggingface_hub[cli]
huggingface-cli download --tool aria2c hustvl/DiffusionDriveV2
- 限制并发连接数(避免被服务器限制):
bash复制huggingface-cli download --concurrency 4 hustvl/DiffusionDriveV2
- 使用本地缓存(避免重复下载):
bash复制export HF_HOME=/path/to/cache
8. 其他下载方式对比
8.1 git lfs方式
传统方法是使用git lfs:
bash复制git lfs install
git clone https://hf-mirror.com/hustvl/DiffusionDriveV2
但这种方式对大模型效率较低,且需要安装git lfs。
8.2 直接HTTP下载
对于单个文件,可以直接使用wget或curl:
bash复制wget https://hf-mirror.com/hustvl/DiffusionDriveV2/resolve/main/config.json
8.3 使用Python代码下载
在Python脚本中:
python复制from huggingface_hub import snapshot_download
snapshot_download(repo_id="hustvl/DiffusionDriveV2", local_dir="./DiffusionDriveV2")
9. 模型文件管理
9.1 检查下载完整性
下载完成后,可以检查文件大小是否匹配:
bash复制du -sh ./DiffusionDriveV2
9.2 清理缓存
定期清理下载缓存可以节省空间:
bash复制huggingface-cli delete-cache
或者手动删除:
bash复制rm -rf ~/.cache/huggingface
10. 安全注意事项
- 只从可信镜像站下载模型
- 下载后检查文件哈希值(如果提供)
- 避免在公共网络传输敏感模型
- 注意模型许可证限制
我在实际使用中发现,通过镜像站下载不仅速度快,而且稳定性更好。特别是在下载10GB以上的大模型时,成功率明显高于直接连接官方服务器。
