YAML

YAML (acrônimo recursivo de "YAML Ain't Markup Language") é uma linguagem de serialização de dados legível por humanos, usada principalmente em arquivos de configuração. Descreve dados aninhados com indentação em vez de colchetes ou tags, oferece suporte a comentários e mapeia diretamente para os dicionários, listas, strings e números das linguagens de programação, facilitando a edição por pessoas e o carregamento por programas. Em aprendizado de máquina, arquivos YAML armazenam caminhos de conjuntos de dados, arquiteturas de modelos, hiperparâmetros e etapas de pipeline fora do código, o que facilita reproduzir, revisar e versionar experimentos no Git. A especificação atual é YAML 1.2.2, e o YAML 1.2 foi projetado para que JSON válido também seja YAML válido.

Noções básicas da sintaxe YAML#

Um documento YAML é composto por três tipos de nós. Mapeamentos são pares key: value, sequências são itens que começam com - ou são escritos em linha como [a, b], e escalares são valores únicos, como strings, números e booleanos. O aninhamento é definido por indentação com espaços, e não são permitidos caracteres de tabulação na indentação. # inicia um comentário, --- separa vários documentos em um arquivo, e âncoras (&name) com aliases (*name) permitem reutilizar um bloco em outra parte do arquivo. Em geral, strings não precisam de aspas, o que mantém os arquivos curtos, mas deixa o analisador decidir o tipo de cada valor sem aspas.

YAML em fluxos de trabalho de aprendizado de máquina#

Manter as configurações em YAML separa o que um experimento faz de como o código o faz: uma equipe pode trocar conjuntos de dados ou alterar taxas de aprendizado editando um arquivo, registrar a configuração exata com o rastreamento de experimentos e revisar alterações em pull requests. Ferramentas de várias partes da pilha usam YAML, incluindo Hydra para compor configurações de experimentos, GitHub Actions para pipelines de integração contínua, Docker Compose para aplicativos com vários contêineres e manifestos do Kubernetes para implantar modelos. O Ultralytics YOLO usa YAML em três níveis: arquivos de conjuntos de dados listam pastas de imagens e nomes de classes; arquivos de modelo, como yolo26.yaml, definem as camadas e as escalas de n a x do YOLO26; e um arquivo de configuração padrão contém todas as configurações de treinamento, previsão e exportação, que podem ser substituídas por um arquivo personalizado passado com cfg=. Este trecho mostra a estrutura do arquivo de conjunto de dados incluído coco8.yaml:

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

O treinamento lê o arquivo pelo nome, resolve as pastas de imagens a partir de path e obtém a quantidade e os nomes das classes de names:

from ultralytics import YOLO

# Carrega um modelo nano YOLO26 pré-treinado
model = YOLO("yolo26n.pt")

# Treina no conjunto de dados descrito pelo arquivo YAML
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

Um conjunto de dados personalizado só precisa do próprio arquivo YAML com as mesmas chaves, apontando para suas imagens e listando suas classes no formato de conjuntos de dados de detecção da Ultralytics.

YAML vs. JSON vs. TOML#

• JSON: Usa chaves, colchetes e chaves entre aspas, não tem comentários e é analisado da mesma forma em todos os lugares. É mais adequado para dados trocados entre programas, como respostas de API e previsões salvas, do que para arquivos editados por pessoas.
• TOML: Formato semelhante ao INI, com tipos explícitos e menos surpresas de indentação, usado pelo pyproject.toml do Python. É menos prático para dados profundamente aninhados.
• XML: Linguagem de marcação verbosa baseada em tags, ainda encontrada em formatos de anotação antigos, como Pascal VOC, mas raramente escolhida para novos arquivos de configuração.

Armadilhas comuns do YAML#

A maioria dos erros de YAML vem da indentação: um caractere de tabulação ou um espaço desalinhado altera a estrutura ou faz o analisador parar com um ScannerError ou ParserError. Os problemas mais sutis vêm da tipagem implícita. O PyYAML, analisador usado pela maioria dos projetos Python, segue as regras mais antigas do YAML 1.1, que convertem algumas palavras sem aspas em booleanos e exigem um ponto decimal em números de ponto flutuante. Carregar arquivos não confiáveis com yaml.unsafe_load ou com UnsafeLoader do PyYAML pode criar objetos Python arbitrários e executar código; por isso, o código de configuração usa yaml.safe_load, que cria apenas tipos de dados 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__})")

O resultado mostra três surpresas: lr0 é carregado como a string '1e-3' por não ter ponto decimal, python: 3.10 vira o número de ponto flutuante 3.1, e o código de país NO vira o booleano False, uma regra do YAML 1.1 apelidada de problema da Noruega. No esquema principal do YAML 1.2, 1e-3 é carregado como número de ponto flutuante e NO continua sendo uma string, enquanto 3.10 ainda vira 3.1.