用 Hugging Face Jobs 加速 GitHub CI

填写：

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 的数据：

最大的收益是 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
本文由前途科技编辑整理