运行和管理作业

Hugging Face Hub 通过作业为 AI 和数据工作流提供计算能力。作业在 Hugging Face 基础设施上运行，通过要运行的命令（例如 Python 命令）、来自 Hugging Face Spaces 或 Docker Hub 的 Docker 镜像以及硬件类型（CPU、GPU、TPU）来定义。本指南将向您展示如何与 Hub 上的作业进行交互，特别是：

运行作业。
检查作业状态。
选择硬件。
配置环境变量和密钥。
运行 UV 脚本。

如果您想在 Hub 上运行和管理作业，您的机器必须已登录。如果您尚未登录，请参阅此部分。本指南的其余部分将假设您的机器已登录。

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

作业命令行界面

使用hf jobs CLI从命令行运行作业，并传递--flavor来指定您的硬件。

hf jobs run 使用 Docker 镜像和命令运行作业，具有熟悉的类似 Docker 的界面。可以把它想象成docker run，但用于在任何硬件上运行代码。

>>> hf jobs run python:12 python -c "print('Hello world!')"
>>> 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())"

使用hf jobs uv run运行本地或远程 UV 脚本。

>>> hf jobs uv run my_script.py
>>> hf jobs uv run --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py"

UV 脚本是 Python 脚本，它们使用UV 文档中定义的特殊注释语法将依赖项直接包含在文件中。

本指南的其余部分将向您展示 Python API。如果您想查看所有可用的hf jobs命令和选项，请查看关于hf jobs命令行界面的指南。

运行作业

在 Hugging Face 基础设施（包括 GPU 和 TPU）上运行由命令和 Docker 镜像定义的计算作业。

您只能管理您自己拥有的（在您的用户名命名空间下）或您拥有写入权限的组织中的作业。此功能按需付费：您只需为您使用的时间付费。

run_job() 允许您在 Hugging Face 的基础设施上运行任何命令。

# Directly run Python code
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "print('Hello from the cloud!')"],
... )

# Use GPUs without any setup
>>> run_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python", "-c", "import torch; print(torch.cuda.get_device_name())"],
...     flavor="a10g-small",
... )

# Run in an organization account
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "print('Running in an org account')"],
...     namespace="my-org-name",
... )

# Run from Hugging Face Spaces
>>> run_job(
...     image="hf.co/spaces/lhoestq/duckdb",
...     command=["duckdb", "-c", "select 'hello world'"],
... )

# Run a Python script with `uv` (experimental)
>>> from huggingface_hub import run_uv_job
>>> run_uv_job("my_script.py")

重要提示：作业有默认超时（30 分钟），之后会自动停止。对于模型训练等长时间运行的任务，请务必使用timeout参数设置自定义超时。有关详细信息，请参阅配置作业超时。

run_job() 返回JobInfo，其中包含 Hugging Face 上作业的 URL，您可以在其中查看作业状态和日志。从JobInfo中保存作业 ID 以管理作业。

>>> from huggingface_hub import run_job
>>> job = run_job(
...     image="python:3.12",
...     command=["python", "-c", "print('Hello from the cloud!')"]
... )
>>> job.url
https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a
>>> job.id
687f911eaea852de79c4a50a

作业在后台运行。下一节将指导您使用inspect_job()来了解作业状态，以及使用fetch_job_logs()来查看日志。

检查作业状态

# List your jobs
>>> from huggingface_hub import list_jobs
>>> jobs = list_jobs()
>>> jobs[0]
JobInfo(id='687f911eaea852de79c4a50a', created_at=datetime.datetime(2025, 7, 22, 13, 24, 46, 909000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='COMPLETED', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a')

# List your running jobs
>>> running_jobs = [job for job in list_jobs() if job.status.stage == "RUNNING"]

# Inspect the status of a job
>>> from huggingface_hub import inspect_job
>>> inspect_job(job_id=job_id)
JobInfo(id='687f911eaea852de79c4a50a', created_at=datetime.datetime(2025, 7, 22, 13, 24, 46, 909000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='COMPLETED', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a')

# View logs from a job
>>> from huggingface_hub import fetch_job_logs
>>> for log in fetch_job_logs(job_id=job_id):
...     print(log)
Hello from the cloud!

# Cancel a job
>>> from huggingface_hub import cancel_job
>>> cancel_job(job_id=job_id)

使用循环和inspect_job()检查多个作业的状态，以了解它们何时全部完成。

# Run multiple jobs in parallel and wait for their completions
>>> import time
>>> from huggingface_hub import inspect_job, run_job
>>> jobs = [run_job(image=image, command=command) for command in commands]
>>> for job in jobs:
...     while inspect_job(job_id=job.id).status.stage not in ("COMPLETED", "ERROR"):
...         time.sleep(10)

选择硬件

在 GPU 上运行作业在许多情况下都非常有用：

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

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

# Use an A10G GPU to check PyTorch CUDA
>>> from huggingface_hub import run_job
>>> run_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"],
...     flavor="a10g-small",
... )

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

This code ran with the following GPU: NVIDIA A10G

使用此命令运行微调脚本，例如trl/scripts/sft.py与 UV。

>>> from huggingface_hub import run_uv_job
>>> run_uv_job(
...     "sft.py",
...     script_args=["--model_name_or_path", "Qwen/Qwen2-0.5B", ...],
...     dependencies=["trl"],
...     env={"HF_TOKEN": ...},
...     flavor="a10g-small",
... )

可用的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

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

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

配置作业超时

作业有默认超时（30 分钟），之后会自动停止。这对于运行模型训练等长时间任务非常重要。

设置自定义超时

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

作为数字（解释为秒）

>>> from huggingface_hub import run_job
>>> job = run_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python", "train_model.py"],
...     flavor="a10g-large",
...     timeout=7200,  # 2 hours in seconds
... )

作为带有时间单位的字符串:

>>> # Using different time units
>>> job = run_job(
...     image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
...     command=["python", "train_model.py"],
...     flavor="a10g-large",
...     timeout="2h",  # 2 hours
... )

>>> # Other examples:
>>> # timeout="30m"    # 30 minutes
>>> # timeout="1.5h"   # 1.5 hours
>>> # timeout="1d"     # 1 day
>>> # timeout="3600s"  # 3600 seconds

支持的时间单位：

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

在 UV 作业中使用超时

对于 UV 作业，您也可以指定超时。

>>> from huggingface_hub import run_uv_job
>>> job = run_uv_job(
...     "training_script.py",
...     flavor="a10g-large",
...     timeout="90m",  # 90 minutes
... )

如果您不指定超时，您的作业将应用默认超时。对于可能需要数小时才能完成的模型训练等长时间运行的任务，请务必设置适当的超时，以避免意外的作业终止。

监控作业持续时间

运行长时间任务时，最佳实践是：

估算作业的预期持续时间并设置包含一定缓冲的超时
通过日志监控作业进度
检查作业状态以确保其未超时

>>> from huggingface_hub import inspect_job, fetch_job_logs
>>> # Check job status
>>> job_info = inspect_job(job_id=job.id)
>>> if job_info.status.stage == "ERROR":
...     print(f"Job failed: {job_info.status.message}")
...     # Check logs for more details
...     for log in fetch_job_logs(job_id=job.id):
...         print(log)

有关超时参数的更多详细信息，请参阅run_job API 参考。

传递环境变量和密钥

您可以使用env和secrets将环境变量传递给您的作业。

# Pass environment variables
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "import os; print(os.environ['FOO'], os.environ['BAR'])"],
...     env={"FOO": "foo", "BAR": "bar"},
... )

# Pass secrets - they will be encrypted server side
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "import os; print(os.environ['MY_SECRET'])"],
...     secrets={"MY_SECRET": "psswrd"},
... )

UV 脚本（实验性）

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

# Run a UV script (creates temporary repo)
>>> from huggingface_hub import run_uv_job
>>> run_uv_job("my_script.py")

# Run with GPU
>>> run_uv_job("ml_training.py", flavor="gpu-t4-small")

# Run with dependencies
>>> run_uv_job("inference.py", dependencies=["transformers", "torch"])

# Run a script directly from a URL
>>> run_uv_job("https://huggingface.co/datasets/username/scripts/resolve/main/example.py")

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

< > 在 GitHub 上更新

Hub Python 库