Hugging Face 的 LOGO

Hub Python 庫文件

執行和管理任務

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

執行和管理任務

Hugging Face Hub 透過任務提供 AI 和資料工作流的計算能力。

有關任務和定價的概述，請參閱 Hub 任務文件。

任務在 Hugging Face 基礎設施上執行，並透過要執行的命令（例如 Python 命令）、來自 Hugging Face Spaces 或 Docker Hub 的 Docker 映象以及硬體型別（CPU、GPU、TPU）來定義。本指南將向您展示如何與 Hub 上的任務進行互動，特別是

  • 執行任務。
  • 檢查任務狀態。
  • 選擇硬體。
  • 配置環境變數和秘密。
  • 執行 UV 指令碼。

如果您想在 Hub 上執行和管理任務，您的計算機必須已登入。如果尚未登入，請參閱 此部分。在本指南的其餘部分，我們將假設您的計算機已登入。

Hugging Face 任務僅對 Pro 使用者以及 Team 或 Enterprise 組織可用。升級您的計劃即可開始！

任務命令列介面

使用 hf jobs CLI 從命令列執行任務，並透過 --flavor 指定您的硬體。

hf jobs run 使用 Docker 映象和命令以類似 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 命令列介面指南。

執行任務

在 Hugging Face 基礎設施上執行由命令和 Docker 映象定義的計算任務（包括 GPU 和 TPU）。

您只能管理您擁有的任務（在您的使用者名稱名稱空間下）或您擁有寫入許可權的組織中的任務。此功能按使用量付費：您只需為使用的秒數付費。

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() 檢視日誌，並使用 fetch_job_metrics() 監控資源使用情況。

檢查任務狀態

# 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 上執行任務的用例很多

  • 模型訓練：在 GPU (T4, A10G, A100) 上微調或訓練模型，無需管理基礎設施
  • 合成數據生成：使用 LLM 在強大的硬體上生成大規模資料集
  • 資料處理：使用高 CPU 配置處理海量資料集以進行並行工作負載
  • 批次推理：使用最佳化的 GPU 設定對數千個樣本進行離線推理
  • 實驗和基準測試：在一致的硬體上執行 ML 實驗以獲得可重現的結果
  • 開發和除錯：無需本地 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",
... )

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

可用的 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 的基礎設施上執行程式碼。

配置任務超時

任務有預設超時時間（30 分鐘），之後任務將自動停止。這一點在使用模型訓練等長時間執行的任務時非常重要。

設定自定義超時

您可以在執行任務時使用 timeout 引數指定自定義超時值。超時可以有兩種方式指定

  1. 作為數字（解釋為秒）
>>> 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
... )
  1. 作為帶有時間單位的字串:
>>> # 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"},
... )

標籤

標籤是應用於任務元資料的鍵值對

# 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 指令碼可以內聯指定其依賴項，但 ML 工作負載通常具有複雜的依賴項。使用預構建的 Docker 映象並預先安裝這些庫可以顯著加快任務啟動速度並避免依賴項問題。

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

您可以使用 --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 時可以正常工作。

定時任務

排程和管理將在 HF 基礎設施上執行的任務。

使用 create_scheduled_job() 或 create_scheduled_uv_job()，並使用 @annually、@yearly、@monthly、@weekly、@daily、@hourly 的計劃，或者使用 CRON 計劃表示式（例如，"0 9 * * 1" 表示每週一早上 9 點）

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

透過 Webhook 觸發任務

Webhook 允許您監聽特定倉庫的新更改，或者監聽屬於特定使用者/組織的所有倉庫（不僅僅是您的倉庫，而是任何倉庫）。

使用 create_webhook() 建立一個 Webhook，當 Hugging Face 倉庫發生更改時觸發任務

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 會在 WEBHOOK_PAYLOAD 環境變數中攜帶 Webhook 有效負載來觸發任務。您可以在 Webhook 文件中找到有關 Webhook 的更多資訊。

在 GitHub 上更新

←推理端點 社群標籤→
© . This site is unofficial and not affiliated with Hugging Face, Inc.