跳到正文
Hugging Face Blog·· 2026-06-09精選AI 評分65

如何將 GitHub CI 遷移至 Hugging Face Jobs

Migrating Your GitHub CI to Hugging Face Jobs

AI 導讀

Hugging Face Blog 示範如何把 GitHub Actions 的 CI 工作交由 Hugging Face Jobs 執行,並以 Trackio 展示透過臨時 self-hosted runner 連接兩者的方式。

推薦理由

文章給出 GitHub Actions 接入 Hugging Face Jobs 的操作流程,並説明 workflow 標籤設定。

正文 · 繁體中文

如果你有 GitHub 儲存庫並啟用了 GitHub Actions,很可能會用 GitHub 託管的 runner 執行 CI。許多項目都預設採用這種方式,因為設定簡單:加入 workflow,設定 runs-on: ubuntu-latest,GitHub 就會提供一部機器。

這種預設方式雖然方便,但也有限制。GitHub Actions 可能很慢,或因維護而暫停;託管機器是通用配置,而且大部分開源項目無法隨意啟用 GPU。對 Trackio 而言,這些限制開始造成影響。我們希望基本單元測試和前端檢查有可靠的 CPU CI,同時也能在實際 CUDA 硬件上執行所需測試的 GPU CI。

於是我們建立了另一種做法:由 GitHub Actions 負責 CI,但改在 Hugging Face Jobs 上執行工作。

結果是:Trackio 的 CI 現在在 Hugging Face Jobs 上執行,並串流傳回即時日誌,CPU 工作的 CI 時間減少約 30%,還新增了一整套在 GPU 機器上執行的測試!

本文會逐步説明如何為你的 GitHub 儲存庫重現相同設定。如果你使用代理程式,也可讓它參考本文;我們同時提供 CLI 指引和適合人手操作的瀏覽器指引。

先簡單介紹 Hugging Face Jobs!

甚麼是 Hugging Face Jobs?

Hugging Face Jobs 讓你在 Hugging Face 的無伺服器基礎設施上,使用幾乎任何硬件類型執行命令或指令碼。一個 Job 基本上包含:

  • 要執行的命令
  • 來自 Docker Hub 或 Hugging Face Space 的 Docker 映像
  • 硬件類型,例如 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 硬件上執行整套測試,毋須維護長期在線的自有 runner。

關鍵步驟是把 GitHub Actions 連接至 HF Jobs,以下會介紹做法。

架構

為了完成這項設定,我們建立了 huggingface/jobs-actions,這個小型橋接工具可把 GitHub Actions 工作轉成在 HF Job 內執行的臨時自託管 runner。

完整流程如下:

  1. Pull request 觸發 GitHub Actions workflow。
  2. GitHub 會將任何 runs-on 標籤不可用的工作排入佇列,例如 hf-jobs-cpu-upgrade 或 hf-jobs-t4-small,再透過 GitHub App 向 dispatcher 發送已簽署的 workflow_job.queued webhook。
  3. Dispatcher Space 會驗證 webhook、檢查是否有 hf-jobs-* 標籤、產生短效 GitHub runner 註冊 token,並在相符硬件上啟動 HF Job。
  4. HF Job 啟動臨時 GitHub Actions runner,再使用該一次性 token 將 runner 註冊到儲存庫。
  5. GitHub 將待處理 workflow 工作指派給該 runner;runner 執行 CI 工作、向 GitHub 回報狀態,然後結束。

從 GitHub 角度看,這只是一個自託管 runner;從 Hugging Face 角度看,這只是一個啟動容器、在其中執行儲存庫 GitHub Actions 工作流程步驟的 Job。

步驟 1:複製 dispatcher Space

首先需要設定 dispatcher。這是一個小型 Docker Space,負責接收 GitHub workflow_job webhook 事件,並據此啟動 HF Jobs。

請先建立這個 Space,因為 GitHub App 需要 webhook URL,而該 URL 會由 Space 提供。Space 應放在你自己的命名空間,或你有寫入權限的 Hugging Face 組織之下。

網頁設定

前往 huggingface/jobs-actions-dispatcher,然後點擊 Duplicate this Space。

image

選擇:

Owner: your HF user or org
Name: jobs-actions-dispatcher
Hardware: cpu-upgrade

正式 CI 請使用 cpu-upgrade,讓 dispatcher 可持續接收 GitHub webhook。測試時使用 cpu-basic 也可以,通常能正常運作,但閒置後可能會休眠;若 GitHub webhook 在 Space 喚醒期間送達,workflow 可能會永遠停留在佇列。

完成建置後,開啟複製的 Space。你會看到「Required Space secrets」區塊,暫時可忽略。首頁會顯示下一步所需的 GitHub App webhook URL,大致如下:

https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook

CLI 設定

若想透過代理程式或 CLI 工作流程設定 dispatcher 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"

步驟 2:建立並安裝 GitHub App

接著,直接從 dispatcher Space 建立並安裝 GitHub App。這個 App 必須有權監聽排隊中的 workflow 工作,並建立臨時自託管 runner 註冊 token。

網頁設定

開啟已複製的 dispatcher Space:

https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space

在設定表單中,輸入要透過 HF Jobs 執行 CI 的 GitHub 儲存庫:

YOUR-GITHUB-ORG/YOUR-REPO

接著點擊按鈕建立 GitHub App。GitHub 會要求你為 App 命名;只要該名稱在你的 GitHub 帳戶或組織中可用,任何名稱皆可。提交後,最後一頁會清楚列出如何使用 hf CLI 將 App 認證資料上載至 dispatcher Space。

重要提示:你需要提供一個Hugging Face token,且具備啟動 Jobs 的權限,並屬於個人帳戶或將要支付 Job 費用的組織。請將此 token 儲存為 dispatcher Space 中的 HF_TOKEN secret。

最後,在你於 Space 中輸入的同一個 GitHub 儲存庫安裝 App。Trackio 的設定中,我們將它安裝在 gradio-app/trackio。

代理程式輔助設定

GitHub App manifest 流程仍須透過瀏覽器操作,但代理程式可依照相同的 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

步驟 3:完成 dispatcher 設定

此時 dispatcher Space 應已完成設定。GitHub App 設定流程會產生指令,用來將 App 認證資料、webhook secret 和 Hugging Face token 上載至 Space。

image

預設情況下,HF Jobs 會在與 dispatcher Space 相同的命名空間中啟動。若想把 Job 費用計入其他 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 設定的 token 應屬於這個命名空間。

步驟 4:更改 runs-on

workflow 實際上只需小幅修改。不要使用:

runs-on: ubuntu-latest

改用 dispatcher 支援的其中一個標籤:

runs-on: hf-jobs-cpu-upgrade

GPU 測試請使用 GPU 標籤:

runs-on: hf-jobs-t4-small

任何你想在 HF Jobs 上執行的 GitHub Action,只需作出 1 行修改!

步驟 5:測試

透過 CLI 加入最精簡的 smoke-test 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。

就是這樣!

選擇合適 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 的數據:

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 後端,尤其適合需要自訂映像或加速器的機器學習項目。

日誌也帶來驚喜。GitHub Actions 日誌很有用,但大型日誌會令網頁介面變得緩慢。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 Blog · huggingface.co