YAML

YAML (acronimo ricorsivo di «YAML non è un linguaggio di markup») è un linguaggio di serializzazione dei dati leggibile dalle persone, usato soprattutto per i file di configurazione. Descrive dati annidati usando l'indentazione invece di parentesi o tag, supporta i commenti e si mappa direttamente su dizionari, liste, stringhe e numeri dei linguaggi di programmazione, perciò lo stesso file è facile da modificare per le persone e da caricare per i programmi. Nel machine learning, i file YAML contengono i percorsi dei dataset, le architetture dei modelli, gli iperparametri e i passaggi della pipeline, separati dal codice, così gli esperimenti sono facili da riprodurre, revisionare e versionare in Git. La specifica attuale è YAML 1.2.2; YAML 1.2 è stato progettato affinché JSON valido sia valido anche come YAML.

Nozioni di base sulla sintassi YAML#

Un documento YAML è composto da tre tipi di nodi. Le mappe sono coppie key: value, le sequenze sono elementi che iniziano con - o sono scritti in linea come [a, b], mentre gli scalari sono singoli valori come stringhe, numeri e valori booleani. L'annidamento è determinato dall'indentazione con spazi; i caratteri di tabulazione non sono ammessi per l'indentazione. Un # avvia un commento, --- separa più documenti nello stesso file e le ancore (&name) con gli alias (*name) permettono di riutilizzare altrove nel file un blocco. Di solito le stringhe non richiedono virgolette, il che mantiene i file brevi ma lascia al parser il compito di determinare il tipo di ogni valore senza virgolette.

YAML nei flussi di lavoro di machine learning#

Mantenere le impostazioni in YAML separa le operazioni di un esperimento dal modo in cui il codice le esegue: il team può cambiare dataset o modificare i tassi di apprendimento modificando un file, registrare la configurazione esatta con il tracciamento degli esperimenti e revisionare le modifiche nelle pull request. Lo usano strumenti di ogni livello, tra cui Hydra per comporre le configurazioni degli esperimenti, GitHub Actions per le pipeline di integrazione continua, Docker Compose per le app multi-container e i manifest di Kubernetes per la distribuzione dei modelli. Ultralytics YOLO usa YAML a tre livelli: i file dei dataset elencano le cartelle delle immagini e i nomi delle classi, i file dei modelli come yolo26.yaml definiscono i layer e le scale da n a x di YOLO26, mentre un file di configurazione predefinita contiene tutte le impostazioni di addestramento, predizione ed esportazione, che puoi sovrascrivere passando un file personalizzato con cfg=. Questo estratto mostra la struttura del file del dataset coco8.yaml incluso nel pacchetto:

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'addestramento legge il file in base al nome, risolve le cartelle delle immagini da path e ricava il numero e i nomi delle classi da names:

from ultralytics import YOLO

# Carica un modello nano YOLO26 preaddestrato
model = YOLO("yolo26n.pt")

# Addestrati sul dataset descritto dal file YAML
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

Per un dataset personalizzato basta un proprio file YAML con le stesse chiavi, che punti alle immagini e riporti le classi nel formato Ultralytics per i dataset di rilevamento.

YAML, JSON e TOML a confronto#

• JSON: usa parentesi graffe e quadre e chiavi tra virgolette, non supporta i commenti e viene analizzato allo stesso modo ovunque. È più adatto ai dati scambiati tra programmi, come le risposte API e le previsioni salvate, che ai file modificati dalle persone.
• TOML: formato simile a INI con tipi espliciti e meno problemi legati all'indentazione, usato da pyproject.toml di Python. È meno pratico per dati profondamente annidati.
• XML: linguaggio di markup dettagliato basato su tag, ancora presente nei formati di annotazione più datati come Pascal VOC, ma scelto raramente per i nuovi file di configurazione.

Errori comuni con YAML#

La maggior parte degli errori YAML deriva dall'indentazione: un carattere di tabulazione o uno spazio fuori allineamento cambia la struttura o blocca il parser con un ScannerError o un ParserError. I problemi meno evidenti derivano dalla tipizzazione implicita. PyYAML, il parser usato dalla maggior parte dei progetti Python, segue le vecchie regole YAML 1.1, che convertono alcune parole senza virgolette in valori booleani e richiedono il punto decimale per i numeri in virgola mobile. Caricare file non attendibili con yaml.unsafe_load o con UnsafeLoader di PyYAML può creare oggetti Python arbitrari ed eseguire codice; perciò il codice di configurazione usa yaml.safe_load, che crea solo tipi di dati semplici:

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

L'output mostra tre sorprese: lr0 viene caricato come stringa '1e-3' perché non contiene un punto decimale, python: 3.10 diventa il float 3.1 e il codice paese NO diventa il valore booleano False, secondo una regola YAML 1.1 soprannominata il problema della Norvegia. Con lo schema di base YAML 1.2, 1e-3 viene caricato come float e NO resta una stringa, mentre 3.10 continua a diventare 3.1.