Использование образов Docker

Каждый Job выполняется внутри Docker-образа, который обеспечивает его программное окружение, включая системные инструменты и установленные библиотеки. С помощью hf jobs run вы указываете образ и команду. С помощью hf jobs uv run uv настраивает Python-окружение для вашего скрипта, а Jobs выбирает образ по умолчанию, если вы не укажете свой.

Выберите способ запуска рабочей нагрузки

Начните с hf jobs uv run, если зависимости вашего Python-скрипта можно установить с помощью uv, как показано в разделе Быстрый старт. Выберите образ, если вам нужны дополнительные системные инструменты или вы хотите использовать готовую программную среду.

По умолчанию образ включает Python и uv. См. Конфигурация UV Jobs для получения информации о текущем образе по умолчанию и доступных вариантах.

Вы можете использовать существующий образ из реестра, например Docker Hub, или собрать и разместить собственный образ с помощью Docker Space.

Использование готового образа

Используйте hf jobs run с образом и командой, которую нужно выполнить внутри него. Подойдёт любой публичный образ из Docker Hub или другого реестра, включая конкретный тег. Начните с небольшого:

hf jobs run ubuntu echo 'Hello from the cloud!'

Job загружает образ, выполняет команду и завершает работу. Чтобы использовать программное обеспечение, уже предоставляемое образом, выберите образ, в который оно включено. Например, используйте образ PyTorch, чтобы создать тензор на GPU и удвоить его значения:

hf jobs run --flavor t4-small --timeout 5m \
    pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
    -- python -c 'import torch; x = torch.ones(3, device="cuda"); print(x * 2)'

Образ предоставляет PyTorch и его программный стек CUDA. --flavor t4-small выбирает GPU, --timeout 5m ограничивает время выполнения Job, а команда Python использует пакет PyTorch, установленный в образе. Его вывод отображается в логах Job.

-- разделяет опции Jobs и команду с её аргументами. Например, --help после этого разделителя передаётся вашей команде. См. Передача аргументов.

Запустите собственный скрипт с входными и выходными файлами

Скрипт, запускаемый командой hf jobs run, должен быть доступен внутри Job. Можно использовать скрипт, входящий в образ, или подключить локальный каталог.

Например, допустим, у вас есть скрипт инференса, использующий пакеты Transformers и PyTorch в образе huggingface/trl. Ваша локальная директория work содержит inference.py и inputs.jsonl, а скрипт принимает пути --input и --output. После создания Storage Bucket для результатов запустите его с помощью:

hf jobs run --flavor t4-small --timeout 10m \
    -v ./work:/work \
    -v hf://buckets/YOUR_USERNAME/results:/output \
    huggingface/trl \
    -- python /work/inference.py --input /work/inputs.jsonl --output /output/results.jsonl

Замените YOUR_USERNAME на пространство имён владельца бакета. CLI загружает локальный каталог и монтирует его в /work. Ваш скрипт читает входные данные оттуда и записывает результаты в бакет, смонтированный в /output, где они остаются доступными после завершения Job. Адаптируйте аргументы команды, оборудование и таймаут под ваш скрипт; см. Volumes для других вариантов входных и выходных данных.

Используйте образ с uv

Используйте hf jobs uv run --image, если вашему скрипту требуются системные инструменты, отсутствующие в образе по умолчанию, при сохранении рабочего процесса управления зависимостями Python через uv. В выбранном образе должен быть установлен uv.

Среда состоит из трёх частей:

• Системные инструменты и библиотеки в образе, такие как ffmpeg или CUDA toolkit, доступны для Job в соответствии с конфигурацией образа.
• Пакеты Python, установленные в образе, принадлежат его существующей среде Python.
• Зависимости скрипта. При использовании встроенного заголовка зависимостей uv устанавливает ваши пакеты Python в изолированную среду. Пакеты, предварительно установленные в образе, автоматически недоступны.

Например, скрипт vLLM может требовать образ с инструментами CUDA, при этом для установки собственных объявленных Python-зависимостей используется uv. Системные инструменты должны оставаться совместимыми с пакетами, которые устанавливает uv.

Если вы хотите использовать предустановленные в образе PyTorch, TRL или vLLM, воспользуйтесь командой hf jobs run. Если также требуется uv для установки дополнительных зависимостей, см. раздел Переиспользование пакетов из образа и добавление зависимостей с помощью uv.

Создайте собственный образ с помощью Docker Space

Docker Space позволяет собирать и размещать образ с инструментами, необходимыми для вашей рабочей нагрузки, включая собственные скрипты, при этом образ может быть приватным без необходимости иметь аккаунт в реестре. Например, можно добавить FFmpeg в Python-образ, чтобы подготовить среду для обработки аудио или видео.

Создайте Docker Space и добавьте этот Dockerfile в корень его репозитория:

FROM python:3.12-slim-bookworm

# Install FFmpeg for audio and video processing.
RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Match the non-root user ID used by Docker Spaces.
RUN useradd --create-home --uid 1000 user
USER user

# Check that FFmpeg is available.
CMD ["ffmpeg", "-version"]

FROM задаёт Python. FFmpeg не входит в этот базовый образ, поэтому RUN устанавливает его на этапе сборки. useradd создаёт пользователя с домашним каталогом и UID 1000, что соответствует Docker Spaces; USER выполняет команды от имени этого пользователя. CMD задаёт команду по умолчанию, здесь — проверка установки FFmpeg.

Зафиксируйте файл и дождитесь, пока в журнале сборки Space не появится сообщение о том, что образ был отправлен. Затем передайте URL Space там, где обычно указывается имя образа, заменив YOUR_USERNAME/video-tools на идентификатор вашего Space:

hf jobs run --flavor cpu-basic --timeout 5m \
    hf.co/spaces/YOUR_USERNAME/video-tools -- ffmpeg -version

Версия отображается в логах Job. Чтобы использовать FFmpeg или Python для вашей рабочей нагрузки, укажите другую команду после URL Space. Чтобы включить собственный скрипт в образ, добавьте в Dockerfile строку вида COPY --chown=user:user process.py /app/process.py и выполните python /app/process.py. См. раздел входные и выходные файлы для подключения данных и сохранения результатов.

В этом примере выводится версия, после чего процесс завершается, поэтому Space показывает ошибку времени выполнения после сборки. Это нормально: Jobs требуется только собранный образ, а не работающий Space.

Гарантии того, что образ, собранный для Space, останется доступным для загрузки, нет. Он может быть утерян из-за технического обслуживания реестра или переноса в другой регион. Если Job сообщает, что образ не найден, выполните factory reboot Space, чтобы пересобрать его. Jobs всегда используют последнюю сборку, поэтому новый коммит также заменяет образ.

Примеры изображений

Образы в реестре поддерживаются их издателями и могут быть зафиксированы на конкретном теге.

Используйте hf jobs run для выполнения команд с пакетами, установленными в образе. Для hf jobs uv run убедитесь, что в образе установлен uv, и следуйте рекомендациям по настройке окружения, приведённым выше. Ознакомьтесь с разделом Примеры и учебные материалы, чтобы найти рабочие нагрузки для запуска и адаптации.

Повторно используйте пакеты из образа и добавьте зависимости с помощью uv

Образы фреймворков содержат предварительно установленные пакеты, сборка которых может быть медленной или сложной, например PyTorch, vLLM и их расширения CUDA. Для вашего скрипта могут потребоваться дополнительные пакеты Python — например, для загрузки конкретного формата данных или отслеживания экспериментов.

Вы можете переиспользовать предустановленный стек образа, используя uv для установки дополнительных пакетов. Объявите дополнительные пакеты в заголовке зависимостей # /// script вашего скрипта, затем укажите uv на интерпретатор образа и добавьте его site-packages в путь импорта:

hf jobs uv run \
    --image vllm/vllm-openai \
    --flavor l4x4 \
    --python /usr/bin/python3 \
    -e PYTHONPATH=/usr/local/lib/python3.12/dist-packages \
    -s HF_TOKEN \
    generate-responses.py

• --python создаёт окружение uv с интерпретатором из образа, соответствующим версии Python, используемой его скомпилированными расширениями. Сам по себе он не предоставляет доступ к пакетам из образа.
• -e PYTHONPATH=... заставляет import vllm использовать предсобранную сборку из образа для данного запуска.
• Сократите зависимости в # /// script до тех, которых не хватает образу. PYTHONPATH ищется раньше окружения uv, поэтому образ перекрывает любые пакеты, объявленные в вашем заголовке, — включая более новую версию, которую вы зафиксировали. Сохранённые зависимости всё ещё могут транзитивно подтягивать эти пакеты; uv не использует PYTHONPATH для разрешения зависимостей.

Пути различаются для каждого изображения, поэтому проверяйте их на cpu-basic, а не используйте жёстко закодированные значения:

hf jobs run --flavor cpu-basic vllm/vllm-openai bash -c 'which python3; which uv; python3 -m pip show vllm | grep Location'

/usr/bin/python3                              # pass to --python
/usr/local/bin/uv                             # uv is present, so `uv run` works
Location: /usr/local/lib/python3.12/dist-packages   # pass to PYTHONPATH

Замените vllm на ту библиотеку, которую вы переиспользуете. Структуры различаются: vllm/vllm-openai и lmsysorg/sglang используют системный dist-packages, описанный выше, unsloth/unsloth использует виртуальное окружение (/opt/venv/...), а huggingface/trl использует conda (/opt/conda/lib/python3.11/site-packages, унаследованный от pytorch/pytorch).

Это определяет сборки образа для импорта, а не для резолвера зависимостей uv. Удаление заголовка может сократить избыточные установки, но не гарантирует их полное устранение. Вариант uv run --system-site-packages, который позволил бы пропустить шаг PYTHONPATH, запрошен в upstream.

Для образа huggingface/trl соответствующие пути к интерпретатору и пакетам:

hf jobs uv run \
    --image huggingface/trl \
    --flavor a100-large \
    --python /opt/conda/bin/python3 \
    -e PYTHONPATH=/opt/conda/lib/python3.11/site-packages \
    -s HF_TOKEN \
    train.py

Эти команды используют generate-responses.py и train.py в качестве имён ваших собственных скриптов.

Устранение неполадок

Использование образов фреймворков для GPU-библиотек

Некоторые GPU-библиотеки требуют дополнительных системных инструментов, таких как компилятор CUDA (nvcc), NCCL или cuDNN. Установка их Python-пакетов не гарантирует, что в образе присутствуют все необходимые инструменты. Например, сэмплер FlashInfer может завершиться с ошибкой при попытке скомпилировать ядро в образе без CUDA toolkit:

RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist

Передача образа фреймворка с необходимым инструментарием CUDA устраняет эту ошибку отсутствия набора инструментов:

hf jobs uv run --image vllm/vllm-openai --flavor l4x4 -s HF_TOKEN generate-responses.py

uv по-прежнему разрешает и устанавливает зависимости вашего скрипта отдельно. Образ предоставляет системные инструменты, но не гарантирует, что разрешённые пакеты Python будут с ними совместимы.