استدلال Ultralytics باستخدام Rust#

إن استدلال Ultralytics هو مكتبة استدلال عالية الأداء لـ YOLO وأداة لسطر الأوامر مكتوبة بلغة Rust. وتشغّل نماذج ONNX المُصدّرة عبر ONNX Runtime لتوفير تنبؤات سريعة وآمنة من ناحية الذاكرة على الصور ومقاطع الفيديو وكاميرات الويب والتدفقات، من دون الحاجة إلى بيئة تشغيل Python وقت الاستدلال.

يأتي المشروع في صورة crate واحدة هي ultralytics-inference، ويمكنك استخدامها بطريقتين: باعتبارها CLI للتنبؤات السريعة والمهام الدفعية، أو باعتبارها مكتبة مضمّنة مباشرةً في تطبيق Rust الخاص بك. وهي تدعم كل مهام Ultralytics ومجموعة واسعة من الواجهات الخلفية للأجهزة عبر واجهة موحّدة للأجهزة.

لماذا الاستدلال باستخدام Rust؟#

• سرعة أصلية وبصمة صغيرة. تُترجم إلى ملف ثنائي أصلي من دون مفسّر، ما يجعلها مثالية للخوادم والحاويات وأجهزة الحافة.
• أمان الذاكرة. يزيل نموذج الملكية في Rust فئات كاملة من أخطاء وقت التشغيل من دون جامع مهملات.
• جميع مهام YOLO. الكشف، والتقسيم، والتقسيم الدلالي، وتقدير العمق، والتصنيف، والوضعيات، وOBB من واجهة API واحدة.
• دعم واسع للأجهزة. تنفيذ على CPU، بالإضافة إلى CUDA وTensorRT وCoreML وOpenVINO وDirectML وROCm وXNNPACK، مع تحديد مزوّدي التنفيذ وقت البناء.
• المعالجة المسبقة على GPU. تحافظ نواة CUDA المدمجة الاختيارية على عمليات letterbox والتطبيع وتحويل التخطيط على الجهاز، لتوفير مسار إدخال من دون نسخ.
• التنزيل التلقائي. تُنزّل أسماء نماذج YOLO المعروفة والأصول النموذجية تلقائيًا عند أول استخدام.

التثبيت#

مطلوب Rust 1.89 أو إصدار أحدث. وتتطلب ميزة الفيديو أيضًا تثبيت FFmpeg 7+ على النظام.

# Install the command-line tool from crates.io
cargo install ultralytics-inference

# Or with GPU support compiled in
cargo install ultralytics-inference --features cuda,tensorrt

البدء السريع باستخدام CLI#

يعرّض CLI أمرًا فرعيًا هو predict. وعند تشغيله من دون وسيطات، ينزّل نموذج كشف nano وصورًا نموذجية، ويشغّل الاستدلال، ويحفظ النتائج المشروحة في runs/detect/predict.

# Detect on the built-in samples (downloads model and images)
ultralytics-inference predict

# Detect on your own image
ultralytics-inference predict --model yolo26n.onnx --source image.jpg

# Segmentation (auto-downloads yolo26n-seg.onnx)
ultralytics-inference predict --task segment --source image.jpg

# Pose on a video, shown live in a window
ultralytics-inference predict --task pose --source video.mp4 --show

# Depth estimation (auto-downloads yolo26n-depth.onnx)
ultralytics-inference predict --task depth --source image.jpg

# Tune thresholds and filter to specific classes
ultralytics-inference predict --source image.jpg --conf 0.5 --iou 0.45 --classes "0,1,2"

# Run a whole folder on the GPU in half precision
ultralytics-inference predict --source images/ --device cuda:0 --half

الخيارات الشائعة:

البدء السريع باستخدام المكتبة#

حمّل نموذجًا وشغّل تنبؤًا. تُقرأ بيانات تعريف النموذج، مثل أسماء الفئات ونوع المهمة وحجم الصورة، تلقائيًا من ملف ONNX.

use ultralytics_inference::YOLOModel;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Metadata (classes, task, imgsz) is parsed from the model.
    let mut model = YOLOModel::load("yolo26n.onnx")?;

    let results = model.predict("image.jpg")?;

    for result in &results {
        if let Some(boxes) = &result.boxes {
            for i in 0..boxes.len() {
                let class_id = boxes.cls()[i] as usize;
                let conf = boxes.conf()[i];
                let name = result.names.get(&class_id).map_or("unknown", |s| s.as_str());
                println!("{name} {conf:.2}");
            }
        }
    }

    Ok(())
}

استخدم InferenceConfig للتحكم في العتبات وحجم الصورة والدقة والجهاز باستخدام واجهة منشئ:

use ultralytics_inference::{Device, InferenceConfig, YOLOModel};

let config = InferenceConfig::new()
    .with_confidence(0.5)
    .with_iou(0.45)
    .with_imgsz(640, 640)
    .with_device(Device::Cuda(0))
    .with_half(true);

let mut model = YOLOModel::load_with_config("yolo26n.onnx", config)?;
let results = model.predict("image.jpg")?;

تملأ كل مهمة حقلًا مختلفًا في Results. كل علامة تبويب أدناه عبارة عن برنامج كامل قابل للتشغيل؛ ويُنزّل النموذج والمدخلات النموذجية تلقائيًا عند التشغيل الأول. استبدل predict_default() بـ predict("image.jpg") للتشغيل على ملفاتك الخاصة.

use ultralytics_inference::YOLOModel;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut model = YOLOModel::load("yolo26n.onnx")?;
    let results = model.predict_default()?;

    for result in &results {
        if let Some(boxes) = &result.boxes {
            println!("{} detections", boxes.len());
            let xyxy = boxes.xyxy(); // rows of [x1, y1, x2, y2]
            for i in 0..boxes.len() {
                let class_id = boxes.cls()[i] as usize;
                let name = result.names.get(&class_id).map_or("unknown", |s| s.as_str());
                println!("  {name} {:.2} {:?}", boxes.conf()[i], xyxy.row(i).to_vec());
            }
        }
    }

    Ok(())
}

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

تُدعَم جميع مهام Ultralytics. عند حذف --model، يُنزّل نموذج nano المطابق للمهمة المحددة تلقائيًا.

توافق النماذج#

يمكن تحميل أي نموذج من Ultralytics مُصدّر إلى ONNX من ملف محلي. ويتوفر التنزيل التلقائي لأسماء نماذج YOLO26 وYOLO11 وYOLOv8 القياسية بالأحجام n وs وm وl وx:

التقسيم الدلالي (-sem) وتقدير العمق (-depth) متاحان لنماذج YOLO26 فقط.

مصادر الإدخال#

تقبل الوسيطة --source (والنوع Source في المكتبة) أنواعًا عديدة من الإدخال، ويُكتشف نوعها تلقائيًا من السلسلة النصية:

الأجهزة ومزوّدو التنفيذ#

يعمل الاستدلال على CPU افتراضيًا. وتُضمّن الواجهات الخلفية لوحدات GPU والمسرّعات باعتبارها ميزات Cargo، ويُختار بينها وقت التشغيل باستخدام --device (CLI) أو Device (المكتبة).

# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrt

تسريع GPU والمعالجة المسبقة باستخدام CUDA#

على أجهزة NVIDIA، تفعّل ميزة cuda مزوّد تنفيذ CUDA، وتضيف tensorrt مزوّد TensorRT لمزيد من التحسين. ولتحقيق أقل زمن استجابة ممكن، تنقل ميزة cuda-preprocess المعالجة المسبقة إلى GPU.

تنفّذ cuda-preprocess تغيير حجم letterbox والتطبيع وتحويل التخطيط من HWC إلى CHW باعتبارها نواة CUDA مدمجة واحدة، ثم تمرّر النتيجة إلى النموذج باعتبارها موتر جهاز من دون نسخ. ويزيل ذلك تكلفة المعالجة المسبقة لكل صورة على CPU ونسخ المضيف إلى الجهاز، وهو أمر مهم خصوصًا للدفعات عالية الإنتاجية والتدفقات في الوقت الفعلي.

# Build with fused GPU preprocessing (implies cuda + tensorrt)
cargo build --release --features cuda-preprocess

يُستخدم المسار السريع تلقائيًا، من دون تغيير في API، عند تحقق جميع الشروط التالية: تكون الميزة مضمّنة، ويكون الجهاز CUDA أو TensorRT، وتكون المهمة كشفًا أو تقسيمًا أو وضعية أو OBB أو تقسيمًا دلاليًا أو تقديرًا للعمق، ويستخدم النموذج إدخال FP32. ويكون مفعّلًا افتراضيًا، ويمكن إيقافه لكل نموذج:

use ultralytics_inference::{Device, InferenceConfig};

let config = InferenceConfig::new()
    .with_device(Device::TensorRt(0))
    .with_cuda_preprocess(false); // force CPU preprocessing

ميزات Cargo#

تُفعّل الميزات وقت البناء. وتغطي الإعدادات الافتراضية التعليق التوضيحي والعرض المباشر.

تجمع المجموعات الملائمة مزوّدي التنفيذ ذوي الصلة: nvidia (cuda، tensorrt)، وamd (rocm، migraphx)، وintel (openvino، onednn)، وmobile (nnapi، coreml، qnn)، وall (annotate، visualize، video). كما تتوفر مزوّدات إضافية مثل nnapi وqnn وxnnpack وwebgpu وغيرها.

فعّل الميزات عند تثبيت CLI أو إضافة المكتبة:

cargo install ultralytics-inference --features video
cargo install ultralytics-inference --features cuda,tensorrt

[dependencies]
ultralytics-inference = { version = "0.0.35", features = ["video"] }

الإخراج والحفظ#

تُعلَّم التنبؤات وتحفظ افتراضيًا في دليل تشغيل يزداد رقمه تلقائيًا:

runs/
└── detect/
    └── predict/          # then predict2, predict3, ...
        └── image.jpg     # annotated result

يتطابق المجلد الفرعي مع المهمة (runs/segment/ وruns/pose/ وما إلى ذلك). بالنسبة إلى مصادر الفيديو، يُكتب الإخراج المُعلَّم كملف فيديو؛ مرّر --save-frames لكتابة الإطارات الفردية بدلًا من ذلك. بالنسبة إلى المهمة semantic، يكتب --save-json خرائط الفئات بصيغة PNG لكل بكسل ضمن مجلد فرعي باسم results/. وبالنسبة إلى المهمة depth، تُدمج خريطة العمق الملوّنة فوق الصورة المصدر، بما يطابق إخراج plot() في Ultralytics Python. يتطلب حفظ الصور والفيديو المُعلَّمين ميزة annotate؛ أما تصدير خرائط الفئات الدلالية بصيغة PNG فلا يتطلبها. يتطلب إدخال الفيديو وإخراجه ميزة video.

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