YAML

YAML (acrónimo recursivo de «YAML no es un lenguaje de marcado») es un lenguaje de serialización de datos legible por personas, utilizado principalmente en archivos de configuración. Describe datos anidados mediante sangría en lugar de corchetes o etiquetas, admite comentarios y se corresponde directamente con los diccionarios, listas, cadenas y números de los lenguajes de programación, por lo que las personas pueden editar fácilmente el mismo archivo y los programas pueden cargarlo sin problemas. En aprendizaje automático, los archivos YAML contienen rutas de conjuntos de datos, arquitecturas de modelos, hiperparámetros y pasos de canalización fuera del código, lo que facilita reproducir, revisar y versionar los experimentos en Git. La especificación actual es YAML 1.2.2, y YAML 1.2 se diseñó para que el JSON válido también fuera YAML válido.

Conceptos básicos de la sintaxis YAML#

Un documento YAML se compone de tres tipos de nodos. Las asignaciones son pares key: value, las secuencias son elementos que empiezan por - o se escriben en línea como [a, b], y los escalares son valores individuales, como cadenas, números y valores booleanos. El anidamiento se indica con espacios de sangría; no se permiten tabuladores para la sangría. # inicia un comentario, --- separa varios documentos en un mismo archivo, y los anclajes (&name) y los alias (*name) permiten reutilizar un bloque en otra parte del archivo. Las cadenas normalmente no necesitan comillas, lo que mantiene los archivos breves, pero implica que el analizador determina el tipo de cada valor sin comillas.

YAML en los flujos de trabajo de aprendizaje automático#

Almacenar la configuración en YAML separa lo que hace un experimento de cómo lo hace el código: el equipo puede cambiar conjuntos de datos o modificar las tasas de aprendizaje editando un archivo, registrar la configuración exacta con el seguimiento de experimentos y revisar los cambios en solicitudes de incorporación de cambios. Distintas herramientas de la pila lo utilizan, como Hydra para combinar configuraciones de experimentos, GitHub Actions para las canalizaciones de integración continua, Docker Compose para aplicaciones con varios contenedores y los manifiestos de Kubernetes para desplegar modelos. Ultralytics YOLO utiliza YAML en tres niveles: los archivos de conjuntos de datos enumeran las carpetas de imágenes y los nombres de las clases; los archivos de modelos, como yolo26.yaml, definen las capas y las escalas de n a x de YOLO26; y un archivo de configuración predeterminado contiene todos los ajustes de entrenamiento, predicción y exportación, que se pueden sobrescribir con un archivo personalizado pasado mediante cfg=. Este fragmento muestra la estructura del archivo del conjunto de datos coco8.yaml incluido:

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

El entrenamiento lee el archivo por su nombre, resuelve las carpetas de imágenes desde path y obtiene el número de clases y sus nombres de names:

from ultralytics import YOLO

# Carga un modelo nano YOLO26 preentrenado
model = YOLO("yolo26n.pt")

# Entrena con el conjunto de datos descrito en el archivo YAML
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

Un conjunto de datos personalizado solo necesita su propio archivo YAML con las mismas claves, que apunte a sus imágenes y enumere sus clases en el formato de conjuntos de datos de detección de Ultralytics.

YAML, JSON y TOML#

• JSON: Utiliza llaves, corchetes y claves entre comillas, no admite comentarios y se analiza igual en todas partes. Es adecuado para intercambiar datos entre programas, como respuestas de API y predicciones guardadas, más que para archivos que editan las personas.
• TOML: Un formato similar a INI, con tipos explícitos y menos sorpresas relacionadas con la sangría, utilizado por pyproject.toml de Python. Es menos práctico para datos muy anidados.
• XML: Un lenguaje de marcado prolijo basado en etiquetas que aún se encuentra en formatos de anotación antiguos, como Pascal VOC, pero que rara vez se elige para archivos de configuración nuevos.

Errores habituales con YAML#

La mayoría de los errores de YAML se deben a la sangría: un tabulador o un espacio mal alineado cambia la estructura o hace que el analizador se detenga con ScannerError o ParserError. Los problemas más sutiles se deben a la tipificación implícita. PyYAML, el analizador que utilizan la mayoría de los proyectos de Python, sigue las reglas antiguas de YAML 1.1, que convierten algunas palabras sin comillas en valores booleanos y exigen un punto decimal en los números de coma flotante. Cargar archivos no fiables con yaml.unsafe_load o UnsafeLoader de PyYAML puede crear objetos de Python arbitrarios y ejecutar código; por eso, el código de configuración utiliza yaml.safe_load, que solo crea tipos de datos sencillos:

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 salida muestra tres sorpresas: lr0 se carga como la cadena '1e-3' porque carece de punto decimal; python: 3.10 se convierte en el número de coma flotante 3.1; y el código de país NO se convierte en el valor booleano False, una regla de YAML 1.1 conocida como el problema de Noruega. Con el esquema básico de YAML 1.2, 1e-3 se carga como número de coma flotante y NO sigue siendo una cadena, mientras que 3.10 sigue convirtiéndose en 3.1.