YAML

YAML ("YAML İşaretleme Dili Değildir" ifadesinin özyinelemeli kısaltması), çoğunlukla yapılandırma dosyalarında kullanılan, insanlar tarafından okunabilir bir veri serileştirme dilidir. İç içe verileri köşeli ayraçlar veya etiketler yerine girintilerle tanımlar, yorumları destekler ve programlama dillerinin sözlükleri, listeleri, dizeleri ve sayılarıyla doğrudan eşleşir. Böylece aynı dosyayı insanların düzenlemesi, programların da yüklemesi kolaylaşır. Makine öğreniminde YAML dosyaları veri kümesi yollarını, model mimarilerini, hiperparametreleri ve iş hattı adımlarını kod dışında tutar; böylece deneylerin yeniden üretilmesi, incelenmesi ve Git'te sürümlenmesi kolaylaşır. Geçerli belirtim YAML 1.2.2 sürümüdür ve YAML 1.2, geçerli JSON'un aynı zamanda geçerli YAML olacağı şekilde tasarlanmıştır.

YAML Sözdiziminin Temelleri#

Bir YAML belgesi üç tür düğümden oluşur. Eşlemeler key: value çiftleridir; diziler - ile başlayan öğelerden oluşur veya satır içinde [a, b] biçiminde yazılır; skalerler ise dizeler, sayılar ve Boole değerleri gibi tek değerlerdir. İç içe yerleşim boşluklarla belirlenen girintiye bağlıdır; girintilemede sekme karakterlerine izin verilmez. # yorumu başlatır, --- tek dosyada birden fazla belgeyi ayırır ve çapalar (&name) ile takma adlar (*name) bir bloğun dosyanın başka bir yerinde yeniden kullanılmasını sağlar. Dizeler genellikle tırnak gerektirmez; bu dosyaları kısaltır ama ayrıştırıcının her tırnaksız değerin türüne karar vermesi anlamına gelir.

Makine Öğrenimi İş Akışlarında YAML#

Ayarları YAML'de tutmak, deneyin ne yaptığını kodun bunu nasıl yaptığından ayırır: Ekip, dosyayı düzenleyerek veri kümelerini değiştirebilir veya öğrenme oranlarını güncelleyebilir, deney takibi ile yapılandırmanın tam hâlini kaydedebilir ve değişiklikleri çekme isteklerinde inceleyebilir. Yığın boyunca çeşitli araçlar YAML kullanır: deney yapılandırmalarını birleştirmek için Hydra, sürekli entegrasyon iş hatları için GitHub Actions, çok kapsayıcılı uygulamalar için Docker Compose ve model dağıtımı için Kubernetes bildirimleri. Ultralytics YOLO, YAML'i üç düzeyde kullanır: veri kümesi dosyaları görüntü klasörlerini ve sınıf adlarını listeler; yolo26.yaml gibi model dosyaları, YOLO26 için katmanları ve n'den x'e ölçekleri tanımlar; bir varsayılan yapılandırma dosyası ise tüm eğitim, tahmin ve dışa aktarma ayarlarını içerir ve cfg= ile geçirilen özel bir dosya bu ayarları geçersiz kılabilir. Bu alıntı, paketteki coco8.yaml veri kümesi dosyasının yapısını gösterir:

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

Eğitim dosyayı adına göre okur, görüntü klasörlerinin konumunu path üzerinden çözümler ve sınıf sayısı ile adlarını names üzerinden alır:

from ultralytics import YOLO

# Önceden eğitilmiş bir YOLO26 nano modeli yükle
model = YOLO("yolo26n.pt")

# # YAML dosyasında açıklanan veri kümesinde eğitim yap
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

Özel bir veri kümesinin yalnızca kendi YAML dosyasına ihtiyacı vardır; YAML dosyası aynı anahtarları içerir, veri kümesinin görüntülerine işaret eder ve veri kümesinin sınıflarını Ultralytics nesne algılama veri kümesi biçiminde listeler.

YAML, JSON ve TOML Karşılaştırması#

• JSON: Küme ayraçları, köşeli ayraçlar ve tırnaklı anahtarlar kullanır; yorum içermez ve her yerde aynı şekilde ayrıştırılır. API yanıtları ve kaydedilmiş tahminler gibi programlar arasında aktarılan veriler için, insanların düzenlediği dosyalardan daha uygundur.
• TOML: Açık türler kullanan ve girintiden kaynaklanan sürprizleri azaltan INI benzeri bir biçimdir; Python'ın pyproject.toml dosyasında kullanılır. Derin iç içe geçmiş veriler için kullanımı daha az rahattır.
• XML: Pascal VOC gibi eski açıklama biçimlerinde hâlâ kullanılan, ayrıntılı ve etiket tabanlı bir işaretleme dilidir; yeni yapılandırma dosyalarında nadiren tercih edilir.

Yaygın YAML Sorunları#

YAML hatalarının çoğu girintiden kaynaklanır: Bir sekme karakteri veya hizası bozuk tek bir boşluk yapıyı değiştirir ya da ayrıştırıcının ScannerError veya ParserError hatasıyla durmasına neden olur. Daha ince sorunlar örtük tür belirlemeden kaynaklanır. Python projelerinin çoğunun kullandığı ayrıştırıcı PyYAML, eski YAML 1.1 kurallarını izler; bu kurallar bazı tırnaksız sözcükleri Boole değerlerine dönüştürür ve kayan noktalı sayılarda ondalık nokta gerektirir. Güvenilmeyen dosyaları yaml.unsafe_load veya PyYAML'ın UnsafeLoader aracıyla yüklemek, rastgele Python nesneleri oluşturup kod çalıştırabilir. Bu nedenle yapılandırma kodu yalnızca düz veri türleri oluşturan yaml.safe_load kullanır:

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

Çıktıda üç sürpriz görülür: lr0, ondalık noktası olmadığı için '1e-3' dizesi olarak yüklenir; python: 3.10, 3.1 kayan noktalı sayısına dönüşür; ülke kodu NO ise YAML 1.1'de Norveç sorunu adı verilen kural nedeniyle False Boole değerine dönüşür. YAML 1.2 temel şemasında 1e-3 kayan noktalı sayı olarak yüklenir ve NO dize olarak kalır; 3.10 ise yine 3.1'e dönüşür.