将 GitHub CI 迁移到 Hugging Face Jobs 源：https://huggingface.co/blog/github-ci-hf-jobs 返回文章列表 (https://huggingface.co/blog) https://huggingface.co/login?next=%2Fblog%2Fgithub-ci-hf-jobs- Abubakar Abid 的头像 (https://huggingface.co/abidlabs) - 什么是 Hugging Face Jobs？ (https://huggingface.co/blog/github-ci-hf-jobs#what-is-hugging-face-jobs) - 架构 (https://huggingface.co/blog/github-ci-hf-jobs#the-architecture) - 步骤 1：复制调度器 Space (https://huggingface.co/blog/github-ci-hf-jobs#step-1-duplicate-the-dispatcher-space) - 步骤 2：创建并安装 GitHub App (https://huggingface.co/blog/github-ci-hf-jobs#step-2-create-and-install-the-github-app) - Web 设置 (https://huggingface.co/blog/github-ci-hf-jobs#web-setup-1) - 辅助设置（Agent） (https://huggingface.co/blog/github-ci-hf-jobs#agent-assisted-setup) - 步骤 3：最终调度器设置 (https://huggingface.co/blog/github-ci-hf-jobs#step-3-final-dispatcher-settings) - 步骤 4：更改 runs\-on (https://huggingface.co/blog/github-ci-hf-jobs#step-4-change-runs-on) - 步骤 5：测试 (https://huggingface.co/blog/github-ci-hf-jobs#step-5-test-it-out) - 结果 (https://huggingface.co/blog/github-ci-hf-jobs#results) 如果你的 GitHub 仓库启用了 GitHub Actions，你很可能默认使用 GitHub 托管的 runner 来运行 CI。这对很多项目来说很简单：添加一个 workflow，写上 runs\-on: ubuntu\-latest，GitHub 就会分配一台机器。这个默认方式很方便，但也有其局限性。GitHub Actions 可能会因为维护而变慢或停机，托管的机器是通用的，而且 GPU 访问对大多数开源项目来说并非轻而易举就能启用。 对于 Trackio (https://github.com/gradio-app/trackio) 来说，这些限制开始变得重要。我们既希望有可靠的 CPU CI 来进行基础单元测试和前端检查，又需要 GPU CI 来运行那些必须在实际 CUDA 硬件上执行的测试。于是，我们构建了一个替代方案：让 GitHub Actions 继续负责 CI 的调度，但将作业实际运行在 Hugging Face Jobs (https://huggingface.co/docs/hub/en/jobs-overview) 上。结果是：Trackio 的 CI 现在在 Hugging Face Jobs 上运行，并实时返回日志，CPU 作业的 CI 时间减少了约 30%，并且启用了在 GPU 机器上运行的全新测试套件！ 在本文中，我们将逐步解释如何为你的 GitHub 仓库重现同样的设置。如果你使用的是 Agent，可以直接将本文指向它，因为我们在浏览器操作说明的同时也提供了 CLI 指令（供人类使用）。 让我们先快速介绍一下 Hugging Face Jobs！ ## https://huggingface.co/blog/github-ci-hf-jobs#what-is-hugging-face-jobs 什么是 Hugging Face Jobs？ Hugging Face Jobs (https://huggingface.co/docs/hub/en/jobs-overview) 允许你在 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 作业本身就是命令驱动的，通常在干净的环境中运行，并且经常受益于选择恰好合适的硬件。对于 ML 库来说，GPU 场景尤其吸引人：你可以在真实的 GPU 硬件上运行测试套件，而无需维护自己的常驻 runner。关键步骤是将 GitHub Actions 连接到 HF Jobs，下面我们将描述如何操作。 ## https://huggingface.co/blog/github-ci-hf-jobs#the-architecture 架构 对于此设置，我们创建了 huggingface/jobs\-actions (https://github.com/huggingface/jobs-actions)，这是一个小型桥接工具，可将 GitHub Actions 作业转换为在 HF Job 内运行的临时自托管 runner。完整流程如下： 1. 拉取请求触发 GitHub Actions workflow。 2. GitHub 将任何 runs\-on 标签不可用的作业排队，例如 hf\-jobs\-cpu\-upgrade 或 hf\-jobs\-t4\-small，并通过 GitHub App 向调度器发送一个已签名的 workflow\_job\.queued webhook。 3. 调度器 Space 验证 webhook，检查是否存在 hf\-jobs\-* 标签，生成一个短期的 GitHub runner 注册令牌，并在匹配的硬件上启动一个 HF Job。 4. HF Job 启动一个临时的 GitHub Actions runner，并使用该一次性令牌将其注册到仓库。 5. GitHub 将待处理的 workflow 作业分配给该 runner；runner 执行 CI 作业，向 GitHub 报告状态，然后退出。 从 GitHub 的角度来看，这只是一个自托管 runner。从 Hugging Face 的角度来看，这只是一个 Job，它启动一个容器来运行仓库 GitHub Actions 中的 workflow 步骤。 ## https://huggingface.co/blog/github-ci-hf-jobs#step-1-duplicate-the-dispatcher-space 步骤 1：复制调度器 Space 首先你需要调度器。这是一个小型 Docker Space，负责接收 GitHub 的 workflow\_job webhook 事件并相应地启动 HF Jobs。请先创建它，因为 GitHub App 需要 webhook URL，而这个 URL 来自该 Space。 这个 Space 应该放在你自己的命名空间下，或者放在你有写入权限的 Hugging Face 组织下。 #### https://huggingface.co/blog/github-ci-hf-jobs#web-setup Web 设置 前往 huggingface/jobs\-actions\-dispatcher (https://huggingface.co/spaces/huggingface/jobs-actions-dispatcher) 并点击 Duplicate this Space。 image 使用以下设置： Owner：你的 HF 用户名或组织 Name：jobs-actions-dispatcher Hardware：cpu-upgrade 对于真实的 CI，使用 cpu\-upgrade，这样调度器能保持在线以接收 GitHub webhook。cpu\-basic 对于测试也可以，并且通常能工作，但它可能会在闲置后休眠；如果 GitHub 的 webhook 在它唤醒期间到达，workflow 可能会一直处于排队状态。 构建完成后，打开复制的 Space。你会看到一个显示“Required Space secrets”的部分，暂时忽略即可。登陆页面应该会显示你在下一步中需要的 GitHub App webhook URL，类似这样： https://你的-HF-命名空间-jobs-actions-dispatcher.hf.space/webhook #### https://huggingface.co/blog/github-ci-hf-jobs#cli-setup CLI 设置 如果你更倾向于用 Agent 或 CLI 工作流来设置调度器 Space： export HF_NAMESPACE=your-hf-user-or-org 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" ## https://huggingface.co/blog/github-ci-hf-jobs#step-2-create-and-install-the-github-app 步骤 2：创建并安装 GitHub App 接下来，从调度器 Space 本身创建并安装 GitHub App。这个 App 需要权限来监听排队的 workflow 作业并创建临时的自托管 runner 注册令牌。 ### https://huggingface.co/blog/github-ci-hf-jobs#web-setup-1 Web 设置 打开你复制的调度器 Space： https://你的-HF-命名空间-jobs-actions-dispatcher.hf.space 在设置表单中，输入你想要将 CI 运行在 HF Jobs 上的 GitHub 仓库： 你的-GITHUB-组织/你的-REPO 然后点击按钮创建 GitHub App。GitHub 会要求你为 App 选择一个名称；只要在你的 GitHub 账户或组织中可用，名称可以是任意的。 提交后，最终屏幕会明确指示如何使用 hf CLI 将 App 凭据上传到调度器 Space。 重要提示：你需要提供一个 Hugging Face 令牌 (https://huggingface.co/settings/tokens)，该令牌具有启动 Jobs 的权限，对应于你的个人账户或应计费的组织。该令牌应作为 HF\_TOKEN 密钥保存在你的调度器 Space 中。 最后，你将在你在 Space 中输入的那个 GitHub 仓库上安装该 App。在 Trackio 的设置中，我们将其安装在 gradio\-app/trackio 上。 ### https://huggingface.co/blog/github-ci-hf-jobs#agent-assisted-setup 辅助设置（Agent） GitHub App 的 manifest 流程仍然基于浏览器，但 Agent 可以遵循相同的 Space 驱动路径： export HF_NAMESPACE=your-hf-user-or-org export GITHUB_REPO=YOUR-GITHUB-ORG/YOUR-REPO open "https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space" 将 $GITHUB\_REPO 粘贴到 Space 中，点击 GitHub App 创建按钮，选择任何可用的 App 名称，然后按照生成的 GitHub 说明操作。 App 创建后，在 App 设置页面上将其安装到你的仓库。对于 GitHub 组织，安装设置位于： https://github.com/organizations/YOUR-GITHUB-ORG/settings/installations ## https://huggingface.co/blog/github-ci-hf-jobs#step-3-final-dispatcher-settings 步骤 3：最终调度器设置 此时，调度器 Space 应该已经配置完毕。GitHub App 设置流程生成了将 App 凭据、webhook 密钥和 Hugging Face 令牌上传到 Space 的命令。 image 默认情况下，HF Jobs 会在与调度器 Space 相同的命名空间下启动。如果你希望将作业计费到不同的 Hugging Face 用户或组织，可以选择设置 HF\_NAMESPACE 作为 Space 变量： export SPACE_ID=YOUR-HF-NAMESPACE/jobs-actions-dispatcher hf spaces variables add "$SPACE_ID" -e HF_NAMESPACE=your-billing-namespace hf spaces restart "$SPACE_ID" 你在步骤 2 中设置的令牌应对应于此命名空间。 ## https://huggingface.co/blog/github-ci-hf-jobs#step-4-change-runs-on 步骤 4：更改 runs\-on 实际的 workflow 改动很小。将原来： runs-on: ubuntu-latest 替换为调度器处理的标签之一： runs-on: hf-jobs-cpu-upgrade 对于 GPU 测试，使用 GPU 标签： runs-on: hf-jobs-t4-small 对于任何你想在 HF Jobs 上运行的 GitHub Action，只需要这一行改动即可！ ## https://huggingface.co/blog/github-ci-hf-jobs#step-5-test-it-out 步骤 5：测试 要通过 CLI 添加一个最小的冒烟测试 workflow： 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 YOUR-GITHUB-ORG/YOUR-REPO --limit 5 hf jobs ps --namespace "$HF_NAMESPACE" hf spaces logs "$SPACE_ID" 你应该能够看到类似常规 GitHub Action 的日志——例如，在这个 Trackio PR #565 (https://github.com/gradio-app/trackio/pull/565) 中就是如此。 这样就完成了！ 关于选择正确的 Docker 镜像的说明 我们最初的 CPU 设置使用了 ubuntu:22\.04，并在每次运行时安装缺失的系统包。这虽然可行，但速度不够快。GitHub 的 ubuntu\-latest 镜像默认包含大量开发者工具；而一个裸 Ubuntu 镜像则没有。对于 Trackio，UI 测试需要 Playwright 浏览器、Node、ffmpeg、sqlite、git 和常见的 Linux 构建依赖。Hugging Face Jobs 支持使用任何 Docker 镜像 (https://huggingface.co/docs/hub/jobs-popular-images)，因此我们切换到了 Microsoft Playwright 镜像，效果很好： mcr.microsoft.com/playwright:v1.60.0-jammy 对于 GPU 作业，我们使用了： nvidia/cuda:12.4.0-runtime-ubuntu22.04 ## https://huggingface.co/blog/github-ci-hf-jobs#results 结果 以下是 Trackio CI 的数据： | Runner 设置 | 运行时间 | 与 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 费率计算，成本不到一美分。CPU 的结果也令人鼓舞。使用正确的镜像，Linux 测试作业比 GitHub 托管的基线更快。这表明 HF Jobs 可以成为实用的 CI 后端，特别是对于那些需要自定义镜像或加速器的 ML 项目。 日志也是另一个令人惊喜的地方。GitHub Actions 日志很有用，但对于大型日志来说，Web UI 可能会变得沉重。HF Jobs 的日志很容易通过 CLI 获取： hf jobs logs > logs.txt 这使得它们可以方便地用本地工具或编码 Agent 进行审查。在我们的桥接器中，我们还将 GitHub Actions 作业日志镜像到 HF Job 日志中，这样任一系统都有足够的信息来调试运行。 最后，虽然 Trackio 的 CI 不需要，但 HF Jobs 还支持挂载卷 (https://huggingface.co/docs/huggingface_hub/en/guides/jobs#mount-a-volume)，如果你需要在 CI 中快速从 Hugging Face 加载数据集或模型，这会非常有帮助。 希望这篇文章能为你提供运行 GitHub Actions 时尝试 HF Jobs 所需的一切信息！