رؤية YOLO 2026:

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

يدعم إطار عمل Ultralytics الاستدعاءات (callbacks)، والتي تعمل كنقاط دخول في مراحل استراتيجية خلال أوضاع 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 Callbacks)#

رد الاستدعاءالوصف
on_pretrain_routine_startيتم تفعيله في بداية روتين ما قبل التدريب، قبل تحميل البيانات وإعداد النموذج.
on_pretrain_routine_endيتم تفعيله في نهاية روتين ما قبل التدريب، بعد اكتمال تحميل البيانات وإعداد النموذج.
on_train_startيتم تنشيطه عند بدء التدريب، قبل أن تبدأ حقب التدريب (epoch) الأولى.
on_train_epoch_startيتم تنشيطه في بداية كل حقبة تدريب (epoch)، قبل أن يبدأ تكرار الدُفعات (batch iteration).
on_train_batch_startيتم تفعيله في بداية كل دفعة تدريب، قبل التمرير الأمامي.
optimizer_stepيتم تفعيله أثناء خطوة المُحسِّن (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يتم تفعيله عند تنظيف عملية التدريب.

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

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

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

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

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

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

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

  • استدعاءات 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 مجموعة متنوعة من استدعاءات التدريب، مثل 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)

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

  • يؤدي استخدام الاستدعاءات أثناء التحقق في 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

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

المساهمون
GLglenn-jocher15RIRizwanMunawar3RAraimbekovm2Y-Y-T-G1

التعليقات