跳转至

Hugging Face

本文介绍 Hugging Face 的一些概念与用法。

HF 的定位

Hugging Face (HF) 是一个类似于 GitHub 的在线存储库，其主要提供以下三种服务：

  • Models：存储模型的预训练权重；
  • Datasets：存储数据集；
  • Spaces：托管在线 demo。

本质上就是一个 Large File Storage (LFS)。

HF CLI

既然 HF 主要做的是存储服务，那么就和 Git 一样好理解了。HF 官方开发了一个 CLI 名为 hf，主要用来做上传、下载和鉴权等工作。虽然很多时候可以用 Git LFS、Python SDK 来完成一些操作，但我还是更喜欢用 CLI，因为所有的一切都是可控的。完整内容详见 hf cli docs，下面只罗列一些常用命令。

注意

你也许会在一些老项目上看到诸如 huggingface-cli <command> 的命令，这是老版 CLI 的语法，HF 团队在 25 年 7 月对 CLI 进行了大更新并将其更名为了 hf。更新详情见 hf blog。

安装 hf

1
pip install -U "huggingface_hub"

身份鉴权

HF 上大多数 Model 和 Dataset 可以直接下载，但有些敏感内容需要鉴权才能下载，有时如果不鉴权还可能被限速。我们可以借助 hf 进行鉴权：

首先需要在 HF 官网 创建一个 token，注意只能选择读或写权限的，原因见 GitHub Issue：

创建一个 token

接下来我们进入终端进行鉴权即可：

1
hf auth login

之后输入刚才创建的 token 即可正常下载模型。

下载模型

1
hf download <model_name> --local-dir <local_dir>

下载数据集

1
hf download <dataset_name> --repo-type=dataset <local_dir>

网络问题

由于 HF 的服务器不在大陆，并且会刻意封禁大陆 IP，所以如果你的算力平台无法访问 HF，就不得不采用别的方法进行下载。

hf-mirrow

hf-mirrow 是国人发起的一个公益项目，旨在完全镜像 HF，加速大陆的访问。使用上，仍然基于 HF 的 CLI，更换下载源即可。

临时更换：

1
set HF_ENDPOINT=https://hf-mirror.com

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

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

永久更换：

1
2
# 直接编辑环境变量或者输入以下命令编辑环境变量，然后重启终端
setx HF_ENDPOINT https://hf-mirror.com

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# zsh 用户将下列 .bashrc 改成 .zshrc 即可

# 编辑 .bash 文件
vim ~/.bashrc

# 在末尾添加
export HF_ENDPOINT=https://hf-mirror.com

# 重启终端或使用以下命令刷新终端
source ~/.bashrc

之后就可以使用 HF 的 CLI 畅通无阻地下载模型和数据集了。

ModelScope

魔搭社区 (ModelScope) 是阿里的一个产品，和 Hugging Face 的定位完全一致，使用逻辑基本一样。与 HF 相比，ModelScope 的好处是服务器在大陆，不会有网络上的约束了，坏处是有些模型的开发者不一定会把模型上传到 ModelScope，对应的社区也就不如 HF 丰富了。