ردود الاستدعاء (Callbacks)

يدعم إطار عمل Ultralytics ردود الاستدعاء، والتي تعمل كنقاط دخول في مراحل استراتيجية أثناء أوضاع train و val و export و predict. يقبل كل رد استدعاء كائن Trainer أو Validator أو Predictor، اعتمادًا على نوع العملية. جميع خصائص هذه الكائنات مفصلة في قسم المرجع من التوثيق.



Watch: How to use Ultralytics Callbacks | Predict, Train, Validate and Export Callbacks | Ultralytics YOLO🚀

أمثلة

إرجاع معلومات إضافية مع التنبؤ

في هذا المثال، نوضح كيفية إرجاع الإطار الأصلي مع كل كائن نتيجة:

from ultralytics import YOLO

def on_predict_batch_end(predictor):
    """Combine prediction results with corresponding frames."""
    _, image, _, _ = predictor.batch

    # Ensure that image is a list
    image = image if isinstance(image, list) else [image]

    # Combine the prediction results with the corresponding frames
    predictor.results = zip(predictor.results, image)

# Create a YOLO model instance
model = YOLO("yolo26n.pt")

# Add the custom callback to the model
model.add_callback("on_predict_batch_end", on_predict_batch_end)

# Iterate through the results and frames
for result, frame in model.predict():  # or model.track()
    pass

الوصول إلى مقاييس النموذج باستخدام رد الاستدعاء on_model_save

يوضح هذا المثال كيفية استرداد تفاصيل التدريب، مثل درجة best_fitness و total_loss ومقاييس أخرى بعد حفظ نقطة فحص (checkpoint) باستخدام رد الاستدعاء 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)

جميع ردود الاستدعاء

فيما يلي جميع ردود الاستدعاء المدعومة. لمزيد من التفاصيل، راجع الكود المصدري لردود الاستدعاء.

ردود استدعاء المدرب (Trainer)

رد الاستدعاءالوصف
on_pretrain_routine_startيتم تشغيله في بداية روتين ما قبل التدريب، قبل تحميل البيانات وإعداد النموذج.
on_pretrain_routine_endيتم تشغيله في نهاية روتين ما قبل التدريب، بعد اكتمال تحميل البيانات وإعداد النموذج.
on_train_startيتم تشغيله عند بدء التدريب، قبل بداية الدورة التدريبية (epoch) الأولى.
on_train_epoch_startيتم تشغيله في بداية كل دورة تدريبية (epoch)، قبل بدء تكرار الدفعة (batch).
on_train_batch_startيتم تشغيله في بداية كل دفعة تدريب، قبل التمرير الأمامي (forward pass).
optimizer_stepيتم تشغيله أثناء خطوة المُحسن. مخصص للتكاملات المخصصة؛ لا يتم استدعاؤه بواسطة حلقة التدريب الافتراضية.
on_before_zero_gradيتم تشغيله قبل تصفير التدرجات (gradients). مخصص للتكاملات المخصصة؛ لا يتم استدعاؤه بواسطة حلقة التدريب الافتراضية.
on_train_batch_endيتم تشغيله في نهاية كل دفعة تدريب، بعد التمرير العكسي (backward pass). قد يتم تأجيل خطوة المُحسن بسبب تراكم التدرج.
on_train_epoch_endيتم تشغيله في نهاية كل دورة تدريبية، بعد معالجة جميع الدفعات ولكن قبل التحقق (validation). قد لا تكون مقاييس التحقق واللياقة (fitness) متاحة بعد.
on_model_saveيتم تشغيله عند حفظ نقطة فحص النموذج، بعد التحقق.
on_fit_epoch_endيتم تشغيله في نهاية كل دورة تدريب ومطابقة (train + val)، بعد التحقق وأي حفظ لنقطة الفحص. مقاييس التحقق متاحة، واللياقة متاحة لاستدعاء التدريب لكل دورة. يتم استدعاء رد الاستدعاء هذا أيضاً أثناء التقييم النهائي لأفضل نموذج، حيث لا يحدث حفظ لنقطة الفحص وقد لا تكون اللياقة موجودة.
on_train_endيتم تشغيله عند انتهاء عملية التدريب، بعد التقييم النهائي لأفضل نموذج.
on_params_updateيتم تشغيله عند تحديث معلمات النموذج. مخصص للتكاملات المخصصة؛ لا يتم استدعاؤه بواسطة حلقة التدريب الافتراضية.
teardownيتم تشغيله عند تنظيف عملية التدريب.

ردود استدعاء المُحقق (Validator)

رد الاستدعاءالوصف
on_val_startيتم تشغيله عند بدء التحقق.
on_val_batch_startيتم تشغيله في بداية كل دفعة تحقق.
on_val_batch_endيتم تشغيله في نهاية كل دفعة تحقق.
on_val_endيتم تشغيله عند انتهاء التحقق.

ردود استدعاء المُتنبئ (Predictor)

رد الاستدعاءالوصف
on_predict_startيتم تشغيله عند بدء عملية التنبؤ.
on_predict_batch_startيتم تشغيله في بداية كل دفعة تنبؤ.
on_predict_postprocess_endيتم تشغيله في نهاية معالجة ما بعد التنبؤ.
on_predict_batch_endيتم تشغيله في نهاية كل دفعة تنبؤ.
on_predict_endيتم تشغيله عند انتهاء عملية التنبؤ.

ردود استدعاء المُصدِّر (Exporter)

رد الاستدعاءالوصف
on_export_startيتم تشغيله عند بدء عملية التصدير.
on_export_endيتم تشغيله عند انتهاء عملية التصدير.

الأسئلة الشائعة

ما هي ردود استدعاء Ultralytics وكيف يمكنني استخدامها؟

ردود استدعاء Ultralytics هي نقاط دخول متخصصة يتم تشغيلها خلال مراحل رئيسية لعمليات النموذج مثل التدريب والتحقق والتصدير والتنبؤ. تتيح ردود الاستدعاء هذه وظائف مخصصة في نقاط محددة في العملية، مما يسمح بالتحسينات والتعديلات على سير العمل. يقبل كل رد استدعاء كائن Trainer أو Validator أو Predictor، اعتماداً على نوع العملية. لمعرفة الخصائص التفصيلية لهذه الكائنات، راجع قسم المرجع.

لاستخدام رد استدعاء، حدد دالة وأضفها إلى النموذج باستخدام طريقة 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 من Ultralytics مجموعة متنوعة من ردود استدعاء التدريب، مثل on_train_start و on_train_end و on_train_batch_end، والتي تسمح لك بإضافة مقاييس مخصصة أو معالجة أو تسجيل.

إليك كيفية تجميد إحصائيات BatchNorm عند تجميد الطبقات باستخدام ردود الاستدعاء:

from ultralytics import YOLO

# Add a callback to put the frozen layers in eval mode to prevent BN values from changing
def put_in_eval_mode(trainer):
    n_layers = trainer.args.freeze
    if not isinstance(n_layers, int):
        return

    for i, (name, module) in enumerate(trainer.model.named_modules()):
        if name.endswith("bn") and int(name.split(".")[1]) < n_layers:
            module.eval()
            module.track_running_stats = False

model = YOLO("yolo26n.pt")
model.add_callback("on_train_epoch_start", put_in_eval_mode)
model.train(data="coco.yaml", epochs=10)

لمزيد من التفاصيل حول الاستخدام الفعال لردود استدعاء التدريب، راجع دليل التدريب.

لماذا يجب أن أستخدم ردود الاستدعاء أثناء التحقق في YOLO من Ultralytics؟

يؤدي استخدام ردود الاستدعاء أثناء التحقق في YOLO من Ultralytics إلى تعزيز تقييم النموذج من خلال تمكين المعالجة المخصصة أو التسجيل أو حساب المقاييس. توفر ردود الاستدعاء مثل 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")

لمزيد من الأفكار حول دمج ردود الاستدعاء في عملية التحقق الخاصة بك، راجع دليل التحقق.

كيف أقوم بإرفاق رد استدعاء مخصص لوضع التنبؤ في YOLO من Ultralytics؟

لإرفاق رد استدعاء مخصص لوضع التنبؤ في YOLO من Ultralytics، حدد دالة رد استدعاء وقم بتسجيلها في عملية التنبؤ. تشمل ردود استدعاء التنبؤ الشائعة 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 = model("pedestrians.mp4", stream=True, save=True)

for results in results:
    pass

لمزيد من الاستخدام الشامل، راجع دليل التنبؤ، والذي يتضمن تعليمات مفصلة وخيارات تخصيص إضافية.

ما هي بعض الأمثلة العملية لاستخدام ردود الاستدعاء في YOLO من Ultralytics؟

يدعم YOLO من Ultralytics تطبيقات عملية متنوعة لردود الاستدعاء لتعزيز وتخصيص مراحل مختلفة مثل التدريب والتحقق والتنبؤ. تتضمن بعض الأمثلة العملية ما يلي:

  • تسجيل مقاييس مخصصة: سجل مقاييس إضافية في مراحل مختلفة، مثل نهاية الدورات التدريبية (epochs) للتدريب أو التحقق.
  • تعزيز البيانات (Data Augmentation): قم بتنفيذ تحويلات أو تعزيزات بيانات مخصصة أثناء دفعات التنبؤ أو التدريب.
  • نتائج وسيطة: احفظ النتائج الوسيطة، مثل التنبؤات أو الإطارات، لمزيد من التحليل أو التصور.

مثال: دمج الإطارات مع نتائج التنبؤ أثناء التنبؤ باستخدام 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

استكشف الكود المصدري لردود الاستدعاء لمزيد من الخيارات والأمثلة.

التعليقات