دوال الاستدعاء#
يدعم إطار عمل Ultralytics عمليات الاستدعاء، التي تعمل كنقاط دخول في مراحل استراتيجية أثناء أوضاع train وval وexport وpredict. ويقبل كل استدعاء كائنًا من النوع Trainer أو Validator أو Predictor، وفقًا لنوع العملية. وتُفصّل جميع خصائص هذه الكائنات في صفحات مرجع BaseTrainer وBaseValidator وBasePredictor.
شاهد: كيفية استخدام عمليات الاستدعاء في Ultralytics | عمليات الاستدعاء للتنبؤ والتدريب والتحقق والتصدير | Ultralytics YOLO26 🚀
أمثلة#
إرجاع معلومات إضافية مع التنبؤ#
في هذا المثال، نوضح كيفية إرجاع الإطار الأصلي مع كل كائن نتيجة:
from ultralytics import YOLO
def on_predict_batch_end(predictor):
"""Combine prediction results with corresponding frames."""
_, image, _ = predictor.batch
# تأكّد من أن image قائمة
image = image if isinstance(image, list) else [image]
# ادمج نتائج التنبؤ مع الإطارات المقابلة
predictor.results = zip(predictor.results, image)
# أنشئ مثيلًا من نموذج YOLO
model = YOLO("yolo26n.pt")
# أضف استدعاءك المخصّص إلى النموذج
model.add_callback("on_predict_batch_end", on_predict_batch_end)
# كرّر النتائج والإطارات
for result, frame in model.predict(): # أو model.track()
passتسجيل خطافات PyTorch الأمامية قبل التدريب#
تنشئ model.train() نموذج تدريب من تهيئة النموذج وتنقل إليه الأوزان المحمّلة. وتُعدّ خطافات PyTorch المسجّلة مباشرةً على model.model قبل هذا الاستدعاء حالة وقت تشغيل، ولذلك لا يرثها نموذج التدريب المُعاد إنشاؤه. سجّل خطافات التدريب في on_pretrain_routine_end بعد اكتمال إعداد النموذج:
from ultralytics import YOLO
from ultralytics.utils.torch_utils import unwrap_model
def preprocess_input(module, inputs):
"""Center each input channel before the first model layer."""
images = inputs[0]
return (images - images.mean(dim=(-2, -1), keepdim=True),)
def register_forward_pre_hook(trainer):
"""Attach preprocessing to the active training model."""
train_model = unwrap_model(trainer.model)
train_model.model[0].register_forward_pre_hook(preprocess_input)
model = YOLO("yolo26n.pt")
model.add_callback("on_pretrain_routine_end", register_forward_pre_hook)
model.train(data="coco8.yaml", epochs=1)تتعامل unwrap_model() مع التدريب على جهاز واحد والتدريب باستخدام DistributedDataParallel. لا تربط خطافًا معرّفًا محليًا بـtrainer.ema.ema، لأن نقاط التحقق التدريبية تحفظ نموذج EMA، وقد لا تتمكن عملية أخرى من استيراد دالة الاستدعاء عند تحميل نقطة التحقق. إذا كان يجب تنفيذ المعالجة المسبقة نفسها أثناء التحقق من التدريب، فنفّذها بوصفها مكوّنًا قابلًا للاستيراد ضمن النموذج بدلًا من خطاف وقت تشغيل. تعيد معالجة NaN بناء EMA من نموذج التدريب، لذا يُنسخ الخطاف المسجّل بهذه الطريقة إلى EMA ونقاط التحقق المحفوظة بعد الاستعادة؛ عرّف دالة الخطاف في وحدة قابلة للاستيراد إذا كان يجب تحميل نقاط التحقق في عملية أخرى.
تنسخ model.val() المستقلة النموذج المحمّل عند كل استدعاء. ينشئ التنبؤ نسخةً ويخزّنها مؤقتًا عند أول استدعاء، لذا سجّل الخطافات على model.model قبل أول استدعاء لـmodel.predict() أو model.track()؛ فالخطافات المضافة بعد ذلك لا تصل إلى المتنبئ المخزّن مؤقتًا. أعد تسجيل خطافات وقت التشغيل بعد تحميل نقطة تحقق في عملية جديدة.
الوصول إلى مقاييس النموذج باستخدام استدعاء on_model_save#
يوضح هذا المثال كيفية استرجاع تفاصيل التدريب، مثل best_fitness وtotal_loss والمقاييس الأخرى، بعد حفظ نقطة تحقق باستخدام استدعاء on_model_save.
from ultralytics import YOLO
# Load a YOLO model
model = YOLO("yolo26n.pt")
def print_checkpoint_metrics(trainer):
"""Print trainer metrics and loss details after each checkpoint is saved."""
print(
f"Model details\n"
f"Best fitness: {trainer.best_fitness}, "
f"Loss names: {trainer.loss_names}, " # List of loss names
f"Metrics: {trainer.metrics}, "
f"Total loss: {trainer.tloss}" # Total loss value
)
if __name__ == "__main__":
# Add on_model_save callback.
model.add_callback("on_model_save", print_checkpoint_metrics)
# Run model training on custom dataset.
results = model.train(data="coco8.yaml", epochs=3)جميع عمليات الاستدعاء#
فيما يلي جميع عمليات الاستدعاء المدعومة. لمزيد من التفاصيل، راجع الشيفرة المصدرية لعمليات الاستدعاء.
عمليات استدعاء المدرّب#
| استدعاء | الوصف |
|---|---|
on_pretrain_routine_start | يُفعّل في بداية إجراء ما قبل التدريب، قبل تحميل البيانات وإعداد النموذج. |
on_pretrain_routine_end | يُفعّل في نهاية إجراء ما قبل التدريب، بعد اكتمال تحميل البيانات وإعداد النموذج. |
on_train_start | يُفعّل عند بدء التدريب، قبل بدء حقبة التدريب الأولى. |
on_train_epoch_start | يُفعّل في بداية كل حقبة تدريب، قبل بدء التكرار على الدُفعات. |
on_train_batch_start | يُفعّل في بداية كل دفعة تدريب، قبل المرور الأمامي. |
optimizer_step | يُفعّل أثناء خطوة المحسِّن. مخصّص للتكاملات المخصّصة؛ ولا تستدعيه حلقة التدريب الافتراضية. |
on_before_zero_grad | يُفعّل قبل تصفير التدرجات. مخصّص للتكاملات المخصّصة؛ ولا تستدعيه حلقة التدريب الافتراضية. |
on_train_batch_end | يُفعّل في نهاية كل دفعة تدريب، بعد المرور الخلفي. وقد تُؤجّل خطوة المحسِّن بسبب تراكم التدرجات. |
on_train_epoch_end | يُفعّل في نهاية كل حقبة تدريب، بعد معالجة جميع الدُفعات ولكن قبل التحقق. وقد لا تكون مقاييس التحقق والملاءمة متاحة بعد. |
on_model_save | يُفعّل عند حفظ نقطة تحقق النموذج، بعد التحقق. |
on_fit_epoch_end | يُفعّل في نهاية كل حقبة ملاءمة (تدريب + تحقق)، بعد التحقق وحفظ أي نقطة تحقق. تكون مقاييس التحقق متاحة، وتكون قيمة الملاءمة متاحة لاستدعاء التدريب لكل حقبة. ويُستدعى هذا الاستدعاء أيضًا أثناء التقييم النهائي لأفضل نموذج، حيث لا تُحفظ أي نقطة تحقق وقد لا تكون قيمة الملاءمة متاحة. |
on_train_end | يُفعّل عند انتهاء عملية التدريب، بعد التقييم النهائي لأفضل نموذج. |
on_params_update | يُفعّل عند تحديث معلمات النموذج. مخصّص للتكاملات المخصّصة؛ ولا تستدعيه حلقة التدريب الافتراضية. |
teardown | يُفعّل أثناء تنظيف عملية التدريب. |
عمليات استدعاء المدقّق#
| استدعاء | الوصف |
|---|---|
on_val_start | يُفعّل عند بدء التحقق. |
on_val_batch_start | يُفعّل في بداية كل دفعة تحقق. |
on_val_batch_end | يُفعّل في نهاية كل دفعة تحقق. |
on_val_end | يُفعّل عند انتهاء التحقق. |
عمليات استدعاء المتنبئ#
| استدعاء | الوصف |
|---|---|
on_predict_start | يُفعّل عند بدء عملية التنبؤ. |
on_predict_batch_start | يُفعّل في بداية كل دفعة تنبؤ. |
on_predict_postprocess_end | يُفعّل في نهاية المعالجة اللاحقة للتنبؤ. |
on_predict_batch_end | يُفعّل في نهاية كل دفعة تنبؤ. |
on_predict_end | يُفعّل عند انتهاء عملية التنبؤ. |
عمليات استدعاء المُصدِّر#
| استدعاء | الوصف |
|---|---|
on_export_start | يُفعّل عند بدء عملية التصدير. |
on_export_end | يُفعّل عند انتهاء عملية التصدير. |
الأسئلة الشائعة#
عمليات استدعاء Ultralytics هي نقاط دخول متخصصة تُفعّل خلال مراحل أساسية من عمليات النموذج، مثل التدريب والتحقق والتصدير والتنبؤ. تتيح هذه العمليات إضافة وظائف مخصّصة في نقاط محددة من العملية، ما يسمح بتحسين سير العمل وتعديله. ويقبل كل استدعاء كائنًا من النوع
TrainerأوValidatorأوPredictor، وفقًا لنوع العملية. للاطلاع على الخصائص التفصيلية لهذه الكائنات، راجع صفحات المرجعBaseTrainerوBaseValidatorوBasePredictor.لاستخدام استدعاء، عرّف دالة وأضفها إلى النموذج باستخدام الطريقة
model.add_callback(). إليك مثالًا على إرجاع معلومات إضافية أثناء التنبؤ:from ultralytics import YOLO def on_predict_batch_end(predictor): """Handle prediction batch end by combining results with corresponding frames; modifies predictor results.""" _, image, _ = predictor.batch image = image if isinstance(image, list) else [image] predictor.results = zip(predictor.results, image) model = YOLO("yolo26n.pt") model.add_callback("on_predict_batch_end", on_predict_batch_end) for result, frame in model.predict(): passخصّص إجراء التدريب في Ultralytics عن طريق إدراج منطق في مراحل محددة من عملية التدريب. يوفر Ultralytics YOLO مجموعة متنوعة من استدعاءات التدريب، مثل
on_train_startوon_train_endوon_train_batch_end، التي تتيح لك إضافة مقاييس مخصّصة أو معالجة أو تسجيل.إليك كيفية تسجيل معدل التعلّم لكل مجموعة من معلمات المحسِّن في نهاية كل حقبة تدريب:
from ultralytics import YOLO def log_learning_rates(trainer): """Print the current learning rates after each training epoch.""" print(f"Epoch {trainer.epoch + 1}: {trainer.lr}") model = YOLO("yolo26n.pt") model.add_callback("on_train_epoch_end", log_learning_rates) model.train(data="coco8.yaml", epochs=3)نصيحةلا تحتاج إلى استدعاء لتجميد إحصاءات BatchNorm عند استخدام
freeze: إذ يضع المدرّب تلقائيًا طبقات BatchNorm للطبقات المجمّدة في وضع التقييم في بداية كل حقبة.لمزيد من التفاصيل حول الاستخدام الفعّال لاستدعاءات التدريب، راجع دليل التدريب.
يعزز استخدام عمليات الاستدعاء أثناء التحقق في Ultralytics YOLO تقييم النموذج من خلال إتاحة المعالجة المخصّصة أو التسجيل أو حساب المقاييس. وتوفر استدعاءات مثل
on_val_startوon_val_batch_endوon_val_endنقاط دخول لإدراج منطق مخصّص، بما يضمن عمليات تحقق مفصّلة وشاملة.على سبيل المثال، لرسم جميع دفعات التحقق بدلًا من الدفعات الثلاث الأولى فقط:
import inspect from ultralytics import YOLO def plot_samples(validator): frame = inspect.currentframe().f_back.f_back v = frame.f_locals validator.plot_val_samples(v["batch"], v["batch_i"]) validator.plot_predictions(v["batch"], v["preds"], v["batch_i"]) model = YOLO("yolo26n.pt") model.add_callback("on_val_batch_end", plot_samples) model.val(data="coco.yaml")لمزيد من المعلومات حول دمج عمليات الاستدعاء في عملية التحقق، راجع دليل التحقق.
لربط استدعاء مخصّص بوضع التنبؤ في Ultralytics YOLO، عرّف دالة استدعاء وسجّلها في عملية التنبؤ. تشمل استدعاءات التنبؤ الشائعة
on_predict_startوon_predict_batch_endوon_predict_end. وتتيح هذه الاستدعاءات تعديل مخرجات التنبؤ ودمج وظائف إضافية، مثل تسجيل البيانات أو تحويل النتائج.إليك مثالًا على استدعاء مخصّص يحفظ التنبؤات استنادًا إلى وجود كائن من فئة معينة:
from ultralytics import YOLO model = YOLO("yolo26n.pt") class_id = 2 def save_on_object(predictor): r = predictor.results[0] if class_id in r.boxes.cls: predictor.args.save = True else: predictor.args.save = False model.add_callback("on_predict_postprocess_end", save_on_object) results_stream = model("pedestrians.mp4", stream=True, save=True) for result in results_stream: passللاطلاع على استخدام أشمل، راجع دليل التنبؤ، الذي يتضمن تعليمات مفصّلة وخيارات إضافية للتخصيص.
يدعم Ultralytics YOLO تطبيقات عملية متنوعة لعمليات الاستدعاء بهدف تحسين مراحل مختلفة وتخصيصها، مثل التدريب والتحقق والتنبؤ. ومن الأمثلة العملية:
- تسجيل المقاييس المخصّصة: سجّل مقاييس إضافية في مراحل مختلفة، مثل نهاية حقبات التدريب أو التحقق.
- زيادة البيانات: نفّذ تحويلات أو زيادات مخصّصة للبيانات أثناء دفعات التنبؤ أو التدريب.
- النتائج الوسيطة: احفظ النتائج الوسيطة، مثل التنبؤات أو الإطارات، لإجراء مزيد من التحليل أو التصوير المرئي.
مثال: دمج الإطارات مع نتائج التنبؤ أثناء التنبؤ باستخدام
on_predict_batch_end:from ultralytics import YOLO def on_predict_batch_end(predictor): """Combine prediction results with frames.""" _, image, _ = predictor.batch image = image if isinstance(image, list) else [image] predictor.results = zip(predictor.results, image) model = YOLO("yolo26n.pt") model.add_callback("on_predict_batch_end", on_predict_batch_end) for result, frame in model.predict(): passاستكشف الشيفرة المصدرية لعمليات الاستدعاء لمزيد من الخيارات والأمثلة.