Hub Python 库文档
命令行界面 (CLI)
并获得增强的文档体验
开始使用
命令行界面 (CLI)
huggingface_hub
Python 包带有一个内置的 CLI,名为 huggingface-cli
。此工具允许您直接从终端与 Hugging Face Hub 交互。例如,您可以登录您的帐户、创建仓库、上传和下载文件等。它还具有方便的功能来配置您的机器或管理您的缓存。在本指南中,我们将了解 CLI 的主要功能以及如何使用它们。
入门指南
首先,让我们安装 CLI
>>> pip install -U "huggingface_hub[cli]"
在上面的代码片段中,我们还安装了 [cli]
额外依赖项,以获得更好的用户体验,尤其是在使用 delete-cache
命令时。
安装完成后,您可以检查 CLI 是否正确设置
>>> huggingface-cli --help
usage: huggingface-cli <command> [<args>]
positional arguments:
{env,login,whoami,logout,repo,upload,download,lfs-enable-largefiles,lfs-multipart-upload,scan-cache,delete-cache,tag}
huggingface-cli command helpers
env Print information about the environment.
login Log in using a token from huggingface.co/settings/tokens
whoami Find out which huggingface.co account you are logged in as.
logout Log out
repo {create} Commands to interact with your huggingface.co repos.
upload Upload a file or a folder to a repo on the Hub
download Download files from the Hub
lfs-enable-largefiles
Configure your repository to enable upload of files > 5GB.
scan-cache Scan cache directory.
delete-cache Delete revisions from the cache directory.
tag (create, list, delete) tags for a repo in the hub
options:
-h, --help show this help message and exit
如果 CLI 正确安装,您应该看到 CLI 中所有可用选项的列表。如果您收到错误消息,例如 command not found: huggingface-cli
,请参考安装指南。
--help
选项非常方便,可以获取有关命令的更多详细信息。您可以随时使用它来列出所有可用选项及其详细信息。例如,huggingface-cli upload --help
提供了有关如何使用 CLI 上传文件的更多信息。
其他安装方式
使用 pkgx
Pkgx 是一个速度极快的跨平台软件包管理器,可以运行任何程序。您可以使用 pkgx 安装 huggingface-cli,如下所示
>>> pkgx install huggingface-cli
或者您可以直接运行 huggingface-cli
>>> pkgx huggingface-cli --help
查看 pkgx huggingface 页面此处了解更多详情。
使用 Homebrew
您还可以使用 Homebrew 安装 CLI
>>> brew install huggingface-cli
查看 Homebrew huggingface 页面此处了解更多详情。
huggingface-cli login
在许多情况下,您必须登录 Hugging Face 帐户才能与 Hub 交互(下载私有仓库、上传文件、创建 PR 等)。为此,您需要从您的设置页面获取用户访问令牌。用户访问令牌用于验证您在 Hub 中的身份。如果您想上传或修改内容,请确保设置具有写入权限的令牌。
获得令牌后,在终端中运行以下命令
>>> huggingface-cli login
此命令将提示您输入令牌。复制粘贴您的令牌并按 Enter 键。然后,系统会询问您是否也应将令牌另存为 git 凭据。如果您计划在本地使用 git
,请再次按 Enter 键(默认为“是”)。最后,它将调用 Hub 以检查您的令牌是否有效并将其保存在本地。
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_|
_| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_|
_| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_|
To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens .
Enter your token (input will not be visible):
Add token as git credential? (Y/n)
Token is valid (permission: write).
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
或者,如果您想在不提示的情况下登录,您可以直接从命令行传递令牌。为了更安全,我们建议您将令牌作为环境变量传递,以避免将其粘贴到命令历史记录中。
# Or using an environment variable
>>> huggingface-cli login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`
有关身份验证的更多详细信息,请查看此部分。
huggingface-cli whoami
如果您想知道是否已登录,可以使用 huggingface-cli whoami
。此命令没有任何选项,只是在 Hub 上打印您的用户名以及您所属的组织
huggingface-cli whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster
如果您未登录,则会打印错误消息。
huggingface-cli logout
此命令将您注销。实际上,它将删除存储在您机器上的所有令牌。如果要删除特定令牌,可以指定令牌名称作为参数。
如果您使用 HF_TOKEN
环境变量登录(请参阅参考),则此命令不会注销您。如果是这种情况,您必须在机器配置中取消设置环境变量。
huggingface-cli download
使用 huggingface-cli download
命令直接从 Hub 下载文件。在内部,它使用与hf_hub_download() 和 snapshot_download() 助手相同的方法,这些助手在下载指南中进行了描述,并在终端上打印返回的路径。在下面的示例中,我们将介绍最常见的用例。有关可用选项的完整列表,您可以运行
huggingface-cli download --help
下载单个文件
要从仓库下载单个文件,只需按如下方式提供 repo_id 和文件名
>>> huggingface-cli download gpt2 config.json downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o (…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json
该命令始终在最后一行打印本地机器上文件的路径。
下载整个仓库
在某些情况下,您只想下载仓库中的所有文件。只需指定仓库 ID 即可完成此操作
>>> huggingface-cli download HuggingFaceH4/zephyr-7b-beta Fetching 23 files: 0%| | 0/23 [00:00<?, ?it/s] ... ... /home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720
下载多个文件
您还可以使用单个命令从仓库下载文件子集。这可以通过两种方式完成。如果您已经有一个精确的文件列表要下载,您可以简单地按顺序提供它们
>>> huggingface-cli download gpt2 config.json model.safetensors Fetching 2 files: 0%| | 0/2 [00:00<?, ?it/s] downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o (…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s] Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00, 3.76it/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10
另一种方法是提供模式来过滤您要使用 --include
和 --exclude
下载的文件。例如,如果您想下载 stabilityai/stable-diffusion-xl-base-1.0 中的所有 safetensors 文件,但排除 FP16 精度的文件
>>> huggingface-cli download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files: 0%| | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7b
下载数据集或 Space
上面的示例展示了如何从模型仓库下载。要下载数据集或 Space,请使用 --repo-type
选项
# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> huggingface-cli download HuggingFaceH4/ultrachat_200k --repo-type dataset
# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> huggingface-cli download HuggingFaceH4/zephyr-chat --repo-type space
...
下载特定修订版本
上面的示例展示了如何从 main 分支上的最新提交下载。要从特定修订版本(提交哈希、分支名称或标签)下载,请使用 --revision
选项
>>> huggingface-cli download bigcode/the-stack --repo-type dataset --revision v1.1 ...
下载到本地文件夹
从 Hub 下载文件的推荐(和默认)方式是使用缓存系统。但是,在某些情况下,您希望下载文件并将它们移动到特定文件夹。这对于使工作流程更接近 git 命令提供的功能非常有用。您可以使用 --local-dir
选项来执行此操作。
在您的本地目录的根目录中创建了一个 .cache/huggingface/
文件夹,其中包含有关已下载文件的元数据。这可以防止在文件已是最新版本时重新下载文件。如果元数据已更改,则会下载新文件版本。这使得 local-dir
针对仅拉取最新更改进行了优化。
有关下载到本地文件的工作原理的更多详细信息,请查看下载指南。
>>> huggingface-cli download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu ... fuyu/model-00001-of-00002.safetensors
指定缓存目录
如果不使用 --local-dir
,则默认情况下所有文件都将下载到 HF_HOME
环境变量定义的缓存目录。您可以使用 --cache-dir
指定自定义缓存
>>> huggingface-cli download adept/fuyu-8b --cache-dir ./path/to/cache ... ./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745
指定令牌
要访问私有或门控仓库,您必须使用令牌。默认情况下,将使用本地保存的令牌(使用 huggingface-cli login
)。如果您想显式进行身份验证,请使用 --token
选项
>>> huggingface-cli download gpt2 config.json --token=hf_**** /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json
静默模式
默认情况下,huggingface-cli download
命令将非常详细。它将打印详细信息,例如警告消息、有关已下载文件的信息和进度条。如果您想静默所有这些,请使用 --quiet
选项。仅打印最后一行(即已下载文件的路径)。如果您想将输出传递给脚本中的另一个命令,这可能会很有用。
>>> huggingface-cli download gpt2 --quiet /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10
下载超时
在网络连接缓慢的机器上,您可能会遇到如下超时问题
`requests.exceptions.ReadTimeout: (ReadTimeoutError("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`
为了缓解这个问题,您可以将 HF_HUB_DOWNLOAD_TIMEOUT
环境变量设置为更高的值(默认为 10)
export HF_HUB_DOWNLOAD_TIMEOUT=30
有关更多详细信息,请查看 环境变量参考。然后重新运行您的下载命令。
huggingface-cli upload
使用 huggingface-cli upload
命令直接将文件上传到 Hub。 在内部,它使用 upload_file() 和 upload_folder() 助手函数,这些函数在 Upload 指南中进行了描述。 在下面的示例中,我们将介绍最常见的用例。 有关可用选项的完整列表,您可以运行
>>> huggingface-cli upload --help
上传整个文件夹
此命令的默认用法是
# Usage: huggingface-cli upload [repo_id] [local_path] [path_in_repo]
要将当前目录上传到仓库的根目录,请使用
>>> huggingface-cli upload my-cool-model . . https://huggingface.co/Wauplin/my-cool-model/tree/main/
如果仓库尚不存在,它将自动创建。
您还可以上传特定文件夹
>>> huggingface-cli upload my-cool-model ./models . https://huggingface.co/Wauplin/my-cool-model/tree/main/
最后,您可以将文件夹上传到仓库中的特定目标位置
>>> huggingface-cli upload my-cool-model ./path/to/curated/data /data/train https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train
上传单个文件
您还可以通过设置 local_path
指向您机器上的文件来上传单个文件。 在这种情况下,path_in_repo
是可选的,默认值为您的本地文件名
>>> huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors
如果您想将单个文件上传到特定目录,请相应地设置 path_in_repo
>>> huggingface-cli upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors
上传多个文件
要一次性从文件夹上传多个文件,而无需上传整个文件夹,请使用 --include
和 --exclude
模式。 它还可以与 --delete
选项结合使用,在上传新文件的同时删除仓库中的文件。 在下面的示例中,我们通过删除远程文件并上传除 /logs
中的文件之外的所有文件来同步本地 Space
# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> huggingface-cli upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...
上传到数据集或 Space
要上传到数据集或 Space,请使用 --repo-type
选项
>>> huggingface-cli upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset ...
上传到组织
要将内容上传到组织拥有的仓库而不是个人仓库,您必须在 repo_id
中显式指定它
>>> huggingface-cli upload MyCoolOrganization/my-cool-model . . https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/
上传到特定修订版本
默认情况下,文件上传到 main
分支。 如果您想将文件上传到另一个分支或引用,请使用 --revision
选项
# Upload files to a PR
>>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...
注意:如果 revision
不存在且未设置 --create-pr
,则将从 main
分支自动创建分支。
上传并创建 PR
如果您没有推送仓库的权限,则必须打开 PR 并让作者知道您想要进行的更改。 这可以通过设置 --create-pr
选项来完成
# Create a PR and upload the files to it
>>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/
定期上传
在某些情况下,您可能希望定期向仓库推送更新。 例如,如果您正在训练模型并且想要每 10 分钟上传 logs 文件夹,这将非常有用。 您可以使用 --every
选项来执行此操作
# Upload new logs every 10 minutes
huggingface-cli upload training-model logs/ --every=10
指定提交消息
使用 --commit-message
和 --commit-description
为您的提交设置自定义消息和描述,而不是默认消息和描述
>>> huggingface-cli upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/main
指定令牌
要上传文件,您必须使用令牌。 默认情况下,将使用本地保存的令牌(使用 huggingface-cli login
)。 如果您想显式进行身份验证,请使用 --token
选项
>>> huggingface-cli upload Wauplin/my-cool-model ./models . --token=hf_**** ... https://huggingface.co/Wauplin/my-cool-model/tree/main
静默模式
默认情况下,huggingface-cli upload
命令将是详细模式。 它将打印详细信息,例如警告消息、有关上传文件的信息和进度条。 如果您想静默所有这些信息,请使用 --quiet
选项。 只会打印最后一行(即上传文件的 URL)。 如果您想将输出传递给脚本中的另一个命令,这将非常有用。
>>> huggingface-cli upload Wauplin/my-cool-model ./models . --quiet https://huggingface.co/Wauplin/my-cool-model/tree/main
huggingface-cli repo-files
如果您想从 Hugging Face 仓库中删除文件,请使用 huggingface-cli repo-files
命令。
删除文件
huggingface-cli repo-files <repo_id> delete
子命令允许您从仓库中删除文件。 以下是一些用法示例。
删除文件夹
>>> huggingface-cli repo-files Wauplin/my-cool-model delete folder/ Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
删除多个文件
>>> huggingface-cli repo-files Wauplin/my-cool-model delete file.txt folder/pytorch_model.bin Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
使用 Unix 样式的通配符删除文件集
>>> huggingface-cli repo-files Wauplin/my-cool-model delete "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...
指定令牌
要从仓库中删除文件,您必须经过身份验证和授权。 默认情况下,将使用本地保存的令牌(使用 huggingface-cli login
)。 如果您想显式进行身份验证,请使用 --token
选项
>>> huggingface-cli repo-files --token=hf_**** Wauplin/my-cool-model delete file.txt
huggingface-cli scan-cache
如果您想知道您下载了哪些仓库以及它们在磁盘上占用了多少空间,扫描您的缓存目录非常有用。 您可以通过运行 huggingface-cli scan-cache
来做到这一点
>>> huggingface-cli scan-cache
REPO ID REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS LOCAL PATH
--------------------------- --------- ------------ -------- ------------- ------------- ------------------- -------------------------------------------------------------------------
glue dataset 116.3K 15 4 days ago 4 days ago 2.4.0, main, 1.17.0 /home/wauplin/.cache/huggingface/hub/datasets--glue
google/fleurs dataset 64.9M 6 1 week ago 1 week ago refs/pr/1, main /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs
Jean-Baptiste/camembert-ner model 441.0M 7 2 weeks ago 16 hours ago main /home/wauplin/.cache/huggingface/hub/models--Jean-Baptiste--camembert-ner
bert-base-cased model 1.9G 13 1 week ago 2 years ago /home/wauplin/.cache/huggingface/hub/models--bert-base-cased
t5-base model 10.1K 3 3 months ago 3 months ago main /home/wauplin/.cache/huggingface/hub/models--t5-base
t5-small model 970.7M 11 3 days ago 3 days ago refs/pr/1, main /home/wauplin/.cache/huggingface/hub/models--t5-small
Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G.
Got 1 warning(s) while scanning. Use -vvv to print details.
有关如何扫描缓存目录的更多详细信息,请参阅 管理缓存 指南。
huggingface-cli delete-cache
huggingface-cli delete-cache
是一个工具,可帮助您删除缓存中不再使用的部分。 这对于节省和释放磁盘空间非常有用。 要了解有关使用此命令的更多信息,请参阅 管理缓存 指南。
huggingface-cli tag
huggingface-cli tag
命令允许您标记、取消标记和列出仓库的标签。
标记模型
要标记仓库,您需要提供 repo_id
和标签名称
>>> huggingface-cli tag Wauplin/my-cool-model v1.0 You are about to create tag v1.0 on model Wauplin/my-cool-model Tag v1.0 created on Wauplin/my-cool-model
标记特定修订版本的模型
如果您想标记特定修订版本,可以使用 --revision
选项。 默认情况下,标签将在 main
分支上创建
>>> huggingface-cli tag Wauplin/my-cool-model v1.0 --revision refs/pr/104 You are about to create tag v1.0 on model Wauplin/my-cool-model Tag v1.0 created on Wauplin/my-cool-model
标记数据集或 Space
如果您想标记数据集或 Space,则必须指定 --repo-type
选项
>>> huggingface-cli tag bigcode/the-stack v1.0 --repo-type dataset You are about to create tag v1.0 on dataset bigcode/the-stack Tag v1.0 created on bigcode/the-stack
列出标签
要列出仓库的所有标签,请使用 -l
或 --list
选项
>>> huggingface-cli tag Wauplin/gradio-space-ci -l --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1
删除标签
要删除标签,请使用 -d
或 --delete
选项
>>> huggingface-cli tag -d Wauplin/my-cool-model v1.0 You are about to delete tag v1.0 on model Wauplin/my-cool-model Proceed? [Y/n] y Tag v1.0 deleted on Wauplin/my-cool-model
您还可以传递 -y
以跳过确认步骤。
huggingface-cli env
huggingface-cli env
命令打印有关您机器设置的详细信息。 当您在 GitHub 上打开 issue 以帮助维护人员调查您的问题时,这非常有用。
>>> huggingface-cli env
Copy-and-paste the text below in your GitHub issue.
- huggingface_hub version: 0.19.0.dev0
- Platform: Linux-6.2.0-36-generic-x86_64-with-glibc2.35
- Python version: 3.10.12
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- FastAI: N/A
- Tensorflow: 2.11.0
- Torch: 1.12.1
- Jinja2: 3.1.2
- Graphviz: 0.20.1
- Pydot: 1.4.2
- Pillow: 9.2.0
- hf_transfer: 0.1.3
- gradio: 4.0.2
- tensorboard: 2.6
- numpy: 1.23.2
- pydantic: 2.4.2
- aiohttp: 3.8.4
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_ENABLE_HF_TRANSFER: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10