YAML

YAML (اختصار عودي لعبارة «YAML ليست لغة ترميز») لغة تسلسل بيانات مقروءة للبشر، تُستخدم غالباً في ملفات الإعداد. تصف البيانات المتداخلة باستخدام المسافات البادئة بدلاً من الأقواس أو الوسوم، وتدعم التعليقات، وترتبط مباشرةً بالقواميس والقوائم والسلاسل النصية والأعداد في لغات البرمجة؛ لذا يسهل على الأشخاص تحرير الملف وعلى البرامج تحميله. في التعلم الآلي، تخزّن ملفات YAML مسارات مجموعات البيانات وبنى النماذج والمعلمات الفائقة وخطوات سير العمل خارج الشيفرة، ما يسهل إعادة التجارب ومراجعتها وإدارة إصداراتها في Git. والمواصفة الحالية هي YAML 1.2.2، وقد صُمم YAML 1.2 بحيث يكون JSON الصالح YAML صالحاً أيضاً.

أساسيات صياغة YAML#

يتكون مستند YAML من ثلاثة أنواع من العقد. التعيينات هي أزواج key: value، والتسلسلات عناصر تبدأ بـ- أو تُكتب بشكل مضمن على هيئة [a, b]، والقيم المفردة قيم منفردة مثل السلاسل النصية والأعداد والقيم المنطقية. يُحدد التداخل بالمسافات البادئة، ولا يُسمح باستخدام محارف الجدولة للمسافة البادئة. يبدأ # تعليقاً، ويفصل --- مستندات متعددة في ملف واحد، وتتيح المراسي (&name) مع الأسماء المستعارة (*name) إعادة استخدام كتلة في موضع آخر من الملف. لا تحتاج السلاسل النصية عادةً إلى علامات اقتباس، ما يجعل الملفات أقصر، لكن ذلك يعني أن المحلّل يحدد نوع كل قيمة غير مقتبسة.

YAML في سير عمل التعلم الآلي#

يفصل الاحتفاظ بالإعدادات في YAML بين ما تفعله التجربة وكيفية تنفيذ الشيفرة لذلك: يستطيع الفريق تبديل مجموعات البيانات أو تغيير معدلات التعلّم بتعديل ملف، وتسجيل الإعداد الدقيق باستخدام تتبّع التجارب، ومراجعة التغييرات في طلبات السحب. تستخدمه أدوات في مختلف مكونات الحزمة، ومنها Hydra لتجميع إعدادات التجارب، وGitHub Actions لخطوط أنابيب التكامل المستمر، وDocker Compose للتطبيقات متعددة الحاويات، وبيانات Kubernetes الوصفية الخاصة بـنشر النماذج. تستخدم Ultralytics YOLO ملفات YAML على ثلاثة مستويات: تسرد ملفات مجموعات البيانات مجلدات الصور وأسماء الفئات، وتحدد ملفات النماذج مثل yolo26.yaml الطبقات ومقاييس n إلى x في YOLO26، ويحوي ملف الإعداد الافتراضي جميع إعدادات التدريب والتنبؤ والتصدير، ويمكن لملف مخصص يُمرر باستخدام 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

تقرأ عملية التدريب الملف باسمه، وتحل مسارات مجلدات الصور انطلاقاً من path، وتأخذ عدد الفئات وأسماءها من names:

from ultralytics import YOLO

# ⁨تحميل نموذج YOLO26 nano مُدرَّب مسبقًا⁩
model = YOLO("yolo26n.pt")

# ⁨درّب النموذج على مجموعة البيانات الموصوفة في ملف YAML⁩
results = model.train(data="coco8.yaml", epochs=3, imgsz=640)

لا تحتاج مجموعة البيانات المخصصة إلا إلى ملف YAML خاص بها بالمفاتيح نفسها، يشير إلى صورها ويسرد فئاتها وفق تنسيق مجموعة بيانات الكشف في Ultralytics.

مقارنة YAML وJSON وTOML#

• JSON: يستخدم الأقواس المعقوفة والمربعة والمفاتيح الموضوعة بين علامتي اقتباس، ولا يدعم التعليقات، ويُحلّل بالطريقة نفسها في كل مكان. وهو أنسب للبيانات المتبادلة بين البرامج، مثل استجابات API والتنبؤات المحفوظة، من الملفات التي يحررها الأشخاص.
• TOML: تنسيق شبيه بـINI يتضمن أنواعاً صريحة ومفاجآت أقل بسبب المسافات البادئة، ويستخدمه pyproject.toml الخاص بـPython. وهو أقل ملاءمة للبيانات المتداخلة بعمق.
• XML: لغة ترميز مطوّلة قائمة على الوسوم، ما زالت مستخدمة في تنسيقات التعليقات التوضيحية الأقدم مثل Pascal VOC، ونادراً ما تُختار لملفات الإعداد الجديدة.

المزالق الشائعة في YAML#

تنشأ معظم أخطاء YAML من المسافات البادئة: إذ يغيّر محرف جدولة أو مسافة واحدة في غير موضعها البنية، أو يوقف المحلّل بسبب ScannerError أو ParserError. أما المشكلات الأقل وضوحاً فتنشأ من تحديد الأنواع الضمني. تتبع PyYAML، وهي المحلّل الذي تستخدمه معظم مشاريع Python، قواعد YAML 1.1 الأقدم، التي تحول بعض الكلمات غير الموضوعة بين علامتي اقتباس إلى قيم منطقية، وتتطلب نقطة عشرية في الأعداد العشرية. ويمكن أن يؤدي تحميل ملفات غير موثوقة باستخدام yaml.unsafe_load أو UnsafeLoader في PyYAML إلى إنشاء كائنات 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 إلى القيمة المنطقية False، وهي قاعدة في YAML 1.1 تلقب بمشكلة النرويج. وفق المخطط الأساسي لـYAML 1.2، يُحمّل 1e-3 عدداً عشرياً وتبقى NO سلسلة نصية، بينما تظل 3.10 تتحول إلى 3.1.