Link to this sectionكيفية تصدير نماذج PyTorch غير التابعة لـ YOLO باستخدام Ultralytics#

عادة ما يعني نشر نماذج PyTorch في بيئة الإنتاج التعامل مع أداة تصدير مختلفة لكل هدف: torch.onnx.export لـ ONNX، وcoremltools لأجهزة Apple، وonnx2tf لـ TensorFlow، وpnnx لـ NCNN، وما إلى ذلك. لكل أداة واجهة برمجة تطبيقات (API) خاصة بها، وخصائص تبعيات فريدة، واتفاقيات مخرجات معينة.

توفر Ultralytics أدوات تصدير مستقلة تغلف خوادم خلفية متعددة (backends) خلف واجهة واحدة متسقة. يمكنك تصدير أي torch.nn.Module، بما في ذلك نماذج الصور timm، ومصنفات وكاشفات torchvision، أو بنياتك المخصصة، إلى ONNX، وTorchScript، وOpenVINO، وCoreML، وNCNN، وPaddlePaddle، وMNN، وExecuTorch، وTensorFlow SavedModel دون الحاجة لتعلم كل خادم خلفي على حدة.

Link to this sectionلماذا تستخدم Ultralytics لتصدير النماذج غير التابعة لـ YOLO؟#

• واجهة برمجة تطبيقات (API) واحدة عبر 10 تنسيقات: تعلم اتفاقية استدعاء واحدة بدلاً من اثنتي عشرة.
• سطح أداة مشترك: توجد أدوات المساعدة في التصدير تحت ultralytics.utils.export، لذا بمجرد تثبيت حزم الخادم الخلفي، يمكنك الاحتفاظ بنفس نمط الاستدعاء عبر التنسيقات المختلفة.
• نفس مسار التعليمات البرمجية لتصدير YOLO: نفس أدوات المساعدة التي تشغل كل عمليات تصدير Ultralytics YOLO.
• تكميم FP16 و INT8 مضمن للتنسيقات التي تدعم ذلك (OpenVINO و CoreML و MNN و NCNN).
• يعمل على CPU: لا يتطلب GPU لخطوة التصدير نفسها، لذا يمكنك تشغيله محلياً على أي حاسوب محمول.

Link to this sectionبداية سريعة#

المسار الأسرع هو تصدير في خطوتين إلى ONNX بدون كود YOLO وبدون إعداد سوى pip install ultralytics onnx timm:

import timm
import torch

from ultralytics.utils.export import torch2onnx

model = timm.create_model("resnet18", pretrained=True).eval()
torch2onnx(model, torch.randn(1, 3, 224, 224), output_file="resnet18.onnx")

Link to this sectionتنسيقات التصدير المدعومة#

تأخذ دوال torch2* نموذج torch.nn.Module قياسياً وموتر إدخال مثالياً. تمر MNN و TF SavedModel و TF Frozen Graph عبر ملف ONNX أو Keras وسيط. لا يلزم وجود سمات خاصة بـ YOLO في أي من الحالتين.

Link to this sectionأمثلة خطوة بخطوة#

يستخدم كل مثال أدناه نفس الإعداد، وهو نموذج ResNet-18 مُدرب مسبقاً من timm في وضع التقييم:

import timm
import torch

model = timm.create_model("resnet18", pretrained=True).eval()
im = torch.randn(1, 3, 224, 224)

Link to this sectionالتصدير إلى ONNX#

from ultralytics.utils.export import torch2onnx

torch2onnx(model, im, output_file="resnet18.onnx")

بالنسبة لحجم الدفعة الديناميكي، مرر قاموس dynamic:

torch2onnx(model, im, output_file="resnet18_dyn.onnx", dynamic={"images": {0: "batch_size"}})

مجموعة العمليات (opset) الافتراضية هي 14 واسم الإدخال الافتراضي هو "images". يمكنك التجاوز باستخدام وسائط opset أو input_names أو output_names.

Link to this sectionالتصدير إلى TorchScript#

لا حاجة لتبعيات إضافية. يستخدم torch.jit.trace خلف الكواليس.

from ultralytics.utils.export import torch2torchscript

torch2torchscript(model, im, output_file="resnet18.torchscript")

Link to this sectionالتصدير إلى OpenVINO#

from ultralytics.utils.export import torch2openvino

ov_model = torch2openvino(model, im, output_dir="resnet18_openvino_model")

يحتوي الدليل على زوج ملفات model.xml و model.bin ذو أسماء ثابتة:

resnet18_openvino_model/
├── model.xml
└── model.bin

مرر dynamic=True لأشكال الإدخال الديناميكية، وhalf=True لـ FP16، أو int8=True لتكميم INT8. يتطلب INT8 بالإضافة إلى ذلك وسيط calibration_dataset.

يتطلب openvino>=2024.0.0 (أو >=2025.2.0 على macOS 15.4+) و torch>=2.1.

Link to this sectionالتصدير إلى CoreML#

import coremltools as ct

from ultralytics.utils.export import torch2coreml

inputs = [ct.TensorType("input", shape=(1, 3, 224, 224))]
ct_model = torch2coreml(model, inputs, im, output_file="resnet18.mlpackage")

بالنسبة لنماذج التصنيف، مرر قائمة بأسماء الفئات إلى classifier_names لإضافة رأس تصنيف إلى نموذج CoreML.

يتطلب coremltools>=9.0 و torch>=1.11 و numpy<=2.3.5. غير مدعوم على Windows.

Link to this sectionالتصدير إلى TensorFlow SavedModel#

تتم عملية تصدير TF SavedModel عبر ONNX كخطوة وسيطة:

from ultralytics.utils.export import onnx2saved_model, torch2onnx

torch2onnx(model, im, output_file="resnet18.onnx")
keras_model = onnx2saved_model("resnet18.onnx", output_dir="resnet18_saved_model")

ترجع الدالة نموذج Keras كما تقوم بإنشاء ملفات TFLite (.tflite) داخل دليل المخرجات:

resnet18_saved_model/
├── saved_model.pb
├── variables/
├── resnet18_float32.tflite
├── resnet18_float16.tflite
└── resnet18_int8.tflite

المتطلبات:

• tensorflow>=2.0.0,<=2.19.0
• onnx2tf>=1.26.3,<1.29.0
• tf_keras<=2.19.0
• sng4onnx>=1.0.1
• onnx_graphsurgeon>=0.3.26 (التثبيت باستخدام --extra-index-url https://pypi.ngc.nvidia.com)
• ai-edge-litert>=1.2.0,<1.4.0 على macOS (ai-edge-litert>=1.2.0 على المنصات الأخرى)
• onnxslim>=0.1.71
• onnx>=1.12.0,<2.0.0
• protobuf>=5

Link to this sectionالتصدير إلى TensorFlow Frozen Graph#

استكمالاً لتصدير SavedModel أعلاه، قم بتحويل نموذج Keras المرجع إلى مخطط .pb مجمد:

from pathlib import Path

from ultralytics.utils.export import keras2pb

keras2pb(keras_model, output_file=Path("resnet18_saved_model/resnet18.pb"))

Link to this sectionالتصدير إلى NCNN#

from ultralytics.utils.export import torch2ncnn

torch2ncnn(model, im, output_dir="resnet18_ncnn_model")

يحتوي الدليل على ملفات param و bin ذات أسماء ثابتة بالإضافة إلى غلاف Python:

resnet18_ncnn_model/
├── model.ncnn.param
├── model.ncnn.bin
└── model_ncnn.py

تتحقق torch2ncnn() من وجود ncnn و pnnx عند الاستخدام لأول مرة.

Link to this sectionالتصدير إلى MNN#

يتطلب تصدير MNN ملف ONNX كإدخال. قم بالتصدير إلى ONNX أولاً، ثم التحويل:

from ultralytics.utils.export import onnx2mnn, torch2onnx

torch2onnx(model, im, output_file="resnet18.onnx")
onnx2mnn("resnet18.onnx", output_file="resnet18.mnn")

يدعم half=True لـ FP16 و int8=True لتكميم INT8. يتطلب MNN>=2.9.6 و torch>=1.10.

Link to this sectionالتصدير إلى PaddlePaddle#

from ultralytics.utils.export import torch2paddle

torch2paddle(model, im, output_dir="resnet18_paddle_model")

يحتوي الدليل على نموذج PaddlePaddle وملفات المعلمات:

resnet18_paddle_model/
├── model.pdmodel
└── model.pdiparams

يتطلب x2paddle وتوزيع PaddlePaddle الصحيح لمنصتك:

• paddlepaddle-gpu>=3.0.0,<3.3.0 على CUDA
• paddlepaddle==3.0.0 على ARM64 CPU
• paddlepaddle>=3.0.0,<3.3.0 على CPUs الأخرى

غير مدعوم على NVIDIA Jetson.

Link to this sectionالتصدير إلى ExecuTorch#

from ultralytics.utils.export import torch2executorch

torch2executorch(model, im, output_dir="resnet18_executorch_model")

يتم حفظ ملف .pte المُصدَّر داخل دليل المخرجات:

resnet18_executorch_model/
└── model.pte

يتطلب torch>=2.9.0 وبيئة تشغيل ExecuTorch متوافقة (pip install executorch). لاستخدام وقت التشغيل، راجع تكامل ExecuTorch.

Link to this sectionتحقق من نموذجك المُصدَّر#

بعد التصدير، تحقق من التكافؤ العددي مع نموذج PyTorch الأصلي قبل النشر. يقوم اختبار سريع باستخدام ONNXBackend من ultralytics.nn.backends بمقارنة المخرجات وتحديد أخطاء التتبع أو التكميم في وقت مبكر:

import numpy as np
import timm
import torch

from ultralytics.nn.backends import ONNXBackend

model = timm.create_model("resnet18", pretrained=True).eval()
im = torch.randn(1, 3, 224, 224)
with torch.no_grad():
    pytorch_output = model(im).numpy()

onnx_model = ONNXBackend("resnet18.onnx", device=torch.device("cpu"))
onnx_output = onnx_model(im)[0]

diff = np.abs(pytorch_output - onnx_output).max()
print(f"Max difference: {diff:.6f}")  # should be < 1e-5

بالنسبة لأوقات التشغيل الأخرى، قد يختلف اسم مصفوفة الإدخال. على سبيل المثال، يستخدم OpenVINO اسم وسيط التمرير للنموذج (عادةً x للنماذج العامة)، بينما يستخدم torch2onnx القيمة الافتراضية "images".

Link to this sectionالقيود المعروفة#

• دعم المدخلات المتعددة غير متساوٍ: تقبل torch2onnx وtorch2openvino صفاً أو قائمة من مصفوفات الأمثلة للنماذج ذات المدخلات المتعددة. بينما تفترض torch2torchscript وtorch2coreml وtorch2ncnn وtorch2paddle وtorch2executorch وجود مصفوفة إدخال واحدة.
• ExecuTorch يحتاج إلى flatc: تتطلب بيئة تشغيل ExecuTorch مترجم FlatBuffers. قم بالتثبيت باستخدام brew install flatbuffers على macOS أو apt install flatbuffers-compiler على Ubuntu.
• لا يوجد استنتاج عبر Ultralytics: لا يمكن تحميل النماذج غير التابعة لـ YOLO التي تم تصديرها مرة أخرى عبر YOLO() للاستنتاج. استخدم وقت التشغيل الأصلي لكل تنسيق (ONNX Runtime، OpenVINO Runtime، إلخ).
• تنسيقات YOLO فقط: تتطلب تصديرات Axelera وSony IMX500 سمات نموذج خاصة بـ YOLO وغير متاحة للنماذج العامة.
• تنسيقات خاصة بالمنصة: يتطلب TensorRT وجود وحدة معالجة رسومات NVIDIA. يتطلب RKNN حزمة SDK rknn-toolkit2 (لنظام Linux فقط). يتطلب Edge TPU ثنائي edgetpu_compiler (لنظام Linux فقط).

Link to this sectionالأسئلة الشائعة#

Link to this sectionما هي النماذج التي يمكنني تصديرها باستخدام Ultralytics؟#

أي torch.nn.Module. وهذا يشمل النماذج من timm أو torchvision أو أي نموذج PyTorch مخصص. يجب أن يكون النموذج في وضع التقييم (model.eval()) قبل التصدير. بالإضافة إلى ذلك، تقبل ONNX وOpenVINO صفاً من مصفوفات الأمثلة للنماذج ذات المدخلات المتعددة.

Link to this sectionأي تنسيقات التصدير تعمل بدون وحدة معالجة رسومات (GPU)؟#

جميع التنسيقات المدعومة (TorchScript، ONNX، OpenVINO، CoreML، TF SavedModel، TF Frozen Graph، NCNN، PaddlePaddle، MNN، ExecuTorch) يمكن تصديرها على وحدة المعالجة المركزية (CPU). لا يلزم وجود وحدة معالجة رسومات لعملية التصدير نفسها. TensorRT هو التنسيق الوحيد الذي يتطلب وحدة معالجة رسومات NVIDIA.

Link to this sectionما هو إصدار Ultralytics الذي أحتاجه؟#

استخدم Ultralytics >=8.4.38، والذي يتضمن وحدة ultralytics.utils.export والوسيطات القياسية output_file/output_dir.

Link to this sectionهل يمكنني تصدير نموذج torchvision إلى CoreML للنشر على iOS؟#

نعم. يتم تصدير نماذج التصنيف والكشف والتقسيم في torchvision إلى .mlpackage عبر torch2coreml. بالنسبة لنماذج تصنيف الصور، قم بتمرير قائمة بأسماء الفئات إلى classifier_names لإدراج رأس تصنيف. قم بتشغيل التصدير على macOS أو Linux. CoreML غير مدعوم على Windows. راجع تكامل CoreML للحصول على تفاصيل النشر على iOS.

Link to this sectionهل يمكنني تكميم النموذج المُصدَّر الخاص بي إلى INT8 أو FP16؟#

نعم، للعديد من التنسيقات. قم بتمرير half=True لـ FP16 أو int8=True لـ INT8 عند التصدير إلى OpenVINO أو CoreML أو MNN أو NCNN. يتطلب INT8 في OpenVINO بالإضافة إلى ذلك وسيط calibration_dataset لـ تكميم ما بعد التدريب. راجع صفحة تكامل كل تنسيق لمعرفة مقايضات التكميم.