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

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

توفر Ultralytics أدوات تصدير مستقلة تغلّف واجهات خلفية متعددة ضمن واجهة واحدة متسقة. يمكنك تصدير أي 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 قياسياً وموتراً (tensor) كمدخل تجريبي. تمر ملفات MNN، وTF SavedModel، وTF Frozen Graph عبر وسيط ONNX أو Keras artifact. لا تتطلب أي سمات خاصة بـ 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 batch size)، مرر قاموس 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, classifier_names=None, 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 مجمد (frozen):

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
• paddlepaddle>=3.0.0,<3.3.0 على وحدات المعالجة المركزية الأخرى

غير مدعوم على 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

بالنسبة لبيئات التشغيل الأخرى، قد يختلف اسم مصفوفة الإدخال (input tensor). على سبيل المثال، يستخدم 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 حزمة rknn-toolkit2 SDK (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). لا يلزم وجود GPU لعملية التصدير نفسها. TensorRT هو التنسيق الوحيد الذي يتطلب GPU من 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 لـ تكميم ما بعد التدريب. راجع صفحة تكامل كل تنسيق لمعرفة مقايضات التكميم.