【Hugging Face】Hugging Face Hub与Hugging Face CLI

前言

前面了解了Hugging Face的基本功能，今天了解Hugging Face中一个比较重要的部分，它是外部与Hugging Face交互的桥梁，这就是Hugging Face Hub。对往期内容感兴趣的小伙伴也可以看往期：

• 【Hugging Face】初识Hugging Face

Hugging Face Hub

简介

Hugging Face Hub 是Hugging Face提供的Hub客户端库，通过 huggingface_hub 库，我们可以与面向机器学习开发者和协作者的平台 Hugging Face Hub 进行交互，找到适用于您所在项目的预训练模型和数据集，体验在平台托管的数百个机器学习应用，还可以创建或分享自己的模型和数据集并于社区共享。

Hugging Face Hub文档地址：huggingface.co/docs/huggin...

安装

安装huggingface_hub也很简单，只需要执行如下指令

$ pip install --upgrade huggingface_hub

登录

登录操作非常重要，所有与Hugging Face交互的操作基本上都需要在登录状态下

from huggingface_hub import login
login()

创建存储库

创建存储库可以使用 HfApi

from huggingface_hub import HfApi
if __name__ == "__main__":
    api = HfApi()
    api.create_repo(
        repo_id="xiaoxi/pegasus-xsum",
        repo_type="model", # 仓库类型 model、dataset、space
        private=True, # 是否私有
    )

也可以直接使用create_repoo

from huggingface_hub import create_repo
if __name__ == "__main__":
    create_repo(
        repo_id="xiaoxi/pegasus-xsum",
        repo_type="model", # 仓库类型 model、dataset、space
        private=True, # 是否私有
    )

下载文件

下载单文件

调用 hf_hub_download 配置要下载的仓库id和文件名即可下载该文件，注意这里只能接受一个文件

from huggingface_hub import hf_hub_download
if __name__ == "__main__":
    hf_hub_download(
        repo_id="google/pegasus-xsum",
        filename="config.json", # 下载哪个文件
        local_dir="./tmp", # 下载到本地哪个目录
        revision="main", # 下载哪个版本
        token="", # 使用哪个token
    )

下载多文件

hf_hub_download 默认只接收一个fileName，但是我们可以通过循环的方式下载多个文件

from huggingface_hub import hf_hub_download
# 使用循环调用 hf_hub_download 下载多个文件
files_to_download = ["config.json", "tokenizer_config.json"]
for filename in files_to_download:
    print(f"正在下载: {filename}")
    hf_hub_download(
        repo_id="google/pegasus-xsum",
        filename=filename,
        local_dir="./tmp",
    )
    print(f"已下载: {filename}")

也可以通过 snapshot_download 进行下载

from huggingface_hub import hf_hub_download, snapshot_download
snapshot_download(
    repo_id="google/pegasus-xsum",
    local_dir="./tmp",
    allow_patterns=["config.json", "tokenizer_config.json"],  # 指定具体文件
)

下载子目录文件

如果代码库文件包含目录层级，可以尝试指定文件目录结构的形式进行下载，不能使用glob通配符

from huggingface_hub import hf_hub_download
if __name__ == "__main__":
    hf_hub_download(
        repo_id="openai-community/gpt2",
        filename="onnx/vocab.json", # 下载哪个文件
        local_dir="./tmp", # 下载到本地哪个目录
    )

下载整个仓库

下载整个仓库比较简单，直接传入仓库id即可，注意该方式下载的仓库不包含git信息

from huggingface_hub import snapshot_download
snapshot_download(
    repo_id="multimodalart/dreambooth_sd3_lora", 
    repo_type="model",
    local_dir="./tmp/dreambooth_sd3_lora",
)

Hugging Face CLI

huggingface-cli命令行很强大，对命令行不熟的建议还是使用git

Hugging Face CLI是Hugging Face Hub中提供的终端命令行工具，安装 huggingface_hub 后即可使用 huggingface-cli 。在命令行终端输入

$ huggingface-cli --help

可以看到 huggingface-cli 提供了很多命令：

• download：从 Hub 下载文件
• upload：上传文件或文件夹到 Hub 上的仓库
• repo-files：在 Hub 上管理仓库中的文件
• env：打印环境信息。
• login：使用 huggingface.co/设置/令牌中的令牌登录。
• whoami：显示当前登录的 huggingface.co 账户。
• logout：登出
• auth：其他认证相关命令
• repo：{创建} 与您的 huggingface.co 仓库交互的命令。
• lfs-enable-largefiles：配置您的仓库以启用上传大于 5GB 的文件。
• scan-cache：扫描缓存目录。
• delete-cache：从缓存目录中删除修订。
• tag：（创建, 列出, 删除）仓库中的标签。
• version：打印 huggingface-cli 版本的信息。
• upload-large-folder：上传大文件夹到 Hub 上的仓库

这里介绍一些可能常用的命令。

登录

在使用 huggingface-cli 登录之前我们需要创建一个用于拉取和提交代码的授权token

一键直达：huggingface.co/settings/to...

创建完成后，保存token，在命令行终端执行如下指令：

$ huggingface-cli login

根据提示输入Hugging Face token回车

或者直接使用下面的方式，直接通过命令行变量传递，推荐这种方式

$ export HF_TOKEN="your api key"
$ huggingface-cli login --token $HF_TOKEN --add-to-git-credential

退出登录

需要退出登录可以直接执行如下命令，这个命令将删除设备上存储的所有令牌

$ huggingface-cli logout

查看环境

通过env命令可以查看Hugging Face所有配置信息，需要查找缓存或者token等相关配置可以使用该命令查看

下载

下载后文件会被移动，注意到目标路径查找

下载单文件

要从仓库下载单个文件，只需提供 repo_id 和 文件名，默认类型为 model，可通过 --repo-type 指定类型

# 下载模型中的文件
$ huggingface-cli download openai-community/gpt2 config.json
# 下载空间中的文件
$ huggingface-cli download zhouxiaoxi/gradio-text-to-image app.py --repo-type space
# 下载数据集中的文件
$ huggingface-cli download zhouxiaoxi/gradio-text-to-image app.py --repo-type dataset

下载多文件

# 下载模型中的文件
$ huggingface-cli download openai-community/gpt2 config.json model.safetensors

下载子目录文件

# 下载模型中的文件
$ huggingface-cli download openai-community/gpt2 onnx/vocab.json

下载完成后，根据提示可以找到下载的文件路径，没有指定本地下载路径，默认会被下载到Hugging Face CLI的默认路径

下载整个仓库

注意：通过命令行下载的仓库和通过git下载的仓库略有不同

$ huggingface-cli download <your space>/gradio-text-to-image --repo-type space

指定下载路径

下载的文件也可以通过 --local-dir 指定下载到本地路径，不用每次都到默认下载路径查找了

# 指定下载到本地路径
$ huggingface-cli download zhouxiaoxi/gradio-text-to-image --repo-type space --local-dir .

指定令牌

要访问私有或受限制的仓库，必须使用令牌。如果通过 huggingface-cli login 登录的令牌不满足权限要求，来回切换登录是非常麻烦的，通过指定令牌可以很好的避免这种问题

$ huggingface-cli download openai-community/gpt2 config.json --token=hf_****

上传文件

上传文件允许我们通过命令行将文件上传到Hugging Face仓库，命令行格式如下：

$ huggingface-cli upload [repo_id] [local_path] [path_in_repo]

上传单文件

上传单个文件时，path_in_repo可选，不传将默认使用本地文件名称

# 上传单个文件
$ huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors
# 上传单个文件到指定目录
$ huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors ./trains/model.safetensors

上传多文件

要一次性从文件夹中上传多个文件而不上传整个文件夹，请使用 --include 和 --exclude 模式。它还可以与 --delete 选项结合使用，在上传新文件的同时删除存储库中的文件。

$ huggingface-cli upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"

上传子目录

$ huggingface-cli upload Wauplin/my-cool-model ./models .
$ huggingface-cli upload Wauplin/my-cool-model ./models ./trains

上传整个目录

仓库不存在将自动创建

$ huggingface-cli upload zhouxiaoxi/gradio-text-to-image . .

管理仓库文件

想从Hugging Face仓库中删除文件，可以使用 repo-files 命令

$ huggingface-cli repo-files [repo_id] delete [path_in_repo]

删除单文件

$ huggingface-cli repo-files Wauplin/my-cool-model delete file.txt

上传多文件

$ huggingface-cli repo-files Wauplin/my-cool-model delete file.txt folder/pytorch_model.bin

删除目录

$ huggingface-cli repo-files Wauplin/my-cool-model delete folder/

打标

如果想标记特定版本，可以使用 tag 命令，格式如下

$ huggingface-cli tag [repo_id] [tag]

查看所有标签

$ huggingface-cli tag Wauplin/my-cool-model --list

打标签

默认基于master创建，如需指定其他分支可使用 --revision 选项

# 基于master分支
$ huggingface-cli tag Wauplin/my-cool-model v1.0
# 基于master分支
$ huggingface-cli tag Wauplin/my-cool-model v1.0 --revision refs/pr/10

删除标签

$ huggingface-cli tag -d Wauplin/my-cool-model v1.0

常见问题

TimeoutError: timed out

检测登录信息，使用 huggingface-cli login 重新登录

友情提示

见原文：【Hugging Face】Hugging Face Hub与Hugging Face CLI

本文同步自微信公众号 "程序员小溪" ，这里只是同步，想看及时消息请移步我的公众号，不定时更新我的学习经验。