huggingface下载

更新时间：

本节介绍如何从 Huggingface 的国内镜像站（hf-mirror.com (opens new window)）下载模型和数据。

# 背景说明

因 Huggingface 为国外网站，我们从该网站下载模型和数据集时总会因网络不稳定、限速等问题下载模型和数据失败。
hf-mirror.com (opens new window) 为 AI 爱好者自制 Huggingface 在国内的代理站，为公益项目，致力于帮助国内 AI 开发者快速、稳定的下载 Huggingface 的模型、数据集，详见其官网。

本文仅为提供模型获取的参考，不做网站推广，亦不为盈利目的，请您自行甄别是否从该网站获取。

# 前提条件

无

# 网页下载

适用：Windows、Mac
方法：在hf-mirror.com (opens new window)站内搜索，并在模型主页的 “Files” 中下载文件，如下图所示：

# huggingface-cli下载

说明：huggingface-cli 是 Hugging Face 官方提供的命令行工具，自带完善的下载功能。
适用：Windows、MacOS、其他 Linux
方法：如下。

下述命令，Windows 在 PowerShell 中执行；MacOS 在其 Terminal 中执行；其他 Linux 在其终端中执行。

安装依赖
```
pip install -U huggingface_hub
```
huggingface_hub 依赖于 Python>=3.8，此外需要安装 0.17.0 及以上的版本，推荐0.19.0+

设置环境变量如下命令介绍在各系统中如何设置环境变量，并写入终端的配置文件以便后续启动终端时自动加载。

若未写入配置文件，则每次重开终端需手动再次写入该环境变量。

# MacOS
export HF_ENDPOINT=https://hf-mirror.com
echo 'export HF_ENDPOINT="https://hf-mirror.com"' >> ~/.zshrc

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

# Windows
$env:HF_ENDPOINT = "https://hf-mirror.com"
Add-Content -Path $PROFILE -Value '$env:HF_ENDPOINT = "https://hf-mirror.com"'
#若Add-Content命令执行时提示：未能找到“xxx”路径的一部分。则执行如下命令
new-item -path $profile -itemtype file -force #新建该配置文件
Add-Content -Path $PROFILE -Value '$env:HF_ENDPOINT = "https://hf-mirror.com"' #写入配置到该文件
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser #设置执行策略以便配置文件可加载

下载模型和数据

#下载模型
huggingface-cli download --resume-download <modelName> --local-dir <本地路径>
#示例
huggingface-cli download --resume-download gpt2 --local-dir /data/gpt2

#下载数据
huggingface-cli download --repo-type dataset --resume-download <datasetName> --local-dir <本地路径>
#示例
huggingface-cli download --repo-type dataset --resume-download wikitext --local-dir wikitext

hf_transfer下载加速。

Consider using `hf_transfer` for faster downloads. This solution comes with some limitations. See https://huggingface.co/docs/huggingface_hub/hf_transfer for more details.

下载执行时，界面会有上述提示建议您使用 hf_transfer，它是 hugging face 官方专门为提高下载速度基于 Rust 开发的一个模块，依附并兼容 huggingface-cli。参考如下方法开启 hf_transfer 并重新执行下载。

#安装依赖
pip install -U hf-transfer

#设置环境变量
#Linux
export HF_HUB_ENABLE_HF_TRANSFER=1
#Windows
$env:HF_HUB_ENABLE_HF_TRANSFER = 1

#下载，同huggingface-cli下载一样，详细可参考上述 3 中的描述。
huggingface-cli download --resume-download <modelName> --local-dir <本地路径>

须知，hf_transfer 加速如遇网络不稳定会报错并提示关闭该模块，建议视网络情况开启和使用。

# hfd下载

说明：hfd 是 hf-mirror.com 开发的 huggingface 专用下载工具，基于成熟工具 git+aria2，可以做到稳定下载不断线。
适用： Linux 和 Mac OS
方法：如下。

下述命令，MacOS 在其 Terminal 中执行；其他 Linux 在其终端中执行。

下载 hfd 工具并安装相关依赖。

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

#安装aria2c
apt update
apt install -y aria2

#安装git-lfs
apt install -y git-lfs

设置环境变量。如下命令介绍在各系统中如何设置环境变量，并写入终端的配置文件以便后续启动终端时自动加载。

若未写入配置文件，则每次重开终端需手动再次写入该环境变量。

# MacOS
export HF_ENDPOINT=https://hf-mirror.com
echo 'export HF_ENDPOINT="https://hf-mirror.com"' >> ~/.zshrc

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

# Windows
$env:HF_ENDPOINT = "https://hf-mirror.com"
Add-Content -Path $PROFILE -Value '$env:HF_ENDPOINT = "https://hf-mirror.com"'
#若Add-Content命令执行时提示：未能找到“xxx”路径的一部分。则执行如下命令
new-item -path $profile -itemtype file -force #新建该配置文件
Add-Content -Path $PROFILE -Value '$env:HF_ENDPOINT = "https://hf-mirror.com"' #写入配置到该文件
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser #设置执行策略以便配置文件可加载

下载数据和模型

#下载模型
./hfd.sh <model_id> [--tool wget|aria2c] [-x threads]
#示例：模型将下载到当前命令执行的路径下
./hfd.sh gpt2 --tool aria2c -x 4
./hfd meta-llama/Llama-2-7b --hf_username myuser --hf_token mytoken --tool aria2c -x 8

#下载数据
./hfd.sh <dataset_id> [--dataset] [--tool wget|aria2c] [-x threads]
#示例：数据将下载到当前命令执行的路径下
./hfd.sh wikitext --dataset --tool aria2c -x 4

参考：hfd 工具的完整命令格式如下，各参数使用可参考下述表格。

hfd <model_id> [--include include_pattern] [--exclude exclude_pattern] [--hf_username username] [--hf_token token] [--tool wget|aria2c] [-x threads] [--dataset]

参数	说明
model_id	Hugging Face 模型 ID，格式为 `repo/model_name`。
--include	（可选）用于指定要下载的文件其文件名的模式，即名称符合此处指定的字符串模式的文件都将被下载。
--exclude	（可选）用于指定不下载的文件其文件名的模式，即名称符合该字符串模式的文件都不下载，只下载该模型下的其他文件。
--hf_username	（可选）Hugging Face 用户名，用于身份验证。
--hf_token	（可选）Hugging Face 令牌，用于身份验证。
--tool	（可选）使用的下载工具。默认为 weget，可使用该参数指定为 aria2c。指定为 aria2c 时可接 -x 指定下载线程数。
--dataset	（可选）标志，表示下载数据集。

# python方式下载

说明：huggingface 官方提供了 snapshot_download 方法下载完整模型。
适用：略懂 Python 脚本的用户。因为该方法依赖 transformers 库，且参数众多，需要用户依据这些参数自行写下载脚本。
方法：详见huggingface 官方 (opens new window)。

# 非公开模型下载

说明：由于模型发布者的版权的要求，部分模型无法公开访问下载，需要在 huggingface 上申请许可通过后，才可以下载。这类模型称之为 Gated Model。
方法：如下。

申请许可。需在 huggingface 官网注册登录后申请，登录及申请方法如图。
注册后有邮箱确认邮件，需在邮件中单击链接确认注册邮箱可用，才算注册成功。登录后在如图相同的位置填写并提交申请，后等待邮件通知审批结果。
获取 access token。
申请通过后，工具方式下载如 huggingface-cli 下载，需获取 access token；网页方式下载则无需获取，直接在模型详情页的 “Files and Versions” 页签中单击各文件对应的下载按钮逐个下载即可。获取 access token 方法：进入Access Tokens (opens new window)页面，随后 “New token”，如下图。

生成后的 token 信息需复制并记录，下载时需使用。

下载。
若上述申请许可、token 获取您使用了代理，那么执行下述下载命令时，建议关掉代理。

#huggingface-cli方式下载
huggingface-cli download --token hf_xxx --resume-download bigscience/bloom-560m --local-dir    bloom-560m

#hfd方式下载
hfd meta-llama/Llama-2-7b --hf_username username --hf_token hf_xxx --tool aria2c -x 8

# 常见问题

报错 Error downloading ... https://cdn-lfs.huggingface.co/xxx...。
报错中有出现 http://huggingface.co 这个域名的，可能是因为没有正确设置镜像断点环境变量，导致走的仍然是hf官方服务器出现的网络错误。请正确设置 HF_ENDPOINT 环境变量。
非公开模型下载执行时总是提示连接不到网络。
- 检查 HF_ENDPOINT 环境变量是否配置为了 https://hf-mirror.com。
- 确认是否关了 VPN 或其他网络代理。
huggingface-cli 命令执行后报错 error: invalid choice: 'download' (choose from 'login', 'whoami'...。
huggingface-hub 0.17.0 及以上的版本才支持 download 子命令，而 >=0.17.0 的版本安装依赖于 Python>=3.8，您可以查看当前环境是否有 >=3.8 的 Python 版本，并使用该版本重新安装 huggingface_hub 后再尝试执行 huggingface-cli 下载命令。指定 python 版本安装命令如：
```
pip3.10 install -U huggingface_hub
```
报错 429 Client Error: Too Many Requests。
网站访问量过大，达到速率上限，过五分钟会重置限制。

← 保存Checkpoint 网页终端 →