執行與管理 Jobs

Hugging Face Hub 透過 Jobs 提供 AI 與資料工作流所需的運算能力。

有關 Jobs 的一般概覽與定價，請參閱 Hub Jobs 文件。

Job 在 Hugging Face 的基礎設施上運行，並定義了要執行的命令（例如 python 命令）、來自 Hugging Face Spaces 或 Docker Hub 的 Docker 映像，以及硬體類型（CPU、GPU、TPU）。本指南將向您展示如何在 Hub 上與 Jobs 互動，特別是：

執行一個 Job。
檢查 Job 狀態。
選擇硬體。
配置環境變數與秘密（secrets）。
執行 UV 腳本。

如果您想在 Hub 上執行並管理 Job，您的機器必須已登入。如果您尚未登入，請參考此章節。在本指南的後續內容中，我們將假設您的機器已登入。

Hugging Face Jobs 僅供 Pro 用戶與 Team 或 Enterprise 組織使用。升級您的方案以開始使用！

Jobs 命令列介面 (CLI)

使用 hf jobs CLI 從命令列執行 Jobs，並傳遞 --flavor 來指定您的硬體。

hf jobs run 使用 Docker 映像和命令來執行 Jobs，並具有熟悉的類 Docker 介面。就像 docker run，但可以在任何硬體上執行代碼。

>>> hf jobs run python:3.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 命令列介面指南。

執行一個 Job

在 Hugging Face 的基礎設施（包括 GPU 和 TPU）上，執行以命令和 Docker 映像定義的運算 Jobs。

您只能管理您擁有的 Job（在您的用戶名稱命名空間下）或來自您具有寫入權限的組織的 Job。此功能採隨用隨付制：您只需為使用的秒數付費。

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")

重要提示：Job 設有預設逾時時間（30 分鐘），之後會自動停止。對於模型訓練等長時間執行的任務，請務必使用 timeout 參數設置自定義逾時。詳情請參閱配置 Job 逾時。

run_job() 會返回 JobInfo，其中包含 Job 在 Hugging Face 上的 URL，您可以在該處查看 Job 狀態與日誌。請從 JobInfo 中保存 Job 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

Jobs 在背景執行。下一節將引導您使用 inspect_job() 了解作業狀態，fetch_job_logs() 查看日誌，以及 fetch_job_metrics() 監控資源使用情況。

檢查 Job 狀態

# 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!

# View resources usage metrics from a job
>>> from huggingface_hub import fetch_job_metrics
>>> for metrics in fetch_job_metrics(job_id=job_id):
...     print(metrics)
{
    "cpu_usage_pct": 0,
    "cpu_millicores": 2000,
    "memory_used_bytes": 929792,
    "memory_total_bytes": 17179869184,
    "rx_bps": 0,
    "tx_bps": 0,
    "gpus": {},
    "replica": "4dzsh"
}

# 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 上執行 Jobs 是非常有用的

模型訓練：在 GPU (T4, A10G, A100) 上微調或訓練模型，無需管理基礎設施
合成數據生成：在強大的硬體上使用 LLM 生成大規模數據集
數據處理：使用高 CPU 配置處理海量數據集以進行並行工作負載
批次推論：使用優化的 GPU 設置對數千個樣本執行離線推論
實驗與基準測試：在一致的硬體上執行機器學習實驗以獲得可重複的結果
開發與除錯：測試 GPU 代碼而無需本地 CUDA 設置

使用 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

使用此命令搭配 UV 執行微調腳本，例如 trl/scripts/sft.py

>>> 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",
... )

有關在 Hugging Face 基礎設施上使用 TRL 執行模型訓練作業的全面指南，請參閱 TRL Jobs 訓練文件。內容涵蓋微調方案、硬體選擇以及高效訓練模型的最佳實踐。

可用的 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 文件）

就是這樣！您現在已在 Hugging Face 的基礎設施上執行代碼。

掛載磁碟卷

使用 Volume 列表在 Job 的磁碟上掛載磁碟卷。

您可以掛載任何 Hugging Face 存儲庫 (model/dataset/space) 或儲存貯體 (Storage Bucket)。例如：

掛載模型存儲庫：Volume(type="model", source="openai/gpt-oss-120b", mount_path="/model")
掛載數據集存儲庫：Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")
掛載儲存貯體：Volume(type="bucket", source="username/my-bucket", mount_path="/mnt")

接著，您就可以像使用本地目錄一樣使用掛載的磁碟卷

>>> from huggingface_hub import run_job, Volume
>>> job = run_job(
...     image="duckdb/duckdb",
...     command=["duckdb", "-c", "SELECT * FROM '/data/**/*.parquet' LIMIT 5"],
...     volumes=[Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")],
... )

您也可以寫入掛載的儲存貯體，例如在訓練模型時保存檢查點 (checkpoints)

>>> from huggingface_hub import run_uv_job, Volume
>>> script = "my_sft.py"
>>> script_args = ["--output_dir", "/training-outputs/training-v3-final", ...]
>>> checkpoints_bucket = Volume(type="bucket", source="username/my-bucket", mount_path="/training-outputs")
>>> run_uv_job(script, script_args=script_args, volumes=[checkpoints_bucket])

預設情況下，掛載的儲存貯體具有讀寫權限。這對於儲存貯體特別有用，因為它們為頻繁更改的數據提供了快速、可變的儲存空間——文件可以就地覆蓋或刪除。

使用 read_only=True 啟用唯讀：Volume(type="bucket", read_only=True, ...)。

配置 Job 逾時

Jobs 設有預設逾時時間（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 jobs 中使用逾時

對於 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)

有關 timeout 參數的更多詳情，請參閱 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"},
... )

內建環境變數

在作業容器內部，以下環境變數會自動生效：

可變	說明
`JOB_ID`	當前作業的唯一識別碼。可用於以程式化方式引用作業，例如將輸出存儲在具有唯一名稱的數據集中。
`ACCELERATOR`	可用的加速器類型（例如 `t4-medium`, `a10g-small`, `a100x4`）。如果沒有加速器則為空值。
`CPU_CORES`	作業可用的 CPU 核心數（例如 `2`, `4`, `8`）。
`MEMORY`	作業可用的記憶體量（例如 `16Gi`, `32Gi`）。

# Access job environment information
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", """
... import os
... print(f"Job ID: {os.environ.get('JOB_ID')}")
... print(f"Accelerator: {os.environ.get('ACCELERATOR', 'none')}")
... print(f"CPU cores: {os.environ.get('CPU_CORES')}")
... print(f"Memory: {os.environ.get('MEMORY')}")
... """],
... )

當您需要為輸出創建唯一識別碼、根據可用硬體調整代碼或記錄資源信息時，這些變數非常有用。

標籤 (Labels)

標籤 (Labels) 是 key=value 對，用於向作業套用詮釋資料 (metadata)。

# Pass extra metadata with Labels
>>> from huggingface_hub import run_job
>>> run_job(
...     image="python:3.12",
...     command=["python", "-c", "import os; print(os.environ['MY_SECRET'])"],
...     labels={"my-label": "my-value", "foo": "bar"},
... )

UV 腳本（實驗性）

正在尋找即開即用的 UV 腳本嗎？請查看 Hugging Face Hub 上的 uv-scripts 組織，該組織提供社群收集的 UV 腳本，可用於模型訓練、合成數據生成、數據處理等任務。

在 HF 基礎設施上執行 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")

# Run a command
>>> run_uv_job("python", script_args=["-c", "import lighteval"], dependencies=["lighteval"])

UV 腳本是 Python 腳本，透過特殊的註釋語法直接在文件中包含其依賴項。這使得它們非常適合不需要複雜項目設置的獨立任務。在 UV 文件中了解更多關於 UV 腳本的信息。

用於 UV 腳本的 Docker 映像

雖然 UV 腳本可以在內聯指定依賴項，但機器學習任務通常具有複雜的依賴。使用已安裝這些庫的預建 Docker 映像可以顯著加快作業啟動速度並避免依賴問題。

預設情況下，當您執行 hf jobs uv run 時，會使用 astral-sh/uv:python3.12-bookworm 映像。此映像基於預裝了 uv 的 Python 3.12 Bookworm 發行版。

您可以使用 --image 標籤指定不同的映像：

hf jobs uv run \
 --flavor a10g-large \
 --image vllm/vllm-openai:latest \
...

上述命令將使用 vllm/vllm-openai:latest 映像運行。如果您使用 vLLM 進行合成數據生成，此方法可能會很有用。

許多推論框架提供了經過優化的 Docker 映像。隨著 uv 在 Python 生態系統中被越來越多地採用，更多此類映像將會預裝 uv，這意味著它們在使用 hf jobs uv run 時也能正常工作。

排程作業 (Scheduled Jobs)

在 HF 基礎設施上排程與管理任務。

使用 create_scheduled_job() 或 create_scheduled_uv_job()，並設置 @annually（每年）、@yearly（每年）、@monthly（每月）、@weekly（每週）、@daily（每日）、@hourly（每小時）的排程，或使用 CRON 表達式（例如，每週一上午 9 點為 "0 9 * * 1"）。

# Schedule a job that runs every hour
>>> from huggingface_hub import create_scheduled_job
>>> create_scheduled_job(
...     image="python:3.12",
...     command=["python",  "-c", "print('This runs every hour!')"],
...     schedule="@hourly"
... )

# Use the CRON syntax
>>> create_scheduled_job(
...     image="python:3.12",
...     command=["python",  "-c", "print('This runs every 5 minutes!')"],
...     schedule="*/5 * * * *"
... )

# Schedule with GPU
>>> create_scheduled_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()}")'],
...     schedule="@hourly",
...     flavor="a10g-small",
... )

# Schedule a UV script
>>> from huggingface_hub import create_scheduled_uv_job
>>> create_scheduled_uv_job("my_script.py", schedule="@hourly")

使用與 run_job() 和 run_uv_job() 相同的參數來傳遞環境變數、秘密、逾時等。

使用 list_scheduled_jobs、inspect_scheduled_job()、suspend_scheduled_job()、resume_scheduled_job() 以及 delete_scheduled_job() 來管理排程作業。

# List your active scheduled jobs
>>> from huggingface_hub import list_scheduled_jobs
>>> list_scheduled_jobs()

# Inspect the status of a job
>>> from huggingface_hub import inspect_scheduled_job
>>> inspect_scheduled_job(scheduled_job_id)

# Suspend (pause) a scheduled job
>>> from huggingface_hub import suspend_scheduled_job
>>> suspend_scheduled_job(scheduled_job_id)

# Resume a scheduled job
>>> from huggingface_hub import resume_scheduled_job
>>> resume_scheduled_job(scheduled_job_id)

# Delete a scheduled job
>>> from huggingface_hub import delete_scheduled_job
>>> delete_scheduled_job(scheduled_job_id)

使用 webhooks 觸發 Jobs

Webhooks 讓您能夠監聽特定存儲庫或屬於特定用戶/組織集的所有存儲庫（不僅限於您的存儲庫，而是任何存儲庫）的新變更。

使用 create_webhook() 創建一個 webhook，當 Hugging Face 存儲庫發生變化時觸發 Job。

from huggingface_hub import create_webhook

# Example: Creating a webhook that triggers a Job
webhook = create_webhook(
    job_id=job_id,
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Webhook 會觸發 Job，並將 webhook payload 放入環境變數 WEBHOOK_PAYLOAD 中。您可以在 Webhooks 文件中找到更多關於 webhooks 的資訊。

在 GitHub 上更新

Hub Python 函式庫

執行與管理 Jobs

Jobs 命令列介面 (CLI)

執行一個 Job

檢查 Job 狀態

選擇硬體

掛載磁碟卷

配置 Job 逾時

設置自定義逾時

在 UV jobs 中使用逾時

監控作業執行時長

傳遞環境變數與秘密

內建環境變數

標籤 (Labels)

UV 腳本（實驗性）

用於 UV 腳本的 Docker 映像

排程作業 (Scheduled Jobs)

使用 webhooks 觸發 Jobs