如何將 GitHub CI 遷移至 Hugging Face Jobs
Migrating Your GitHub CI to Hugging Face Jobs
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、h200GPU - 可選的環境變數和機密
例如,你可以執行:
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。
完整流程如下:
- Pull request 觸發 GitHub Actions workflow。
- GitHub 會將任何
runs-on標籤不可用的工作排入佇列,例如hf-jobs-cpu-upgrade或hf-jobs-t4-small,再透過 GitHub App 向 dispatcher 發送已簽署的workflow_job.queuedwebhook。 - Dispatcher Space 會驗證 webhook、檢查是否有
hf-jobs-*標籤、產生短效 GitHub runner 註冊 token,並在相符硬件上啟動 HF Job。 - HF Job 啟動臨時 GitHub Actions runner,再使用該一次性 token 將 runner 註冊到儲存庫。
- 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。
選擇:
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。
預設情況下,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