YAML

YAML (một ngôn ngữ tuần tự hóa dữ liệu có tên là từ viết tắt đệ quy, nghĩa là "YAML không phải ngôn ngữ đánh dấu") là ngôn ngữ tuần tự hóa dữ liệu dễ đọc, chủ yếu dùng cho các file cấu hình. YAML biểu diễn dữ liệu lồng nhau bằng thụt lề thay vì dấu ngoặc hoặc thẻ, hỗ trợ comment và ánh xạ trực tiếp sang dictionary, list, chuỗi và số của các ngôn ngữ lập trình; nhờ đó, cả người dùng lẫn chương trình đều dễ chỉnh sửa và tải cùng một file. Trong machine learning, các file YAML lưu đường dẫn tập dữ liệu, kiến trúc model, siêu tham số và các bước pipeline bên ngoài mã nguồn, giúp dễ tái lập, đánh giá và quản lý phiên bản thí nghiệm trong Git. Đặc tả hiện hành là YAML 1.2.2; YAML 1.2 được thiết kế để JSON hợp lệ cũng là YAML hợp lệ.

Những kiến thức cơ bản về cú pháp YAML#

Tài liệu YAML được xây dựng từ ba loại nút. Mapping là các cặp key: value, sequence là các mục bắt đầu bằng - hoặc được viết nội dòng dưới dạng [a, b], còn scalar là các giá trị đơn như chuỗi, số và boolean. Cấu trúc lồng nhau được xác định bằng thụt lề với dấu cách; không được dùng ký tự tab để thụt lề. # mở đầu comment, --- phân tách nhiều tài liệu trong cùng một file, còn anchor (&name) cùng alias (*name) cho phép tái sử dụng một khối ở nơi khác trong file. Chuỗi thường không cần đặt trong dấu ngoặc kép, giúp file ngắn gọn nhưng đồng nghĩa parser sẽ quyết định kiểu của từng giá trị không có dấu ngoặc kép.

YAML trong quy trình machine learning#

Lưu các thiết lập trong YAML giúp tách biệt việc một thí nghiệm thực hiện với cách mã nguồn thực hiện: nhóm có thể đổi tập dữ liệu hoặc điều chỉnh tốc độ học bằng cách sửa file, ghi lại cấu hình chính xác bằng theo dõi thí nghiệm và xem xét thay đổi qua pull request. Nhiều công cụ trong toàn bộ stack sử dụng YAML, gồm Hydra để kết hợp cấu hình thí nghiệm, GitHub Actions cho pipeline tích hợp liên tục, Docker Compose cho ứng dụng đa container và manifest Kubernetes để triển khai model. Ultralytics YOLO sử dụng YAML ở ba cấp độ: file tập dữ liệu liệt kê thư mục hình ảnh và tên lớp; file model như yolo26.yaml định nghĩa các lớp và kích thước từ n đến x của YOLO26; còn file cấu hình mặc định chứa mọi thiết lập huấn luyện, dự đoán và xuất model, có thể được ghi đè bằng file tùy chỉnh truyền qua cfg=. Đoạn trích này cho thấy cấu trúc của file tập dữ liệu coco8.yaml đi kèm:

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

Quá trình huấn luyện đọc file theo tên, phân giải thư mục hình ảnh từ path và lấy số lượng lớp cùng tên lớp từ names:

from ultralytics import YOLO

# Tải model YOLO26 nano đã pretrained
model = YOLO("yolo26n.pt")

# Huấn luyện trên tập dữ liệu được mô tả trong file YAML
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

Bộ dữ liệu tùy chỉnh chỉ cần tệp YAML riêng với cùng các khóa, trỏ đến ảnh và liệt kê các lớp theo định dạng bộ dữ liệu detection của Ultralytics.

YAML, JSON và TOML#

• JSON: Dùng dấu ngoặc nhọn, ngoặc vuông và khóa đặt trong dấu ngoặc kép, không hỗ trợ comment và được phân tích cú pháp nhất quán ở mọi nơi. JSON phù hợp để trao đổi dữ liệu giữa các chương trình, chẳng hạn phản hồi API và dự đoán đã lưu, hơn là các file do con người chỉnh sửa.
• TOML: Định dạng tương tự INI với kiểu dữ liệu tường minh và ít rắc rối về thụt lề hơn, được Python dùng trong pyproject.toml. TOML kém thuận tiện hơn khi biểu diễn dữ liệu lồng nhau sâu.
• XML: Ngôn ngữ đánh dấu dựa trên thẻ, dài dòng, vẫn xuất hiện trong các định dạng chú thích cũ như Pascal VOC nhưng hiếm khi được chọn cho file cấu hình mới.

Các lỗi thường gặp khi dùng YAML#

Hầu hết lỗi YAML bắt nguồn từ thụt lề: ký tự tab hoặc chỉ một dấu cách lệch cũng có thể làm thay đổi cấu trúc hoặc khiến parser dừng với lỗi ScannerError hoặc ParserError. Các vấn đề khó nhận biết hơn đến từ việc tự động suy luận kiểu dữ liệu. PyYAML, parser được phần lớn dự án Python sử dụng, tuân theo quy tắc YAML 1.1 cũ hơn; các quy tắc này chuyển một số từ không đặt trong dấu ngoặc kép thành boolean và yêu cầu dấu thập phân trong số thực. Tải file không đáng tin cậy bằng yaml.unsafe_load hoặc UnsafeLoader của PyYAML có thể tạo đối tượng Python tùy ý và thực thi mã; vì vậy, mã cấu hình sử dụng yaml.safe_load, vốn chỉ tạo các kiểu dữ liệu thông thường:

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

Kết quả cho thấy ba điều bất ngờ: lr0 được tải dưới dạng chuỗi '1e-3' vì thiếu dấu thập phân, python: 3.10 trở thành số thực 3.1, còn mã quốc gia NO trở thành boolean False, theo quy tắc YAML 1.1 có biệt danh là vấn đề Na Uy. Theo schema lõi YAML 1.2, 1e-3 được tải dưới dạng số thực và NO vẫn là chuỗi, trong khi 3.10 vẫn trở thành 3.1.