استدلال Ultralytics للغة Rust#

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

يتم توفير المشروع كوحدة برمجية (Crate) واحدة تُدعى ultralytics-inference، ويمكنك استخدامها بطريقتين: كأداة CLI للتنبؤات السريعة ووظائف الدُفعات، أو كمكتبة library مُدمجة مباشرة في تطبيق Rust الخاص بك. وهي تدعم جميع مهام Ultralytics ومجموعة واسعة من بنيات الأجهزة الأساسية من خلال واجهة أجهزة موحدة.

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

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

التثبيت#

مطلوب إصدار Rust 1.89 أو أحدث. تتطلب ميزة video أيضًا تثبيت 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. بدون معاملات، تقوم بتنزيل نموذج اكتشاف دقيق وصور عينة، وتشغيل الاستدلال، وحفظ النتائج المُعلّقة في 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 للتحكم في العتبات، وحجم الصورة، والدقة، والجهاز باستخدام واجهة برمجة البناء (builder API):

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، يتم تنزيل نموذج النانو المطابق للمهمة المحددة تلقائيًا.

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

يمكن تحميل أي نموذج 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)، التطبيع (normalization)، وتحويل تخطيط HWC إلى CHW كنواة CUDA مدمجة واحدة، ثم يغذي النتيجة إلى النموذج كـموجه جهاز خالي من النسخ (zero-copy device tensor). هذا يزيل تكلفة المعالجة المسبقة لوحدة المعالجة المركزية لكل صورة ونسخ البيانات من المضيف إلى الجهاز، وهو أمر بالغ الأهمية للدُفعات عالية الإنتاجية وتدفقات الوقت الفعلي.

# 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.33", features = ["video"] }

المخرجات والحفظ#

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

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

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

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

هل أحتاج إلى تثبيت Python؟#

لا. تشغل الوحدة البرمجية نماذج ONNX المُصدّرة مباشرة من خلال ONNX Runtime. تكون Python مطلوبة فقط إذا قمت بتدريب أو تصدير النماذج باستخدام حزمة Ultralytics مسبقًا.

ما هي النماذج التي يمكنني تشغيلها؟#

أي نموذج YOLO من Ultralytics مُصدّر إلى ONNX، بما في ذلك YOLO26، YOLO11، وYOLOv8. يتم تنزيل أسماء النماذج المعروفة تلقائيًا؛ يمكنك أيضًا توجيه --model إلى أي ملف .onnx محلي.

كيف أحصل على ملف نموذج؟#

قم بالتصدير من حزمة Python، على سبيل المثال باستخدام تكامل ONNX، أو دع أداة CLI تنزل نموذج نانو قياسي للمهمة المختارة عند التشغيل الأول.

هل يتم دعم الفيديو؟#

نعم، مع تمكين ميزة video وتثبيت FFmpeg 7+ على النظام. يغطي هذا ملفات الفيديو، وكاميرات الويب، وتدفقات RTSP/RTMP/HTTP.

ماذا تفعل ميزتا annotate وvisualize؟#

كلا الميزتين ممكّنتان افتراضيًا. تقوم annotate برسم الصناديق، والأقنعة، والنقاط الرئيسية، وتسميات الفئات على الصورة وهي مطلوبة لكي تتمكن --save من كتابة النتائج المُعلّقة. تفتح visualize نافذة حية لـ --show. بالنسبة لبناء أصغر بدون واجهة رسومية والذي يُرجع النتائج برمجياً فقط، قم بتعطيلها باستخدام cargo build --no-default-features (مع إعادة إضافة الميزات الفردية حسب الحاجة).

أين أجد مرجع API الكامل؟#

هذه الصفحة عبارة عن نظرة عامة عالية المستوى. يتم نشر مرجع واجهة برمجة التطبيقات الكامل، حسب النوع، لكل بنية عامة، وطريقة، وخيار تكوين على docs.rs، وتم إنشاؤه مباشرة من المصدر.