Конфигурация

Аутентификация

Для запуска Jobs необходимо пройти аутентификацию с помощью hf auth login и использовать токен с разрешениями на запуск и управление Jobs.

В качестве альтернативы вы можете передать токен Hugging Face вручную с помощью --token в CLI или аргумента token в Python.

Передача аргументов

Используйте --, чтобы отделить опции Jobs от вашей команды или скрипта и их аргументов. Опции после --, такие как --help или --timeout, передаются дальше, а не интерпретируются Jobs. Это относится как к UV, так и к Docker Jobs.

hf jobs uv run --flavor t4-small -- script.py --early-stopping-patience 3
               └─ Jobs option ┘    └─ script + arguments ─────────────┘

UV Jobs

Укажите скрипт UV или команду python для запуска так, как вы это делаете с UV:

>>> hf jobs uv run train.py

>>> hf jobs uv run python -c 'print("Hello from the cloud!")'

Команда hf jobs uv run принимает аргументы UV, такие как --with и --python. Аргумент --with позволяет указать зависимости python, а --python — выбрать версию python:

>>> hf jobs uv run --with trl train.py
>>> hf jobs uv run --python 3.12 train.py

Например, передайте аргументы команде с помощью --:

>>> hf jobs uv run --with trl-jobs -- trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara

Список всех аргументов приведён в документации CLI и в документации команд UV.

По умолчанию UV Jobs запускаются с Docker-образом ghcr.io/astral-sh/uv:python3.12-bookworm, но вы можете использовать другой образ, если в нём установлен UV, с помощью --image <docker-image>.

См. Использование образов Docker, чтобы выбрать образ и понять, как его окружение взаимодействует с зависимостями UV.

Определите конфигурацию запуска в скрипте

Скрипт, который корректно работает только в определённой среде выполнения (конкретный образ, тип GPU или системный интерпретатор), может переносить с собой эту конфигурацию в необязательной таблице [tool.hf-jobs] в заголовке PEP 723:

# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# image   = "vllm/vllm-openai:unlimited-ocr"
# flavor  = "l4x1"
# python  = "/usr/bin/python3"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run ocr.py затем запускается на этом образе и оборудовании. Обычный uv run игнорирует таблицу, так как таблицы [tool.*] являются частью PEP 723, и инструменты пропускают те, которые им не принадлежат.

Поддерживаемые ключи, все необязательные: image, flavor, python, timeout, name, namespace, env, secrets, labels, volumes, network_group и network_aliases. Они соответствуют флагам с теми же именами. Значения из скрипта являются значениями по умолчанию: явный флаг всегда имеет приоритет, а env, secrets, labels и volumes объединяются поэлементно, поэтому -e и -v дополняют то, что объявлено в скрипте. Неизвестный ключ приводит к ошибке, а secrets содержит только имена: значения берутся из окружения того, кто запускает скрипт, и секрет, который не задан локально, также является ошибкой.

Используйте --dry-run, чтобы вывести разрешённую конфигурацию без отправки; значения, полученные из скрипта, отмечены как (from script). Полные правила слияния описаны в руководстве по CLI hf.

Таблица используется только CLI hf. Функции run_uv_job() и create_scheduled_uv_job() её игнорируют, поэтому при вызове из Python явно передавайте параметры image=, flavor=, …

Docker Jobs

Укажите образ Docker и команду для запуска так, как вы бы это делали с docker:

>>> hf jobs run ubuntu echo "Hello from the cloud!"

Здесь --help передаётся в Python, а не выводит справку по Jobs:

>>> hf jobs run --flavor cpu-basic python:3.12 -- python --help

Список всех аргументов приведён в документации CLI.

См. Использование образов Docker для примеров с использованием существующих образов и образов, созданных с помощью Docker Spaces.

Переменные окружения и секреты

Встроенные переменные окружения

Аналогично встроенным переменным окружения в Spaces, Jobs автоматически предоставляют следующие переменные окружения внутри контейнера:

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

# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"

Пользовательские переменные окружения

Вы можете передать переменные окружения в вашу задачу с помощью

# Pass environment variables
>>> hf jobs uv run -e FOO=foo -e BAR=bar python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass an environment from a local .env file
>>> hf jobs uv run --env-file .env python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass secrets - they will be encrypted server side
>>> hf jobs uv run -s MY_SECRET=psswrd python -c 'import os; print(os.environ["MY_SECRET"])'

# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs uv run --secrets-file .env.secrets python -c 'import os; print(os.environ["MY_SECRET"])'

Используйте --secrets HF_TOKEN, чтобы неявно передать локальный токен Hugging Face. При таком синтаксисе секрет извлекается из переменной окружения. Для HF_TOKEN при отсутствии переменной окружения может быть прочитан файл токена, расположенный в домашней папке Hugging Face.

Томы

Подключайте репозитории Hugging Face (модели, наборы данных), Storage Buckets или локальные каталоги в качестве томов в контейнере вашего задания с помощью -v или --volume. Для источников из Hub используется схема URL hf://: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]; локальный каталог передаётся непосредственно в качестве источника.

Поскольку смонтированные файлы загружаются по требованию, монтирование позволяет Job работать с наборами данных, значительно превышающими объём локального диска. См. Обработка больших наборов данных для информации о монтировании, потоковой передаче и обработке больших данных в Jobs.

Типы томов:

Затем используйте смонтированный том как локальный каталог внутри контейнера:

# Mount a dataset and query it with DuckDB
>>> hf jobs run -v hf://datasets/stanfordnlp/imdb:/dataset \
...     duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"

# Mount a bucket to save training checkpoints
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
...     sft.py --output-dir /training-outputs/training-v3-final

Несколько томов можно смонтировать, повторив флаг -v:

>>> hf jobs run -v hf://datasets/username/my-dataset:/data -v hf://buckets/username/my-bucket:/output \
...     python:3.12 python script.py

Модели и наборы данных всегда монтируются в режиме только для чтения. Бuckets хранения по умолчанию доступны в режиме чтения и записи, что удобно для сохранения результатов, контрольных точек или промежуточных данных. Используйте :ro, чтобы смонтировать bucket в режиме только для чтения:

>>> hf jobs run -v hf://buckets/username/my-bucket:/mnt:ro python:3.12 ls /mnt

Локальные каталоги

Передача локального каталога в качестве источника синхронизирует его с вашим приватным Storage Bucket jobs-artifacts (создаётся автоматически) перед запуском Job, после чего монтирует его в контейнере. Локальные каталоги по умолчанию монтируются в режиме read-only; для записи результатов используйте :rw:

>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py

Повторная синхронизация того же каталога загружает только новые или изменённые файлы. Чтобы получить файлы, которые Job записал в том с правами чтения и записи, после завершения Job выполните обратную синхронизацию папки его бакета — при запуске Job CLI выводит точную команду hf buckets sync. Это работает и для запланированных задач: каталог синхронизируется один раз при создании расписания, а каждый запуск монтирует ту же папку. В Python используйте sync_job_volume.

В Python используйте класс Volume:

from huggingface_hub import Volume, run_job

job = run_job(
    image="python:3.12",
    command=["python", "-c", "import os; print(os.listdir('/data'))"],
    volumes=[
        Volume(type="dataset", source="username/my-dataset", mount_path="/data"),
        Volume(type="bucket", source="username/my-bucket", mount_path="/output"),
    ],
)

Для монтирования тома требуется huggingface_hub >= 1.8.0. Подробности см. в документации Python-клиента и руководстве по установке.

Вариант аппаратного обеспечения

Запускайте задачи на GPU или TPU с помощью аргумента flavor. Например, чтобы запустить задачу PyTorch на GPU A10G:

>>> hf jobs uv run --with torch --flavor a10g-small python -c "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"

При запуске этого кода вы увидите следующий вывод!

This code ran with the following GPU: NVIDIA A10G

Вот ещё один пример запуска скрипта дообучения, например trl/scripts/sft.py:

>>> hf jobs uv run --with trl --flavor a10g-small -s HF_TOKEN -- sft.py --model_name_or_path Qwen/Qwen2-0.5B ...

Для подробных рекомендаций по запуску задач обучения моделей с помощью TRL на инфраструктуре Hugging Face обратитесь к документации TRL Jobs Training. В ней описаны рецепты дообучения, выбор аппаратного обеспечения и лучшие практики для эффективного обучения моделей.

Список доступных вариантов --flavor можно посмотреть с помощью команды hf jobs hardware (по умолчанию — cpu-basic):

>>> hf jobs hardware
name             pretty name             cpu       ram      storage   accelerator               cost/min  cost/hour
cpu-basic        CPU Basic               2 vCPU    16 GB    50 GB                               $0.0002   $0.01
cpu-upgrade      CPU Upgrade             8 vCPU    32 GB    50 GB                               $0.0005   $0.03
cpu-performance  CPU Performance         32 vCPU   256 GB   1024 GB                             $0.0317   $1.90
cpu-xl           CPU XL                  16 vCPU   124 GB   1000 GB                             $0.0167   $1.00
t4-small         Nvidia T4 - small       4 vCPU    15 GB    50 GB     1x T4 (16 GB)             $0.0067   $0.40
t4-medium        Nvidia T4 - medium      8 vCPU    30 GB    100 GB    1x T4 (16 GB)             $0.0100   $0.60
a10g-small       Nvidia A10G - small     4 vCPU    15 GB    110 GB    1x A10G (24 GB)           $0.0167   $1.00
a10g-large       Nvidia A10G - large     12 vCPU   46 GB    200 GB    1x A10G (24 GB)           $0.0250   $1.50
a10g-largex2     2x Nvidia A10G - large  24 vCPU   92 GB    1000 GB   2x A10G (48 GB)           $0.0500   $3.00
a10g-largex4     4x Nvidia A10G - large  48 vCPU   184 GB   2000 GB   4x A10G (96 GB)           $0.0833   $5.00
a100-large       Nvidia A100 - large     12 vCPU   142 GB   1000 GB   1x A100 (80 GB)           $0.0417   $2.50
a100x4           4x Nvidia A100          48 vCPU   568 GB   4000 GB   4x A100 (320 GB)          $0.1667   $10.00
a100x8           8x Nvidia A100          96 vCPU   1136 GB  8000 GB   8x A100 (640 GB)          $0.3333   $20.00
h200             Nvidia H200             23 vCPU   256 GB   3000 GB   1x H200 (141 GB)          $0.0833   $5.00
h200x2           Nvidia H200             46 vCPU   512 GB   6000 GB   2x H200 (282 GB)          $0.1667   $10.00
h200x4           Nvidia H200             92 vCPU   1024 GB  12000 GB  4x H200 (564 GB)          $0.3333   $20.00
h200x8           Nvidia H200             184 vCPU  2048 GB  24000 GB  8x H200 (1128 GB)         $0.6667   $40.00
rtx-pro-6000     Nvidia RTX PRO 6000     23 vCPU   256 GB   475 GB    1x RTX PRO 6000 (96 GB)   $0.0458   $2.75
rtx-pro-6000x2   Nvidia RTX PRO 6000     46 vCPU   512 GB   950 GB    2x RTX PRO 6000 (192 GB)  $0.0917   $5.50
rtx-pro-6000x4   Nvidia RTX PRO 6000     92 vCPU   1024 GB  1900 GB   4x RTX PRO 6000 (384 GB)  $0.1833   $11.00
rtx-pro-6000x8   Nvidia RTX PRO 6000     184 vCPU  2048 GB  3800 GB   8x RTX PRO 6000 (768 GB)  $0.3667   $22.00
l4x1             1x Nvidia L4            8 vCPU    30 GB    400 GB    1x L4 (24 GB)             $0.0133   $0.80
l4x4             4x Nvidia L4            48 vCPU   186 GB   3200 GB   4x L4 (96 GB)             $0.0633   $3.80
l40sx1           1x Nvidia L40S          8 vCPU    62 GB    380 GB    1x L40S (48 GB)           $0.0300   $1.80
l40sx4           4x Nvidia L40S          48 vCPU   382 GB   3200 GB   4x L40S (192 GB)          $0.1383   $8.30
l40sx8           8x Nvidia L40S          192 vCPU  1534 GB  6500 GB   8x L40S (384 GB)          $0.3917   $23.50

Открыть порты

Задачи могут открывать порты контейнеров через публичный прокси задач с помощью --expose <port> (CLI) или expose=[<port>] (Python API). Каждый открытый порт доступен по адресу https://<job_id>--<port>.hf.jobs и требует токен HF с доступом read к пространству имён задачи:

curl -H "Authorization: Bearer $HF_TOKEN" https://<job_id>--<port>.hf.jobs/

Это работает для hf jobs run, hf jobs uv run и их запланированных вариантов. Повторите флаг, чтобы открыть несколько портов (--expose 8000 --expose 8001), или передайте несколько портов в списке (expose=[8000, 8001]).

Чтобы сделать порт доступным без HF-токена, используйте --expose-public <port> (CLI) или expose_public=[<port>] (Python API). В этом случае порт будет доступен любому, у кого есть URL, поэтому используйте этот вариант только для сервисов, которые безопасно публиковать. Можно комбинировать оба варианта: тогда для одних портов потребуется HF-токен, а другие будут публичными.

Открытые порты тарифицируются по небольшой фиксированной почасовой ставке сверх стоимости оборудования задачи, но только во время её выполнения. Подробности см. на странице с тарифами.

CLI

# Expose a web server running on port 8000
>>> hf jobs run --expose 8000 python:3.12 python -m http.server 8000
✓ Job started
  id: 6a2aa7cec4f53f9fc5aa4cff
  url: https://huggingface.co/jobs/Wauplin/6a2aa7cec4f53f9fc5aa4cff
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a2aa7cec4f53f9fc5aa4cff--8000.hf.jobs
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

Python

>>> from huggingface_hub import run_job
>>> job = run_job(image="python:3.12", command=["python", "-m", "http.server", "8000"], expose=[8000])
>>> job.status.expose_urls
['https://6a2ab384c4f53f9fc5aa4d4f--8000.hf.jobs']

Изменение портов запущенного Job

Используйте hf jobs expose, чтобы изменить открытые порты, не перезапуская Job:

# Expose port 8000 (requires an HF token)
>>> hf jobs expose <job_id> 8000

# Expose port 8000 (requires an HF token) and port 9000 publicly
>>> hf jobs expose <job_id> 8000 --public 9000

# Close all exposed ports
>>> hf jobs expose <job_id> --clear

Команда заменяет полный список открытых портов, поэтому порт, который вы не укажете, будет закрыт. В Python используйте update_job_expose.

SSH

Вы можете открыть интерактивную SSH-сессию в работающем Job для отладки, инспекции или прямой работы внутри контейнера. Включите её при создании задания с помощью --ssh (CLI) или ssh=True (Python API), затем подключитесь с помощью hf jobs ssh <job_id>.

Доступ разрешён только пользователям с правами записи (Write) в пространстве имён задачи (Job) (то есть создателю задачи или членам организации-владельца с правами записи). Аутентификация выполняется с помощью SSH-ключей, зарегистрированных на странице https://huggingface.co/settings/keys.

SSH доступен в hf jobs run и hf jobs uv run. Он не поддерживается для запланированных задач.

CLI

# Start a job with SSH enabled
>>> hf jobs run --ssh --detach --timeout 10m python:3.12 sleep infinity
✓ Job started
  id: 6a2bd1f1871c005b5352ad31
  url: https://huggingface.co/jobs/Wauplin/6a2bd1f1871c005b5352ad31
Hint: Use `hf jobs ssh 6a2bd1f1871c005b5352ad31` to open an SSH session into the job.

# Open an SSH session into the job
>>> hf jobs ssh 6a2bd1f1871c005b5352ad31

Вы также можете вывести команду SSH без её выполнения (--dry-run) или передать конкретный файл идентификации (-i/--identity-file):

>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 --dry-run
ssh 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 -i ~/.ssh/id_ed25519

Python

>>> from huggingface_hub import run_job
>>> job = run_job(image="python:3.12", command=["sleep", "infinity"], ssh=True)
>>> job.status.ssh_url
'ssh://6a2bd1f1871c005b5352ad31@ssh.hf.jobs'

Затем подключитесь из терминала с помощью hf jobs ssh <job_id> или напрямую с помощью ssh <job_id>@ssh.hf.jobs.

Перенаправление портов

Поскольку это обычное SSH-соединение, вы можете использовать флаги -L и -R SSH для перенаправления портов между вашим компьютером и Job. Подключитесь напрямую с помощью ssh (чтобы получить точный адрес назначения, выполните hf jobs ssh <job_id> --dry-run) и добавьте флаги перенаправления.

Используйте -L (локальное перенаправление) для доступа к сервису, работающему внутри Job, с вашего компьютера. Например, чтобы подключиться к TensorBoard, запущенному в Job обучения:

# Forward local port 6006 to the Job's TensorBoard on port 6006
>>> ssh -L 6006:localhost:6006 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

Затем откройте http://localhost:6006 в вашем браузере.

Используйте -R (удалённое перенаправление), чтобы дать Job доступ к сервису, работающему на вашем компьютере. Например, чтобы предоставить Job доступ к локальной базе данных или API:

# Make your local port 8080 reachable from inside the Job on port 8080
>>> ssh -R 8080:localhost:8080 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

Группы сетей

Задачи могут присоединяться к сетевой группе с помощью --network-group <name> (CLI) или network_group="<name>" (Python API). Задачи в одном и том же namespace и resource group, объединённые в группу, могут взаимодействовать друг с другом на любом порту: HF_NETWORK_GROUP_HOSTNAME разрешается в адрес каждого участника, а ${HF_NETWORK_GROUP_PREFIX}<alias> — в адрес тех участников, которые указали псевдоним с помощью --network-alias <alias> (CLI) или network_aliases=[<alias>] (Python API).

Это работает для hf jobs run и hf jobs uv run. Члены группы разрешаются до того, как они станут готовы, поэтому подключайтесь с повторными попытками. Имена групп и псевдонимы — это строчные буквы, цифры и дефисы, максимум 46 и 34 символа соответственно; псевдонимы задачи должны быть уникальными.

CLI

# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000

# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'

Python

>>> from huggingface_hub import run_job
>>> server = run_job(
...     image="python:3.12",
...     command=["python", "-m", "http.server", "8000"],
...     network_group="train",
...     network_aliases=["master"],
... )
>>> client = run_job(
...     image="python:3.12",
...     command=["sh", "-c", 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'],
...     network_group="train",
... )

Фреймворки обучения на нескольких узлах могут использовать алиас в качестве хоста для rendezvous, например torchrun --master_addr "${HF_NETWORK_GROUP_PREFIX}master".

Тайм-аут

У заданий есть тайм-аут по умолчанию (30 минут), после которого они автоматически останавливаются. Это важно учитывать при выполнении длительных задач, таких как обучение моделей.

Вы можете указать собственное значение тайм-аута с помощью параметра --timeout при запуске задания. Тайм-аут можно задать двумя способами:

1. В виде числа (интерпретируется как секунды):

Используйте --timeout и укажите значение в секундах (здесь 2 часа = 7200 секунд):

>>> hf jobs uv run --timeout 7200 --with torch --flavor a10g-large train.py

2. В виде строки с единицами времени:

Или используйте --timeout и задавайте разные единицы времени:

>>> hf jobs uv run --timeout 2h --with torch --flavor a10g-large train.py

Другие примеры:

--timeout 30m    # 30 minutes
--timeout 1.5h   # 1.5 hours
--timeout 1d     # 1 day
--timeout 3600s  # 3600 seconds

Поддерживаемые единицы времени:

• s - секунды
• m - минуты
• h - часы
• d - дни

Если вы не укажете тайм-аут, для вашей задачи будет применён тайм-аут по умолчанию. Для длительных задач, таких как обучение моделей, которые могут занимать часы, убедитесь, что вы задали подходящий тайм-аут, чтобы избежать неожиданного завершения задачи.

Повторные попытки

По умолчанию Job выполняется один раз. Используйте --attempts <n> (CLI) или attempts=<n> (Python API), чтобы повторить выполнение Job в случае сбоя. В это число входит и первый запуск, поэтому --attempts 3 позволяет сделать до двух повторных попыток:

>>> hf jobs uv run --attempts 3 --flavor a10g-large train.py

Это работает для hf jobs run, hf jobs uv run и их запланированных вариантов.

Повторный запуск выполняет команду заново, начиная с начала, в рамках того же Job ID. Чтобы повторный запуск мог продолжить работу с того места, где остановилась предыдущая попытка, записывайте контрольные точки в смонтированное хранилище и настраивайте ваш скрипт на возобновление работы из них. См. раздел After it ends в документации Train Models on Jobs.

Пространство имён

Запускайте Jobs под учётной записью вашей организации с помощью аргумента --namespace. Убедитесь, что вы вошли в систему с токеном, имеющим разрешения на запуск и управление Jobs под учётной записью вашей организации.

>>> hf jobs uv run --namespace my-org-name python -c "print('Running in an org account')"

Обратите внимание, что вы можете передать токен с соответствующими правами вручную:

>>> hf jobs uv run --namespace my-org-name --token hf_xxx python -c "print('Running in an org account')"

Метки

Добавьте одну или несколько меток к Job, чтобы прикрепить к нему метаданные с помощью -l или --label. Позже вы можете использовать такие метаданные для фильтрации Jobs на сайте или в CLI.

Добавьте метки с помощью --label my-label или метки в формате ключ-значение с помощью --label key=value. Ключи и значения могут содержать буквы, цифры, - и _. Например:

hf jobs uv run --label fine-tuning --label model=Qwen3-06B --label dataset=Capybara ...

Обратите внимание, что многократное использование одного и того же key приводит к тому, что последнее key=value перезаписывает и отбрасывает все предыдущие метки с этим key.

Название задания

Укажите имя для Job, чтобы его было проще найти и распознать в интерфейсе. Имя сохраняется как метка name и не обязательно должно быть уникальным. В интерфейсе Jobs группируются по имени.

hf jobs run --name daily-report python:3.12 python report.py

Если не передать --name, имя Job формируется на основе его Docker-образа или скрипта, дополненного коротким хэшем команды. Благодаря этому повторные запуски одной и той же команды получают одинаковое имя, а разные команды — разные (например, python-3-12-6b9d662c для Job, работающего на python:3.12).

Обновить метки

Обновите метки существующей задачи с помощью hf jobs labels. Передача --label заменяет все существующие метки; передача только --name сохраняет их:

# Replace the labels on a Job
hf jobs labels <job_id> --label env=prod --label team=ml

# Name an existing Job (keeps its other labels)
hf jobs labels <job_id> --name daily-report

# Remove all labels from a Job
hf jobs labels <job_id> --clear