用 Hugging Face Jobs 加速 GitHub CI

如果你的 GitHub 仓库启用了 GitHub Actions，你大概率使用 GitHub 托管的运行器来执行 CI。这是许多项目的默认选择，因为它很简单：添加一个工作流，写上 runs-on: ubuntu-latest，GitHub 就会为你分配一台机器。

这个默认设置虽然方便，但也有局限。GitHub Actions 可能因为维护而变慢或停机，托管机器配置通用，且 GPU 访问不是大多数开源项目能随便开启的。对于 Trackio 项目，这些限制开始变得重要。我们既需要可靠的 CPU CI 来运行基础单元测试和前端检查，也需要 GPU CI 来执行需要真实 CUDA 硬件的测试。

所以我们构建了一个替代方案：让 GitHub Actions 继续负责 CI 调度，但将作业运行在 Hugging Face Jobs 上。

结果：Trackio 的 CI 现在运行在 Hugging Face Jobs 上，并实时传回日志，CPU 作业的 CI 时间缩短了约 30%，同时还支持了一套全新的 GPU 测试套件！

在本文中，我们将逐步说明如何为你的 GitHub 仓库实现相同的设置。如果你在使用 AI 智能体，可以将本文作为参考，因为我们同时提供了 CLI 指令（适合智能体）和浏览器操作指南（适合人类）。

我们先快速介绍 Hugging Face Jobs！

什么是 Hugging Face Jobs？

Hugging Face Jobs 让你在 Hugging Face 的无服务器基础设施上运行命令或脚本，几乎可以选择任何硬件配置。一个 Job 本质上包含：

• 要运行的命令
• 一个 Docker 镜像（来自 Docker Hub 或 Hugging Face Space）
• 硬件配置，例如 CPU 或 t4-small 或 h200 GPU
• 可选的环境变量和密钥

例如，你可以运行：

hf jobs run python:3.12 python -c "print('Hello world')"

或者

hf jobs uv run --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py"

这使得 Jobs 非常适合 CI。CI 作业本身就是命令驱动的，在干净的环境中运行，并且经常受益于精确选择合适的硬件。对于机器学习库，GPU 场景尤其有吸引力：你可以在真实的 GPU 硬件上运行测试套件，而无需维护自己的常开运行器。

关键步骤是将 GitHub Actions 连接到 HF Jobs，下面我们将进行描述。

架构

为了实现这个设置，我们创建了 huggingface/jobs-actions，这是一个小型桥梁，将 GitHub Actions 作业转换为一个运行在 HF Job 内部的临时自托管运行器。

完整流程如下：

1. 一个 Pull Request 触发 GitHub Actions 工作流。
2. GitHub 将任何 runs-on 标签不可用的作业放入队列（例如 hf-jobs-cpu-upgrade 或 hf-jobs-t4-small），并通过 GitHub App 向调度器发送一个签名的 workflow_job.queued webhook。
3. 调度器 Space 验证 webhook，检查是否有 hf-jobs-* 标签，生成一个临时的 GitHub 运行器注册令牌，并在匹配的硬件上启动一个 HF Job。
4. HF Job 启动一个临时的 GitHub Actions 运行器，并使用那个一次性令牌将其注册到仓库。
5. GitHub 将挂起的作业分配给该运行器；运行器执行 CI 作业，将状态报告回 GitHub，然后退出。

从 GitHub 的角度来看，这只是一个自托管运行器。从 Hugging Face 的角度来看，这只是一个 Job，它启动一个容器来执行仓库 GitHub Actions 中的工作流步骤。

步骤 1：复制调度器 Space

首先你需要一个调度器。这是一个小型的 Docker Space，它接收 GitHub 的 workflow_job webhook 事件，并相应地启动 HF Jobs。

先创建这个，因为 GitHub App 需要一个 webhook URL，而这个 URL 来自该 Space。这个 Space 应该放在你自己的命名空间下，或者放在你有写入权限的 Hugging Face 组织下。

网页设置

访问 huggingface/jobs-actions-dispatcher，点击 Duplicate this Space。

填写：

Owner: 你的 HF 用户名或组织
Name: jobs-actions-dispatcher
Hardware: cpu-upgrade

对于正式 CI 使用 cpu-upgrade，这样调度器能持续接收 GitHub webhook。cpu-basic 可以用于测试，但可能在无活动时休眠；如果 GitHub 的 webhook 在它唤醒时到达，工作流可能永远处于队列中。

构建完成后，打开复制出的 Space。你会看到一个“Required Space secrets”部分，暂时不用管。首页会显示 GitHub App 的 webhook URL，你将在下一步用到。它看起来像：

https://你的HF命名空间-jobs-actions-dispatcher.hf.space/webhook

CLI 设置

如果你更愿意用 AI 智能体或 CLI 工作流来设置调度器 Space：

export HF_NAMESPACE=你的hf用户名或组织
export SPACE_ID="$HF_NAMESPACE/jobs-actions-dispatcher"

hf repo duplicate huggingface/jobs-actions-dispatcher "$SPACE_ID" \
  --type space \
  --flavor cpu-upgrade \
  --exist-ok

然后设置：

export DISPATCHER_URL="https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

步骤 2：创建并安装 GitHub App

接下来，从调度器 Space 本身创建并安装 GitHub App。这个 App 需要权限来监听已排队的作业并创建临时自托管运行器的注册令牌。

网页设置

打开你复制出的调度器 Space：

https://你的HF命名空间-jobs-actions-dispatcher.hf.space

在设置表单中，输入希望在其上运行 CI 的 GitHub 仓库：

你的GitHub组织/你的仓库

然后点击按钮创建 GitHub App。GitHub 会要求你为 App 选择一个名称，只要能确保名称在你的 GitHub 账户或组织中可用即可。提交后，最后一步会明确告诉你如何将 App 凭证上传到调度器 Space，需要使用 hf CLI。

重要提示：你需要提供一个 Hugging Face 令牌，该令牌要有启动 Jobs 的权限，对应你的个人账户或应该计费的组织。这个令牌应作为 HF_TOKEN 密钥保存在你的调度器 Space 中。

最后，你需要在之前在 Space 中输入的那个 GitHub 仓库上安装该 App。在 Trackio 的设置中，我们安装在 gradio-app/trackio 上。

智能体辅助设置

GitHub App 清单流程仍然需要浏览器操作，但智能体可以遵循相同的 Space 驱动路径：

export HF_NAMESPACE=你的hf用户名或组织
export GITHUB_REPO=你的GitHub组织/你的仓库
open "https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

将 $GITHUB_REPO 粘贴到 Space 中，点击 GitHub App 创建按钮，选择任意可用的 App 名称，然后按照生成的 GitHub 说明操作。

创建 App 后，在 App 设置页面上将其安装到你的仓库。对于 GitHub 组织，安装设置位于：

https://github.com/organizations/你的GITHUB组织/settings/installations

步骤 3：最后配置调度器

现在，调度器 Space 应该已经配置好了。GitHub App 设置流程生成了上传 App 凭证、webhook 密钥和 Hugging Face 令牌到 Space 的命令。

默认情况下，HF Jobs 在调度器 Space 相同的命名空间下启动。可选地，如果你希望将作业计费到不同的 Hugging Face 用户或组织，可以设置 HF_NAMESPACE 作为 Space 变量：

export SPACE_ID=你的HF命名空间/jobs-actions-dispatcher
hf spaces variables add "$SPACE_ID" -e HF_NAMESPACE=你的计费命名空间
hf spaces restart "$SPACE_ID"

你在步骤 2 中设置的令牌应对应于这个命名空间。

步骤 4：修改 runs-on

工作流的实际改动很小。不再使用：

runs-on: ubuntu-latest

而是使用调度器可以处理的标签之一：

runs-on: hf-jobs-cpu-upgrade

对于 GPU 测试，使用 GPU 标签：

runs-on: hf-jobs-t4-small

对于任何你想要在 HF Jobs 上运行的 GitHub Action，只需要这一行改动就足够了！

步骤 5：测试

从 CLI 添加一个最小的烟雾测试工作流：

mkdir -p .github/workflows
cat > .github/workflows/hf-jobs-test.yml <<'EOF'
name: HF Jobs Test

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  test:
    runs-on: hf-jobs-cpu-upgrade
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Hugging Face Jobs"
EOF

git add .github/workflows/hf-jobs-test.yml
git commit -m "Run CI on Hugging Face Jobs"
git push

从 CLI 验证：

gh run list --repo 你的GITHUB组织/你的仓库 --limit 5
hf jobs ps --namespace "$HF_NAMESPACE"
hf spaces logs "$SPACE_ID"

你应该能看到与常规 GitHub Action 类似的日志——例如，在 Trackio PR #565 中可以看到。

就这样！

关于选择合适的 Docker 镜像的提示

我们最初的 CPU 设置使用了 ubuntu:22.04，并在每次运行时安装缺失的系统包。虽然能运行，但速度不如预期。GitHub 的 ubuntu-latest 镜像默认包含大量开发者工具；而一个裸 Ubuntu 镜像没有这些工具。

对于 Trackio，UI 测试需要 Playwright 浏览器、Node、ffmpeg、sqlite、git 以及常规的 Linux 构建依赖。Hugging Face Jobs 支持使用任何 Docker 镜像，所以我们切换到了 Microsoft Playwright 镜像，效果很好：

mcr.microsoft.com/playwright:v1.60.0-jammy

对于 GPU 作业，我们使用了：

nvidia/cuda:12.4.0-runtime-ubuntu22.04

结果

以下是 Trackio CI 的数据：

运行器设置	运行时间	与 GitHub 平均值对比
GitHub ubuntu-latest 基线	1m40s	基线
HF Jobs CPU，Playwright 镜像	1m10s	-30s，约快 30%
HF Jobs GPU，t4-small 标签	45s	无 GitHub 托管 GPU 基线

最大的收益是 GPU CI。Trackio 的 GPU 检查在 HF Jobs 上运行并花了 45s，按照 t4-small 费率计算，该持续时间的花费不到 1 美分。

CPU 结果也令人鼓舞。使用合适的镜像后，Linux 测试作业比 GitHub 托管的基线更快。这表明 HF Jobs 可以作为一个实用的 CI 后端，特别是对于需要自定义镜像或加速器的机器学习项目。

日志是另一个惊喜。GitHub Actions 日志很有用，但大型日志的 Web UI 可能很重。HF Jobs 的日志易于从 CLI 获取：

hf jobs logs <job_id> > logs.txt

这使得它们可以轻松地用本地工具或编码智能体进行检查。在我们的桥梁中，我们还把 GitHub Actions 作业日志镜像到了 HF Job 日志中，这样任一系统都有足够的信息来调试运行。

最后，虽然 Trackio 的 CI 不需要，但 HF Jobs 还支持挂载卷，如果你需要在 CI 过程中快速从 Hugging Face 加载数据集或模型，这会非常有用。

希望这篇指南能让你有信心尝试用 HF Jobs 来运行你的 GitHub Actions！

---

原文链接：Hugging Face
本文由前途科技编辑整理