hugging-face-jobs

在 Hugging Face Jobs 上运行工作负载

概览

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

常见用例：

• 数据处理 - 转换、筛选或分析大型数据集
• 批量推理 - 对数千个样本运行推理
• 实验与基准测试 - 可复现的机器学习实验
• 模型训练 - 微调模型（基于 TRL 的训练请参阅 model-trainer skill）
• 合成数据生成 - 使用大模型生成数据集
• 开发与测试 - 无需本地 GPU 设置即可测试代码
• 定时作业 - 自动执行重复任务

专门针对模型训练： 基于 TRL 的训练工作流请参阅 model-trainer skill。

何时使用此技能

当用户希望执行以下操作时，请使用此技能：

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

关键指示

协助处理作业时：

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

2. 始终处理身份验证 - 与 Hub 交互的作业需要通过密钥提供 HF_TOKEN。请参阅下方的 Token 使用部分。

3. 提交后提供作业详情 - 提交后，提供作业 ID、监控 URL、预计耗时，并说明用户之后可以请求查询状态。

4. 设置合适的超时时间 - 对于长时间运行的任务，默认的 30 分钟可能不够。

先决条件检查清单

开始任何作业前，请确认：

✅ 账户与身份验证

• 拥有 Hugging Face 账户，并订阅 Pro、Team 或 Enterprise 计划（Jobs 需要付费计划）
• 已完成身份验证登录：使用 hf_whoami() 检查
• 用于访问 Hub 的 HF_TOKEN ⚠️ 重要 - 执行任何 Hub 操作（推送模型/数据集、下载私有仓库等）都需要此令牌
• 令牌必须具备相应权限（下载需要读取权限，上传需要写入权限）

✅ 令牌用法（详情请参阅 Token 使用部分）

需要令牌的情况：

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

如何提供令牌：

# hf_jobs MCP tool — $HF_TOKEN is auto-replaced with real token:
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}

# HfApi().run_uv_job() — MUST pass actual token:
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"}  # ✅ Automatic replacement
})

工作原理：

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

优点：

• 不会在代码中暴露令牌
• 使用当前登录会话
• 重新登录后会自动更新
• 可与 MCP 工具无缝配合

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

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ Hardcoded token
})

适用场景：

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

安全隐患：

• 令牌会在代码/日志中显示
• 令牌轮换后必须手动更新
• 存在令牌泄露风险

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

hf_jobs("uv", {
    "script": "your_script.py",
    "env": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ Less secure than secrets
})

与密钥的区别：

• env 变量会显示在作业日志中
• secrets 会在服务器端加密
• 令牌应始终优先使用 secrets

在脚本中使用令牌

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

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

import os
from huggingface_hub import HfApi

# Token is automatically available if passed via secrets
token = os.environ.get("HF_TOKEN")

# Use with Hub API
api = HfApi(token=token)

# Or let huggingface_hub auto-detect
api = HfApi()  # Automatically uses HF_TOKEN env var

最佳实践：

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

令牌验证

检查是否已登录：

from huggingface_hub import whoami
user_info = whoami()  # Returns your username if authenticated

在作业中验证令牌：

import os
assert "HF_TOKEN" in os.environ, "HF_TOKEN not found!"
token = os.environ["HF_TOKEN"]
print(f"Token starts with: {token[:7]}...")  # Should start with "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")

错误：拒绝访问仓库

• 原因： 令牌无权访问私有仓库
• 修复方法： 使用有权访问该仓库的账户所对应的令牌
• 检查： 确认仓库的可见性和你的权限

令牌安全最佳实践

1. 切勿提交令牌——使用 $HF_TOKEN 占位符或环境变量
2. 使用 secrets，而非 env——Secrets 会在服务器端加密
3. 定期轮换令牌——定期生成新令牌
4. 使用最小权限——创建仅包含所需权限的令牌
5. 不要分享令牌——每位用户都应使用自己的令牌
6. 监控令牌使用情况——在 Hub 设置中检查令牌活动

完整令牌示例

# Example: Push results to Hub
hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["huggingface-hub", "datasets"]
# ///

import os
from huggingface_hub import HfApi
from datasets import Dataset

# Verify token is available
assert "HF_TOKEN" in os.environ, "HF_TOKEN required!"

# Use token for Hub operations
api = HfApi(token=os.environ["HF_TOKEN"])

# Create and push dataset
data = {"text": ["Hello", "World"]}
dataset = Dataset.from_dict(data)
dataset.push_to_hub("username/my-dataset", token=os.environ["HF_TOKEN"])

print("✅ Dataset pushed successfully!")
""",
    "flavor": "cpu-basic",
    "timeout": "30m",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # ✅ Token provided securely
})

快速入门：两种方式

方式 1：UV 脚本（推荐）

UV 脚本使用 PEP 723 内联依赖项来运行整洁、自包含的工作负载。

MCP 工具：

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

from transformers import pipeline
import torch

# Your workload here
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",  # Pre-built image with 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",  # Use 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 工具时的常见错误：

# ❌ Will fail (remote container can't see your local path)
hf_jobs("uv", {"script": "./scripts/foo.py"})

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

# ✅ Inline: read the local script file and pass its *contents*
from pathlib import Path
script = Path("hf-jobs/scripts/foo.py").read_text()
hf_jobs("uv", {"script": script})

# ✅ URL: host the script somewhere reachable
hf_jobs("uv", {"script": "https://huggingface.co/datasets/uv-scripts/.../raw/main/foo.py"})

# ✅ URL from GitHub
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"],  # Extra deps
    "flavor": "a10g-small"
})

Python API：

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

方法 2：基于 Docker 的 Jobs

使用自定义 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 as Docker image
    "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 组织提供了可直接使用的 UV 脚本，这些脚本以数据集形式存储在 Hugging Face Hub 上：

# Discover available UV script collections
dataset_search({"author": "uv-scripts", "sort": "downloads", "limit": 20})

# Explore a specific collection
hub_repo_details(["uv-scripts/classification"], repo_type="dataset", include_readme=True)

热门集合： OCR、分类、合成数据、vLLM、数据集创建

硬件选择

参考： HF Jobs 硬件文档（更新于 07/2025）

工作负载类型	推荐硬件	使用场景
数据处理、测试	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

关键事项：保存结果

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

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

持久化选项

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

# Push models
model.push_to_hub("username/model-name", token=os.environ["HF_TOKEN"])

# Push datasets
dataset.push_to_hub("username/dataset-name", token=os.environ["HF_TOKEN"])

# Push artifacts
api.upload_file(
    path_or_fileobj="results.json",
    path_in_repo="results.json",
    repo_id="username/results",
    token=os.environ["HF_TOKEN"]
)

2. 使用外部存储

# Upload to S3, GCS, etc.
import boto3
s3 = boto3.client('s3')
s3.upload_file('results.json', 'my-bucket', 'results.json')

3. 通过 API 发送结果

# POST results to your API
import requests
requests.post("https://your-api.com/results", json=results)

推送到 Hub 的必要配置

提交作业时：

# hf_jobs MCP tool:
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}  # auto-replaced

# HfApi().run_uv_job():
from huggingface_hub import get_token
secrets={"HF_TOKEN": get_token()}  # must pass real token

在脚本中：

import os
from huggingface_hub import HfApi

# Token automatically available from secrets
api = HfApi(token=os.environ.get("HF_TOKEN"))

# Push your results
api.upload_file(...)

验证清单

提交前：

• 选择结果持久化方式
• 如果使用 Hub，在 secrets 中配置 Token（MCP："$HF_TOKEN"，Python API：get_token()）
• 脚本能够妥善处理 Token 缺失的情况
• 测试持久化路径是否可用

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

超时管理

⚠️ 默认值：30 分钟

达到超时时间后，Jobs 会自动停止。对于训练等长时间运行的任务，务必设置自定义超时时间。

设置超时时间

MCP 工具：

{
    "timeout": "2h"   # 2 hours
}

支持的格式：

• 整数／浮点数：秒（例如，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 hours in seconds

超时指南

场景	建议时长	备注
快速测试	10-30 分钟	验证设置
数据处理	1-2 小时	取决于数据量
批量推理	2-4 小时	大批次
实验	4-8 小时	多次运行
长时间运行	8-24 小时	生产工作负载

务必额外预留 20-30% 的缓冲时间，用于设置、网络延迟和清理。

**超时后：**任务会立即终止，所有未保存的进度都会丢失

成本估算

一般指南：

Total Cost = (Hours of runtime) × (Cost per hour)

计算示例：

快速测试：

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

数据处理：

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

批量推理：

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

成本优化技巧：

1. 从小规模开始 - 在 cpu-basic 或 t4-small 上测试
2. 监控运行时间 - 设置合适的超时时间
3. 使用检查点 - 任务失败时可恢复运行
4. 优化代码 - 减少不必要的计算
5. 选择合适的硬件 - 不要过度配置

监控与跟踪

检查任务状态

MCP 工具：

# List all jobs
hf_jobs("ps")

# Inspect specific job
hf_jobs("inspect", {"job_id": "your-job-id"})

# View logs
hf_jobs("logs", {"job_id": "your-job-id"})

# Cancel a job
hf_jobs("cancel", {"job_id": "your-job-id"})

Python API：

from huggingface_hub import list_jobs, inspect_job, fetch_job_logs, cancel_job

# List your jobs
jobs = list_jobs()

# List running jobs only
running = [j for j in list_jobs() if j.status.stage == "RUNNING"]

# Inspect specific job
job_info = inspect_job(job_id="your-job-id")

# View logs
for log in fetch_job_logs(job_id="your-job-id"):
    print(log)

# Cancel a job
cancel_job(job_id="your-job-id")

CLI：

hf jobs ps                    # List jobs
hf jobs logs <job-id>         # View logs
hf jobs cancel <job-id>       # Cancel job

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

任务 URL

提交后，任务会有监控 URL：

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

在浏览器中查看日志、状态和详情。

等待多个任务

import time
from huggingface_hub import inspect_job, run_job

# Run multiple jobs
jobs = [run_job(image=img, command=cmd) for img, cmd in workloads]

# Wait for all to complete
for job in jobs:
    while inspect_job(job_id=job.id).status.stage not in ("COMPLETED", "ERROR"):
        time.sleep(10)

定时任务

使用 CRON 表达式或预定义计划定时运行任务。

MCP 工具：

# Schedule a UV script that runs every hour
hf_jobs("scheduled uv", {
    "script": "your_script.py",
    "schedule": "@hourly",
    "flavor": "cpu-basic"
})

# Schedule with CRON syntax
hf_jobs("scheduled uv", {
    "script": "your_script.py",
    "schedule": "0 9 * * 1",  # 9 AM every Monday
    "flavor": "cpu-basic"
})

# Schedule a Docker-based job
hf_jobs("scheduled run", {
    "image": "python:3.12",
    "command": ["python", "-c", "print('Scheduled!')"],
    "schedule": "@daily",
    "flavor": "cpu-basic"
})

Python API：

from huggingface_hub import create_scheduled_job, create_scheduled_uv_job

# Schedule a Docker job
create_scheduled_job(
    image="python:3.12",
    command=["python", "-c", "print('Running on schedule!')"],
    schedule="@hourly"
)

# Schedule a UV script
create_scheduled_uv_job("my_script.py", schedule="@daily", flavor="cpu-basic")

# Schedule with GPU
create_scheduled_uv_job(
    "ml_inference.py",
    schedule="0 */6 * * *",  # Every 6 hours
    flavor="a10g-small"
)

可用计划：

• @annually、@yearly - 每年一次
• @monthly - 每月一次
• @weekly - 每周一次
• @daily - 每天一次
• @hourly - 每小时一次
• CRON 表达式 - 自定义计划（例如，"*/5 * * * *" 表示每 5 分钟一次）

管理定时任务：

# MCP Tool
hf_jobs("scheduled ps")                              # List scheduled jobs
hf_jobs("scheduled inspect", {"job_id": "..."})     # Inspect details
hf_jobs("scheduled suspend", {"job_id": "..."})     # Pause
hf_jobs("scheduled resume", {"job_id": "..."})      # Resume
hf_jobs("scheduled delete", {"job_id": "..."})      # Delete

用于管理的 Python API：

from huggingface_hub import (
    list_scheduled_jobs,
    inspect_scheduled_job,
    suspend_scheduled_job,
    resume_scheduled_job,
    delete_scheduled_job
)

# List all scheduled jobs
scheduled = list_scheduled_jobs()

# Inspect a scheduled job
info = inspect_scheduled_job(scheduled_job_id)

# Suspend (pause) a scheduled job
suspend_scheduled_job(scheduled_job_id)

# Resume a scheduled job
resume_scheduled_job(scheduled_job_id)

# Delete a scheduled job
delete_scheduled_job(scheduled_job_id)

Webhook：在事件发生时触发任务

当 Hugging Face 仓库发生变更时自动触发任务。

Python API：

from huggingface_hub import create_webhook

# Create webhook that triggers a job when a repo changes
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"
)

工作原理：

1. Webhook 监听受监控仓库的变更
2. 触发后，任务会使用 WEBHOOK_PAYLOAD 环境变量运行
3. 脚本可以解析有效负载，了解发生了哪些变更

使用场景：

• 上传新数据集时自动处理
• 模型更新时触发推理
• 代码变更时运行测试
• 根据仓库活动生成报告

在脚本中访问 Webhook 有效负载：

import os
import json

payload = json.loads(os.environ.get("WEBHOOK_PAYLOAD", "{}"))
print(f"Event type: {payload.get('event', {}).get('action')}")

更多详情请参阅 Webhooks 文档。

常见工作负载模式

此仓库在 hf-jobs/scripts/ 中提供了开箱即用的 UV 脚本。优先使用这些脚本，而不是自行编写新模板。

模式 1：数据集 → 模型响应（vLLM）— scripts/generate-responses.py

功能：加载 Hub 数据集（聊天 messages 或 prompt 列），应用模型聊天模板，使用 vLLM 生成响应，并将输出数据集和数据集卡片推送回 Hub。

**要求：**GPU + 写入令牌（用于推送数据集）。

from pathlib import Path

script = Path("hf-jobs/scripts/generate-responses.py").read_text()
hf_jobs("uv", {
    "script": script,
    "script_args": [
        "username/input-dataset",
        "username/output-dataset",
        "--messages-column", "messages",
        "--model-id", "Qwen/Qwen3-30B-A3B-Instruct-2507",
        "--temperature", "0.7",
        "--top-p", "0.8",
        "--max-tokens", "2048",
    ],
    "flavor": "a10g-large",
    "timeout": "4h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
})

模式 2：CoT Self-Instruct 合成数据 — scripts/cot-self-instruct.py

功能：通过 CoT Self-Instruct 生成合成提示词和答案，可选择筛选输出（答案一致性 / RIP），然后将生成的数据集和数据集卡片推送到 Hub。

**要求：**GPU + 写入令牌（用于推送数据集）。

from pathlib import Path

script = Path("hf-jobs/scripts/cot-self-instruct.py").read_text()
hf_jobs("uv", {
    "script": script,
    "script_args": [
        "--seed-dataset", "davanstrien/s1k-reasoning",
        "--output-dataset", "username/synthetic-math",
        "--task-type", "reasoning",
        "--num-samples", "5000",
        "--filter-method", "answer-consistency",
    ],
    "flavor": "l4x4",
    "timeout": "8h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
})

模式 3：流式数据集统计（Polars + HF Hub）— scripts/finepdfs-stats.py

**功能：**直接扫描 Hub 上的 parquet 文件（无需下载 300GB 数据），计算时间统计数据，并可选择将结果上传到 Hub 数据集仓库。

**要求：**通常只需 CPU；只有传入 --output-repo（上传）时才需要令牌。

from pathlib import Path

script = Path("hf-jobs/scripts/finepdfs-stats.py").read_text()
hf_jobs("uv", {
    "script": script,
    "script_args": [
        "--limit", "10000",
        "--show-plan",
        "--output-repo", "username/finepdfs-temporal-stats",
    ],
    "flavor": "cpu-upgrade",
    "timeout": "2h",
    "env": {"HF_XET_HIGH_PERFORMANCE": "1"},
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
})

常见故障模式

内存不足（OOM）

修复方法：

1. 减小批次大小或数据块大小
2. 分批处理数据，每批数据量更小
3. 升级硬件：cpu → t4 → a10g → a100

作业超时

修复方法：

1. 查看日志，了解实际运行时间
2. 增加超时时间并留出缓冲："timeout": "3h"
3. 优化代码以加快执行速度
4. 分块处理数据

Hub 推送失败

修复方法：

1. 在密钥中添加令牌：MCP 使用 "$HF_TOKEN"（会自动替换），Python API 使用 get_token()（必须传入真实令牌）
2. 在脚本中验证令牌：assert "HF_TOKEN" in os.environ
3. 检查令牌权限
4. 确认仓库已存在或可以创建

缺少依赖项

修复方法： 添加到 PEP 723 标头：

# /// script
# dependencies = ["package1", "package2>=1.0.0"]
# ///

身份验证错误

修复方法：

1. 检查 hf_whoami() 是否能在本地正常运行
2. 验证密钥中的令牌 — MCP："$HF_TOKEN"，Python API：get_token()（不能使用 "$HF_TOKEN"）
3. 重新登录：hf auth login
4. 检查令牌是否具有所需权限

故障排除

常见问题：

• 作业超时 → 增加超时时间，优化代码
• 结果未保存 → 检查持久化方法，验证 HF_TOKEN
• 内存不足 → 减小批次大小，升级硬件
• 导入错误 → 将依赖项添加到 PEP 723 标头
• 身份验证错误 → 检查令牌，验证 secrets 参数

参见： references/troubleshooting.md，了解完整的故障排除指南

资源

参考资料（此技能中）

• references/token_usage.md - 完整的令牌使用指南
• references/hardware_guide.md - 硬件规格和选择指南
• references/hub_saving.md - Hub 持久化指南
• references/troubleshooting.md - 常见问题和解决方案

脚本（此技能中）

• scripts/generate-responses.py - vLLM 批量生成：数据集 → 响应 → 推送到 Hub
• scripts/cot-self-instruct.py - CoT Self-Instruct 合成数据生成与筛选 → 推送到 Hub
• scripts/finepdfs-stats.py - 对 Hub 上的 finepdfs-edu parquet 进行 Polars 流式统计（可选推送）

外部链接

官方文档：

• HF Jobs 指南 - 主要文档
• HF Jobs CLI 参考 - 命令行接口
• HF Jobs API 参考 - Python API 详情
• 硬件规格参考 - 可用硬件

相关工具：

• UV 脚本指南 - PEP 723 内联依赖项
• UV 脚本集合 - 社区 UV 脚本集合
• HF Hub 身份验证 - 令牌设置
• Webhooks 文档 - 事件触发器

关键要点

1. 内联提交脚本 - script 参数可直接接受 Python 代码；除非用户要求，否则无需保存文件
2. 作业以异步方式运行 - 不要等待或轮询；让用户在作业就绪时自行检查
3. 始终设置超时时间 - 默认的 30 分钟可能不够；请设置合适的超时时间
4. 始终持久化结果 - 环境是临时的；不进行持久化，所有工作都会丢失
5. 安全使用令牌 - MCP：secrets={"HF_TOKEN": "$HF_TOKEN"}，Python API：secrets={"HF_TOKEN": get_token()} — "$HF_TOKEN" 仅适用于 MCP 工具
6. 选择合适的硬件 - 从小型硬件开始，根据需要扩展（参见硬件指南）
7. 使用 UV 脚本 - 对于 Python 工作负载，默认使用带内联脚本的 hf_jobs("uv", {...})
8. 处理身份验证 - 在执行 Hub 操作前，确认令牌可用
9. 监控作业 - 提供作业 URL 和状态检查命令
10. 优化成本 - 选择合适的硬件并设置适当的超时时间

速查：MCP 工具、CLI 与 Python API

操作	MCP 工具	CLI	Python API
运行 UV 脚本	hf_jobs("uv", {...})	hf jobs uv run script.py	run_uv_job("script.py")
运行 Docker 作业	hf_jobs("run", {...})	hf jobs run image cmd	run_job(image, command)
列出作业	hf_jobs("ps")	hf jobs ps	list_jobs()
查看日志	hf_jobs("logs", {...})	hf jobs logs <id>	fetch_job_logs(job_id)
取消作业	hf_jobs("cancel", {...})	hf jobs cancel <id>	cancel_job(job_id)
安排 UV 作业	hf_jobs("scheduled uv", {...})	-	create_scheduled_uv_job()
安排 Docker 作业	hf_jobs("scheduled run", {...})	-	create_scheduled_job()