命令行界面 (CLI)

huggingface_hub Python 包自带一个名为 hf 的 CLI。此工具允许您直接从终端与 Hugging Face Hub 交互。例如，您可以登录您的帐户、创建仓库、上传和下载文件等。它还附带了用于配置您的机器或管理缓存的便捷功能。在本指南中，我们将介绍 CLI 的主要功能以及如何使用它们。

开始使用

首先，让我们安装 CLI

>>> pip install -U "huggingface_hub[cli]"

在上面的代码片段中，我们还安装了 [cli] 额外依赖项，以改善用户体验，尤其是在使用 cache delete 命令时。

安装完成后，您可以检查 CLI 是否正确设置

>>> hf --help
usage: hf <command> [<args>]

positional arguments:
  {auth,cache,download,repo,repo-files,upload,upload-large-folder,env,version,lfs-enable-largefiles,lfs-multipart-upload}
                        hf command helpers
    auth                Manage authentication (login, logout, etc.).
    cache               Manage local cache directory.
    download            Download files from the Hub
    repo                Manage repos on the Hub.
    repo-files          Manage files in a repo on the Hub.
    upload              Upload a file or a folder to the Hub. Recommended for single-commit uploads.
    upload-large-folder
                        Upload a large folder to the Hub. Recommended for resumable uploads.
    env                 Print information about the environment.
    version             Print information about the hf version.

options:
  -h, --help            show this help message and exit

如果 CLI 正确安装，您应该会看到 CLI 中所有可用选项的列表。如果您收到错误消息，例如 command not found: hf，请参阅安装指南。

--help 选项非常方便，可以获取有关命令的更多详细信息。您可以随时使用它来列出所有可用选项及其详细信息。例如，hf 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 页面此处获取更多详细信息。

hf auth login

在许多情况下，您必须登录 Hugging Face 帐户才能与 Hub 交互（下载私有仓库、上传文件、创建 PR 等）。为此，您需要从设置页面获取用户访问令牌。用户访问令牌用于向 Hub 验证您的身份。如果您想上传或修改内容，请确保设置具有写入权限的令牌。

获得令牌后，在终端中运行以下命令

>>> hf auth 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
>>> hf auth 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`

有关身份验证的更多详细信息，请查看此部分。

hf auth whoami

如果您想知道是否已登录，可以使用 hf auth whoami。此命令没有任何选项，只打印您的用户名和您所属的 Hub 组织

hf auth whoami
Wauplin
orgs:  huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster

如果您未登录，将打印错误消息。

hf auth logout

此命令会注销您。实际上，它将删除您机器上存储的所有令牌。如果您想删除特定令牌，可以将其名称指定为参数。

如果您使用 HF_TOKEN 环境变量登录（请参阅参考），此命令不会注销您。在这种情况下，您必须在机器配置中取消设置该环境变量。

hf download

使用 hf download 命令直接从 Hub 下载文件。在内部，它使用hf_hub_download() 和snapshot_download() 辅助函数，这些函数在下载指南中描述，并打印返回的路径到终端。在下面的示例中，我们将介绍最常见的用例。有关可用选项的完整列表，您可以运行

hf download --help

下载单个文件

要从仓库下载单个文件，只需提供仓库 ID 和文件名，如下所示

>>> hf 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

命令将始终在最后一行打印文件在您本地机器上的路径。

要下载位于仓库子目录中的文件，您应该按 POSIX 格式提供文件在仓库中的路径，如下所示

>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensors

下载整个仓库

在某些情况下，您只想下载仓库中的所有文件。这可以通过仅指定仓库 ID 来完成

>>> hf 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

下载多个文件

您还可以通过单个命令下载仓库中的部分文件。这可以通过两种方式完成。如果您已经有一个要下载的精确文件列表，您可以简单地按顺序提供它们

>>> hf 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 精度文件除外

>>> hf 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

下载数据集或空间

上面的示例展示了如何从模型仓库下载。要下载数据集或空间，请使用 --repo-type 选项

# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset

# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space

...

下载特定修订版

上面的示例展示了如何从主分支的最新提交下载。要从特定修订版（提交哈希、分支名称或标签）下载，请使用 --revision 选项

>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
...

下载到本地文件夹

从 Hub 下载文件的推荐（也是默认）方式是使用缓存系统。但是，在某些情况下，您希望下载文件并将其移动到特定文件夹。这对于使工作流更接近 git 命令所提供的功能非常有用。您可以使用 --local-dir 选项来完成此操作。

在本地目录的根目录中创建了一个 .cache/huggingface/ 文件夹，其中包含有关已下载文件的元数据。这可以防止在文件已是最新状态时重新下载文件。如果元数据已更改，则下载新文件版本。这使得 local-dir 针对仅拉取最新更改进行了优化。

有关下载到本地文件如何工作的更多详细信息，请查看下载指南。

>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensors

指定缓存目录

如果不使用 --local-dir，所有文件默认将下载到 HF_HOME 环境变量定义的缓存目录。您可以使用 --cache-dir 指定自定义缓存

>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745

指定令牌

要访问私有或受限仓库，您必须使用令牌。默认情况下，将使用本地保存的令牌（使用 hf auth login）。如果您想显式进行身份验证，请使用 --token 选项

>>> hf download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

静默模式

默认情况下，hf download 命令将非常详细。它将打印警告消息、有关下载文件的信息和进度条等详细信息。如果您想静默所有这些，请使用 --quiet 选项。只打印最后一行（即下载文件的路径）。如果您想在脚本中将输出传递给另一个命令，这可能会很有用。

>>> hf 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

有关更多详细信息，请查看环境变量参考。并重新运行您的下载命令。

hf upload

使用 hf upload 命令直接将文件上传到 Hub。在内部，它使用upload_file() 和upload_folder() 辅助函数，这些函数在上传指南中描述。在下面的示例中，我们将介绍最常见的用例。有关可用选项的完整列表，您可以运行

>>> hf upload --help

上传整个文件夹

此命令的默认用法是

# Usage:  hf upload [repo_id] [local_path] [path_in_repo]

>>> hf upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/

如果仓库尚不存在，它将自动创建。

您还可以上传特定文件夹

>>> hf upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/

最后，您可以将文件夹上传到仓库中的特定目的地

>>> hf 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 是可选的，并且将默认为您的本地文件名

>>> hf upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors

如果您想将单个文件上传到特定目录，请相应地设置 path_in_repo

>>> hf 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 中的所有文件来同步本地空间。

# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...

上传到数据集或空间

要上传到数据集或空间，请使用 --repo-type 选项

>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...

上传到组织

要将内容上传到组织拥有的仓库而不是个人仓库，您必须在 repo_id 中明确指定

>>> hf upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/

上传到特定版本

默认情况下，文件上传到 main 分支。如果您想将文件上传到其他分支或引用，请使用 --revision 选项

# Upload files to a PR
>>> hf 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
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/

定期上传

在某些情况下，您可能希望定期更新仓库。例如，如果您正在训练模型并希望每 10 分钟上传一次日志文件夹，这会很有用。您可以使用 --every 选项来执行此操作。

# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10

指定提交消息

使用 --commit-message 和 --commit-description 设置自定义的提交消息和描述，而不是默认的

>>> hf 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

指定令牌

要上传文件，您必须使用令牌。默认情况下，将使用本地保存的令牌（使用 hf auth login）。如果您想显式进行身份验证，请使用 --token 选项

>>> hf upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/main

静默模式

默认情况下，hf upload 命令将非常详细。它将打印警告消息、有关上传文件的信息和进度条。如果您想静默所有这些，请使用 --quiet 选项。只打印最后一行（即上传文件的 URL）。如果您想在脚本中将输出传递给另一个命令，这可能会很有用。

>>> hf upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/main

hf repo-files

如果您想从 Hugging Face 仓库中删除文件，请使用 hf repo-files 命令。

删除文件

hf repo-files delete <repo_id> 子命令允许您从仓库中删除文件。以下是一些用法示例。

删除文件夹

>>> hf repo-files delete Wauplin/my-cool-model folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

删除多个文件

>>> hf repo-files delete Wauplin/my-cool-model file.txt folder/pytorch_model.bin
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

使用 Unix 风格的通配符删除文件集

>>> hf repo-files delete Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...

指定令牌

要从仓库中删除文件，您必须经过身份验证和授权。默认情况下，将使用本地保存的令牌（使用 hf auth login）。如果您想显式进行身份验证，请使用 --token 选项

>>> hf repo-files delete --token=hf_**** Wauplin/my-cool-model file.txt

hf cache scan

如果您想知道您下载了哪些仓库以及它们在磁盘上占用了多少空间，扫描缓存目录会很有用。您可以通过运行 hf cache scan 来完成此操作

>>> hf cache scan
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.

有关如何扫描缓存目录的更多详细信息，请参阅管理缓存指南。

hf cache delete

hf cache delete 是一种工具，可帮助您删除不再使用的缓存部分。这对于节省和释放磁盘空间非常有用。要了解有关使用此命令的更多信息，请参阅管理缓存指南。

hf repo tag create

hf repo tag create 命令允许您为仓库添加标签、取消标签和列出标签。

为模型添加标签

要为仓库添加标签，您需要提供 repo_id 和 tag 名称

>>> hf repo tag create 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 分支上

>>> hf repo tag create 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

为数据集或空间添加标签

如果要为数据集或空间添加标签，则必须指定 --repo-type 选项

>>> hf repo tag create 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 选项

>>> hf repo tag create 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 选项

>>> hf repo tag create -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 来跳过确认步骤。

hf env

hf env 命令打印有关您的机器设置的详细信息。当您在 GitHub 上提交问题时，这有助于维护人员调查您的问题。

>>> hf 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

hf jobs

使用熟悉的 Docker 类似界面在 Hugging Face 基础设施上运行计算作业。

hf jobs 是一个命令行工具，它允许您通过简单的命令在 Hugging Face 的基础设施（包括 GPU 和 TPU！）上运行任何东西。可以将其视为 docker run，但用于在 A100 上运行代码。

# Directly run Python code
>>> hf jobs run python:3.12 python -c 'print("Hello from the cloud!")'

# Use GPUs without any setup
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(torch.cuda.get_device_name())"

# Run in an organization account
>>> hf jobs run --namespace my-org-name python:3.12 python -c "print('Running in an org account')"

# Run from Hugging Face Spaces
>>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c "select 'hello world'"

# Run a Python script with `uv` (experimental)
>>> hf jobs uv run my_script.py

✨ 主要功能

🐳 类似 Docker 的 CLI：熟悉的命令（run、ps、logs、inspect）来运行和管理作业
🔥 任何硬件：从 CPU 到 A100 GPU 和 TPU pod - 使用简单的标志即可切换
📦 运行任何内容：使用 Docker 镜像、HF Spaces 或您的自定义容器
🔐 简单身份验证：只需使用您的 HF 令牌
📊 实时监控：实时流式传输日志，就像在本地运行一样
💰 按使用付费：只按使用秒数付费

Hugging Face Jobs 仅适用于专业用户和团队或企业组织。升级您的计划即可开始使用！

快速入门

1. 运行您的第一个作业

# Run a simple Python script
>>> hf jobs run python:3.12 python -c "print('Hello from HF compute!')"

此命令运行作业并显示日志。您可以传递 --detach 在后台运行作业并仅打印作业 ID。

2. 检查作业状态

# List your running jobs
>>> hf jobs ps

# Inspect the status of a job
>>> hf jobs inspect <job_id>

# View logs from a job
>>> hf jobs logs <job_id>

# Cancel a job
>>> hf jobs cancel <job_id>

3. 在 GPU 上运行

您还可以使用 --flavor 选项在 GPU 或 TPU 上运行作业。例如，要在 A10G GPU 上运行 PyTorch 作业

# Use an A10G GPU to check PyTorch CUDA
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")"

运行此命令将显示以下输出！

This code ran with the following GPU: NVIDIA A10G

就这样！您现在正在 Hugging Face 的基础设施上运行代码。

常见用例

模型训练：在 GPU（T4、A10G、A100）上微调或训练模型，无需管理基础设施
合成数据生成：使用强大的硬件上的 LLM 生成大规模数据集
数据处理：使用高 CPU 配置处理海量数据集以进行并行工作负载
批量推理：使用优化的 GPU 设置对数千个样本进行离线推理
实验与基准测试：在一致的硬件上运行 ML 实验以获得可重现的结果
开发与调试：无需本地 CUDA 设置即可测试 GPU 代码

传递环境变量和密钥

您可以使用以下方式将环境变量传递给您的作业

# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c "import os; print(os.environ['FOO'], os.environ['BAR'])"

# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c "import os; print(os.environ['FOO'], os.environ['BAR'])"

# Pass secrets - they will be encrypted server side
>>> hf jobs run -s MY_SECRET=psswrd python:3.12 python -c "import os; print(os.environ['MY_SECRET'])"

# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs run --secrets-file .env.secrets python:3.12 python -c "import os; print(os.environ['MY_SECRET'])"

使用 --secrets HF_TOKEN 隐式传递您的本地 Hugging Face 令牌。使用此语法，将从环境变量中检索密钥。对于 HF_TOKEN，如果未设置环境变量，它可能会读取位于 Hugging Face 主文件夹中的令牌文件。

硬件

可用的 --flavor 选项

CPU: cpu-basic, cpu-upgrade
GPU: t4-small, t4-medium, l4x1, l4x4, a10g-small, a10g-large, a10g-largex2, a10g-largex4,a100-large
TPU: v5e-1x1, v5e-2x2, v5e-2x4

（于 2025 年 7 月从 Hugging Face suggested_hardware docs 更新）

UV 脚本（实验性）

在 HF 基础设施上运行 UV 脚本（带内联依赖项的 Python 脚本）

# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py

# Run with persistent repo
>>> hf jobs uv run my_script.py --repo my-uv-scripts

# Run with GPU
>>> hf jobs uv run ml_training.py --flavor gpu-t4-small

# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet --repo data-scripts

# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py

UV 脚本是 Python 脚本，它使用特殊的注释语法直接将依赖项包含在文件中。这使得它们非常适合不需要复杂项目设置的自包含任务。在 UV 文档中了解有关 UV 脚本的更多信息。

< > 在 GitHub 上更新

Hub Python 库

命令行界面 (CLI)

开始使用

替代安装

使用 pkgx

使用 Homebrew

hf auth login

hf auth whoami

hf auth logout

hf download

下载单个文件

下载整个仓库

下载多个文件

下载数据集或空间

下载特定修订版

下载到本地文件夹

指定缓存目录

指定令牌

静默模式

下载超时

hf upload

上传整个文件夹

上传单个文件

上传多个文件

上传到数据集或空间

上传到组织

上传到特定版本

上传并创建 PR

定期上传

指定提交消息

指定令牌

静默模式

hf repo-files

删除文件

指定令牌

hf cache scan

hf cache delete

hf repo tag create

为模型添加标签

在特定修订版本上为模型添加标签

为数据集或空间添加标签

列出标签

删除标签

hf env

hf jobs

✨ 主要功能

快速入门

1. 运行您的第一个作业

2. 检查作业状态

3. 在 GPU 上运行

常见用例

传递环境变量和密钥

硬件

UV 脚本（实验性）