YAML

YAML (acronyme récursif de « YAML n'est pas un langage de balisage ») est un langage de sérialisation de données lisible par l'humain, principalement utilisé pour les fichiers de configuration. Il décrit les données imbriquées au moyen de l'indentation plutôt que de crochets ou de balises, prend en charge les commentaires et correspond directement aux dictionnaires, listes, chaînes et nombres des langages de programmation. Un même fichier est ainsi facile à modifier pour les personnes et à charger pour les programmes. En apprentissage automatique, les fichiers YAML contiennent les chemins des jeux de données, les architectures des modèles, les hyperparamètres et les étapes des pipelines, en dehors du code, ce qui facilite la reproduction, la revue et le suivi des expériences dans Git. La spécification actuelle est YAML 1.2.2, et YAML 1.2 a été conçu de sorte que tout JSON valide soit également du YAML valide.

Notions de base de la syntaxe YAML#

Un document YAML se compose de trois types de nœuds. Les mappages sont des paires key: value, les séquences sont des éléments qui commencent par - ou sont écrits en ligne sous la forme [a, b], et les scalaires sont des valeurs simples telles que des chaînes, des nombres et des booléens. L'imbrication est déterminée par l'indentation avec des espaces ; les tabulations ne sont pas autorisées pour l'indentation. # ouvre un commentaire, --- sépare plusieurs documents dans un même fichier, et les ancres (&name) et leurs alias (*name) permettent de réutiliser un bloc ailleurs dans le fichier. Les chaînes n'ont généralement pas besoin de guillemets, ce qui raccourcit les fichiers, mais laisse l'analyseur déterminer le type de chaque valeur non encadrée.

YAML dans les workflows d'apprentissage automatique#

Conserver les paramètres en YAML sépare la fonction d'une expérience de la façon dont le code l'exécute : une équipe peut changer de jeu de données ou modifier les taux d'apprentissage en éditant un fichier, consigner la configuration exacte avec le suivi des expériences et examiner les modifications dans les demandes de tirage. De nombreux outils de la pile l'utilisent, notamment Hydra pour composer les configurations d'expériences, GitHub Actions pour les pipelines d'intégration continue, Docker Compose pour les applications à plusieurs conteneurs et les manifestes Kubernetes pour le déploiement de modèles. Ultralytics YOLO utilise YAML à trois niveaux : les fichiers de jeux de données répertorient les dossiers d'images et les noms de classes, les fichiers de modèles tels que yolo26.yaml définissent les couches et les tailles n à x de YOLO26, et un fichier de configuration par défaut contient tous les paramètres d'entraînement, de prédiction et d'exportation, qui peuvent être remplacés par un fichier personnalisé transmis avec cfg=. Cet extrait montre la structure du fichier de jeu de données coco8.yaml fourni avec le package :

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

L'entraînement lit le fichier par son nom, résout les dossiers d'images à partir de path et récupère le nombre et les noms des classes dans names :

from ultralytics import YOLO

# Charger un modèle nano YOLO26 pré-entraîné
model = YOLO("yolo26n.pt")

# Entraîner sur le jeu de données décrit dans le fichier YAML
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

Un jeu de données personnalisé nécessite uniquement son propre fichier YAML, avec les mêmes clés, qui pointe vers ses images et répertorie ses classes au format de jeu de données de détection Ultralytics.

YAML, JSON ou TOML#

• JSON : Utilise des accolades, des crochets et des clés entre guillemets, ne prend pas en charge les commentaires et s'analyse de la même façon partout. Il convient mieux aux données échangées entre programmes, comme les réponses d'API et les prédictions enregistrées, qu'aux fichiers modifiés par des personnes.
• TOML : Format proche d'INI, doté de types explicites et moins sujet aux erreurs d'indentation, utilisé par pyproject.toml de Python. Il est moins pratique pour les données profondément imbriquées.
• XML : Langage de balisage verbeux fondé sur des balises, encore présent dans d'anciens formats d'annotation comme Pascal VOC, mais rarement choisi pour les nouveaux fichiers de configuration.

Erreurs courantes avec YAML#

La plupart des erreurs YAML viennent de l'indentation : une tabulation ou un espace mal aligné modifie la structure ou bloque l'analyseur avec une ScannerError ou une ParserError. Les problèmes plus subtils viennent du typage implicite. PyYAML, l'analyseur utilisé par la plupart des projets Python, suit les anciennes règles YAML 1.1, qui convertissent certains mots non encadrés en booléens et exigent un point décimal pour les nombres à virgule flottante. Le chargement de fichiers non fiables avec yaml.unsafe_load ou UnsafeLoader de PyYAML peut construire des objets Python arbitraires et exécuter du code. Le code de configuration utilise donc yaml.safe_load, qui ne crée que des types de données simples :

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__})")

La sortie révèle trois surprises : lr0 est chargé comme la chaîne '1e-3', car il n'a pas de point décimal ; python: 3.10 devient le nombre à virgule flottante 3.1 ; et le code pays NO devient le booléen False, une règle YAML 1.1 surnommée le problème de la Norvège. Avec le schéma de base YAML 1.2, 1e-3 est chargé comme un nombre à virgule flottante et NO reste une chaîne, tandis que 3.10 devient toujours 3.1.