Справочник по YAML рабочей нагрузки

Important

Эта функция доступна в общедоступной предварительной версии.

Определите имя эксперимента учебного задания, вычисления, команды, среды и источника кода в конфигурации YAML рабочей нагрузки, в которую передается air run --file. Эта страница документирует каждое поле.

Note

Основа конфигурации YAML — это справка в интерфейсе командной строки. Запустите air -h config представление верхнего уровня и air -h config.<section> (например, air -h config.environment) для подробных сведений о каждом разделе.

Минимальная конфигурация

experiment_name: my-training
environment:
  dependencies:
    - mlflow
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: echo "Hello World"

Отправьте с помощью:

air run --file train.yaml -p profile

Основные понятия

Основные поля

Большинство конфигураций обучения включают пять компонентов:

experiment_name:Обязательно. Создает или добавляется в эксперимент MLflow.
environment: необязательный параметр. Python зависимости и базовая среда.
compute:Обязательно. Ресурсы GPU (тип и число).
command:Обязательно. Команда или команды bash, используемые для запуска обучения.
code_source: необязательный параметр. Путь к коду обучения, который был доступен удаленно.

Ваше первое учебное задание

experiment_name: simple-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
command: torchrun --nproc_per_node=8 $CODE_SOURCE_PATH/train.py

В этой конфигурации:

experiment_name создает эксперимент MLflow с именем simple-training (или добавляет новый запуск, если он уже существует).
environmentустанавливает перечисленные Python зависимости (здесь torch иtransformers).
compute выделяет один узел H100 (8 H100 GPU).
code_source отправляет папку repo на узел, доступную по адресу $CODE_SOURCE_PATH.
command выполняется train.py через torchrun 8 GPU H100. Файл находится локально /home/username/repo/train.py .

Распространенные варианты использования

Добавление переменных среды

experiment_name: training-with-env
environment:
  dependencies:
    - torch
    - transformers
env_variables:
  BATCH_SIZE: '32'
  LEARNING_RATE: '0.001'
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main
command: torchrun --nproc_per_node=8 train.py

Использование секретов (ключи API, маркеры)

experiment_name: training-with-secrets
environment:
  dependencies:
    - torch
    - transformers
secrets:
  HF_TOKEN: 'my_scope/hf_token'
  WANDB_API_KEY: 'my_scope/wandb'
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main
command: torchrun --nproc_per_node=8 train.py

Секреты используют формат scope/key и должны быть настроены в секретах Databricks. Сведения об управлении секретами см. в разделе "Управление секретами ".

При совместном использовании шаблона YAML другие пользователи должны создавать собственные секреты или иметь доступ к указанному секрету.

зависимости Python

Перечисление Python зависимостей рабочей нагрузки в виде встроенного списка в разделе environment.dependencies:

environment:
  version: '4'
  dependencies:
    - torch
    - transformers

environment.version выбирает версию бессерверной среды GPU. Он является необязательным и по умолчанию имеет значение "4". Полный список доступных версий среды см. в разделе " Бессерверные версии среды".

5 Доступны и databricks_ai_v5 версии. Версия — это минимальная стандартная 5 среда, которая включает только бессерверный API GPU, зависимости Databricks и MLflow. Версия databricks_ai_v5 — это среда ИИ Databricks, которая включает все пакеты из стандартной среды, а также PyTorch и комплексные библиотеки машинного обучения. Полный список пакетов см. в разделе "Бессерверная среда GPU" версии 5.

Формат зависимостей

Список зависимостей следует спецификации базовой среды Databricks. Каждая запись — это спецификация пакета в стиле pip (например, my-library==6.1). Список также принимает следующие записи:

Файлы требований: ссылка на существующую requirements.txt , -rнапример -r '/Workspace/Shared/requirements.txt'. Такие переменные среды, как $HOME развернуты.
Колеса: абсолютный путь к .whl файлу, например /Workspace/Shared/path/to/simplejson-3.19.3-py3-none-any.whl.
URL-адреса индекса: URL-адрес индекса, например --index-url https://pypi.org/simple.

environment:
  version: '4'
  dependencies:
    - --index-url https://pypi.org/simple
    - -r '/Workspace/Shared/requirements.txt'
    - my-library==6.1
    - /Workspace/Shared/path/to/simplejson-3.19.3-py3-none-any.whl

Поддерживаемые флаги установки

Зависимости устанавливаются с помощью uv. В качестве записей списка поддерживаются следующие флаги стиля pip:

Применяется ко всей установке: --index-urlи --extra-index-url--find-links (-f) набор или расширение индексов пакетов.
Применяется к зависимости, следующей за ними: --no-deps, --no-build-isolation, --no-cache-dirи --force-reinstall. Поместите флаг на собственную строку (или перед спецификацией), за которой следует зависимость, к которой она применяется.

Например, чтобы установить flash-attn для уже установленной torch (без изоляции сборки) и без разрешения собственных зависимостей:

environment:
  version: '4'
  dependencies:
    - torch
    - --no-build-isolation
    - --no-deps
    - flash-attn

Note

Функция --trusted-host не поддерживается. Так как uv настраивает доверие на URL-адрес индекса, используйте --index-url или --extra-index-url вместо этого.

Пользовательские образы Docker

В качестве альтернативы environment.dependenciesможно указать пользовательский образ контейнера Docker с помощью environment.docker_image.url. environment.docker_image.url является взаимоисключающим с обоими environment.dependencies и environment.version — вы не можете использовать в одной рабочей нагрузке.

experiment_name: my-dcs-training
environment:
  docker_image:
    url: myorg/myrepo:mytag
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: python /app/train.py

Перед использованием пользовательского образа зарегистрируйте его в air register image. Полные сведения, включая требования к изображениям, базовые образы Databricks и шаблоны Dockerfile, см. в разделе "Использование пользовательских образов Docker".

Работа с источниками кода

Блок code_source отправляет локальный код, чтобы задание обучения запустите его.

root_path — локальный каталог для моментального снимка. По умолчанию air пакеты рабочего дерева as-is (включая любые незафиксированные изменения) в виде обычного тарбола.
Чтобы создать моментальный снимок закрепленной версии Git, добавьте git: блок с помощью branch или commit. Это требуется root_path для репозитория Git и включает создание моментальных снимков с поддержкой версий (кэширование, git archive).
Для больших репозиториев include_paths можно снимок подмножества.

Минимальный пример

experiment_name: simple-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
command: python $CODE_SOURCE_PATH/train.py

На удаленном компьютере код помещается /databricks/code_source/<directory_name>в папку , где <directory_name> находится конечный компонент root_pathпути. $CODE_SOURCE_PATH имеет абсолютный путь, поэтому используйте его в команде, а не жестко кодировать расположение.

Репозитории Git: закрепление по ветви или фиксации

Для репозиториев Git добавьте git: блок для закрепления версии кода по ветви или фиксации SHA. branch и commit являются взаимоисключающими: укажите именно один в блоке.

Закрепление в ветви (использует локальную голову этой ветви):

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main # Uses local HEAD of main (no remote fetch)
command: train.sh

Закрепление к фиксации SHA (точное воспроизведение):

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      commit: abc1234567 # Pins specific commit
command: train.sh

Ключевые поля:

root_path (Обязательно): локальный путь к корневому каталогу репозитория Git.
git.branch (Необязательно): имя ветви. Использует локальную голову; нет удаленного извлечения. Взаимоисключающ с git.commit.
git.commit (Необязательно): конкретная фиксация SHA. Взаимоисключающ с git.branch.
git.remote (Необязательно): используйте удаленную голову ветви вместо локальной. Установите для true автоматического обнаружения удаленного или удаленного имени (например, upstream), чтобы получить из определенного удаленного сервера. Допустимо только с git.branch.

Если вы опустите git: блок, air упаковав рабочее дерево в виде обычного тарбола, включая любые незафиксированные изменения. Дополнительное поле не требуется.

Каталоги, отличные от Git

Вы можете создавать каталоги моментальных снимков, которые не являются репозиториями Git. Опустите git: блок, который требует root_path быть репозиторием Git. Без него не существует кэширования версий; Свежий тарбол отправляется для каждого запуска.

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/my_project
command: $CODE_SOURCE_PATH/train.py

Фильтрация папок с помощью `include_paths`

Для больших монореспосов моментальный снимок позволяет сократить время отправки и загрузки и размер моментального снимка:

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    include_paths:
      - research/models
      - research/common
      - research/configs
command: python $CODE_SOURCE_PATH/research/models/launch_training.py

Основные моменты:

Поле является необязательным. Если опущено, весь репозиторий включается по умолчанию.
Пути должны быть относительно корневого каталога репозитория (без ведущих /).
.. не допускается; Вы не можете ссылаться на родительские каталоги.

Расширенные функции

Пользовательские гиперпараметры

Передайте структурированную конфигурацию в скрипт обучения с помощью HYPERPARAMETERS_PATH:

experiment_name: parameterized-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main
command: torchrun --nproc_per_node=8 train.py
parameters:
  model:
    name: 'gpt2'
    hidden_size: 768
  training:
    batch_size: 32
    learning_rate: 0.0001

Прочитайте их в скрипте:

import os
import yaml

with open(os.environ['HYPERPARAMETERS_PATH']) as f:
    params = yaml.safe_load(f)

learning_rate = params['training']['learning_rate']
model_name = params['model']['name']

Надежность задания

experiment_name: reliable-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main
command: torchrun --nproc_per_node=8 train.py
max_retries: 2
timeout_minutes: 90

Если рабочая нагрузка завершается ошибкой, она выполняется дважды. Каждая попытка имеет 90 минут для завершения, поэтому общий бюджет стенных часов составляет 90 × 3 = 270 минут.

Атрибуция затрат

Подключите рабочую нагрузку к существующей политике бюджета с помощью usage_policy_name. Имя разрешается в идентификатор политики при запуске рабочей нагрузки. Сведения об использовании атрибутов с бессерверными политиками использования.

experiment_name: my-training
environment:
  dependencies:
    - mlflow
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: echo "Hello World"
usage_policy_name: my team policy

Reference

Основные поля

Поле	Тип	Description	Example
`experiment_name`	string	Имя эксперимента для MLflow.	`"my-training-job"`
`environment.dependencies`	list	Встроенный список спецификаций зависимостей pip.	`["torch", "transformers"]`
`environment.version`	string	Бессерверная версия среды GPU. Optional. По умолчанию — `"4"`.	`"4"`
`compute.num_accelerators`	INT	Количество графических процессоров.	`1`, , `48`
`compute.accelerator_type`	string	Тип GPU.	`"GPU_1xA10"`, `"GPU_8xH100"`
`code_source`	dict	Конфигурация источника кода.	См. статью "Работа с источниками кода".
`command`	string	Команды Bash для запуска обучения.	`torchrun --nproc_per_node=8 train.py`

Поддерживаемые типы GPU

`accelerator_type`	Графические процессоры на узел	Примечания.
`GPU_1xA10`	1	Один A10, хорошо подходит для разработки и небольших рабочих нагрузок.
`GPU_1xH100`	1	Один H100.
`GPU_8xH100`	8	Полный узел H100, типичный для распределенного обучения.

Сведения о возможностях акселератора и рекомендуемых вариантах использования см. в разделе "Параметры оборудования".

Необязательные поля

Конфигурация среды

environment:
  version: '4'
  dependencies:
    - torch
    - transformers
env_variables:
  BATCH_SIZE: '32'
secrets:
  HF_TOKEN: 'my_scope/hf_token'

Формат зависимостей, поддерживаемые флаги установки и environment.versionсм. в разделе Python зависимости.

Настраиваемая конфигурация образа Docker

environment:
  docker_image:
    url: myorg/myrepo:mytag

Взаимоисключаемая с environment.dependencies и environment.version. Зарегистрируйте образ air register image перед использованием. См. раздел "Использование пользовательских образов Docker".

Конфигурация источника кода

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo # REQUIRED — local path to repo or directory
    git: # Optional (git repos only) — pin to a branch or commit
      branch: main # Branch name; uses local HEAD unless 'remote' is set
      # commit: abc1234567 # Mutually exclusive with 'branch'
      remote: false # Optional — true to auto-detect remote HEAD, or a remote name string
    include_paths: # Optional — filter included paths
      - src/
      - configs/

Ограничения полей:

git.branch и git.commit являются взаимоисключающими: укажите именно один в блоке git: .
git.remote требуется git.branch (он не влияет на git.commit).
Если вы опустите git: блок, рабочее дерево упаковается в виде обычного тарбола, включая любые незафиксированные изменения.

Настраиваемые параметры

Передается в рабочую нагрузку с помощью HYPERPARAMETERS_PATH:

parameters:
  model:
    name: 'gpt2'
    hidden_size: 768
  training:
    batch_size: 32

Имя запуска MLflow

mlflow_run_name: 'experiment-001-baseline'

Разрешение пути

Все пути в YAML рабочей нагрузки относятся к YAML рабочей нагрузки, если они не являются абсолютными путями.

Структура папок:

/home/username/my-project/
├── train.yaml
└── scripts/
    └── train.py

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

experiment_name: my-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: . # Relative to train.yaml
    git:
      branch: main
command: torchrun --nproc_per_node=8 $CODE_SOURCE_PATH/scripts/train.py

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-16

Справочник по YAML рабочей нагрузки

Минимальная конфигурация

Основные понятия

Основные поля

Ваше первое учебное задание

Распространенные варианты использования

Добавление переменных среды

Использование секретов (ключи API, маркеры)

зависимости Python

Формат зависимостей

Поддерживаемые флаги установки

Пользовательские образы Docker

Работа с источниками кода

Минимальный пример

Репозитории Git: закрепление по ветви или фиксации

Каталоги, отличные от Git

Фильтрация папок с помощью include_paths

Расширенные функции

Пользовательские гиперпараметры

Надежность задания

Атрибуция затрат

Reference

Основные поля

Поддерживаемые типы GPU

Необязательные поля

Разрешение пути

Обратная связь

Дополнительные ресурсы

Фильтрация папок с помощью `include_paths`