執行和管理作業

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 庫