Интеграция GitHub Actions и Hugging Face Jobs

Стандартный параметр runs-on: ubuntu-latest в GitHub Actions предоставляет виртуальную машину по умолчанию. Это удобно, но накладывает определенные ограничения. Инфраструктура GitHub может работать медленно или отключаться на техническое обслуживание, предоставляемые машины универсальны, а доступ к графическим процессорам (GPU) недоступен для большинства открытых проектов. Для проекта Trackio эти ограничения стали критичными. Разработчикам требовалась как надежная CPU-среда для базовых модульных тестов и проверки интерфейса, так и GPU-инфраструктура для тестов на реальном оборудовании CUDA. В результате было создано альтернативное решение: GitHub Actions по-прежнему управляет процессами CI, но сами задачи выполняются на мощностях Hugging Face Jobs.

Такой подход позволяет запускать CI-процессы на платформе Hugging Face Jobs с трансляцией логов в реальном времени. Это сократило время выполнения CPU-задач примерно на 30% и открыло возможность запускать совершенно новый тестовый набор на GPU-серверах. Ниже приведено пошаговое руководство по созданию аналогичной конфигурации для любого репозитория на GitHub. При необходимости можно использовать ИИ-агент, поскольку в инструкции наряду с интерфейсом браузера приводятся команды для интерфейса командной строки (CLI).

Основы работы с Hugging Face Jobs

Инфраструктура Hugging Face Jobs позволяет выполнять команды или скриптинг на серверной платформе Hugging Face, используя практически любые конфигурации аппаратного обеспечения — от базовых CPU до ускорителей уровня t4-small или h200 GPU. Задача представляет собой запуск контейнера с выбранным образом и параметрами оборудования.

Например, можно выполнить команду через CLI:

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 особенно важен: появляется возможность тестировать код на реальном железе без необходимости содержать собственный постоянно работающий сервер.

Архитектура моста jobs-actions

Ключевой элемент интеграции — связывание GitHub Actions с Hugging Face Jobs. Для этого был разработан проект huggingface/jobs-actions. Этот компактный мост превращает задачу GitHub Actions во временный самоуправляемый бегун (self-hosted runner), выполняющийся внутри задания Hugging Face.

Полный цикл работы выглядит следующим образом:

• В конфигурационном файле рабочего процесса указывается метка, за обработку которой отвечает диспетчер, например hf-jobs-cpu-upgrade или hf-jobs-t4-small.
• Когда GitHub запускает такую задачу, стандартный бегун для нее отсутствует. Вместо этого отправляется подписанный веб-хук workflow_job.queued через приложение GitHub на сервер диспетчера.
• Диспетчер перехватывает событие с меткой hf-jobs-*, генерирует временный токен регистрации бегуна GitHub и запускает соответствующую задачу Hugging Face на нужном железе.
• С точки зрения GitHub это обычный самоуправляемый бегун. С точки зрения Hugging Face — это отдельная задача, которая разворачивает контейнер для выполнения шагов рабочего процесса из репозитория.

Настройка диспетчера задач

Первый шаг заключается в развертывании диспетчера. Он представляет собой небольшое Space-пространство на базе Docker, которое принимает веб-хуки о постановке задач в очередь от GitHub и запускает задания на стороне Hugging Face. Создать его нужно в первую очередь, так как для приложения GitHub потребуется URL веб-хука, который генерируется этим пространством. Пространство следует разместить в своем личном аккаунте или в организации Hugging Face, где у вас есть права на запись.

Перейдите в репозиторий huggingface/jobs-actions-dispatcher и нажмите кнопку Duplicate this Space. Укажите следующие параметры:

• Owner: ваш пользователь или организация на Hugging Face.
• Name: jobs-actions-dispatcher.
• Hardware: cpu-upgrade.

Выбор аппаратного уровня cpu-upgrade важен для полноценного CI, чтобы диспетчер всегда оставался доступным для получения веб-хуков от GitHub. Уровень cpu-basic подходит для тестирования, но может переходить в спящий режим при неактивности; если в этот момент поступит веб-хук от GitHub, рабочий процесс может остаться в очереди навсегда.

После завершения сборки откройте созданное пространство. На главной странице будут указаны необходимые секреты пространства (Required Space secrets), которые на данном этапе можно пропустить. Там же отобразится URL веб-хука для приложения GitHub, который понадобится на следующем шаге:

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

Если вы предпочитаете настраивать диспетчер через CLI или с помощью агента, используйте следующие команды:

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"

Создание и установка приложения GitHub

Следующий этап — создание и интеграция приложения GitHub непосредственно из пространства диспетчера. Приложению требуются права на прослушивание поставленных в очередь задач и создание временных токенов для бегунов.

Откройте созданное пространство диспетчера. В форме настройки укажите репозиторий GitHub, для которого должен выполняться CI:

YOUR-GITHUB-ORG/YOUR-REPO

Затем нажмите кнопку создания приложения GitHub. Платформа предложит выбрать имя для приложения — оно может быть любым, если свободно в вашей учетной записи или организации. После отправки формы на экране появятся инструкции по загрузке учетных данных приложения в пространство диспетчера с помощью утилиты hf CLI.

Важное примечание: вам потребуется предоставить токен Hugging Face с правами на запуск задач (Jobs), соответствующий вашему личного аккаунту или организации, на баланс которой будут записываться затраты. Этот токен необходимо сохранить в качестве секрета HF_TOKEN в настройках пространства диспетчера.

На завершающем этапе приложение устанавливается на тот же репозиторий GitHub, который был указан в пространстве. В случае с проектом Trackio приложение установили для gradio-app/trackio. Процесс настройки через манифест приложения выполняется в браузере, но агент может пройти тот же путь по следующему сценарию:

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 в интерфейсе пространства, нажмите кнопку создания приложения GitHub, выберите доступное имя и следуйте инструкциям на экране. После создания приложения установите его для своего репозитория через страницу настроек. Для организаций на GitHub настройки установки доступны по адресу:

https://github.com/organizations/YOUR-GITHUB-ORG/settings/installations

К этому моменту пространство диспетчера должно быть полностью настроено. Процесс создания приложения GitHub автоматически сформировал команды для загрузки учетных данных, секретов веб-хука и токена Hugging Face в пространство.

По умолчанию задания Hugging Face запускаются в том же пространстве имен, где находится диспетчер. При необходимости можно задать переменную HF_NAMESPACE на уровне пространства, если вы хотите перенести оплату на другой аккаунт или организацию:

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"

Токен, настроенный на предыдущем шаге, должен соответствовать этому пространству имен.

Изменение конфигурации рабочих процессов

Сама модификация CI-скриптов минимальна. Вместо стандартного указания окружения:

runs-on: ubuntu-latest

используйте одну из меток, поддерживаемых диспетчером:

runs-on: hf-jobs-cpu-upgrade

Для тестов с использованием графического процессора применяется метка GPU:

runs-on: hf-jobs-t4-small

Для любого рабочего процесса GitHub Actions такое изменение в одну строку — это всё, что требуется для переноса выполнения на инфраструктуру Hugging Face.

Чтобы добавить базовый тестовый рабочий процесс через командную строку, выполните следующие действия:

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 Actions — например, их можно посмотреть в пулл-реквесте Trackio №565.

Выбор подходящего Docker-образа и результаты тестирования

Первоначальная конфигурация для CPU использовала стандартный образ ubuntu:22.04, при этом недостающие системные пакеты устанавливались во время каждого запуска. Это работало, но медленнее, чем требовалось. Образ ubuntu-latest от GitHub по умолчанию содержит множество инструментов разработки, в то время как чистый образ Ubuntu ими не укомплектован. Для проекта Trackio в тестах интерфейса требуются браузеры 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

Ниже приведены сравнительные показатели производительности CI для проекта Trackio:

• Базовая конфигурация GitHub ubuntu-latest: 1 минута 40 секунд (базовый показатель).
• HF Jobs CPU с образом Playwright: 1 минута 10 секунд (на 30 секунд или примерно на 30% быстрее).
• HF Jobs GPU с меткой t4-small: 45 секунд (сравнение с базовыми серверами GPU на GitHub отсутствует).

Наиболее значительным достижением стал запуск GPU-тестирования. Проверка Trackio с использованием графического процессора на базе Hugging Face Jobs завершилась за 45 секунд, обойдясь менее чем в один цент по тарифу t4-small за это время. Результаты для процессора также оказались показательными: с правильно подобранным контейнером сборка под Linux выполнялась быстрее стандартных серверов GitHub. Это подтверждает жизнеспособность HF Jobs в качестве эффективной серверной базы CI, особенно для проектов в области машинного обучения, которым требуются специализированные образы или аппаратные ускорители.

Система логирования также оказалась удобной. Логи GitHub Actions полезны, но их веб-интерфейс может перегружаться при выводе больших объемов данных. Логи Hugging Face Jobs легко извлекаются через интерфейс командной строки:

hf jobs logs <job_id> > logs.txt

Это упрощает их анализ с помощью локальных инструментов или специализированных агентов. В разработанном мосте также реализовано дублирование логов задач GitHub Actions в логи заданий HF, поэтому любая из систем предоставляет достаточно информации для отладки.

Хотя в рамках CI для Trackio это не потребовалось, инфраструктура HF Jobs поддерживает монтирование томов (volumes). Данная функция полезна, если в процессе тестирования необходимо оперативно загружать датасеты или модели из репозитория Hugging Face. Представленной информации должно быть достаточно для самостоятельного тестирования Hugging Face Jobs в качестве среды выполнения задач GitHub Actions.

Источник: huggingface.co