如果 GitHub Actions 是代码世界的"自动化流水线"，那 HF Jobs 就是 AI 工程师的"GPU 跑腿工"。
写在前面
做过 AI 项目的同学都知道一个痛点：训练和推理需要 GPU，但 GPU 不便宜，环境也不好配。
GitHub Actions 可以帮我们自动化 CI/CD 流程，但跑不了 GPU 任务。本地有显卡的，环境配置折腾半天；没显卡的，只能看着论文叹气。
Hugging Face 最近推出了 Jobs 功能——直接在 HF 基础设施上运行计算任务，按秒计费，支持从 CPU 到 A100、H200 全线硬件。用法跟 uv run 和 docker run 几乎一样，上手成本极低。
这篇文章，我会用 GitHub Actions 用户的视角来讲解 HF Jobs，帮你快速理解它的核心概念和用法。
一、HF Jobs 是什么？
简单说：一行命令，在云端跑你的 Python 脚本或 Docker 容器，支持 GPU。
# 本地跑 uv
uv run train.py
# HF Jobs 跑 uv —— 就多了 "hf jobs" 三个词
hf jobs uv run train.py
# 本地跑 docker
docker run ubuntu echo "Hello"
# HF Jobs 跑 docker —— 同样只多了 "hf jobs"
hf jobs run ubuntu echo "Hello from the cloud!"
对比 GitHub Actions：
| 维度 | GitHub Actions | HF Jobs |
|---|---|---|
| 定位 | 代码构建、测试、部署流水线 | AI 计算、模型训练、数据处理 |
| GPU 支持 | 需自托管 Runner | 原生支持 T4 到 H200 |
| 触发方式 | push/PR/schedule/webhook | 手动/schedule/webhook |
| 定义方式 | YAML 工作流文件 | 命令行一行搞定 |
| 计费 | 免费 2000 分钟/月（GitHub-hosted） | 按分钟计费，CPU 低至 $0.01/h |
| 运行环境 | GitHub 虚拟机 | HF 云基础设施 |
GitHub Actions 解决的是"代码自动化"问题，HF Jobs 解决的是"GPU 算力按需获取"问题。两者互补，不是替代。
二、快速上手：3 分钟跑起你的第一个 Job
2.1 安装 CLI
# 推荐方式
curl -LsSf https://hf.co/cli/install.sh | bash
# 或用 Homebrew
brew install huggingface-cli
# 或用 uv
uv tool install huggingface-cli
2.2 登录
hf auth login
需要一个有 Jobs 权限的 Token。PRO 账户、Team 或 Enterprise 订阅可用。
2.3 跑起来
# 最简单的 Python Job
hf jobs uv run python -c 'print("Hello from the cloud!")'
输出：
Job started with ID: 693aef401a39f67af5a41c0e
View at: https://huggingface.co/jobs/lhoestq/693aef401a39f67af5a41c0e
Hello from the cloud!
对比 GitHub Actions 的"Hello World"：
GitHub Actions 需要你创建一个 .github/workflows/hello.yml：
name: Hello
on: [push]
jobs:
hello:
runs-on: ubuntu-latest
steps:
- run: echo "Hello from GitHub Actions"
然后 push 到仓库才能触发。
HF Jobs 只需要一行命令，即时执行，无需仓库。
# Docker Job 同样简单
hf jobs run ubuntu echo 'Hello from the cloud!'
2.4 跑一个本地脚本
echo "print('Hello from uv script!')" > script.py
hf jobs uv run script.py
输出：
Job started with ID: 695f6cd8d2f3efac77e8cf7f
View at: https://huggingface.co/jobs/lhoestq/695f6cd8d2f3efac77e8cf7f
Hello from uv script!
三、核心配置：从"能跑"到"好用"
3.1 GPU 支持——HF Jobs 的杀手锏
GitHub Actions 的 GitHub-hosted Runner 不提供 GPU。要用 GPU，得自建 Runner 并配好显卡——这对大多数开发者来说门槛很高。
HF Jobs 选择硬件只需要一个参数：
# 在 A10G GPU 上跑 PyTorch
hf jobs uv run --with torch --flavor a10g-small python -c \
"import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"
输出：
This code ran with the following GPU: NVIDIA A10G
就这么简单。一条命令，GPU 到手。
可用的硬件列表：
hf jobs hardware
输出：
NAME PRETTY NAME CPU RAM ACCELERATOR COST/MIN COST/HOUR
------------ ---------------------- -------- ------- ---------------- -------- ---------
cpu-basic CPU Basic 2 vCPU 16 GB N/A $0.0002 $0.01
cpu-upgrade CPU Upgrade 8 vCPU 32 GB N/A $0.0005 $0.03
t4-small Nvidia T4 - small 4 vCPU 15 GB 1x T4 (16 GB) $0.0067 $0.40
t4-medium Nvidia T4 - medium 8 vCPU 30 GB 1x T4 (16 GB) $0.0100 $0.60
a10g-small Nvidia A10G - small 4 vCPU 15 GB 1x A10G (24 GB) $0.0167 $1.00
a10g-large Nvidia A10G - large 12 vCPU 46 GB 1x A10G (24 GB) $0.0250 $1.50
a100-large Nvidia A100 - large 12 vCPU 142 GB 1x A100 (80 GB) $0.0417 $2.50
a100x4 4x Nvidia A100 48 vCPU 568 GB 4x A100 (320 GB) $0.1667 $10.00
a100x8 8x Nvidia A100 96 vCPU 1136 GB 8x A100 (640 GB) $0.3333 $20.00
l4x1 1x Nvidia L4 8 vCPU 30 GB 1x L4 (24 GB) $0.0133 $0.80
l40sx1 1x Nvidia L40S 8 vCPU 62 GB 1x L40S (48 GB) $0.0300 $1.80
l40sx4 4x Nvidia L40S 48 vCPU 382 GB 4x L40S (192 GB) $0.1383 $8.30
l40sx8 8x Nvidia L40S 192 vCPU 1534 GB 8x L40S (384 GB) $0.3917 $23.50
h200 Nvidia H200 23 vCPU 256 GB 1x H200 (141 GB) $0.0833 $5.00
h200x2 2x Nvidia H200 46 vCPU 512 GB 2x H200 (282 GB) $0.1667 $10.00
h200x4 4x Nvidia H200 92 vCPU 1024 GB 4x H200 (564 GB) $0.3333 $20.00
h200x8 8x Nvidia H200 184 vCPU 2048 GB 8x H200 (1128GB) $0.6667 $40.00
从 $0.01/h 的 CPU Basic 到 $40/h 的 8 卡 H200，按需选择。
对比 GitHub Actions 自托管 Runner： 你得自己买卡、装驱动、配 CUDA、维护机器。HF Jobs 这些全省了。
3.2 环境变量与密钥
跟 GitHub Actions 的 env 和 secrets 概念一致：
GitHub Actions：
env:
FOO: bar
jobs:
build:
steps:
- name: Use secret
env:
MY_SECRET: ${{ secrets.MY_SECRET }}
run: echo $MY_SECRET
HF Jobs：
# 环境变量
hf jobs uv run -e FOO=foo -e BAR=bar python -c \
'import os; print(os.environ["FOO"], os.environ["BAR"])'
# 从 .env 文件加载
hf jobs uv run --env-file .env python -c \
'import os; print(os.environ["FOO"], os.environ["BAR"])'
# 密钥（服务端加密存储）
hf jobs uv run -s MY_SECRET=psswrd python -c \
'import os; print(os.environ["MY_SECRET"])'
# 从 .env.secrets 文件加载密钥
hf jobs uv run --secrets-file .env.secrets python -c \
'import os; print(os.environ["MY_SECRET"])'
# 直接传入本地 HF Token
hf jobs uv run --secrets HF_TOKEN ...
3.3 Python 依赖管理
HF Jobs 的 UV 模式会自动处理依赖，类似 GitHub Actions 的 pip install 步骤，但更简洁：
# 指定依赖
hf jobs uv run --with trl train.py
# 指定 Python 版本
hf jobs uv run --python 3.12 train.py
# 复杂依赖 + 分隔符
hf jobs uv run --with trl-jobs -- trl-jobs sft \
--model_name Qwen/Qwen3-0.6B \
--dataset_name trl-lib/Capybara
对比 GitHub Actions： 你需要一个 step 来 pip install -r requirements.txt。HF Jobs 用 --with 一行搞定，不用维护 requirements 文件。
3.4 超时设置
默认 30 分钟超时。对于训练任务，必须手动设置：
# 数字形式（秒）
hf jobs uv run --timeout 7200 --with torch --flavor a10g-large train.py
# 时间单位形式
hf jobs uv run --timeout 2h --with torch --flavor a10g-large train.py
# 其他格式
--timeout 30m # 30 分钟
--timeout 1.5h # 1.5 小时
--timeout 1d # 1 天
--timeout 3600s # 3600 秒
对比 GitHub Actions： GHA 默认 6 小时超时，通过 timeout-minutes 设置。HF Jobs 默认 30 分钟，更短，需要显式延长。
3.5 组织账户与标签
# 在组织账户下运行
hf jobs uv run --namespace my-org-name python -c \
"print('Running in an org account')"
# 带标签（方便后续筛选）
hf jobs uv run \
--label fine-tuning \
--label model=Qwen3-0.6B \
--label dataset=Capybara \
...
标签类比 GitHub Actions 的 labels，用于分类和检索。
四、实战：用 HF Jobs 微调一个开源模型
这是一个完整的端到端例子——用 TRL 库微调 Qwen2.5-0.5B。
4.1 训练脚本
# train.py
from datasets import load_dataset
from trl import SFTTrainer
dataset = load_dataset("trl-lib/Capybara", split="train")
trainer = SFTTrainer(
model="Qwen/Qwen2.5-0.5B",
train_dataset=dataset,
)
trainer.train()
trainer.push_to_hub("Qwen2.5-0.5B-SFT")
4.2 提交训练 Job
hf jobs uv run \
--flavor a100-large \
--timeout 6h \
--with trl \
--secrets HF_TOKEN \
train.py
一行命令完成：选择 A100 GPU → 最长跑 6 小时 → 自动装 trl → 传入 HF Token（用于推送模型）。
日志会实时流式输出到终端，Ctrl+C 只停止流式查看，Job 继续在云端运行：
...
Installed 66 packages in 233ms
Generating train set: 100%|██████████| 15806/15806
Generating test set: 100%|██████████| 200/200
{'loss': 1.7357, 'grad_norm': 4.8733, 'learning_rate': 1.997e-05, 'epoch': 0.01}
{'loss': 1.6239, 'grad_norm': 6.2002, 'learning_rate': 1.994e-05, 'epoch': 0.01}
{'loss': 1.4449, 'grad_norm': 6.1673, 'learning_rate': 1.990e-05, 'epoch': 0.02}
...
训练完成后，模型自动推送到你的 HF 账户下。
对比 GitHub Actions 做同样的事： 你需要写一个完整的 workflow YAML，配置 CUDA 环境、安装 PyTorch、处理 GPU 驱动问题……至少几十行配置。HF Jobs 一行命令搞定。
五、Job 管理
5.1 查看任务列表
# 运行中的任务
hf jobs ps
# 所有任务（含历史）
hf jobs ps -a
# 组织下的任务
hf jobs ps --namespace my-org-name
输出：
JOB ID IMAGE/SPACE COMMAND CREATED STATUS
------------ ---------------- ----------- ------------------- -------
69402ea6c... ghcr.io/astra... uv run p... 2025-12-15 15:52:06 RUNNING
693b06b8c... ghcr.io... uv run p... 2025-12-11 18:00:24 CANCELED
693b069fc... ghcr.io... uv run p... 2025-12-11 17:59:59 ERROR
693aef401... ghcr.io... uv run p... 2025-12-11 16:20:16 COMPLETED
5.2 过滤任务
# 按标签过滤
hf jobs ps --filter label=fine-tuning --filter label=model=Qwen3-06B -a
# 按状态过滤
hf jobs ps --filter status=error -a
# 支持否定和通配符
hf jobs ps -a --filter status!=completed
hf jobs ps -a --filter "command=*train.py"
hf jobs ps -a --filter label=fine-tuning
hf jobs ps -a --filter label!=prod --filter "label=data-*"
hf jobs ps -a --filter label=model=Qwen3-06B --filter label=dataset!=Capybara
5.3 监控资源占用
hf jobs stats
输出：
JOB ID CPU % NUM CPU MEM % MEM USAGE NET I/O GPU UTIL % GPU MEM % GPU MEM USAGE
------------------------ ----- ------- ----- ---------------- --------------- ---------- --------- ---------------
695e83c5d2f3efac77e8cf18 8% 12.0 7.18% 10.9GB / 152.5GB 0.0bps / 0.0bps 100% 31.92% 25.9GB / 81.2GB
对比 GitHub Actions： GHA 只能看日志，没有实时资源监控。HF Jobs 能看到 CPU、内存、网络、GPU 利用率的实时数据。
5.4 查看详情和日志
# 查看任务详情（JSON 格式）
hf jobs inspect <job-id>
# 查看日志
hf jobs logs <job-id>
# 查看日志最后几行（调试错误）
hf jobs logs <job-id> | tail -n 10
5.5 取消任务
hf jobs cancel <job-id>
# 组织下的任务
hf jobs cancel --namespace my-org-name <job-id>
六、自动化：定时任务与 Webhook
6.1 定时任务（类似 GitHub Actions 的 schedule）
GitHub Actions 用 cron 语法定义定时任务：
on:
schedule:
- cron: '0 */6 * * *' # 每 6 小时
HF Jobs 同样用 cron 语法，但直接在命令行指定：
# 每小时执行
hf jobs scheduled uv run @hourly python -c "print('This runs every hour!')"
# 每 5 分钟执行
hf jobs scheduled uv run "*/5 * * * *" python -c "print('This runs every five minutes!')"
# 带 GPU 的定时任务
hf jobs scheduled uv run --flavor a10g-small --with torch @hourly python -c \
'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'
# Docker 镜像的定时任务
hf jobs scheduled run @hourly python:3.12 python -c "print('This runs every hour!')"
# 带标签的定时任务
hf jobs scheduled uv run --label fine-tuning @hourly my_script.py
支持的别名：@annually、@yearly、@monthly、@weekly、@daily、@hourly。
6.2 管理定时任务
# 查看活跃的定时任务
hf jobs scheduled ps
# 查看所有定时任务（含暂停的）
hf jobs scheduled ps -a
# 查看某个定时任务状态
hf jobs scheduled inspect <scheduled-job-id>
# 暂停
hf jobs scheduled suspend <scheduled-job-id>
# 恢复
hf jobs scheduled resume <scheduled-job-id>
# 删除
hf jobs scheduled delete <scheduled-job-id>
6.3 Webhook 自动触发（类似 GitHub Actions 的 repository_dispatch）
GitHub Actions 可以通过 repository_dispatch 或 push 事件触发 workflow。HF Jobs 通过 Webhook 监听仓库变化来触发 Job：
from huggingface_hub import create_webhook
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 传入 Job：
- event:
- action: one of "create", "delete", "move", "update"
- scope: string
- repo:
- owner: string
- headSha: string
- name: string
- type: one of "dataset", "model", "space"
典型场景： 模型仓库有新版本更新 → Webhook 触发 Job → 自动跑评测或重新部署。
七、计费与成本控制
7.1 定价一览
CPU：
| 硬件 | CPU | 内存 | 每小时价格 |
|---|---|---|---|
| CPU Basic | 2 vCPU | 16 GB | $0.01 |
| CPU Upgrade | 8 vCPU | 32 GB | $0.03 |
| CPU XL | 16 vCPU | 124 GB | $1.00 |
| CPU Performance | 32 vCPU | 256 GB | $1.90 |
GPU（精选）：
| 硬件 | GPU 显存 | 每小时价格 |
|---|---|---|
| T4 - small | 16 GB | $0.40 |
| A10G - small | 24 GB | $1.00 |
| A10G - large | 24 GB | $1.50 |
| A100 - large | 80 GB | $2.50 |
| 4x A100 | 320 GB | $10.00 |
| H200 | 141 GB | $5.00 |
| 4x H200 | 564 GB | $20.00 |
关键细节： 按分钟计费，只在 Starting 和 Running 阶段收费。构建阶段（build）不计费。Job 失败会自动暂停并停止计费。
7.2 省钱建议
# 1. 设置超时，防止跑飞
hf jobs uv run --timeout 2h --flavor a100-large train.py
# 2. 不需要的 Job 及时取消
hf jobs cancel <job-id>
# 3. 开发调试用 CPU，正式训练切 GPU
hf jobs uv run --flavor cpu-basic python -c "..." # $0.01/h 调试
hf jobs uv run --flavor a100-large --timeout 6h train.py # 正式训练
八、调试技巧
8.1 本地复现
Job 跑挂了？先本地复现：
# HF Jobs 命令 → 对应的本地命令
hf jobs uv run ... → uv run ...
hf jobs run ... → docker run ...
8.2 看日志尾部
hf jobs logs <job-id> | tail -n 10
8.3 常见错误
- "Job timeout" → 默认 30 分钟不够，加
--timeout - Python 依赖缺失 → 用
--with package-name指定 - CUDA 相关错误 → 确认用了
--flavor选了 GPU，并加--with torch
九、HF Jobs vs GitHub Actions：什么时候用哪个？
| 场景 | 推荐工具 | 原因 |
|---|---|---|
| 代码构建、测试、Lint | GitHub Actions | 成熟的 CI/CD 生态，免费额度充足 |
| 模型训练、微调 | HF Jobs | 原生 GPU，一行命令，按需计费 |
| 模型评测自动化 | HF Jobs | 直接访问 HF 模型和数据集生态 |
| 数据处理管道 | HF Jobs | GPU 加速 + 灵活的 Python 环境 |
| 代码部署到 K8s/云 | GitHub Actions | 丰富的部署 Action 和集成 |
| 模型更新 → 自动推理 | HF Jobs Webhook | 原生监听 HF 仓库变化 |
| 定时数据采集 | 都行 | 简单任务两者皆可 |
最佳实践：组合使用。 GitHub Actions 负责 CI/CD 流水线，HF Jobs 负责 GPU 计算任务。比如：
GitHub Actions (push trigger)
→ 构建镜像、跑测试
→ 触发 HF Jobs (通过 API)
→ 在 A100 上跑模型训练
→ 训练完成推送模型到 HF Hub
十、总结
HF Jobs 填补了一个空白：让 GPU 算力的获取像跑一行命令一样简单。
如果你是 GitHub Actions 用户，可以把 HF Jobs 理解为：
- 不需要写 YAML 的 Actions
- 自带 GPU 的 Runner
- 按秒计费 的云端计算
三个核心命令就能覆盖大部分场景：
hf jobs uv run ... # 跑 Python（UV 模式）
hf jobs run ... # 跑 Docker（Docker 模式）
hf jobs scheduled uv run ... # 定时跑
对于 AI 工程师来说，这意味着：不用买卡、不用配环境、不用维护服务器。把精力留给模型和数据，基础设施交给 HF Jobs。
参考资料：