YAML

YAML — человекочитаемый язык сериализации данных, используемый преимущественно в файлах конфигурации. Это рекурсивная аббревиатура: её расшифровка также содержит название YAML. Вложенные данные описываются отступами, а не скобками или тегами; поддерживаются комментарии, а структуры напрямую соответствуют словарям, спискам, строкам и числам в языках программирования. Поэтому один и тот же файл удобно редактировать людям и загружать программам. В машинном обучении YAML-файлы хранят пути к наборам данных, архитектуры моделей, гиперпараметры и этапы конвейера отдельно от кода, что упрощает воспроизведение экспериментов, проверку и версионирование в Git. Текущая спецификация — YAML 1.2.2; YAML 1.2 спроектирован так, что корректный JSON одновременно является корректным YAML.

Основы синтаксиса YAML#

Документ YAML состоит из трёх типов узлов. Отображения — это пары key: value, последовательности — элементы, начинающиеся с - или записанные в строку как [a, b], а скаляры — отдельные значения, например строки, числа и логические значения. Вложенность задаётся пробелами в отступах; табуляцию для отступов использовать нельзя. Символ # начинает комментарий, --- разделяет несколько документов в одном файле, а якоря (&name) с псевдонимами (*name) позволяют повторно использовать блок в другом месте файла. Строки обычно не нужно заключать в кавычки. Это сокращает файлы, но означает, что тип каждого значения без кавычек определяет парсер.

YAML в рабочих процессах машинного обучения#

Хранение настроек в YAML отделяет назначение эксперимента от того, как его реализует код: команда может переключать наборы данных или менять скорости обучения, редактируя файл, сохранять точную конфигурацию с помощью отслеживания экспериментов и проверять изменения в запросах на слияние. YAML используют инструменты на разных уровнях стека: Hydra для объединения конфигураций экспериментов, GitHub Actions для конвейеров непрерывной интеграции, Docker Compose для приложений из нескольких контейнеров и манифесты Kubernetes для развёртывания моделей. Ultralytics YOLO использует YAML на трёх уровнях: в файлах наборов данных перечислены папки с изображениями и названия классов; файлы моделей, например yolo26.yaml, задают слои и масштабы от n до x для YOLO26; файл конфигурации по умолчанию содержит все настройки обучения, предсказания и экспорта, которые можно переопределить пользовательским файлом, переданным через cfg=. В этом фрагменте показана структура входящего в пакет файла набора данных coco8.yaml dataset:

path: coco8 # dataset root dir
train: images/train # train images (relative to 'path')
val: images/val # val images (relative to 'path')

# Classes
names:
  0: person
  1: bicycle
  2: car
  # ... up to 79: toothbrush

Обучение загружает файл по имени, находит папки с изображениями относительно path и считывает количество и названия классов из names:

from ultralytics import YOLO

# Загрузи предварительно обученную nano-модель YOLO26
model = YOLO("yolo26n.pt")

# Обучение на наборе данных, описанном в YAML-файле
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

Для пользовательского набора данных достаточно собственного YAML-файла с теми же ключами, в котором указаны пути к изображениям и перечислены классы в формате набора данных Ultralytics для обнаружения объектов.

YAML, JSON и TOML#

• JSON: Использует фигурные и квадратные скобки и ключи в кавычках, не поддерживает комментарии и одинаково разбирается всеми парсерами. Лучше подходит для обмена данными между программами — например, для ответов API и сохранённых предсказаний, — чем для редактируемых человеком файлов.
• TOML: Формат, похожий на INI, с явным указанием типов и меньшим риском ошибок из-за отступов; используется, например, в pyproject.toml для Python. Менее удобен для глубоко вложенных данных.
• XML: Объёмный язык разметки с тегами, который всё ещё встречается в старых форматах аннотаций, например Pascal VOC, но редко выбирается для новых конфигурационных файлов.

Распространённые ошибки при работе с YAML#

Большинство ошибок YAML связано с отступами: символ табуляции или один неправильно поставленный пробел меняет структуру либо останавливает парсер с ошибкой ScannerError или ParserError. Более неочевидные проблемы связаны с неявным определением типов. PyYAML, который используют большинство проектов на Python, следует старым правилам YAML 1.1: некоторые слова без кавычек превращаются в логические значения, а для чисел с плавающей точкой требуется десятичная точка. Загрузка ненадёжных файлов с помощью yaml.unsafe_load или UnsafeLoader из PyYAML может создавать произвольные объекты Python и выполнять код. Поэтому в конфигурационном коде используют yaml.safe_load, который создаёт только простые типы данных:

import yaml

config = """
model: yolo26n.pt
epochs: 100
lr0: 1e-3
python: 3.10
country: NO
classes: [person, car]
"""

# safe_load builds plain Python dicts, lists, and scalars from the text
data = yaml.safe_load(config)
for key, value in data.items():
    print(f"{key}: {value!r} ({type(value).__name__})")

Вывод демонстрирует три неожиданности: lr0 загружается как строка '1e-3', потому что в нём нет десятичной точки; python: 3.10 становится числом с плавающей точкой 3.1; а код страны NO превращается в логическое значение False — это правило YAML 1.1 прозвали «норвежской проблемой». Согласно базовой схеме YAML 1.2, 1e-3 загружается как число с плавающей точкой, а NO остаётся строкой, тогда как 3.10 по-прежнему становится числом 3.1.