文章目录
翻译整理自：
https://huggingface.co/docs/huggingface_hub/guides/cli
https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/cli.md
一、关于 CLI
huggingface_hubPython包带有一个名为huggingface-cli的内置CLI。
该工具允许您直接从终端与HugingFace Hub进行交互。
例如，您可以登录您的帐户、创建存储库、上传和下载文件等。
它还带有方便的功能来配置您的机器或管理您的缓存。
在本指南中，我们将了解CLI的主要功能以及如何使用它们。
二、开始工作
1、pip 安装
首先，让我们安装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上传文件的更多信息。
2、其他安装方式
1）使用pkgx
pkgx是一个非常快速的跨平台包管理器，可以运行任何东西。
pkgx install huggingface-cli
或者你可以直接运行 huggingface-cli：
pkgx huggingface-cli --help
查看此处的pkgx huggingface页面了解更多详细信息。
2）使用 Homebrew
brew install huggingface-cli
查看此处的Homebrew huggingface页面了解更多详细信息。
三、huggingface-cli login
在许多情况下，您必须已登录 HuggingFace 帐户才能与Hub 交互（下载私人存储库、上传文件、创建PR等）。
为此，您需要从设置页面获得用户访问token。
用户访问token用于向Hub 验证您的身份。
如果要上传或修改内容，请确保设置具有写入权限的token。
获得token后，在终端中运行以下命令：
huggingface-cli login
此命令将提示您输入token。
复制粘贴您的token，然后按Enter。
然后会询问您是否也应将token保存为git凭据。
如果您计划在本地使用git，请再次按Enter（默认为yes）。
最后，它将调用Hub检查您的token是否有效并将其保存在本地。
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_|
_| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_|
_| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_|
To login, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens .
Token:
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
或者，如果您想在没有提示的情况下登录，您可以直接从命令行传递token。
为了更安全，我们建议将token作为环境变量传递，以避免将其粘贴到命令历史记录中。
# Or using an environment variable
>>> huggingface-cli login --token $HUGGINGFACE_TOKEN --add-to-git-credential
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
有关鉴权的更多详细信息，请查看此部分。
四、huggingface-cli whoami
如果您想知道您是否已登录，可以使用huggingface-cli whoami。
此命令没有任何选项，只需在Hub上打印您的用户名和您所属的组织：
huggingface-cli whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster
如果您尚未已登录，将打印错误消息。
五、huggingface-cli logout 注销
此命令会将您注销。
实际上，它会删除保存在您机器上的token。
如果您已登录使用HF_TOKEN环境变量（请参阅参考资料），此命令将不会注销您。
如果是这种情况，您必须取消设置计算机配置中的环境变量。
六、huggingface-cli download 下载
使用huggingface-cli download命令直接从Hub 下载文件。
在内部，它使用下载指南中描述的相同hf_hub_download()和snapshot_download()助手，并将返回的路径打印到终端。
在下面的示例中，我们将介绍最常见的用例。
有关可用选项的完整列表，您可以运行：
huggingface-cli download --help
1、下载单个文件
要从存储库下载单个文件，只需提供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
该命令将始终在最后一行打印本地计算机上文件的路径。
2、下载整个存储库
在某些情况下，您只想从存储库下载所有文件。
这可以通过指定repo 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
3、下载多个文件
您还可以使用单个命令从存储库下载文件的子集。
这可以通过两种方式完成。
如果您已经有要下载的文件的精确列表，您可以简单地按顺序提供它们：
>>> 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下载哪些文件。
例如，如果您想从稳定ai/stable-diffusion-xl-base-1.0下载所有安全传感器文件，除了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
4、下载数据集或空间
上面的示例展示了如何从模型存储库下载。
要下载数据集或空间，请使用--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
...
5、下载特定版本
上面的示例展示了如何从主分支上的最新提交下载。
要从特定版本（提交哈希、分支名称或标签）下载，请使用--revision选项：
>>> huggingface-cli download bigcode/the-stack --repo-type dataset --revision v1.1
...
6、下载到本地文件夹
从Hub 下载文件的推荐（也是默认）方法是使用缓存系统。
但是，在某些情况下，您希望下载文件并将它们移动到特定文件夹。
这有助于使工作流更接近git命令提供的内容。
您可以使用--local_dir选项来做到这一点。
一个./huggingface/文件夹将在本地目录的根目录下创建，其中包含有关下载文件的元信息。
如果文件已经是最新的，这将防止重新下载文件。
如果元信息已更改，则下载新文件版本。
这使得local_dir针对仅提取最新更改进行了优化。
有关如何下载到本地文件的更多详细信息，请查看下载指南。
>>> huggingface-cli download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensors
7、指定缓存目录
默认情况下，所有文件都将下载到HF_HOME 环境变量定义的缓存目录。
您还可以使用--cache-dir指定自定义缓存：
>>> huggingface-cli download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745
8、指定token
要访问私有或门控存储库，您必须使用token。
默认情况下，将使用本地保存的token（使用huggingface-cli login）。
如果要显式验证，请使用--token选项：
>>> huggingface-cli download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json
9、静音模式
默认情况下，huggingface-cli download命令将是冗长的。
它将打印详细信息，如警告消息、有关下载文件的信息和进度条。
如果您想使所有这些都静音，请使用--quiet选项。
仅打印最后一行（即下载文件的路径）。
如果您想将输出传递给脚本中的另一个命令，这可能很有用。
>>> huggingface-cli download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10
10、下载超时
在连接速度较慢的机器上，您可能会遇到如下超时问题：
`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()助手。
在下面的示例中，我们将介绍最常见的用例。
有关可用选项的完整列表，您可以运行：
>>> huggingface-cli upload --help
1、上传整个文件夹
此命令的默认用法是：
# Usage: huggingface-cli upload [repo_id] [local_path] [path_in_repo]
要上传repo根目录下的当前目录，请使用：
>>> huggingface-cli upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/
如果repo尚不存在，它将自动创建。
您还可以上传特定文件夹：
>>> huggingface-cli upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/
最后，您可以将文件夹上传到repo上的特定目标：
>>> huggingface-cli upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train
2、上传单个文件
您也可以通过将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
3、上传多个文件
要在不上传整个文件夹的情况下一次从一个文件夹上传多个文件，请使用--include和--exclude模式。
它也可以与--delete选项结合使用，在上传新文件时删除repo上的文件。
在下面的示例中，我们通过删除远程文件并上传除/logs中的文件之外的所有文件来同步本地空间：
# 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"
...
4、上传到数据集或空间
要上传到数据集或空间，请使用--repo-type选项：
>>> huggingface-cli upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...
5、上传到组织
要将内容上传到组织拥有的存储库而不是个人存储库，您必须在repo_id中明确指定它：
>>> huggingface-cli upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/
6、上传到特定版本
默认情况下，文件被上传到main分支。
如果要将文件上传到另一个分支或引用，请使用--revision选项：
# Upload files to a PR
>>> huggingface-cli upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...
**注意：**如果revision不存在并且没有设置--create-pr，将从main分支自动创建一个分支。
7、上传并创建PR
如果您没有推送到repo的权限，您必须打开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/
8、定期上传
在某些情况下，您可能希望将定期更新推送到存储库。
例如，如果您正在训练模型并且希望每10分钟上传一次日志文件夹，这将非常有用。
您可以使用--every选项执行此操作：
# Upload new logs every 10 minutes
huggingface-cli upload training-model logs/ --every=10
9、指定提交消息
使用--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
10、指定token
要上传文件，必须使用token。
默认情况下，将使用本地保存的token（使用huggingface-cli login）。
如果要显式验证，请使用--token选项：
>>> huggingface-cli upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/main
11、 静音模式
默认情况下，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 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 命令允许你去 tag、untag，列出 repo 的所有tag
1、标记模型
要标记repo，需要提供repo_id和tag名称：
>>> 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
2、在特定版本标记模型
如果要标记特定的修订，可以使用--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
3、标记数据集或空间
如果要标记数据集或空间，则必须指定--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
4、列表标签
要列出存储库的所有标签，请使用-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
5、删除标签
要删除标签，请使用-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上打开一个问题时，这很有用，可以帮助维护人员调查你的问题。
>>> 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
伊织 + NMT
2024-07-13 (六)
2015
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
