Hub documentation

配置

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

配置

身份验证

运行 Jobs 需要通过 hf auth login 进行身份验证，并使用具有启动和管理 Jobs 权限的令牌。

或者，在 CLI 中通过 --token 手动传入 Hugging Face 令牌，或在 Python 中使用 token 参数。

传递参数

使用 -- 将 Jobs 选项与您的命令或脚本及其参数分隔开。-- 之后的选项（例如 --help 或 --timeout）会被直接传递，而不会被 Jobs 解释。此规则同时适用于 UV 和 Docker Jobs。

hf jobs uv run --flavor t4-small -- script.py --early-stopping-patience 3
               └─ Jobs option ┘    └─ script + arguments ─────────────┘

UV 任务

按照使用 UV 的方式，指定要运行的 UV 脚本或 python 命令：

>>> hf jobs uv run train.py

>>> hf jobs uv run python -c 'print("Hello from the cloud!")'

hf jobs uv run 命令支持 --with 和 --python 等 UV 参数。--with 参数用于指定 Python 依赖项，--python 参数用于选择要使用的 Python 版本：

>>> hf jobs uv run --with trl train.py
>>> hf jobs uv run --python 3.12 train.py

例如，使用--向命令传递参数：

>>> hf jobs uv run --with trl-jobs -- trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara

在 CLI 文档和 UV Commands 文档中查找所有参数的列表。

默认情况下，UV Jobs 使用 ghcr.io/astral-sh/uv:python3.12-bookworm Docker 镜像运行，但你可以使用其他镜像，只要其中已安装 UV，使用 --image <docker-image> 即可。

请参阅使用 Docker 镜像，了解如何选择镜像以及如何理解其环境与 UV 依赖项之间的交互。

在脚本中定义启动配置

仅在特定运行时（例如特定镜像、GPU 型号或系统解释器）上才能正确运行的脚本，可以在其 PEP 723 头部的可选 [tool.hf-jobs] 表中携带该配置：

# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# image   = "vllm/vllm-openai:unlimited-ocr"
# flavor  = "l4x1"
# python  = "/usr/bin/python3"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run ocr.py 随后会在该镜像和硬件上启动。普通的 uv run 会忽略该表格，因为 [tool.*] 表格属于 PEP 723 的一部分，而工具会跳过它们不拥有的表格。

支持的键，均为可选：image、flavor、python、timeout、name、namespace、env、secrets、labels、volumes、network_group 和 network_aliases。它们映射到同名的标志。脚本中的值作为默认值：显式指定的标志始终优先，且 env、secrets、labels 和 volumes 会逐项合并，因此 -e 和 -v 会追加到脚本声明的内容中。未知的键会引发错误，且 secrets 仅列出名称：值来自运行脚本者的环境，未在本地设置的 secret 同样会引发错误。

使用 --dry-run 可以打印解析后的配置而不提交；来自脚本的值会标记为 (from script)。有关完整的合并规则，请参阅 hf CLI 指南。

该表格仅由 hf CLI 读取。run_uv_job() 和 create_scheduled_uv_job() 会忽略它，因此请从 Python 中显式传入 image=、flavor= 等参数。

Docker 任务

像使用 docker 一样，指定 Docker 镜像和要运行的命令：

>>> hf jobs run ubuntu echo "Hello from the cloud!"

在此，--help 会传递给 Python，而不是显示 Jobs 的帮助信息：

>>> hf jobs run --flavor cpu-basic python:3.12 -- python --help

在 CLI 文档中查找所有参数的列表。

有关使用现有镜像和由 Docker Spaces 构建的镜像的示例，请参阅使用 Docker 镜像。

环境变量和 Secrets

内置环境变量

与 Spaces 中的内置环境变量类似，Jobs 会在容器内自动提供以下环境变量：

变量	描述
`JOB_ID`	当前任务的唯一标识符（例如，`699d874f1aad19adb8aaeadc`）。这与 UI 和任务 URL 中显示的 ID 相同。
`ACCELERATOR`	可用的加速器类型（例如，`t4-medium`、`a10g-small`、`a100x4`），或者对于仅使用 CPU 的任务，使用 `none`。
`CPU_CORES`	分配给该作业的 CPU 核心数量。
`MEMORY`	分配给该任务的内存量（例如，`8Gi`）。
`HF_NETWORK_GROUP_HOSTNAME`	解析到该作业网络组中每个作业的 Hostname。仅在作业声明了网络组时才会设置。
`HF_NETWORK_GROUP_PREFIX`	要添加到别名前缀以获取声明该别名的组成员主机名的前缀（例如，`${HF_NETWORK_GROUP_PREFIX}master`）。仅在作业声明了网络组时设置。

您可以使用这些变量来跟踪输出、根据可用资源调整代码，或以编程方式引用当前任务：

# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"

用户定义的环境变量

您可以使用

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

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

# Pass secrets - they will be encrypted server side
>>> hf jobs uv run -s MY_SECRET=psswrd 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 uv run --secrets-file .env.secrets python -c 'import os; print(os.environ["MY_SECRET"])'

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

卷

使用 -v 或 --volume 将 Hugging Face 仓库（模型、数据集）、Storage Buckets 或本地目录作为卷挂载到您的作业容器中。Hub 源使用 hf:// URL 方案：hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]；本地目录则直接作为源传入。

由于挂载的文件是按需获取的，因此挂载功能可以让 Job 处理远大于其本地磁盘容量的数据集。有关在 Job 上挂载、流式传输和处理大数据集的信息，请参阅处理大型数据集。

卷类型：

类型	示例
模型仓库	`-v hf://openai/gpt-oss-120b:/model`
数据集仓库	`-v hf://datasets/stanfordnlp/imdb:/data`
存储桶	`-v hf://buckets/username/my-bucket:/mnt`
子文件夹	`-v hf://datasets/org/my-dataset/train:/data`
本地目录	`-v ./training-data:/data`

然后在容器内部将挂载的卷用作本地目录：

# Mount a dataset and query it with DuckDB
>>> hf jobs run -v hf://datasets/stanfordnlp/imdb:/dataset \
...     duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"

# Mount a bucket to save training checkpoints
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
...     sft.py --output-dir /training-outputs/training-v3-final

可以通过重复使用 -v 标志来挂载多个卷：

>>> hf jobs run -v hf://datasets/username/my-dataset:/data -v hf://buckets/username/my-bucket:/output \
...     python:3.12 python script.py

模型和数据集始终以只读方式挂载。存储桶默认是读写的，这便于保存输出、检查点或中间结果。使用:ro可以以只读模式挂载存储桶：

>>> hf jobs run -v hf://buckets/username/my-bucket:/mnt:ro python:3.12 ls /mnt

本地目录

将本地目录作为源传入时，会在 Job 启动前将其同步到私有的 jobs-artifacts Storage Bucket（自动创建），然后在容器中挂载该目录。本地目录默认以只读方式挂载；如需写入输出，请使用 :rw：

>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py

重新同步同一目录时，仅上传新增或已修改的文件。若要获取 Job 写入读写卷的文件，请在 Job 结束后将其存储桶文件夹同步回本地——Job 启动时，CLI 会打印出确切的 hf buckets sync 命令。定时任务同样适用：创建计划时目录会同步一次，每次触发都会挂载相同的文件夹。在 Python 中，请使用 sync_job_volume。

在 Python 中，使用 Volume 类：

from huggingface_hub import Volume, run_job

job = run_job(
    image="python:3.12",
    command=["python", "-c", "import os; print(os.listdir('/data'))"],
    volumes=[
        Volume(type="dataset", source="username/my-dataset", mount_path="/data"),
        Volume(type="bucket", source="username/my-bucket", mount_path="/output"),
    ],
)

使用卷挂载需要 huggingface_hub >= 1.8.0。有关更多详细信息，请参阅 Python 客户端文档和安装指南。

硬件类型

使用 flavor 参数在 GPU 或 TPU 上运行任务。例如，要在 A10G GPU 上运行 PyTorch 任务：

>>> hf jobs uv run --with torch --flavor a10g-small 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

以下是另一个运行微调脚本（例如 trl/scripts/sft.py）的示例：

>>> hf jobs uv run --with trl --flavor a10g-small -s HF_TOKEN -- sft.py --model_name_or_path Qwen/Qwen2-0.5B ...

如需了解如何在 Hugging Face 基础设施上使用 TRL 运行模型训练任务的全面指南，请参阅 TRL Jobs 训练文档。该文档涵盖了微调方案、硬件选择以及高效训练模型的最佳实践。

使用 hf jobs hardware 命令查看可用的 --flavor 选项列表（默认为 cpu-basic）：

>>> hf jobs hardware
name             pretty name             cpu       ram      storage   accelerator               cost/min  cost/hour
cpu-basic        CPU Basic               2 vCPU    16 GB    50 GB                               $0.0002   $0.01
cpu-upgrade      CPU Upgrade             8 vCPU    32 GB    50 GB                               $0.0005   $0.03
cpu-performance  CPU Performance         32 vCPU   256 GB   1024 GB                             $0.0317   $1.90
cpu-xl           CPU XL                  16 vCPU   124 GB   1000 GB                             $0.0167   $1.00
t4-small         Nvidia T4 - small       4 vCPU    15 GB    50 GB     1x T4 (16 GB)             $0.0067   $0.40
t4-medium        Nvidia T4 - medium      8 vCPU    30 GB    100 GB    1x T4 (16 GB)             $0.0100   $0.60
a10g-small       Nvidia A10G - small     4 vCPU    15 GB    110 GB    1x A10G (24 GB)           $0.0167   $1.00
a10g-large       Nvidia A10G - large     12 vCPU   46 GB    200 GB    1x A10G (24 GB)           $0.0250   $1.50
a10g-largex2     2x Nvidia A10G - large  24 vCPU   92 GB    1000 GB   2x A10G (48 GB)           $0.0500   $3.00
a10g-largex4     4x Nvidia A10G - large  48 vCPU   184 GB   2000 GB   4x A10G (96 GB)           $0.0833   $5.00
a100-large       Nvidia A100 - large     12 vCPU   142 GB   1000 GB   1x A100 (80 GB)           $0.0417   $2.50
a100x4           4x Nvidia A100          48 vCPU   568 GB   4000 GB   4x A100 (320 GB)          $0.1667   $10.00
a100x8           8x Nvidia A100          96 vCPU   1136 GB  8000 GB   8x A100 (640 GB)          $0.3333   $20.00
h200             Nvidia H200             23 vCPU   256 GB   3000 GB   1x H200 (141 GB)          $0.0833   $5.00
h200x2           Nvidia H200             46 vCPU   512 GB   6000 GB   2x H200 (282 GB)          $0.1667   $10.00
h200x4           Nvidia H200             92 vCPU   1024 GB  12000 GB  4x H200 (564 GB)          $0.3333   $20.00
h200x8           Nvidia H200             184 vCPU  2048 GB  24000 GB  8x H200 (1128 GB)         $0.6667   $40.00
rtx-pro-6000     Nvidia RTX PRO 6000     23 vCPU   256 GB   475 GB    1x RTX PRO 6000 (96 GB)   $0.0458   $2.75
rtx-pro-6000x2   Nvidia RTX PRO 6000     46 vCPU   512 GB   950 GB    2x RTX PRO 6000 (192 GB)  $0.0917   $5.50
rtx-pro-6000x4   Nvidia RTX PRO 6000     92 vCPU   1024 GB  1900 GB   4x RTX PRO 6000 (384 GB)  $0.1833   $11.00
rtx-pro-6000x8   Nvidia RTX PRO 6000     184 vCPU  2048 GB  3800 GB   8x RTX PRO 6000 (768 GB)  $0.3667   $22.00
l4x1             1x Nvidia L4            8 vCPU    30 GB    400 GB    1x L4 (24 GB)             $0.0133   $0.80
l4x4             4x Nvidia L4            48 vCPU   186 GB   3200 GB   4x L4 (96 GB)             $0.0633   $3.80
l40sx1           1x Nvidia L40S          8 vCPU    62 GB    380 GB    1x L40S (48 GB)           $0.0300   $1.80
l40sx4           4x Nvidia L40S          48 vCPU   382 GB   3200 GB   4x L40S (192 GB)          $0.1383   $8.30
l40sx8           8x Nvidia L40S          192 vCPU  1534 GB  6500 GB   8x L40S (384 GB)          $0.3917   $23.50

暴露端口

作业可以通过公共作业代理使用 --expose <port>（CLI）或 expose=[<port>]（Python API）来暴露容器端口。每个暴露的端口都可以通过 https://<job_id>--<port>.hf.jobs 访问，并且需要一个对作业命名空间具有 read 访问权限的 HF token：

curl -H "Authorization: Bearer $HF_TOKEN" https://<job_id>--<port>.hf.jobs/

此功能适用于 hf jobs run、hf jobs uv run 及其定时任务变体。重复该标志以公开多个端口（--expose 8000 --expose 8001），或在列表中传入多个端口（expose=[8000, 8001]）。

若要在没有 HF token 的情况下使端口可访问，请改用 --expose-public <port>（CLI）或 expose_public=[<port>]（Python API）。这样，任何拥有该 URL 的人都可以访问此端口，因此请仅将其用于可以安全共享的服务。您可以同时使用这两个选项：部分端口需要 HF token，而其他端口则公开访问。

暴露的端口会在任务运行期间，在任务硬件价格的基础上按每小时固定费率额外计费。详情请参阅定价页面。

CLI

# Expose a web server running on port 8000
>>> hf jobs run --expose 8000 python:3.12 python -m http.server 8000
✓ Job started
  id: 6a2aa7cec4f53f9fc5aa4cff
  url: https://huggingface.co/jobs/Wauplin/6a2aa7cec4f53f9fc5aa4cff
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a2aa7cec4f53f9fc5aa4cff--8000.hf.jobs
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

Python

>>> from huggingface_hub import run_job
>>> job = run_job(image="python:3.12", command=["python", "-m", "http.server", "8000"], expose=[8000])
>>> job.status.expose_urls
['https://6a2ab384c4f53f9fc5aa4d4f--8000.hf.jobs']

更改正在运行的 Job 的端口

使用 hf jobs expose 可以更改暴露的端口，而无需重启 Job：

# Expose port 8000 (requires an HF token)
>>> hf jobs expose <job_id> 8000

# Expose port 8000 (requires an HF token) and port 9000 publicly
>>> hf jobs expose <job_id> 8000 --public 9000

# Close all exposed ports
>>> hf jobs expose <job_id> --clear

该命令会替换完整的暴露端口列表，因此未包含在内的端口将被关闭。在 Python 中，请使用 update_job_expose。

SSH

您可以打开一个交互式 SSH 会话，进入正在运行的 Job 进行调试、检查，或直接在容器内操作。在创建 Job 时通过 --ssh（CLI）或 ssh=True（Python API）启用此功能，然后使用 hf jobs ssh <job_id> 进行连接。

仅允许对作业命名空间具有写入权限的用户（即作业创建者，或拥有写入权限的所有者组织成员）。身份验证通过注册在 https://huggingface.co/settings/keys 的 SSH 公钥进行。

hf jobs run 和 hf jobs uv run 支持 SSH。计划任务不支持 SSH。

CLI

# Start a job with SSH enabled
>>> hf jobs run --ssh --detach --timeout 10m python:3.12 sleep infinity
✓ Job started
  id: 6a2bd1f1871c005b5352ad31
  url: https://huggingface.co/jobs/Wauplin/6a2bd1f1871c005b5352ad31
Hint: Use `hf jobs ssh 6a2bd1f1871c005b5352ad31` to open an SSH session into the job.

# Open an SSH session into the job
>>> hf jobs ssh 6a2bd1f1871c005b5352ad31

您也可以在不执行的情况下打印 SSH 命令（--dry-run），或传入特定的身份文件（-i/--identity-file）：

>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 --dry-run
ssh 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 -i ~/.ssh/id_ed25519

Python

>>> from huggingface_hub import run_job
>>> job = run_job(image="python:3.12", command=["sleep", "infinity"], ssh=True)
>>> job.status.ssh_url
'ssh://6a2bd1f1871c005b5352ad31@ssh.hf.jobs'

然后在终端中使用 hf jobs ssh <job_id> 进行连接，或者直接使用 ssh <job_id>@ssh.hf.jobs。

端口转发

由于这是一个普通的 SSH 连接，您可以使用 SSH 的 -L 和 -R 标志在您的机器和 Job 之间转发端口。直接使用 ssh 连接（使用 hf jobs ssh <job_id> --dry-run 获取确切的目的地），并添加转发标志。

使用 -L（本地转发）从您的机器访问在 Job 内部运行的服务。例如，要访问在训练 Job 中启动的 TensorBoard：

# Forward local port 6006 to the Job's TensorBoard on port 6006
>>> ssh -L 6006:localhost:6006 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

然后在浏览器中打开 http://localhost:6006。

使用 -R（远程转发）让 Job 访问运行在你机器上的服务。例如，将本地数据库或 API 暴露给 Job：

# Make your local port 8080 reachable from inside the Job on port 8080
>>> ssh -R 8080:localhost:8080 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

网络组

作业可以使用 --network-group <name>（CLI）或 network_group="<name>"（Python API）加入网络组。同一命名空间和资源组中共享同一组的作业可以在所有端口上相互访问：HF_NETWORK_GROUP_HOSTNAME 会解析到所有成员，而 ${HF_NETWORK_GROUP_PREFIX}<alias> 会解析到使用 --network-alias <alias>（CLI）或 network_aliases=[<alias>]（Python API）声明了别名的成员。

此功能适用于 hf jobs run 和 hf jobs uv run。成员在就绪之前即可解析，因此连接时需进行重试。组名和别名仅包含小写字母、数字和连字符，最大长度分别为 46 和 34 个字符；作业的别名必须唯一。

CLI

# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000

# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'

Python

>>> from huggingface_hub import run_job
>>> server = run_job(
...     image="python:3.12",
...     command=["python", "-m", "http.server", "8000"],
...     network_group="train",
...     network_aliases=["master"],
... )
>>> client = run_job(
...     image="python:3.12",
...     command=["sh", "-c", 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'],
...     network_group="train",
... )

多节点训练框架可以使用别名作为会合主机，例如 torchrun --master_addr "${HF_NETWORK_GROUP_PREFIX}master"。

超时

任务具有默认超时时间（30 分钟），超时后会自动停止。在运行模型训练等长时间任务时，了解这一点非常重要。

在运行作业时，您可以使用 --timeout 参数指定自定义超时值。超时的指定方式有两种：

作为数字（解释为秒）：

使用 --timeout 并传入以秒为单位的数值（此处 2 小时 = 7200 秒）：

>>> hf jobs uv run --timeout 7200 --with torch --flavor a10g-large train.py

作为带时间单位的字符串：

或者使用 --timeout 并采用不同的时间单位：

>>> hf jobs uv run --timeout 2h --with torch --flavor a10g-large train.py

其他示例：

--timeout 30m    # 30 minutes
--timeout 1.5h   # 1.5 hours
--timeout 1d     # 1 day
--timeout 3600s  # 3600 seconds

支持的时间单位：

s - 秒
m - 分钟
h - 小时
d - 天

如果未指定超时时间，系统将为您提交的任务应用默认超时时间。对于可能需要数小时的长时间运行任务（例如模型训练），请务必设置合适的超时时间，以避免任务意外终止。

重试

默认情况下，Job 只运行一次。使用 --attempts <n>（CLI）或 attempts=<n>（Python API）来重试失败的 Job。该次数包含首次运行，因此 --attempts 3 允许最多两次重试：

>>> hf jobs uv run --attempts 3 --flavor a10g-large train.py

此功能适用于 hf jobs run、hf jobs uv run 及其定时任务变体。

重试会在相同的 Job ID 下从头开始重新运行该命令。若要让重试从上次尝试停止的位置继续，请将检查点写入已挂载的存储桶，并让脚本从这些检查点恢复。请参阅 Train Models on Jobs 中的 After it ends。

命名空间

使用 --namespace 参数在您的组织账户下运行任务。请确保您已使用具有在组织账户下启动和管理任务权限的令牌登录。

>>> hf jobs uv run --namespace my-org-name python -c "print('Running in an org account')"

请注意，您可以手动传递具有相应权限的令牌：

>>> hf jobs uv run --namespace my-org-name --token hf_xxx python -c "print('Running in an org account')"

如果未传入 --name，Job 的名称将基于其 Docker 镜像或脚本名称，再加上命令的短哈希值。这样，相同命令的重新运行会共享同一名称，而不同命令则会获得不同的名称（例如，在 python:3.12 上运行的 Job 会被命名为 python-3-12-6b9d662c）。

更新标签

使用 hf jobs labels 更新现有 Job 的标签。传入 --label 会替换所有现有标签；仅传入 --name 则会保留它们：

# Replace the labels on a Job
hf jobs labels <job_id> --label env=prod --label team=ml

# Name an existing Job (keeps its other labels)
hf jobs labels <job_id> --name daily-report

# Remove all labels from a Job
hf jobs labels <job_id> --clear

Update on GitHub

←管理任务使用 Docker 镜像→

Hub

配置

身份验证

传递参数

UV 任务

在脚本中定义启动配置

Docker 任务

环境变量和 Secrets

内置环境变量

用户定义的环境变量

卷

本地目录

硬件类型

暴露端口

CLI

Python

更改正在运行的 Job 的端口

SSH

CLI

Python

端口转发

网络组

CLI

Python

超时

重试

命名空间

标签

为作业命名

更新标签