Обучение на GPU-сервере, кластере SLURM или машине за NAT

Новое в v2.14.0

В этом руководстве обучение моделей Potato переносится с сервера разметки на машину с GPU. Руководство написано для администратора исследования, у которого сервер разметки — небольшая облачная виртуальная машина или ноутбук, а GPU стоят на лабораторном сервере, университетском кластере или рабочей станции, к которой сервер не может подключиться. Для каждого из трёх удалённых бэкендов на странице описано, когда выбирать бэкенд, что должно быть установлено на удалённой машине, конфигурация, команда проверки, что происходит во время запуска, как отменить запуск и какие сбои встречаются чаще всего. Руководство предполагает проект, который уже обучается на сервере разметки, например проект с отзывами из руководства Обучите свою первую модель.

Четыре места, где может выполняться запуск

Бэкенд — это место, где выполняется запуск обучения. В Potato всегда есть бэкенд local, подпроцесс на сервере разметки. Остальные бэкенды вы называете в model_training.backends:

Выбирайте ssh, когда сервер разметки может войти на GPU-машину по ключу ssh. Выбирайте slurm, когда GPU стоят за планировщиком SLURM, а машина, на которую вы можете войти, — головной узел. Выбирайте agent, когда соединение от сервера к GPU-машине открыть нельзя, потому что агент сам открывает каждое соединение. Рабочая станция за домашним роутером или университетским брандмауэром — обычный случай для агента. Предсказания и результат запуска доходят до сервера с любого бэкенда, поэтому обратная запись и оценка на отложенных объектах работают одинаково, где бы ни работал тренер. Любой тренер, кроме decision-calibrate, работает на любом бэкенде.

Конфигурация проекта

Конфигурация ниже — проект с отзывами из первого руководства, к которому добавлены все три удалённых бэкенда. Настоящему проекту нужны только те бэкенды, которыми вы пользуетесь, и каждому бэкенду посвящён отдельный раздел ниже. max_wall_seconds: 3600 останавливает любой запуск, не завершившийся за час. На бэкенде ssh или agent сервер проверяет лимит каждую секунду, поэтому запуск, зависший на удалённой машине, не держит очередь запусков дольше лимита:

annotation_task_name: "Review Sentiment"
task_dir: "."
data_files:
  - "data/reviews.json"
item_properties:
  id_key: "id"
  text_key: "text"
output_annotation_dir: "annotation_output"
admin_api_key: "change-me"
 
annotation_schemes:
  - annotation_type: "radio"
    name: "sentiment"
    description: "Is this review positive or negative?"
    labels: ["positive", "negative"]
 
model_training:
  enabled: true
  backend: gpu-server        # the default for runs; leave out to keep runs local
  max_wall_seconds: 3600
  writeback:
    schemas: ["sentiment"]
    include_unlabeled: true
    min_confidence: 0.6
  backends:
    gpu-server:
      type: ssh
      host: gpu.example.org
      python: /opt/conda/bin/python3
      gpus: auto
      min_free_gpu_mb: 4000
    cluster:
      type: slurm
      host: login.cluster.example.org
      python: /opt/conda/bin/python3
      job_python: /shared/envs/train/bin/python
      remote_dir: /shared/projects/me/potato-training
      gres: gpu:1
      time: "04:00:00"
      prelude: ["module load cuda/12.4"]
    lab-workstation:
      type: agent
      queue_timeout_s: 3600

Проверьте конфигурацию до запуска сервера:

potato validate config.yaml --strict

Валидатор сообщает о ключе, которого тип бэкенда не принимает, о бэкенде ssh или slurm без host, о remote_dir SLURM в /tmp и о model_training.backend, который не называет ни одного бэкенда. На те же ошибки сервер отказывается запускаться, поэтому опечатка pyhton останавливает сервер при старте, а не отправляет запуски на python3 по умолчанию.

Меню Runs on и API

На странице Training по адресу /admin/training есть меню Runs on, которое перечисляет каждый бэкенд с его типом и хостом, например gpu-server (ssh to gpu.example.org). model_training.backend задаёт пункт, который меню выбирает первым, а таблица Runs записывает, где выполнялся каждый запуск, в колонке Ran on. Запуск через API называет свой бэкенд в поле backend тела запроса:

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "hf-text-classification", "schemas": ["sentiment"], "backend": "cluster"}'

Имя бэкенда, которого нет в конфигурации, отклоняется с кодом 409. Автоматическое переобучение использует model_training.backend, если auto_retrain.backend не называет другой бэкенд, а auto_retrain целиком описан в руководстве Модель в цикле. Одновременно выполняется один запуск, каким бы ни был бэкенд, а запуск, начатый во время другого, ждёт в очереди.

Обучение на этой машине

Прежде чем переносить запуски на другие машины, проверьте, какое устройство получает локальный запуск. При device: auto по умолчанию локальный запуск берёт сначала CUDA, затем Apple Metal (mps), затем CPU, а device: cuda:1 называет один GPU. Команда проверки выводит устройство, которое получил бы локальный запуск:

potato training check local config.yaml

На Mac с процессором Apple команда выводит local: this machine, Apple Metal (mps). Запрошенное устройство, которого нет, заменяется на CPU или другой ускоритель с предупреждением в журнале запуска. Когда ответ CPU, а тренер дообучает трансформер, перенесите запуск на один из удалённых бэкендов ниже. Конфигурация перечисляет device, num_threads и max_ram_mb для локальных запусков.

GPU-сервер по ssh

Бэкенд ssh запускает тренер на машине, до которой сервер разметки дотягивается по ssh, обычно на лабораторном GPU-сервере. Potato сам запускает всё на удалённой стороне, поэтому вручную там ничего не устанавливается и не запускается, кроме Python и пакетов тренера. Potato на GPU-хосте устанавливать не нужно, потому что при первом запуске Potato копирует на хост собственный исходный код Python и использует копию, пока код не изменится.

Требования к бэкенду ssh

Учётной записи, от имени которой работает сервер разметки, нужен ключ ssh, с которым вход на GPU-хост проходит без запроса. Potato запускает ssh с BatchMode=yes, поэтому запрос пароля сразу завершает запуск ошибкой, а не зависает. Команда ssh gpu.example.org true от этой учётной записи должна выполняться успешно, а ключ с парольной фразой подходит, если ключ держит ssh-agent. Значение host — любое имя, которое принимает ssh, подойдёт и псевдоним из ~/.ssh/config. Ключи user, port и identity_file передаются в ssh как -l, -p и -i.

GPU-хосту нужны Python 3.8 или новее и пакеты запускаемого тренера. Для hf-text-classification это torch, transformers и peft, содержимое дополнения potato-annotation[train-text]. Страница Тренеры называет установку для каждого тренера. Если у интерпретатора хоста нет пакета, укажите в python интерпретатор, где этот пакет есть, или перечислите пакет в packages. Если задан packages, Potato создаёт виртуальное окружение в remote_dir с --system-site-packages и один раз устанавливает в него перечисленные пакеты. Собственная сборка torch с CUDA на хосте остаётся видимой внутри окружения:

model_training:
  enabled: true
  backends:
    gpu-server:
      type: ssh
      host: gpu.example.org
      python: /opt/conda/bin/python3
      packages: ["transformers>=4.46.0", "peft>=0.13.0"]
      gpus: auto
      min_free_gpu_mb: 4000
      num_threads: 8

При gpus: auto каждый запуск берёт GPU с наибольшим объёмом свободной памяти и отказывается начинаться, если ни у одного GPU нет min_free_gpu_mb свободной памяти (по умолчанию 2000). Potato сравнивает свободную память, а не загрузку, потому что у карты с низкой загрузкой на общем сервере свободной памяти всё равно может быть мало. Задайте min_free_gpu_mb близко к памяти, которая нужна вашему тренеру. gpus: "1" закрепляет GPU 1, "0,1" закрепляет два GPU, а gpus: none обучает на CPU. Хост вовсе без GPU при auto тоже обучает на CPU. num_threads задаёт OMP_NUM_THREADS, MKL_NUM_THREADS и OPENBLAS_NUM_THREADS для запуска. Некоторые общие серверы задают OMP_NUM_THREADS=1 в login-оболочках, и num_threads переопределяет значение login-оболочки.

Команда проверки для бэкенда ssh

Запустите проверку с сервера разметки, от имени той учётной записи, от которой работает сервер:

potato training check gpu-server config.yaml

Команда подключается и сообщает версию Python на удалённой машине, каждый GPU с объёмом свободной памяти и загрузкой, GPU, который получил бы запуск, и пакеты для обучения, которых нет у удалённого интерпретатора. GPU, для которого у установленного torch нет ядер, помечается (torch there has no kernels for it), и gpus: auto такой GPU пропускает. --json выводит тот же отчёт в виде JSON. Команда завершается с кодом 0, если запуск мог бы начаться, и с кодом 1 в остальных случаях. Кнопка Check рядом с меню Runs on запускает ту же проверку со страницы Training.

Шаги запуска на ssh

Для каждого запуска Potato выполняет такие шаги.

1. Подключается через ssh и открывает обратное перенаправление от unix-сокета в удалённом /tmp к серверу разметки.
2. Проверяет интерпретатор, читает nvidia-smi и выбирает GPU.
3. Копирует исходный код Potato в remote_dir/code/<hash>, если на хосте нет этой версии, и собирает виртуальное окружение, если задан packages, а окружения нет. По умолчанию remote_dir равен ~/.cache/potato-training.
4. Запускает python -m potato.training.agent для этого запуска. Токен запуска доходит до агента через stdin и никогда не попадает в командную строку, потому что командные строки видны каждой учётной записи на общем сервере.
5. Агент скачивает пакет запуска из объектов, меток и медиа. Агент запускает тот же рабочий процесс обучения, что и локальный бэкенд, и отправляет прогресс, предсказания и результат обратно через сокет.
6. Когда запуск завершается успешно, Potato копирует каталог артефактов обратно в artifacts/ запуска, удаляет удалённый каталог задания и закрывает соединение.

Строка шага на странице Training следует этим этапам, например copying Potato's code to gpu.example.org и waiting for the agent on gpu.example.org. Журнал запуска называет Python хоста и GPU, который получил запуск.

Полное дообучение копирует обратно всю модель, и по медленному каналу модель в 330 МБ копируется минуты. Строка шага показывает, какая часть модели уже пришла. Файлы больше max_artifact_mb (по умолчанию 2048) остаются на GPU-хосте и называются в журнале запуска. fetch_artifacts: false оставляет все файлы модели на GPU-хосте, а keep_remote: true сохраняет удалённый каталог задания для осмотра. Публикации на Hugging Face Hub со страницы запуска нужны файлы модели на сервере разметки, поэтому модель, оставленная на GPU-хосте, со страницы запуска не публикуется.

Unix-сокет создаётся с правами 0600, поэтому подключиться через сокет может только учётная запись, под которой Potato вошёл на хост. Запросы через сокет приходят на сервер разметки как запросы с loopback. Сервер, запущенный с debug: true, даёт админский доступ запросам с loopback. Тогда любой, кто может пользоваться этой учётной записью на GPU-хосте, получает админский доступ к серверу в режиме отладки, пока идёт запуск. Держите debug выключенным на сервере, который обучает по ssh.

Отмена и тайм-аут heartbeat

Cancel run на странице Training доходит до агента через сокет, в ответе на следующий отчёт агента о прогрессе. Агент посылает рабочему процессу SIGTERM и SIGKILL, если рабочий процесс всё ещё работает после model_training.grace_seconds (по умолчанию 20), которое сервер отправляет вместе с заданием. Задание от более старого сервера Potato не несёт grace_seconds, и агент тогда ждёт 20 секунд. На сервере запуск завершается как отменённый, как только проходит grace_seconds, и сервер закрывает ssh-сессию агента. Запуск, агент которого ничего не присылает в течение heartbeat_timeout_s (по умолчанию 120), завершается ошибкой, а agent.log в каталоге запуска содержит последний вывод агента.

Кластер SLURM

Бэкенд slurm нужен кластеру, GPU которого стоят за планировщиком SLURM. На таком кластере машина, до которой Potato дотягивается по ssh, — головной узел без GPU, а вычислительные узлы до Potato не дотягиваются вовсе. Поэтому Potato запускает агента на головном узле, как это делает бэкенд ssh, а агент отправляет на вычислительный узел через sbatch только рабочий процесс обучения. Прогресс возвращается через файл на хранилище, общем для головного и вычислительных узлов.

Требования к бэкенду SLURM

Головному узлу нужны ключ ssh без запроса и Python 3.8 или новее для агента, как и хосту бэкенда ssh. Кроме того, на головном узле в PATH должны быть sbatch, squeue и scancel. Агент также вызывает scontrol, если эта команда есть на кластере. Potato никогда не вызывает srun и sacct, поэтому кластер с отключённым srun и без базы учёта работает. remote_dir обязателен и должен лежать на хранилище, общем для вычислительных узлов, потому что задание читает оттуда пакет и пишет туда модель. Валидатор сообщает об ошибке для remote_dir в /tmp или /var/tmp, потому что эти каталоги локальны для каждого узла.

Вычислительным узлам нужен интерпретатор с пакетами тренера, который называет job_python. packages на бэкенде SLURM не поддерживается, потому что виртуальное окружение, созданное на головном узле, может не работать на вычислительных. Укажите в job_python окружение, которое есть на вычислительных узлах, а загрузку модулей или активацию окружения поместите в prelude:

model_training:
  enabled: true
  backends:
    cluster:
      type: slurm
      host: login.cluster.example.org
      python: /opt/conda/bin/python3                    # on the login node, for the agent
      job_python: /shared/envs/train/bin/python         # on the compute nodes, for the worker
      remote_dir: /shared/projects/me/potato-training   # storage the compute nodes share
      partition: gpu
      gres: gpu:1
      time: "04:00:00"
      prelude: ["module load cuda/12.4"]

К бэкенду SLURM применимы все ключи ssh, кроме gpus и packages. GPU берутся из gres, а планировщик задаёт CUDA_VISIBLE_DEVICES для GPU, которые он выделил. Задание без gres не получает GPU. Настройки SLURM соответствуют флагам sbatch:

Значение time больше 6 часов заставляет potato validate и запуск сервера сообщить model_training.backends.cluster.time is 12:00:00. A job that holds a GPU for more than 6 hours is long on a shared cluster; check its policy, а potato validate --strict на этом предупреждении завершается ошибкой. Когда политика кластера допускает более долгое задание, подтвердите предупреждение для одного бэкенда в блоке validation верхнего уровня, который читает только potato validate:

validation:
  acknowledge:
    - "model_training.backends.cluster.time is"

Каждая запись сопоставляется с текстом предупреждения как подстрока длиной не менее 12 символов с учётом регистра, и совпавшее предупреждение переходит в список подтверждённых и больше не приводит к сбою --strict. Запись, которая называет бэкенд, подтверждает предупреждение только для этого бэкенда. Слишком короткая запись или запись, не совпавшая ни с одним предупреждением, сама становится предупреждением.

Команда проверки для бэкенда SLURM

potato training check cluster config.yaml

Проверка входит на головной узел и подтверждает, что sbatch, squeue и scancel есть в PATH, а remote_dir не находится в /tmp. Отчёт называет версию Python на головном узле и job_python, на котором будет работать задание. Проверка не видит, какие пакеты есть на вычислительных узлах, поэтому отсутствующий пакет на вычислительном узле проявляется как неудавшийся запуск с ошибкой импорта в журнале запуска. Запустите первое короткое задание с малым time, чтобы найти такие проблемы раньше.

Шаги запуска на SLURM

Potato подключается к головному узлу и копирует туда свой код, как для бэкенда ssh. Затем агент выполняет такие шаги.

1. Скачивает пакет в remote_dir/jobs/<run>/.
2. Записывает job.sh и отправляет скрипт через sbatch --parsable. Журнал запуска записывает Submitted SLURM job с идентификатором задания и флагами.
3. В каталоге задания рабочий процесс на вычислительном узле пишет события в events.jsonl, ошибки в stderr.log, а код выхода в exit_code. Собственный вывод SLURM идёт в slurm.out.
4. Агент читает events.jsonl по мере роста файла и передаёт прогресс на сервер. Агент вызывает squeue раз в poll_interval_s, а журнал запуска записывает каждое изменение состояния задания в очереди, например SLURM job 4242: PENDING (Priority), а затем RUNNING on node07.
5. Когда задание заканчивается, агент загружает предсказания и сообщает результат. Артефакты возвращаются на сервер, а каталог задания удаляется, как для бэкенда ssh.

Cancel run посылает заданию scancel --full --signal=TERM, а затем обычный scancel, если рабочий процесс не остановился. Когда ssh-сессия с головным узлом обрывается, агент отменяет своё задание, и выделение GPU освобождается. Когда планировщик сам завершает задание, запуск завершается ошибкой с причиной планировщика, прочитанной из scontrol show job или slurm.out. К причинам, о которых сообщает Potato, относятся лимит времени, отказ узла, вытеснение, нехватка памяти и scancel извне Potato.

Набор тестов Potato прогоняет последовательность SLURM против подставной замены для sbatch, squeue и scancel и покрывает отправку задания, статус в очереди, передачу прогресса и отмену. Ограничения разделов и политика вытеснения различаются от кластера к кластеру, поэтому следите за журналом запуска вашего первого задания на новом кластере.

Агент, запущенный вручную на головном узле, который достаёт до сервера, тоже может отправлять задания в SLURM командой potato training agent --server ... --backend <name> --workdir <shared dir> --slurm-config slurm.json. Файл slurm.json содержит настройки из таблицы выше в виде объекта JSON, а --workdir должен находиться на хранилище, общем для вычислительных узлов.

Машина, до которой Potato не дотягивается

Бэкенд agent нужен для машины, к которой сервер разметки не может подключиться, например рабочей станции за NAT. Кто-то запускает potato training agent на этой машине, и агент опрашивает сервер на предмет заданий. Агенту не нужен входящий порт, потому что агент сам открывает каждое соединение. Отмена доходит до агента в ответе сервера на следующий отчёт агента о прогрессе. Файлы модели остаются на машине, где идёт обучение, а возвращаются только предсказания и результат.

Требования к бэкенду agent

На машине, где идёт обучение, должны быть установлены Potato и пакеты запускаемого тренера, а также сетевой маршрут до адреса сервера разметки. Для hf-text-classification одна установка покрывает Potato и пакеты тренера:

pip install "potato-annotation[train-text]"

Серверу нужна только запись бэкенда. Бэкенд agent принимает type, description, heartbeat_timeout_s (по умолчанию 120) и queue_timeout_s, и больше никаких ключей:

model_training:
  enabled: true
  backends:
    lab-workstation:
      type: agent
      queue_timeout_s: 3600

Регистрация и запуск агента

Выпустите токен для бэкенда на сервере разметки:

potato training register lab-workstation config.yaml

Команда один раз выводит токен вместе с командами, которые нужно выполнить на машине, где идёт обучение:

Token for backend 'lab-workstation' (shown once; registering again replaces it):
 
  <token>
 
On the training machine:
 
  export POTATO_TRAINING_TOKEN=<token>
  potato training agent --server http://<this-server>:8000 --backend lab-workstation

Запустите агента на машине, где идёт обучение, с настоящим адресом сервера:

export POTATO_TRAINING_TOKEN=<the token>
potato training agent --server https://annotate.example.org --backend lab-workstation

Агент выполняет задания своего бэкенда, пока вы его не остановите. --token-file читает токен из файла вместо POTATO_TRAINING_TOKEN, а --python называет интерпретатор, в котором работает рабочий процесс обучения, и по умолчанию это собственный интерпретатор агента. --once завершает работу после одного задания, --workdir переносит файлы агента из ~/.cache/potato-training, а --keep сохраняет пакет каждого задания. Повторная регистрация имени выпускает новый токен и делает старый недействительным.

potato training check lab-workstation config.yaml выводит запись токена бэкенда, где last_seen заполняется, как только подключился агент. До регистрации команда выводит no token issued yet и команду регистрации, которую нужно выполнить.

Шаги запуска на agent

Запуск для бэкенда agent ждёт в состоянии queued, пока агент не попросит работу. При queue_timeout_s: 3600 запуск завершается ошибкой через час без агента, а без queue_timeout_s запуск ждёт, пока вы его не отмените. Агент скачивает пакет как файл tar.gz и возобновляет оборвавшуюся загрузку с того места, где она остановилась, до пяти попыток. Затем агент запускает рабочий процесс, отправляет прогресс, загружает predictions.jsonl и сообщает код выхода. На файл предсказаний больше max_predictions_mb (по умолчанию 512) сервер отвечает 413.

Файлы модели остаются на машине, где идёт обучение, в --workdir, а artifact_uri в записи запуска называет хост и каталог. Если во время запуска агент не может достучаться до сервера в течение 300 секунд, агент сам отменяет запуск. Запуск, агент которого ничего не присылает в течение heartbeat_timeout_s, завершается на сервере ошибкой No word from the agent on lab-workstation for 120 seconds.

Типичные сбои

Каждая запись приводит сообщение из журнала запуска или отчёта проверки, а затем способ исправления. Полный список для каждого бэкенда и тренера есть в разделе об устранении неполадок в основном репозитории.

• ssh to gpu.example.org failed: Permission denied. Potato нужен ключ, который работает без запроса. ssh gpu.example.org true от учётной записи сервера должна выполняться успешно.
• /opt/conda/bin/python3 was not found on gpu.example.org. Задайте в бэкенде python как интерпретатор, который существует на хосте.
• No GPU has 4000 MB free. Каждый GPU на хосте загружен сильнее, чем допускает min_free_gpu_mb. potato training check gpu-server config.yaml перечисляет GPU. Подождите, снизьте порог или закрепите GPU через gpus: "1".
• Trainer 'hf-text-classification' could not be imported. У удалённого интерпретатора нет пакета, который нужен тренеру. Укажите в python интерпретатор, где этот пакет есть, или перечислите пакет в packages. На бэкенде SLURM исправьте окружение, которое называет job_python.
• This host's torch has no kernels for any of its GPUs. Удалённый torch собран для более новых GPU, чем есть на хосте. Установите сборку torch для этих GPU или используйте другой хост.
• No word from the agent on gpu-server for 120 seconds. Удалённая машина или сеть пропали. На бэкенде ssh в agent.log в каталоге запуска лежит последний вывод агента.
• The copy from gpu.example.org sent nothing for 180 s. Сеть до хоста остановилась, пока модель копировалась обратно. Предсказания запуска уже сохранены, и в artifacts/ не хватает только файлов модели.
• login.cluster.example.org has no sbatch on PATH, so it cannot submit jobs. host — не головной узел кластера, либо команды лежат в PATH, который задаёт только login-оболочка. Задайте PATH в env бэкенда.
• SLURM job 4242 ended before the worker finished: it reached its time limit. Увеличьте time в бэкенде или обучайте на меньшем числе объектов. Задайте keep_remote: true, чтобы сохранить slurm.out для чтения после других сбоев планировщика.
• Запуск на бэкенде agent остаётся в очереди. Ни один агент с этим именем бэкенда не опрашивает сервер. Запустите агента командой potato training agent --backend lab-workstation и проверьте токен кнопкой Check на странице Training.
• nvrtc: error: failed to open libnvrtc-builtins.so.13.0. torch на хосте и его пакет nvidia-cuda-nvrtc рассчитаны на разные версии CUDA. Установите nvidia-cuda-nvrtc, подходящий к сборке torch, или укажите в python другой интерпретатор.

Дополнительные материалы

• Обзор обучения моделей описывает страницу Training, цикл обучения и публикацию модели на Hugging Face Hub.
• Конфигурация перечисляет все ключи model_training, оценки на отложенных объектах и место хранения запусков.
• Дообучение LLM описывает тренеры, которым чаще всего нужен удалённый GPU, с LoRA и 4-битными базовыми весами.
• Справочник о том, где выполняются запуски, содержит полную таблицу ключей для каждого бэкенда, а раздел о протоколе агента документирует маршруты для тех, кто пишет собственного агента.