ابدأ

تصدير Qualcomm QNN

Qualcomm AI Engine Direct، المعروف أيضًا باسم QNN، هو بيئة تشغيل Qualcomm لوحدة Hexagon NPU في معالجات Snapdragon وDragonwing. يؤدي تصدير نموذج Ultralytics YOLO26 باستخدام format="qnn" إلى إنشاء yolo26n_qnn.onnx، وهو نموذج ONNX لا تحتوي عقدته الوحيدة إلا على سياق QNN ثنائي، جُمّع باستخدام أوزان INT8 وتفعيلات 16-بت للجيل الذي تحدده من Hexagon Tensor Processor (HTP) باستخدام الوسيطة name. يعمل التصدير باستخدام ONNX Runtime على حاسوبك، ولا يتطلب حسابًا أو جهازًا من Qualcomm.

لمحة سريعة#

الخاصيةالتفاصيل
وسيطة formatqnn
المخرجاتyolo26n_qnn.onnx، ملف ONNX واحد بعقدة EPContext تضمّن ثنائية سياق QNN المترجمة، وأسماء الفئات والمهمة وحجم الصورة بوصفها بيانات وصفية
يعمل علىوحدات NPU من Hexagon التابعة لأجيال HTP المحددة باستخدام name: هواتف Snapdragon من Snapdragon 888 إلى 8 Elite Gen 5، وحواسيب Snapdragon X Elite المحمولة، وDragonwing IQ-8275؛ راجع أهداف HTP المدعومة
بيئة التشغيلONNX Runtime مع موفّر تنفيذ QNN: حزمة Python‏ onnxruntime-qnn على Windows وLinux، أو ONNX Runtime مع QNN في تطبيق Android
الدقةW8A16 فقط: أوزان INT8 وتنشيطات 16 بت، مع معايرتها باستخدام صور من data. حجم YOLO26n هو 3.6 MB
جهاز التصديرLinux بنظام x86-64 أو ARM64، أو Windows بنظام x64 أو ARM64، مع Python 3.11 أو أحدث. لا يدعم macOS. اختُبر على Ubuntu 24.04 بنظام x86-64. تُجرى عملية التصدير على CPU ولا تحتاج إلى GPU أو جهاز Snapdragon
التصدير عبر السحابة

يمكن لـ منصة Ultralytics تصدير نموذج مدرّب إلى QNN للهدف HTP الذي تحدده، لذا لا تحتاج إلى بيئة تصدير محلية.

البدء السريع#

ثبّت حزمة Ultralytics مع تبعيات تصدير ONNX وموفّر تنفيذ QNN:

pip install "ultralytics[export-base]" onnxruntime-qnn

توفّر onnxruntime-qnn مكتبات Qualcomm AI Runtime (QAIRT) وتُثبّت بجوار onnxruntime، الذي تتطلبه. عند استخدام pip install ultralytics عادي، تثبّت عملية التصدير الأولى onnx وonnxslim وonnxruntime وonnxruntime-qnn تلقائيًا، وتسجّل Restart runtime or rerun command for updates to take effect، وتكتمل مع ذلك في التشغيل نفسه. تتطلب عملية التصدير الإصدارات التالية:

المتطلبالإصدار
Pythonمن 3.11 إلى 3.14، وهي الإصدارات التي تتوفر لها حزم onnxruntime-qnn 2.x. نُفّذت عمليات التصدير باستخدام Python 3.11 و3.12 و3.14
نظام التشغيلLinux بنظام x86-64 مع glibc 2.35 أو أحدث، وLinux بنظام ARM64 مع glibc 2.34 أو أحدث، وWindows بنظام x64 أو ARM64. لا تتوفر حزم onnxruntime-qnn لنظام macOS؛ راجع القيود
onnxruntime-qnnالإصدار 2.8.0 لكل عملية تصدير في هذه الصفحة، مع onnxruntime 1.32.0. لا تثبّت Ultralytics إصدارًا محددًا

للاطلاع على طرق التثبيت الأخرى، راجع دليل التثبيت. ثم صدّر نموذجك:

التصدير
from ultralytics import YOLO

# ⁨تحميل نموذج YOLO26⁩
model = YOLO("yolo26n.pt")

# ⁨# صدّر النموذج إلى تنسيق QNN لجهاز Snapdragon 8 Elite Gen 5 ‏(HTP v81)⁩
model.export(format="qnn", name="81", imgsz=640)  # ⁨# ينشئ 'yolo26n_qnn.onnx'⁩

تكتب عملية التصدير yolo26n_qnn.onnx بجوار yolo26n.pt، وتفشل إذا كان الملف موجودًا بالفعل؛ لذا احذفه أو أعد تسميته قبل التصدير مجددًا. في غياب data، تُجري المعايرة على مجموعة البيانات الافتراضية الصغيرة للمهمة، مثل الصور الأربع في coco8.yaml، وهي كافية لاختبار التصدير؛ عاير باستخدام صور من بيانات النشر قبل شحن النموذج، وراجع المعايرة.

بعد ذلك، انسخ yolo26n_qnn.onnx إلى جهاز Snapdragon؛ راجع النشر. يعمل كل من Predict وValidate أيضًا، ببطء، على مضيف التصدير Linux بنظام x86-64، لتتمكن من فحص الملف المُصدّر قبل نسخه. شغّل كلًا منهما في عملية Python جديدة، لأن تشغيل نموذج QNN ثانٍ في عملية واحدة يفشل؛ راجع القيود:

التنبؤ
from ultralytics import YOLO

# ⁨# حمّل نموذج QNN المُصدّر⁩
model = YOLO("yolo26n_qnn.onnx")

# ⁨تنفيذ الاستدلال⁩
results = model("https://ultralytics.com/images/bus.jpg")
تحقّق
from ultralytics import YOLO

# ⁨# حمّل نموذج QNN المُصدّر⁩
model = YOLO("yolo26n_qnn.onnx")

# ⁨# التحقق من الدقة على مجموعة بيانات COCO8⁩
metrics = model.val(data="coco8.yaml")

المهام المدعومة#

يدعم تصدير QNN مهام Ultralytics السبع كلها: الكشف، وتجزئة الصور، والتجزئة الدلالية، وتقدير العمق، والتصنيف، وتقدير الوضعية، وOBB. لا يتوفر كل من التجزئة الدلالية وتقدير العمق إلا مع YOLO26، وهي عائلة النماذج الوحيدة التي تتضمن رأسي الإخراج هذين. صُدّر فحص YOLO26n لكل مهمة وشُغّل على مضيف التصدير، وكذلك نموذج كشف YOLO11. لم تُختبر عائلات النماذج الأخرى.

وسيطات التصدير#

المعاملالنوعالافتراضيالوصف
formatstr'qnn'التنسيق المستهدف للنموذج المُصدَّر، ويحدد مدى توافقه مع بيئات النشر المختلفة.
namestr'73'جيل HTP أو SoC الذي تُترجم ثنائية السياق من أجله، مثل '81' أو 'iq-8275'. راجع أهداف HTP المدعومة.
imgszint أو tuple640حجم صورة إدخال النموذج، وهو ثابت في ثنائية السياق: عدد صحيح للصور المربعة أو مجموعة (height, width). إذا لم تحدده، تستخدم عملية التصدير الحجم الذي دُرّب عليه الفحص، مثل 1024 لـ OBB و224 للتصنيف.
quantizeint أو strNoneالدقة. عند عدم التحديد أو استخدام 'w8a16'، تُبنى الدقة الوحيدة المتاحة، وهي أوزان INT8 وتنشيطات 16 بت؛ أما 8 و16 و32 فتؤدي إلى خطأ؛ راجع الدقة. يحل هذا الخيار محل علامتي half/int8 المهملتين.
datastrNoneملف YAML لمجموعة البيانات التي تضم صور المعايرة؛ أما التصنيف فيتطلب دليل مجموعة بيانات أو اسم مجموعة بيانات مضمّنة. تستخدم المعايرة تقسيم val ما لم يُحدّد split. وإذا لم يُحدّد، تستخدم Ultralytics مجموعة البيانات الافتراضية الصغيرة للمهمة، مثل coco8.yaml.
fractionfloat أو int أو list1.0مجموعة المعايرة الفرعية: نسبة أو عدد صور (الأعداد الصحيحة الأكبر من 1) أو قائمة [train, val, test]، ويُستخدم منها الإدخال الخاص بقسم المعايرة.
batchint1حجم الدفعة للنموذج المُصدَّر، وهو ثابت في شكل الإدخال. وهو أيضًا حجم الدفعة المستخدم للمعايرة.
nmsbool، اختياريNoneلا تأثير له: تكتب جميع القيم المخرجات الخام لـ None؛ راجع تنسيق المخرجات.
opsetintNoneإصدار ONNX opset للرسم البياني الوسيط لـ ONNX. عند عدم تحديده، يُستخدم أعلى opset يدعمه إصدار PyTorch لديك حتى 18، وهو 18 مع PyTorch 2.4 أو أحدث. ترفع أداة تكميم ONNX Runtime الإصدار إلى 21 لدعم التنشيطات ذات 16 بت.
simplifyboolTrueيبسّط رسم ONNX الوسيط باستخدام onnxslim.
devicestrNoneالجهاز المستخدم لتتبّع الرسم البياني الوسيط لـ ONNX، وهو cpu افتراضيًا.

للاطلاع على الوسيطات المشتركة بين جميع التنسيقات، راجع وثائق وضع التصدير.

حجم الصورة في نماذج الأجهزة المحمولة الرسمية

صُدّرت نماذج الأجهزة المحمولة الرسمية QNN وLiteRT وCore ML بالحجم imgsz=640، وبالحجم imgsz=224 للتصنيف. تُصدّر فحوص Cityscapes للتجزئة الدلالية والعمق وOBB افتراضيًا بحجم أكبر؛ لذا مرّر imgsz=640 لمطابقتها. تتوفر نماذج QNN للمهام السبع كلها وبجميع الأحجام، لكل من HTP v73 وv81، ضمن إصدار v0.7.0 من yolo-flutter-app.

أهداف HTP المدعومة#

تُترجم ثنائية السياق لجيل HTP واحد، لذا صدّر باستخدام name الخاص بجهازك. يسرد ملف README الخاص بإضافة Flutter جهاز Snapdragon 8 Gen 2 أو أحدث بوصفه متطلبًا لنماذج _v73 الرسمية؛ ولم تُختبر تركيبات أجيال التصدير والأجهزة الأخرى. يقبل name اسم الجيل مع بادئة v أو من دونها، مثل 81 أو v81 أو V81، أو أحد اسمي SoC، بأي حالة أحرف. الأحجام التالية تخص كشف YOLO26n عند imgsz=640:

nameHexagon HTPأمثلة على الأجهزةخيار ONNX Runtimeملف YOLO26n
68v68Snapdragon 888htp_arch=683.7 MB
69v69Snapdragon 8 Gen 1htp_arch=693.8 MB
73 (افتراضي)v73Snapdragon 8 Gen 2، Snapdragon X Elitehtp_arch=733.6 MB
75v75Snapdragon 8 Gen 3htp_arch=753.6 MB
79v79Snapdragon 8 Elite (SM8750)soc_model=693.6 MB
81v81Snapdragon 8 Elite Gen 5htp_arch=813.6 MB
iq-8275v75Dragonwing IQ-8275soc_model=823.5 MB
qcs8275v75Dragonwing QCS8275soc_model=823.5 MB

أجهزة Snapdragon أمثلة على كل جيل وليست قائمة شاملة. في غياب name، تسجّل عملية التصدير Qualcomm QNN export requires a missing 'name' arg for the target Hexagon HTP architecture. Using default name='73' (Snapdragon 8 Gen 2).. وتؤدي أي قيمة أخرى إلى فشل مع Invalid Qualcomm QNN target '66'. Valid targets are ('68', '69', '73', '75', '79', '81', 'iq-8275', 'qcs8275').. يحتوي Dragonwing IQ-615 (QCS615) على DSP من نوع Hexagon v66، ولا يتوفر له هدف QNN في Ultralytics؛ لذا صدّر نموذج ONNX عاديًا لاستخدام CPU أو GPU.

التصدير إلى Dragonwing IQ-8275
from ultralytics import YOLO

model = YOLO("yolo26n.pt")
model.export(format="qnn", name="iq-8275", imgsz=640)  # ⁨# ينشئ 'yolo26n_qnn.onnx'⁩

الدقة#

تُكمَّم كل عملية تصدير QNN باستخدام مسار QNN QDQ في ONNX Runtime إلى أوزان INT8 وتنشيطات 16 بت (W8A16). لا يتوفر تصدير FP32 أو FP16، ولا تصدير INT8 بتنشيطات 8 بت:

quantizeالنتيجة
غير محدد أو 'w8a16'ثنائية سياق W8A16. حجم YOLO26n هو 3.6 MB. في غياب quantize، تسجّل عملية التصدير qnn export requires INT8 quantization, enabling it.
8يفشل باستخدام quantize=8 (INT8) is not supported; format='qnn' supports quantize='w8a16' (INT8 weights + INT16 activations).
16يفشل باستخدام quantize=16 (FP16) is not supported; format='qnn' supports quantize='w8a16' (INT8 weights + INT16 activations).
32يفشل باستخدام quantize=32 (FP32) is not supported; format='qnn' supports quantize='w8a16' (INT8 weights + INT16 activations).

يظل الإدخال والمخرجات من النوع float32، باستثناء خريطة الفئات الدلالية، لأن تكميم الإدخال وإزالة تكميم المخرجات يجريان داخل ثنائية السياق.

المعايرة#

تعاير عملية التصدير نطاقات التنشيط على كل دفعة كاملة من تقسيم val في data، أو من التقسيم الذي تحدده باستخدام split، وتُصدر تحذيرًا >300 images recommended for INT8 calibration, found 4 images. عند وجود أقل من 300 صورة. مرّر data مع صور تشبه بيانات النشر لديك، واستخدم fraction لتحديد عددها. عند الاستخدام الأول، ينزّل coco.yaml مجموعة بيانات COCO كاملة، بحجم يقارب 20 GB:

مثال
from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# ⁨عاير باستخدام 10% من صور التحقق في COCO (500 صورة)؛ واستبدل coco.yaml بمجموعة بياناتك الخاصة⁩
model.export(format="qnn", name="81", imgsz=640, data="coco.yaml", fraction=0.1)

على آخر 500 صورة من COCO val2017، التي لا تستخدمها المعايرة المذكورة أعلاه، حقق YOLO26n النتائج التالية في val على مضيف التصدير بنظام x86-64، مقارنةً بفحص PyTorch وتصدير ONNX بدقة FP32 على الصور نفسها:

النموذجmAPval 50-95mAPval 50
PyTorch42.157.1
ONNX FP3242.056.9
QNN، تمت معايرته باستخدام coco8.yaml (4 صور)38.954.6
QNN، تمت معايرته باستخدام coco.yaml مع fraction=0.1 (500 صورة)39.154.5

أدت المعايرة على 500 صورة من COCO بدلًا من الصور الأربع في coco8.yaml إلى رفع mAPval 50-95 بمقدار 0.2 نقطة وخفض mAPval 50 بمقدار 0.1 نقطة، وسجّل كلا نموذجي QNN نتائج تقل عن تصدير ONNX بدقة FP32 بمقدار 2.9 إلى 3.1 نقطة في mAPval 50-95. في مجموعات البيانات الافتراضية الصغيرة، كان فقدان تقدير العمق هو الأكبر: على صور التحقق الأربع في depth8.yaml، التي استُخدمت أيضًا للمعايرة، بلغ delta1 لنموذج QNN لتقدير العمق 56.0% مقابل 89.7% لتصدير ONNX بدقة FP32. تحقّق من النموذج المُصدّر باستخدام بياناتك قبل نشره.

تنسيق المخرجات#

تكتب عملية التصدير ملفًا واحدًا وتُبقي نموذج ONNX الوسيط بجانبه:

الملفالمحتويات
yolo26n_qnn.onnxنموذج ONNX بعقدة EPContext واحدة تضمّن ثنائية سياق QNN، وأسماء الفئات والمهمة وحجم الصورة وحجم الدفعة والخطوة ومُعاملات التصدير بوصفها بيانات وصفية في ONNX، تقرؤها Ultralytics عند تحميل النموذج
yolo26n.onnxالرسم البياني لـ ONNX بدقة FP32 الذي جرى تكميمه، مع الإدخال نفسه بترتيب القنوات أخيرًا. يحل محل تصدير yolo26n.onnx سابق للفحص نفسه في ذلك الدليل. لا يلزم للنشر: لا يستطيع YOLO() تشغيله ويفشل مع Got invalid dimensions for input: images

يستقبل النموذج إدخالًا واحدًا باسم images وبالشكل (batch, height, width, 3): ‏RGB، والقنوات أخيرًا (NHWC)، وfloat32، مع تحجيم القيم إلى 0-1. يختلف هذا عن الإدخال ذي القنوات أولًا في تصدير ONNX، ويطابق ترتيب إطارات الكاميرا وHTP. للمخرجات أشكال تصدير ONNX الافتراضي. الأشكال أدناه لفحوص YOLO26n عند imgsz=640، وهو حجم نماذج الأجهزة المحمولة الرسمية، وimgsz=224 للتصنيف، مع فحص Cityscapes‏ yolo26n-sem.pt للتجزئة الدلالية:

المهمةimgszالمخرجات
Detect640(1, 84, 8400)
Segment640(1, 116, 8400) و(1, 32, 160, 160)
دلالي640(1, 640, 640) وuint8، مؤشر الفئة لكل بكسل
العمق640(1, 1, 640, 640)، خريطة عمق
التصنيف224(1, 1000)، احتمالات الفئات
الوضعية640(1, 56, 8400)
OBB640(1, 20, 8400)
  • المخرجات الخام: لكل مرساة، مركز الصندوق x ومركزه y وعرضه وارتفاعه بوحدات بكسل الإدخال، ثم درجات الفئات، ثم قيم المهمة (32 معاملًا للقناع، أو 17 × 3 قيمة لنقاط المفتاح، أو زاوية OBB بالراديان). طبّق NMS بنفسك. راجع تنسيق مخرجات ONNX للاطلاع على تخطيط كل مهمة. لا تتوفر مخرجات بلا NMS أو مخرجات تتضمن NMS: يسجّل nms=False‏ This export format does not support end2end models, disabling the end2end branch.، ويسجّل nms=True‏ format=qnn does not support embedded NMS; using nms=None.، ويكتبان كلاهما هذه المخرجات الخام.
  • التجزئة الدلالية: المخرج هو فهرس الفئة لكل بكسل بصيغة uint8 (وint32 للنماذج التي تضم أكثر من 256 فئة)، ويُحتسب على NPU، وليس درجة لكل فئة.
  • التجزئة: يحتوي المخرج الثاني على نماذج أولية للقناع.
  • التخطيط نفسه كما في ONNX: لكل مهمة وعلى صورة واحدة، طابق شكل كل مخرج ونوعه في نماذج QNN مخرجات تصدير ONNX بدقة FP32 للفحص نفسه. بلغ الارتباط 0.999 أو أكثر للمخرج الأول في مهام الكشف والتجزئة والوضعية وOBB، و0.95 للنماذج الأولية لقناع التجزئة. اختلفت المخرجات الخام بدرجة أكبر في التصنيف (ارتباط 0.76) والتجزئة الدلالية (تطابق 69% من وحدات البكسل) وتقدير العمق (ارتباط 0.24). في val ضمن مجموعات البيانات الافتراضية الصغيرة، كان فقدان تقدير العمق هو الأكبر؛ راجع المعايرة.

يقرأ YOLO("yolo26n_qnn.onnx") التخطيط من بيانات ONNX الوصفية؛ لذا لا تحتاج إلى هذه التفاصيل إلا عند تشغيل النموذج في شيفرتك الخاصة. تشمل مفاتيح البيانات الوصفية names وtask وimgsz وstride وbatch وend2end وargs، وkpt_shape لنماذج الوضعية.

التشغيل باستخدام ONNX Runtime#

لتشغيل النموذج خارج حزمة Ultralytics، سجّل موفّر تنفيذ QNN الخاص بـ onnxruntime-qnn مع ONNX Runtime، وحدّد مسار مكتبة الواجهة الخلفية لـ HTP. يتطلب الإصدار onnxruntime-qnn 2.x، الذي يوفر الوحدة onnxruntime_qnn. نُفّذ هذا على مضيف التصدير بنظام x86-64 ولم يُشغّل على جهاز Snapdragon:

# ⁨# صدّر أولًا: yolo export model=yolo26n.pt format=qnn name=81 imgsz=640⁩
import ast

import numpy as np
import onnxruntime as ort
import onnxruntime_qnn as qnn_ep

ort.register_execution_provider_library("QNNExecutionProvider", qnn_ep.get_library_path())
devices = [d for d in ort.get_ep_devices() if d.ep_name == "QNNExecutionProvider"]
options = ort.SessionOptions()
options.add_provider_for_devices(devices, {"backend_path": qnn_ep.get_qnn_htp_path()})
session = ort.InferenceSession("yolo26n_qnn.onnx", sess_options=options)

image = np.zeros((1, 640, 640, 3), dtype=np.float32)  # ⁨# صورتك بعد إضافة الحواف: RGB، NHWC، 0-1⁩
output = session.run(None, {session.get_inputs()[0].name: image})[0]
assert output.shape == (1, 84, 8400), "export a detection model at imgsz=640"

names = ast.literal_eval(session.get_modelmeta().custom_metadata_map["names"])  # ⁨{0: 'شخص', 1: 'دراجة', ...}⁩

النشر#

على حاسوب محمول يعمل بنظام Windows على Snapdragon، أو لوحة Linux ARM64 يوفّر BSP الخاص بها بيئة تشغيل HTP (راجع لوحات Qualcomm Linux)، ثبّت الحزمة باستخدام pip install ultralytics onnxruntime-qnn وانسخ yolo26n_qnn.onnx إليها. يسجّل YOLO("yolo26n_qnn.onnx") بعد ذلك موفّر تنفيذ QNN ويشغّل ثنائية السياق بواجهة HTP الخلفية. لم تُشغّل عمليات التصدير المنفّذة باستخدام onnxruntime-qnn 2.8.0 لهذه الصفحة على جهاز Snapdragon؛ واستخدمت قياسات Windows عمليات تصدير v73 أقدم.

  • مطابقة HTP: صدّر باستخدام name الخاص بجيل HTP في جهازك.
  • تطبيقات Android: يسرد ملف README الخاص بـ إضافة Flutter الإعداد المستخدم لنماذج _qnn.onnx: حزمتا com.microsoft.onnxruntime1.29.0 وcom.qualcomm.qti2.51.0، وuseLegacyPackaging = true في packagingOptions.jniLibs، لأن محمّل Hexagon DSP يحتاج إلى ملفات .so فعلية. ويذكر أيضًا أن عمليات التصدير المنفّذة قبل Ultralytics 8.4.188 باستخدام onnxruntime-qnn 2.4 أو أحدث تفشل في التحميل هناك مع Input name not found. لم يُجرّب هذا الإعداد مع عمليات التصدير الواردة في هذه الصفحة.
  • NPU فقط: تعمل ثنائية السياق على HTP فقط في جهاز Snapdragon. لاستخدام GPU من Adreno أو CPU، صدّر نموذج LiteRT أو ONNX عاديًا بدلًا منه؛ تقارن قياسات Android بين LiteRT على CPU وGPU وQNN على NPU.
  • شكل إدخال ثابت: يعمل النموذج دائمًا باستخدام imgsz وbatch المحددين عند التصدير، واللذين تقرؤهما Ultralytics من بيانات ONNX الوصفية. يُتجاهل imgsz إذا مُرّر إلى predict أو val. تُضاف حشوة إلى الدفعات الأصغر، كما شغّل نموذج batch=2 تنبؤات على صورة واحدة وثلاث صور.
  • نموذج QNN واحد لكل عملية: حمّل نموذج QNN ثانيًا، أو شغّل val بعد predict، في عملية Python جديدة؛ راجع القيود.
  • اسم الملف: أبقِ _qnn.onnx في نهاية اسم الملف، لأن Ultralytics تتعرّف على التنسيق من خلاله. يُحمّل الملف المنسوخ باسم yolo26n_npu.onnx كنموذج ONNX عادي ويفشل مع EPContext node generated by 'QNNExecutionProvider' is not compatible with any execution provider added to the session.

إضافة Ultralytics Flutter#

تشغّل إضافة Ultralytics YOLO لـ Flutter عمليات تصدير QNN لمهام YOLO26 السبع كلها على Android، للاستدلال الفوري عبر الكاميرا والتنبؤ بصورة واحدة. دعم QNN اختياري: فعّل بيئة تشغيل QNN وأضف تبعية ONNX Runtime الخاصة بها كما هو موضّح في ملف README للإضافة. أُجريت قياسات Android الواردة في هذه الصفحة باستخدامها. لنظام iOS، راجع SDK Ultralytics لنظام iOS وتكامل Core ML.

لوحات Qualcomm Linux#

على لوحة Dragonwing مثل IQ-8275، التي تعمل بنظام Qualcomm Linux أو BSP من Yocto، تأتي بيئة التشغيل من BSP المزوّد من الشركة المصنّعة للوحة والمفعّل لـ QAIRT، ولا تُضمّن في النموذج المُصدّر. لاستدلال HTP، يجب أن يوفر BSP موفّر تنفيذ ONNX Runtime QNN وlibQnnSystem.so وlibQnnHtp.so ومكتبات HTP stub وskeleton الخاصة بجيل HTP في اللوحة (v75 لـ IQ-8275) ودعم FastRPC في مساحة المستخدم مثل libcdsprpc.so وبرنامج DSP الثابت ومشغّلات FastRPC المتوافقة مع النواة. يجب أن تكون مكتبة skeleton في مسار مكتبات DSP الخاص بـ BSP. يتطلب تنفيذ GPU استخدام libQnnGpu.so ومشغّل Adreno في مساحة المستخدم بدلًا من ذلك، مع تصدير ONNX عادي، لأن ملفات _qnn.onnx تستهدف HTP.

أدلة النشر#

القيود واستكشاف الأخطاء وإصلاحها#

  • macOS وPython 3.10: تتوفر حزم onnxruntime-qnn 2.x فقط لـ Python من 3.11 إلى 3.14 على Linux وWindows. على macOS وعلى Linux مع Python 3.10، يفشل تثبيت onnxruntime-qnn (يبلّغ pip عن No matching distribution found for onnxruntime-qnn)، ثم تتابع عملية التصدير وتكمّم النموذج قبل أن تفشل مع Failed to load library .../onnxruntime/capi/libonnxruntime_providers_qnn.so. على Windows x64 مع Python 3.10، يثبّت pip الإصدار الأقدم onnxruntime-qnn 1.23.2 بدلًا منه، ولم يُختبر هذا الإصدار. صدّر على Linux أو Windows باستخدام Python 3.11 أو أحدث، أو عبر منصة Ultralytics.
  • تعطيل التثبيت التلقائي: عند استخدام YOLO_AUTOINSTALL=false من دون onnxruntime-qnn، تسجّل عملية التصدير Ultralytics requirement ['onnxruntime-qnn'] not found, AutoUpdate disabled by YOLO_AUTOINSTALL=False وتفشل مع الخطأ نفسه Failed to load library. ثبّته كما هو موضّح في دليل البدء السريع.
  • ملف إخراج موجود: تكتب عملية التصدير yolo26n_qnn.onnx بجوار ملف .pt، ولا تستبدله ONNX Runtime: إذا كان الملف موجودًا، تفشل عملية التصدير مع Failed to generate EP context model since the file '"yolo26n_qnn.onnx"' exists already. Please remove the EP context model if you want to re-generate it.، وقد تنتهي عملية Python بعد ذلك بخطأ تجزئة. احذف الملف السابق أو أعد تسميته قبل التصدير مجددًا، حتى عند استخدام name أو imgsz أو data مختلف.
  • نموذج QNN ثانٍ في عملية واحدة: يفشل تحميل نموذج _qnn.onnx ثانٍ، أو تشغيل val أو عملية تصدير بعد predict مع نموذج QNN، مع الخطأ EP library is already registered under QNNExecutionProvider. ينجح تنفيذ التنبؤ عدة مرات باستخدام كائن YOLO نفسه، وكذلك ينجح predict مباشرة بعد التصدير. استخدم عملية Python جديدة لكل نموذج، كما تفعل واجهة CLI‏ yolo.
  • شكل إدخال ثابت: يفشل dynamic=True مع argument 'dynamic' is not supported for format='qnn'. أعد التصدير لتغيير حجم الصورة أو حجم الدفعة.
  • المعايرة من دون data: تسجّل عملية التصدير INT8 export requires a missing 'data' arg for calibration. Using default 'data=coco8.yaml'. وتجري المعايرة على مجموعة البيانات الافتراضية الصغيرة للمهمة. مرّر data مع صور تمثّل بيانات النشر لديك.
  • تحذير opset: ما لم تمرّر opset=21، تسجّل أداة تكميم ONNX Runtime‏ The original model opset version is 18, which does not support 16-bit integer quantization natively. Please update the model to opset >= 21. Automatically update the model to opset 21. Please verify the quantized model.، مع وضع opset الخاص بتصديرك بدلًا من 18، وترفع الرسم البياني إلى opset 21. تتابع عملية التصدير ولا يلزم اتخاذ أي إجراء.
  • الفحوص المدرّبة باستخدام quantize=8: يفشل فحص ضُبط باستخدام التدريب الواعي بالتكميم مع format='qnn' cannot export a QAT model: its Q/DQ ranges are only read by the 'onnx' and 'engine' backends. صدّر الفحص الذي بدأت منه الضبط بدلًا منه.
  • الاستدلال على مضيف التصدير: على Linux بنظام x86-64، شغّل onnxruntime-qnn ثنائيتي السياق name=73 وname=81 على CPU، بزمن يقارب 0.3 ثانية (للتصنيف) إلى 16 ثانية (للعمق) لكل صورة لـ YOLO26n على CPU خادم مزدحم، مقارنةً ببضعة أجزاء من الثانية على الهاتف. استخدمه لفحص التصدير، لا لقياس سرعته.

للاطلاع على الأخطاء الأخرى، راجع دليل المشكلات الشائعة.

الأداء المقاس#

تعرض الجداول أدناه زمن استجابة صورة واحدة على جهازي Snapdragon، مقاسًا باستخدام نماذج HTP v81 المنشورة v0.7.0 (Android) وعمليات تصدير HTP v73 الأقدم (Windows)، وحجم عمليات التصدير المُنشأة على خادم Linux بنظام x86-64 لهذه الصفحة. تعرض كل خلية لزمن الاستجابة الزمن الإجمالي بالمللي ثانية، مع تقسيم المعالجة المسبقة / الاستدلال / المعالجة اللاحقة أسفلها، ويظهر عمود النموذج الأسرع بالخط العريض. تعرض صفحة نموذج YOLO26 دقة فحوص PyTorch.

هاتف Android#

الأجهزة: Xiaomi 17 بذاكرة LPDDR5X سعتها 12 GB ونظام Android 17 / API 37. يحتوي معالجه Snapdragon 8 Elite Gen 5 بدقة تصنيع 3 nm (SM8850) على CPU‏ Qualcomm Oryon بثماني نوى (نواتا Prime بتردد يصل إلى 4.6 GHz و6 نوى Performance بتردد يصل إلى 3.62 GHz) وGPU من Adreno وNPU من Hexagon (HTP v81).

النموذجالمهمةالحجم
(بكسل)
CPU
w8a32 LiteRT
(مللي ثانية)
GPU
w8a32 LiteRT
(مللي ثانية)
NPU
QNN W8A16
(ms)
YOLO26nDetect64036.9
1.9 / 32.6 / 2.3
10.6
1.8 / 6.2 / 2.6
10.2
1.9 / 6.0 / 2.3
YOLO26n-segSegment64050.5
1.9 / 42.9 / 5.8
18.0
1.9 / 9.5 / 6.6
16.2
2.1 / 8.4 / 5.7
YOLO26n-semدلالي64045.7
1.9 / 35.7 / 8.2
30.6
1.9 / 20.5 / 8.3
10.8
2.0 / 6.2 / 2.6
YOLO26n-depthالعمق64066.8
2.2 / 55.0 / 9.7
21.9
2.1 / 10.1 / 9.8
19.3
2.2 / 7.4 / 9.7
YOLO26n-clsالتصنيف2243.6
0.3 / 3.3 / 0.0
2.0
0.4 / 1.4 / 0.2
0.8
0.3 / 0.5 / 0.0
YOLO26n-poseالوضعية64039.9
2.0 / 36.5 / 1.4
10.0
1.8 / 6.7 / 1.4
9.7
1.9 / 5.9 / 1.8
YOLO26n-obbOBB64036.3
2.0 / 33.2 / 1.2
10.1
2.6 / 5.9 / 1.6
8.1
1.9 / 5.1 / 1.0
  • قيم السرعة هي أزمنة استجابة للدفعات على صورة واحدة: متوسط 15 تشغيلًا بعد 3 عمليات إحماء على bus.jpg، مقاسًا باستخدام أداة قياس الأداء على الجهاز 0.7.1 الخاصة بـإضافة Flutter وأصول v0.7.0 الرسمية (عمليات تصدير Ultralytics 8.4.188). تناوب ترتيب الواجهات الخلفية بين المهام في جولة تسلسلية واحدة. أكدت السجلات الأصلية أن كل صف CPU استخدم LiteRT CPU/XNNPACK، وأن كل صف GPU فوّض الرسم البياني كاملًا إلى LiteRT OpenCL‏ (LITERT_CL)، وأن كل صف NPU استخدم واجهة QNN الخلفية لـ Hexagon HTP.
  • يمثل عمودا CPU وGPU نماذج LiteRT‏ w8a32 من الإصدار نفسه (LiteRT]، لذا يقارن الجدول NPU بالمعالجات الأخرى في الهاتف نفسه.
  • يتوفر سجل قياس الأداء التفصيلي في وثيقة أداء Flutter.
  • قارن أجهزة Android الأخرى في تكامل LiteRT، بما في ذلك دليل MediaTek Dimensity، وأجهزة Apple في تكامل Core ML.

حاسوب محمول بنظام Windows على Snapdragon#

الأجهزة: حاسوب Lenovo محمول بذاكرة 32 GB ونظام Windows 11. يحتوي Snapdragon X Elite (X1E78100) على CPU‏ Qualcomm Oryon باثنتي عشرة نواة وGPU من Adreno وNPU من Hexagon (HTP v73). لم يُسجّل طراز Lenovo المحدد.

تقارن هذه الجولة السابقة خط أساس CPU بدقة PyTorch FP32 بنماذج QNN على NPU من Hexagon. أُجريت باستخدام ultralytics 8.4.67 وonnxruntime-qnn 2.2.0 وtorch 2.10.0+cpu وPython 3.12.10، على نماذج v73 صُدّرت قبل اعتماد أحجام الأجهزة المحمولة 224/640 معيارًا؛ لذا عمل نموذجا التجزئة الدلالية وOBB عند 1024 بكسل، ولا يوجد صف للعمق. تعرض كل خلية الزمن الإجمالي الكامل لـ model.predict() مع تقسيم المعالجة المسبقة / الاستدلال / المعالجة اللاحقة المبلّغ عنه أسفلها؛ وقد يشمل الإجمالي النفقات العامة لإطار العمل خارج هذه المراحل الثلاث.

النموذجالمهمةالحجم
(بكسل)
CPU
PT FP32
(ms)
NPU Hexagon
QNN W8A16
(ms)
YOLO26nDetect64091.4
4.3 / 75.2 / 0.1
27.2
4.9 / 19.4 / 0.9
YOLO26n-segSegment640138.8
4.5 / 127.1 / 2.8
34.3
5.0 / 24.0 / 5.1
YOLO26n-semدلالي1024295.8
9.1 / 189.2 / 94.8
133.0
8.8 / 37.4 / 83.9
YOLO26n-clsالتصنيف22415.4
3.0 / 9.8 / 0.0
11.7
2.7 / 5.5 / 0.0
YOLO26n-poseالوضعية640109.6
4.6 / 102.9 / 0.2
28.9
5.3 / 23.3 / 0.6
YOLO26n-obbOBB1024267.8
8.1 / 254.6 / 0.1
64.8
8.9 / 54.7 / 0.6
  • قيم السرعة هي أزمنة استجابة للدفعات على صورة واحدة: متوسط 100 تشغيل بعد 10 عمليات إحماء على bus.jpg، مقاسًا باستخدام time.perf_counter() حول استدعاء model.predict() الكامل على جهاز استقر حراريًا.
  • كان NPU من Hexagon أسرع بمقدار 2.2 إلى 4.1 مرات من خط أساس CPU في PyTorch عند 640 و1024 بكسل، وأسرع بمقدار 1.3 مرة لمصنّف 224 بكسل، حيث يكون لزمن المعالجة المسبقة الثابت أثر أكبر.

حجم النموذج#

حجم نماذج كشف YOLO26 بالميغابايت (10^6 بايت)، بوصفها فحص PyTorch وملف _qnn.onnx لـ HTP v81 عند imgsz=640. تطبع سجلات التصدير الحجم بوحدة MiB، مثل (3.5 MB) لـ YOLO26n v81:

النموذجPyTorchQNN v81
YOLO26n5.53.6
YOLO26s20.411.1
YOLO26m44.322.8
YOLO26l53.227.9
YOLO26x118.760.6

صُدّرت باستخدام ultralytics 8.4.215 وonnxruntime-qnn 2.8.0 وonnxruntime 1.32.0 على خادم Linux بنظام x86-64 من دون أجهزة Snapdragon. يسرد قسم المعايرة دقة تصدير YOLO26n على COCO.

نبذة عن Qualcomm QNN#

Qualcomm QNN on-device inference

يشكّل Qualcomm AI Engine Direct (QNN) جزءًا من حزمة تطوير البرامج Qualcomm AI Runtime (QAIRT)، ويشغّل الشبكات العصبية على CPU وGPU من Adreno وNPU من Hexagon في معالجات Snapdragon وDragonwing عبر واجهة API واحدة ومكتبة واجهة خلفية لكل معالج. وهو يحل محل حزمة تطوير البرامج الأقدم Snapdragon Neural Processing Engine (SNPE). تستخدم Ultralytics واجهته الخلفية HTP عبر موفّر تنفيذ ONNX Runtime QNN. للاطلاع على المرجع الكامل، راجع مجموعة تطوير برامج Qualcomm AI Engine Direct.

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

  • لا. تُجرى عملية التصدير باستخدام حزمة onnxruntime-qnn من PyPI، التي تتضمن مكتبات QAIRT، ونُفّذت جميع عمليات التصدير المُدرجة في هذه الصفحة على خادم Linux بنظام x86-64 من دون حساب Qualcomm أو تنزيل SDK أو أجهزة Snapdragon. لا تحتاج إلى الجهاز إلا لتشغيل النموذج بسرعة NPU.

  • ‏Qualcomm AI Hub هي خدمة Qualcomm السحابية لتجميع النماذج وتنميط أدائها وقياسه على أجهزة Snapdragon المستضافة، وتتطلب حسابًا لدى Qualcomm. يجمّع تصدير Ultralytics ملفًا ثنائيًا لسياق QNN لـ Hexagon NPU نفسه على حاسوبك باستخدام استدعاء واحد لـ export(format="qnn")، من دون حساب أو رفع ملفات، ويمكنك قياس سرعته على جهازك.

التعليقات

اطرح سؤالًا، وشارك نتائجك، أو ساعد شخصًا آخر.