在 Hugging Face Jobs 基础设施上运行任意工作负载：UV 脚本、Docker 作业、硬件选择、成本估算、认证与密钥管理、超时配置和结果持久化，适合免本地环境的云端计算。

在 Hugging Face Jobs 上运行工作负载

概述

在完全托管的 Hugging Face 基础设施上运行任何工作负载。无需本地设置——作业在云 CPU、GPU 或 TPU 上运行，并可以将结果持久化到 Hugging Face Hub。

常见用例：

数据处理 - 转换、过滤或分析大型数据集
批量推理 - 对数千个样本运行推理
实验和基准测试 - 可重现的 ML 实验
模型训练 - 微调模型（具体训练见 model-trainer 技能）
合成数据生成 - 使用 LLM 生成数据集
开发和测试 - 无需本地 GPU 设置即可测试代码
计划作业 - 自动化重复任务

专门用于模型训练： 请参阅 model-trainer 技能了解基于 TRL 的训练工作流程。

何时使用此技能

当用户想要以下情况时使用此技能：

在云基础设施上运行 Python 工作负载
无需本地 GPU/TPU 设置即可执行作业
大规模处理数据
运行批量推理或实验
计划重复任务
对任何工作负载使用 GPU/TPU
将结果持久化到 Hugging Face Hub

关键指令

在协助处理作业时：

始终使用 `hf_jobs()` MCP 工具 - 使用 hf_jobs("uv", {...}) 或 hf_jobs("run", {...}) 提交作业。script 参数直接接受 Python 代码。除非用户明确要求，否则不要保存到本地文件。将脚本内容作为字符串传递给 hf_jobs()。

始终处理认证 - 与 Hub 交互的作业需要通过密钥提供 HF_TOKEN。请参阅下面的令牌使用部分。

提交后提供作业详细信息 - 提交后，提供作业 ID、监控 URL、预计时间，并注意用户可以稍后请求状态检查。

设置适当的超时 - 默认 30 分钟对于长时间运行的任务可能不足。

先决条件检查清单

在开始任何作业之前，验证：

✅ 账户和认证

具有 Pro、Team 或 Enterprise 计划的 Hugging Face 账户（作业需要付费计划）
已认证登录：使用 hf_whoami() 检查
用于 Hub 访问的 HF_TOKEN ⚠️ 关键 - 任何 Hub 操作（推送模型/数据集、下载私有仓库等）都需要
令牌必须具有适当的权限（下载需要读取权限，上传需要写入权限）

✅ 令牌使用（详情见令牌使用部分）

何时需要令牌：

将模型/数据集推送到 Hub
访问私有仓库
在脚本中使用 Hub API
任何需要认证的 Hub 操作

如何提供令牌：

# hf_jobs MCP 工具 — $HF_TOKEN 会自动替换为真实令牌：
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}

# HfApi().run_uv_job() — 必须传递实际令牌：
from huggingface_hub import get_token
secrets={"HF_TOKEN": get_token()}

⚠️ 关键： $HF_TOKEN 占位符仅由 hf_jobs MCP 工具自动替换。使用 HfApi().run_uv_job() 时，必须通过 get_token() 传递真实令牌。传递字面字符串 "$HF_TOKEN" 会导致 9 个字符的无效令牌和 401 错误。

令牌使用指南

了解令牌

什么是 HF 令牌？

Hugging Face Hub 的认证凭据
需要认证操作（推送、私有仓库、API 访问）
在 hf auth login 后安全地存储在您的机器上

令牌类型：

读取令牌 - 可以下载模型/数据集，读取私有仓库
写入令牌 - 可以推送模型/数据集，创建仓库，修改内容
组织令牌 - 可以代表组织操作

何时需要令牌

始终需要：

将模型/数据集推送到 Hub
访问私有仓库
创建新仓库
修改现有仓库
以编程方式使用 Hub API

不需要：

下载公共模型/数据集
运行不与 Hub 交互的作业
读取公共仓库信息

如何向作业提供令牌

方法 1：自动令牌（推荐）

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # ✅ 自动替换
})

工作原理：

$HF_TOKEN 是一个占位符，会被您的实际令牌替换
使用您登录会话中的令牌（hf auth login）
最安全、最方便的方法
令牌作为密钥传递时在服务器端加密

优势：

代码中不暴露令牌
使用您当前的登录会话
如果重新登录会自动更新
与 MCP 工具无缝配合

方法 2：显式令牌（不推荐）

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ 硬编码令牌
})

何时使用：

仅当自动令牌不起作用时
使用特定令牌进行测试
组织令牌（谨慎使用）

安全问题：

令牌在代码/日志中可见
如果令牌轮换必须手动更新
令牌暴露风险

方法 3：环境变量（安全性较低）

hf_jobs("uv", {
    "script": "your_script.py",
    "env": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ 比密钥安全性低
})

与密钥的区别：

env 变量在作业日志中可见
secrets 在服务器端加密
对于令牌始终优先使用 secrets

在脚本中使用令牌

在您的 Python 脚本中，令牌作为环境变量可用：

# /// script
# dependencies = ["huggingface-hub"]
# ///

import os
from huggingface_hub import HfApi

# 如果通过密钥传递，令牌自动可用
token = os.environ.get("HF_TOKEN")

# 与 Hub API 一起使用
api = HfApi(token=token)

# 或者让 huggingface_hub 自动检测
api = HfApi()  # 自动使用 HF_TOKEN 环境变量

最佳实践：

不要在脚本中硬编码令牌
使用 os.environ.get("HF_TOKEN") 访问
尽可能让 huggingface_hub 自动检测
在 Hub 操作之前验证令牌存在

令牌验证

检查是否已登录：

from huggingface_hub import whoami
user_info = whoami()  # 如果已认证，返回您的用户名

在作业中验证令牌：

import os
assert "HF_TOKEN" in os.environ, "未找到 HF_TOKEN！"
token = os.environ["HF_TOKEN"]
print(f"令牌以：{token[:7]}... 开头")  # 应该以 "hf_" 开头

常见令牌问题

错误：401 Unauthorized

原因： 令牌缺失或无效
修复： 将 secrets={"HF_TOKEN": "$HF_TOKEN"} 添加到作业配置
验证： 检查 hf_whoami() 在本地是否工作

错误：403 Forbidden

原因： 令牌缺少所需权限
修复： 确保令牌具有推送操作的写入权限
检查： 在 https://huggingface.co/settings/tokens 检查令牌类型

错误：环境中未找到令牌

原因： 未传递 secrets 或密钥名称错误
修复： 使用 secrets={"HF_TOKEN": "$HF_TOKEN"}（而不是 env）
验证： 脚本检查 os.environ.get("HF_TOKEN")

错误：仓库访问被拒绝

原因： 令牌无权访问私有仓库
修复： 使用有访问权限的账户的令牌
检查： 验证仓库可见性和您的权限

令牌安全最佳实践

永远不要提交令牌 - 使用 $HF_TOKEN 占位符或环境变量
使用密钥而不是 env - 密钥在服务器端加密
定期轮换令牌 - 定期生成新令牌
使用最小权限 - 创建仅具有所需权限的令牌
不要共享令牌 - 每个用户应使用自己的令牌
监控令牌使用 - 在 Hub 设置中检查令牌活动

完整令牌示例

# 示例：将结果推送到 Hub
hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["huggingface-hub", "datasets"]
# ///

import os
from huggingface_hub import HfApi
from datasets import Dataset

# 验证令牌可用
assert "HF_TOKEN" in os.environ, "需要 HF_TOKEN！"

# 使用令牌进行 Hub 操作
api = HfApi(token=os.environ["HF_TOKEN"])

# 创建并推送数据集
data = {"text": ["Hello", "World"]}
dataset = Dataset.from_dict(data)
dataset.push_to_hub("username/my-dataset", token=os.environ["HF_TOKEN"])

print("✅ 数据集推送成功！")
""",
    "flavor": "cpu-basic",
    "timeout": "30m",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # ✅ 安全提供令牌
})

快速开始：两种方法

方法 1：UV 脚本（推荐）

UV 脚本使用 PEP 723 内联依赖项，实现简洁、自包含的工作负载。

MCP 工具：

hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["transformers", "torch"]
# ///

from transformers import pipeline
import torch

# 您的工作负载在这里
classifier = pipeline("sentiment-analysis")
result = classifier("I love Hugging Face!")
print(result)
""",
    "flavor": "cpu-basic",
    "timeout": "30m"
})

CLI 等效命令：

hf jobs uv run my_script.py --flavor cpu-basic --timeout 30m

Python API：

from huggingface_hub import run_uv_job
run_uv_job("my_script.py", flavor="cpu-basic", timeout="30m")

优势： 直接使用 MCP 工具，代码简洁，依赖项内联声明，无需保存文件

何时使用： 所有工作负载的默认选择、自定义逻辑、任何需要 hf_jobs() 的场景

UV 脚本的自定义 Docker 镜像

默认情况下，UV 脚本使用 ghcr.io/astral-sh/uv:python3.12-bookworm-slim。对于具有复杂依赖项的 ML 工作负载，使用预构建镜像：

hf_jobs("uv", {
    "script": "inference.py",
    "image": "vllm/vllm-openai:latest",  # 预构建的 vLLM 镜像
    "flavor": "a10g-large"
})

CLI：

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

优势： 更快的启动、预安装的依赖项、针对特定框架优化

Python 版本

默认情况下，UV 脚本使用 Python 3.12。指定不同的版本：

hf_jobs("uv", {
    "script": "my_script.py",
    "python": "3.11",  # 使用 Python 3.11
    "flavor": "cpu-basic"
})

Python API：

from huggingface_hub import run_uv_job
run_uv_job("my_script.py", python="3.11")

处理脚本

⚠️ 重要： 根据您运行 Jobs 的方式，有*两个*"脚本路径"故事：

使用 `hf_jobs()` MCP 工具（在此仓库中推荐）：script 值必须是内联代码（字符串）或 URL。本地文件系统路径（如 "./scripts/foo.py"）在远程容器内不存在。
使用 `hf jobs uv run` CLI：本地文件路径可以工作（CLI 会上传您的脚本）。

使用 `hf_jobs()` MCP 工具的常见错误：

# ❌ 将失败（远程容器看不到您的本地路径）
hf_jobs("uv", {"script": "./scripts/foo.py"})

使用 `hf_jobs()` MCP 工具的正确模式：

# ✅ 内联：读取本地脚本文件并传递其*内容*
from pathlib import Path
script = Path("hf-jobs/scripts/foo.py").read_text()
hf_jobs("uv", {"script": script})

# ✅ URL：托管脚本到可访问的位置
hf_jobs("uv", {"script": "https://huggingface.co/datasets/uv-scripts/.../raw/main/foo.py"})

# ✅ 来自 GitHub 的 URL
hf_jobs("uv", {"script": "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py"})

CLI 等效命令（支持本地路径）：

hf jobs uv run ./scripts/foo.py -- --your --args

运行时添加依赖项

添加 PEP 723 标头之外的额外依赖项：

hf_jobs("uv", {
    "script": "inference.py",
    "dependencies": ["transformers", "torch>=2.0"],  # 额外依赖
    "flavor": "a10g-small"
})

Python API：

from huggingface_hub import run_uv_job
run_uv_job("inference.py", dependencies=["transformers", "torch>=2.0"])

方法 2：基于 Docker 的作业

使用自定义 Docker 镜像和命令运行作业。

MCP 工具：

hf_jobs("run", {
    "image": "python:3.12",
    "command": ["python", "-c", "print('Hello from HF Jobs!')"],
    "flavor": "cpu-basic",
    "timeout": "30m"
})

CLI 等效命令：

hf jobs run python:3.12 python -c "print('Hello from HF Jobs!')"

Python API：

from huggingface_hub import run_job
run_job(image="python:3.12", command=["python", "-c", "print('Hello!')"], flavor="cpu-basic")

优势： 完全的 Docker 控制、使用预构建镜像、运行任何命令

何时使用： 需要特定的 Docker 镜像、非 Python 工作负载、复杂环境

GPU 示例：

hf_jobs("run", {
    "image": "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
    "command": ["python", "-c", "import torch; print(torch.cuda.get_device_name())"],
    "flavor": "a10g-small",
    "timeout": "1h"
})

使用 Hugging Face Spaces 作为镜像：

您可以使用来自 HF Spaces 的 Docker 镜像：

hf_jobs("run", {
    "image": "hf.co/spaces/lhoestq/duckdb",  # Space 作为 Docker 镜像
    "command": ["duckdb", "-c", "SELECT 'Hello from DuckDB!'"],
    "flavor": "cpu-basic"
})

CLI：

hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c "SELECT 'Hello!'"

在 Hub 上查找更多 UV 脚本

uv-scripts 组织提供存储在 Hugging Face Hub 上作为数据集的现成 UV 脚本：

# 发现可用的 UV 脚本集合
dataset_search({"author": "uv-scripts", "sort": "downloads", "limit": 20})

# 探索特定集合
hub_repo_details(["uv-scripts/classification"], repo_type="dataset", include_readme=True)

流行集合： OCR、classification、synthetic-data、vLLM、dataset-creation

硬件选择

参考： HF Jobs 硬件文档（2025 年 7 月更新）

| 工作负载类型 | 推荐硬件 | 用例 |

|---------------|---------------------|----------|

| 数据处理、测试 | cpu-basic、cpu-upgrade | 轻量级任务 |

| 小型模型、演示 | t4-small | <1B 模型、快速测试 |

| 中型模型 | t4-medium、l4x1 | 1-7B 模型 |

| 大型模型、生产 | a10g-small、a10g-large | 7-13B 模型 |

| 超大型模型 | a100-large | 13B+ 模型 |

| 批量推理 | a10g-large、a100-large | 高吞吐量 |

| 多 GPU 工作负载 | l4x4、a10g-largex2、a10g-largex4 | 并行/大型模型 |

| TPU 工作负载 | v5e-1x1、v5e-2x2、v5e-2x4 | JAX/Flax、TPU 优化 |

所有可用规格：

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

指南：

从较小的硬件开始进行测试
根据实际需求扩展
对并行工作负载或大型模型使用多 GPU
对 JAX/Flax 工作负载使用 TPU
详见 references/hardware_guide.md 了解详细规格

关键：保存结果

⚠️ 临时环境——必须持久化结果

作业环境是临时的。作业结束时所有文件都会被删除。如果结果未持久化，所有工作都将丢失。

持久化选项

1. 推送到 Hugging Face Hub（推荐）

# 推送模型
model.push_to_hub("username/model-name", token=os.environ["HF_TOKEN"])

# 推送数据集
dataset.push_to_hub("username/dataset-name", token=os.environ["HF_TOKEN"])

# 推送工件
api.upload_file(
    path_or_fileobj="results.json",
    path_in_repo="results.json",
    repo_id="username/results",
    token=os.environ["HF_TOKEN"]
)

2. 使用外部存储

# 上传到 S3、GCS 等
import boto3
s3 = boto3.client('s3')
s3.upload_file('results.json', 'my-bucket', 'results.json')

3. 通过 API 发送结果

# POST 结果到您的 API
import requests
requests.post("https://your-api.com/results", json=results)

Hub 推送的必需配置

在作业提交中：

# hf_jobs MCP 工具：
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}  # 自动替换

# HfApi().run_uv_job()：
from huggingface_hub import get_token
secrets={"HF_TOKEN": get_token()}  # 必须传递真实令牌

在脚本中：

import os
from huggingface_hub import HfApi

# 令牌从密钥自动可用
api = HfApi(token=os.environ.get("HF_TOKEN"))

# 推送您的结果
api.upload_file(...)

验证检查清单

提交之前：

[ ] 已选择结果持久化方法
[ ] 如果使用 Hub，令牌在密钥中（MCP："$HF_TOKEN"，Python API：get_token()）
[ ] 脚本优雅地处理缺失的令牌
[ ] 测试持久化路径是否工作

详见： references/hub_saving.md 了解详细的 Hub 持久化指南

超时管理

⚠️ 默认：30 分钟

作业在超时后自动停止。对于训练等长时间运行的任务，始终设置自定义超时。

设置超时

MCP 工具：

{
    "timeout": "2h"   # 2 小时
}

支持的格式：

整数/浮点数：秒（例如，300 = 5 分钟）
带后缀的字符串："5m"（分钟）、"2h"（小时）、"1d"（天）
示例："90m"、"2h"、"1.5h"、300、"1d"

Python API：

from huggingface_hub import run_job, run_uv_job

run_job(image="python:3.12", command=[...], timeout="2h")
run_uv_job("script.py", timeout=7200)  # 2 小时，以秒为单位

超时指南

| 场景 | 推荐 | 备注 |

|----------|-------------|-------|

| 快速测试 | 10-30 分钟 | 验证设置 |

| 数据处理 | 1-2 小时 | 取决于数据大小 |

| 批量推理 | 2-4 小时 | 大批量 |

| 实验 | 4-8 小时 | 多次运行 |

| 长时间运行 | 8-24 小时 | 生产工作负载 |

始终添加 20-30% 的缓冲时间用于设置、网络延迟和清理。

超时时： 作业立即终止，所有未保存的进度丢失

成本估算

一般指南：

总成本 =（运行小时数）×（每小时成本）

示例计算：

快速测试：

硬件：cpu-basic（$0.10/小时）
时间：15 分钟（0.25 小时）
成本：$0.03

数据处理：

硬件：l4x1（$2.50/小时）
时间：2 小时
成本：$5.00

批量推理：

硬件：a10g-large（$5/小时）
时间：4 小时
成本：$20.00

成本优化技巧：

从小开始 - 在 cpu-basic 或 t4-small 上测试
监控运行时间 - 设置适当的超时
使用检查点 - 如果作业失败则恢复
优化代码 - 减少不必要的计算
选择正确的硬件 - 不要过度配置

监控和跟踪

检查作业状态

MCP 工具：

# 列出所有作业
hf_jobs("ps")

# 检查特定作业
hf_jobs("inspect", {"job_id": "your-job-id"})

# 查看日志
hf_jobs("logs", {"job_id": "your-job-id"})

# 取消作业
hf_jobs("cancel", {"job_id": "your-job-id"})

Python API：

from huggingface_hub import list_jobs, inspect_job, fetch_job_logs, cancel_job

# 列出您的作业
jobs = list_jobs()

# 仅列出运行中的作业
running = [j for j in list_jobs() if j.status.stage == "RUNNING"]

# 检查特定作业
job_info = inspect_job(job_id="your-job-id")

# 查看日志
for log in fetch_job_logs(job_id="your-job-id"):
    print(log)

# 取消作业
cancel_job(job_id="your-job-id")

CLI：

hf jobs ps                    # 列出作业
hf jobs logs <job-id>         # 查看日志
hf jobs cancel <job-id>       # 取消作业

记住： 等待用户请求状态检查。避免重复轮询。

作业 URL

提交后，作业具有监控 URL：

https://huggingface.co/jobs/username/job-id

在浏览器中查看日志、状态和详细信息。

等待多个作业

import time
from huggingface_hub import inspect_job, run_job

# 运行多个作业
jobs = [run_job(image=img, command=cmd) for img, cmd in workloads]

# 等待所有作业完成
for job in jobs:
    while inspect_job(job.id).status.stage != "FINISHED":
        time.sleep(30)

故障排除

作业失败

常见原因：

缺少依赖项
脚本中的语法错误
令牌问题（401/403 错误）
超时
内存不足

调试步骤：

检查日志：hf_jobs("logs", {"job_id": "your-job-id"})
验证令牌：hf_whoami()
在本地测试脚本
增加超时
升级硬件规格

作业卡住

可能原因：

无限循环
等待用户输入
网络问题

解决方案：

取消作业：hf_jobs("cancel", {"job_id": "your-job-id"})
添加超时
添加日志以跟踪进度

内存错误

症状：

OOM（内存不足）错误
作业崩溃

解决方案：

升级到更大的硬件规格
减少批量大小
使用量化模型
优化数据加载

网络问题

症状：

无法下载模型
无法连接到 Hub

解决方案：

检查令牌权限
验证网络连接
使用预构建镜像
在脚本中添加重试逻辑

参考文档

本技能

[硬件指南](./references/hardware_guide.md) - 详细的硬件规格和选择
[Hub 保存](./references/hub_saving.md) - 推送模型、数据集和工件
[令牌使用](./references/token_usage.md) - 认证和令牌管理
[故障排除](./references/troubleshooting.md) - 常见问题和解决方案

官方 Hugging Face Jobs

官方文档：https://huggingface.co/docs/hub/en/jobs
CLI 参考：hf jobs --help
Python API：https://huggingface.co/docs/huggingface_hub/en/guides/jobs

在 Hugging Face Jobs 上运行工作负载