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와 같은 모델 파일은 YOLO26의 레이어와 n부터 x까지의 스케일을 정의하며, 기본 설정 파일에는 모든 학습, 예측, 내보내기 설정이 포함됩니다. cfg=를 사용해 전달한 사용자 지정 파일로 기본 설정을 재정의할 수 있습니다. 다음은 함께 제공되는 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

학습은 파일 이름으로 YAML 파일을 읽고, path에서 이미지 폴더 경로를 확인하며, names에서 클래스 수와 이름을 가져옵니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26 nano 모델을 불러옵니다
model = YOLO("yolo26n.pt")

# YAML 파일에 설명된 데이터 세트로 학습합니다.
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

사용자 지정 데이터 세트에는 이미지 경로를 지정하고 클래스를 나열하는 자체 YAML 파일만 있으면 됩니다. YAML 파일은 동일한 키를 사용하며 Ultralytics 감지 데이터 세트 형식을 따릅니다.

YAML, JSON, TOML 비교#

• JSON: 중괄호, 대괄호, 따옴표로 묶은 키를 사용하고 주석을 지원하지 않으며 모든 곳에서 동일하게 파싱됩니다. 사람이 편집하는 파일보다는 API 응답이나 저장된 예측처럼 프로그램 간에 교환되는 데이터에 적합합니다.
• TOML: 명시적 유형을 사용하고 들여쓰기 관련 혼란이 적은 INI 유사 형식으로, Python의 pyproject.toml에서 사용됩니다. 깊게 중첩된 데이터에는 덜 편리합니다.
• XML: Pascal VOC와 같은 기존 주석 형식에서 여전히 볼 수 있는 장황한 태그 기반 마크업 언어이며, 새 설정 파일에는 거의 선택되지 않습니다.

일반적인 YAML 실수#

대부분의 YAML 오류는 들여쓰기에서 발생합니다. 탭 문자나 공백 하나의 잘못된 정렬로 구조가 바뀌거나 파서가 ScannerError 또는 ParserError 오류를 내며 중단될 수 있습니다. 더 미묘한 문제는 암시적 형식 지정에서 발생합니다. 대부분의 Python 프로젝트에서 사용하는 파서인 PyYAML은 이전 YAML 1.1 규칙을 따릅니다. 이 규칙은 따옴표가 없는 일부 단어를 불리언으로 변환하고 부동 소수점 수에 소수점을 요구합니다. 신뢰할 수 없는 파일을 yaml.unsafe_load 또는 PyYAML의 UnsafeLoader로 불러오면 임의의 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는 YAML 1.1 규칙에서 노르웨이 문제라고 불리는 현상에 따라 불리언 False가 됩니다. YAML 1.2 코어 스키마에서는 1e-3이 부동 소수점 수로 불러와지고 NO은 문자열로 유지되지만, 3.10은 여전히 3.1이 됩니다.