الاستدعاءات#
يدعم إطار عمل Ultralytics عمليات رد الاتصال (callbacks)، والتي تعمل كنقاط دخول في مراحل استراتيجية خلال أوضاع train و val و export و predict. يقبل كل رد اتصال كائناً من نوع Trainer أو Validator أو Predictor، اعتماداً على نوع العملية. يتم تفصيل جميع خصائص هذه الكائنات في صفحات المراجع BaseTrainer و BaseValidator و BasePredictor.
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تسجيل خطافات التوجيه الأمامي لـ 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() يتعامل مع تدريب الجهاز الفردي والتدريب المتوازي الموزع. لا تقم بإرفاق خطاف معرف محليًا بـ trainer.ema.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 | يتم تشغيله عندما تنتهي عملية التصدير. |
الأسئلة الشائعة#
عمليات رد الاتصال (callbacks) في 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 عن طريق حقن المنطق في مراحل محددة من عملية التدريب. توفر 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 إلى تعزيز تقييم النموذج من خلال تمكين المعالجة المخصصة أو التسجيل أو حساب المقاييس. توفر استدعاءات مثل
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، قم بتعريف دالة استدعاء وتسجيلها مع عملية التنبؤ. تشمل استدعاءات التنبؤ الشائعة
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للاطلاع على استخدام أكثر شمولاً، راجع دليل التنبؤ، والذي يتضمن إرشادات مفصلة وخيارات تخصيص إضافية.
تدعم YOLO من Ultralytics تطبيقات عملية مختلفة للاستدعاءات لتحسين وتخصيص المراحل المختلفة مثل التدريب والتحقق والتنبؤ. تتضمن بعض الأمثلة العملية ما يلي:
- تسجيل المقاييس المخصصة: تسجيل مقاييس إضافية في مراحل مختلفة، مثل نهاية حقبة التدريب أو التحقق.
- زيادة البيانات: تنفيذ تحويلات أو زيادات بيانات مخصصة أثناء التنبؤ أو دفعات التدريب.
- النتائج الوسيطة: حفظ النتائج الوسيطة، مثل التنبؤات أو الإطارات، لمزيد من التحليل أو التصور.
مثال: الجمع بين الإطارات ونتائج التنبؤ أثناء التنبؤ باستخدام
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استكشف الشيفرة المصدرية للاستدعاءات لمزيد من الخيارات والأمثلة.