快速下载 HuggingFace 模型的几种方式：从浏览器到 Hf_transfer

Posted on | In , | 1.7k | 6 分钟

针对国内网络环境总结 HuggingFace 模型的下载方法：网页与多线程下载器（IDM、Aria2）、git clone 的取舍，以及 huggingface-cli 配合 hf_transfer 与 snapshot_download 实现断点续传和满速下载的具体命令。

结合国内的网络环境，断点续传、多线程下载等特性还是非常有必要的，否则动辄断掉重来很浪费时间。基于这个考虑，对各类方法做个总结和排序：

方法类别具体方法推荐程度优点缺点
基于URL浏览器网页下载⭐⭐⭐通用性好手动麻烦/无多线程
多线程下载器⭐⭐⭐⭐通用性好手动麻烦
CLI工具git clone命令⭐⭐简单无断点续传/冗余文件/无多线程
专用CLI工具huggingface-cli+hf_transfer⭐⭐⭐官方下载工具链，功能最全无进度条/容错性低
huggingface-cli⭐⭐⭐⭐⭐官方下载工具不支持多线程
Python方法snapshot_download⭐⭐⭐官方支持，功能全脚本复杂/无多线程
from_pretrained⭐官方支持，简单不方便存储，功能不全
hf_hub_download⭐官方支持不支持全量下载/无多线程

浏览器网页下载

模型项目页的 Files 栏中可以获取文件的下载链接。直接网页复制下载链接，或用其他下载工具下载。

多线程下载器下载

常规工具如浏览器默认采用单线程下载，由于国内网络运营商线路质量、QoS等因素有时候会很慢，多线程加速是一种有效、显著提高下载速度的方法。

经典多线程工具推荐两个：IDM、Aria2。 IDM 适用于 Windows、aria2 适用于 Linux

git clone

官方还提供了 git clone repo_url 的方式下载，这种方法相当简单，然而却是最不推荐直接用的方法，缺点有二：

  • 1）不支持断点续传，断了重头再来；
  • 2）clone 会下载历史版本占用磁盘空间，即使没有历史版本，.git文件夹大小也会存储一份当前版本模型的拷贝以及元信息，导致整个模型文件夹磁盘占用两倍以上，对于有些存在历史版本的模型，下载时间两倍以上，对于网络不够稳，磁盘不够大的用户，严重不推荐！

一种比较好的实践是，设置 GIT_LFS_SKIP_SMUDGE=1 环境变量（这可能也是为什么官方huggingface页面提到这个参数的原因），再 git clone，这样 Git 会先下载仓库中除了大文件之外的文件。然后我们再用一些支持断点续传的工具来下载大文件，这样既支持了断点续传，.git 目录也不会太大（一般几百KB）。

huggingface-cli+hf_transfer

huggingface-cli 和 hf_transfer 是 hugging face 官方提供的专门为下载而设计的工具链。前者是一个命令行工具，后者是下载加速模块。

huggingface-cli

huggingface-cli 隶属于 huggingface_hub 库，不仅可以下载模型、数据，还可以可以登录huggingface、上传模型、数据等。

安装依赖

1
pip install -U huggingface_hub

注意：huggingface_hub 依赖于 Python>=3.8，此外需要安装 0.17.0 及以上的版本，推荐0.19.0+。

基本用法

1
huggingface-cli download --resume-download bigscience/bloom-560m --local-dir bloom-560m

缺点

一是其存储逻辑不太直观，其默认会把模型下载到 ~/.cache/huggingface/hub/ 中，即使设置了 --local-dir，也会采用符号链接的形式进行链接，其目的在于防止重复下载。然而我们有时候只想简单的下载到特定目录，其中有一项 --local-dir-use-symlinks，设置为 False 可以部分解决该问题，虽然仍会临时下载到 ~/.cache/huggingface/hub/，但下载完成后会移动到 --local-dir 指定的目录。

二是由于上述逻辑的问题，主动Ctrl+C中断后，断点续传有时存在bug，导致同样的文件无法中断恢复，会重头下载。相信官方后续会改进。

三是不支持单文件多线程。目前的行为是多文件并行，一次性会同时下载多个文件。

四是遇到网络中断会报错退出，不会自动重试，需要重新手动执行。

hf_transfer

hf_transfer 依附并兼容 huggingface-cli，是 hugging face 官方专门为提高下载速度基于 Rust 开发的一个模块，开启后在带宽充足的机器上可以跑到 500MB/s（官方说法）。

然而缺点是：

  • 1. 没有进度条：是真的没有进度条，有进度条说明你没有开启成功。
  • 2. 鲁棒性差，遇到网络不稳定会报错，并提示用户考虑关闭该模块提高容错性。可能这个模块还没有很成熟吧，对国内这种丢包率高的网络还是水土不服。

安装依赖

1
pip install -U hf-transfer

设置 **HF_HUB_ENABLE_HF_TRANSFER** 环境变量为 1

Linux：export HF_HUB_ENABLE_HF_TRANSFER=1

Windows Powershell：$env:HF_HUB_ENABLE_HF_TRANSFER = 1

开启后使用方法同 huggingface-cli：

1
huggingface-cli download --resume-download bigscience/bloom-560m --local-dir bloom-560m

注意：***如果看到进度条，说明 **hf_transfer** 没开启成功！***

snapshot_download

huggingface 官方提供了snapshot_download 方法下载完整模型，参数众多、比较完善。相比下文另两个 python 方法，推荐 **snapshot_download** 方法来下载模型，支持断点续传、指定路径、配置代理、排除特定文件等功能。然而有两个缺点：

  • 该方法依赖于 transformers 库，而这个库是个开发用的库，对于自动化运维有点重；
  • 该方法调用比较复杂，参数较多，例如默认会检查用户缓存目录下是否已有对应模型，如已有则会创建符号链接，不理解的容易导致问题。外加需要配置代理。最佳实践的参数配置如下：
    1
    2
    3
    4
    5
    6
    7
    8
    from huggingface_hub import snapshot_download

    snapshot_download(
      repo_id="bigscience/bloom-560m",
      local_dir="/mnt/lustre/data",
      local_dir_use_symlinks=False,
      proxies={"https": "http://localhost:7890"}
    )

对于需要登录的模型，还需要两行额外代码：

1
2
import huggingface_hub
huggingface_hub.login("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") # token 从 https://huggingface.co/settings/tokens 获取

获取 access token

申请通过后，就可以在模型主页的 Files and versions 中看到模型文件了，浏览器的话直接点击下载即可。但是如果想要用工具例如 huggingface-cli 下载，则需要获取 access token。

*Access Token 获取地址： *https://huggingface.co/settings/tokens

访问 huggingface 设置页面的 token 管理页，选择 New 一个 token，只需要 Read 权限即可，创建后便可以在工具中调用时使用了。

代码类工具设置环境变量

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

Linux：export HF_ENDPOINT="https://hf-mirror.com"

Python

1
2
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

注意os.environ得在import huggingface库相关语句之前执行。

个人推荐方式

下载Mistral-Large-Instruct-2407模型

1
2
wget --header "Authorization: Bearer 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" 
wget -b -c https://hf-mirror.com/mistralai/Mistral-Large-Instruct-2407/resolve/main/model-000{01..51}-of-00051.safetensors?download=true

其它方式（modelscope）

1
2
pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple
modelscope download --mode Qwen/Qwen3-235B-A22B --local_dir /data/models
本文结束 感谢您的阅读