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

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

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

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

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

التثبيت#

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

# 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 --quantize 16

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

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

حمّل نموذجًا ونفّذ تنبؤًا. تُقرأ بيانات النموذج الوصفية، مثل أسماء الفئات ونوع المهمة وحجم الصورة، تلقائيًا من ملف 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, Quantization, YOLOModel};

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

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. تعمل أيضًا نماذج اكتشاف RT-DETR، لكنها لا تُنزَّل تلقائيًا: صدّر أحدها إلى ONNX أولًا.

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

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

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

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

# 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 واحدة مدمجة، ثم تمرّر الناتج إلى النموذج كموتر جهاز دون نسخ. يظل الإطار الخام ذو 8 بت يُرفع إلى GPU، عبر مخزن مرحلي مثبت في وحدات GPU المنفصلة؛ وتتمثل وظيفة النواة في الاستغناء عن تغيير الحجم والتطبيع وتحويل التخطيط على CPU، وعن الرفع المنفصل للموتر المعالَج مسبقًا، وهو ما يكتسب أهمية قصوى مع الدفعات ذات معدل الإنتاجية العالي وتدفقات الزمن الحقيقي.

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

يُستخدم المسار السريع تلقائيًا، دون تغيير في API، عند تحقق الشروط التالية كلها: تضمين الميزة في البناء، وأن يكون الجهاز CUDA أو TensorRT، وأن تكون المهمة detect أو segment أو pose أو 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.50", 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.

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