Link to this sectionاستدلال Ultralytics للغة Rust#

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

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

Link to this sectionلماذا الاستدلال باستخدام Rust؟#

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

Link to this sectionالتثبيت#

مطلوب 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

Link to this sectionالبدء السريع لـ 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

# Depth with the DepthAnything-style palette (disparity is already the default)
ultralytics-inference predict --task depth --source image.jpg --colormap spectral

# Depth normalized by depth value instead (near = low color, far = high color)
ultralytics-inference predict --task depth --source image.jpg --depth-viz metric

# 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

الأعلام الشائعة:

Link to this sectionالبدء السريع للمكتبة#

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

Link to this sectionالمهام المدعومة#

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

Link to this sectionتوافق النموذج#

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

التجزئة الدلالية (-sem) وتقدير العمق (-depth) خاصتان بـ YOLO26 فقط.

Link to this sectionمصادر الإدخال#

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

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

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

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

Link to this sectionتسريع GPU ومعالجة CUDA الأولية#

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

تقوم cuda-preprocess بتنفيذ تغيير حجم الإطار (letterbox)، والتطبيع، وتحويل التخطيط من HWC إلى CHW كعملية CUDA مدمجة واحدة (fused kernel)، ثم تغذي النتيجة إلى النموذج كمصفوفة جهاز (tensor) بدون نسخ. هذا يزيل تكلفة المعالجة الأولية على وحدة المعالجة المركزية (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

Link to this sectionميزات 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.29", features = ["video"] }

Link to this sectionالمخرجات والحفظ#

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

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

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

Link to this sectionالأسئلة الشائعة#

Link to this sectionهل أحتاج إلى تثبيت Python؟#

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

Link to this sectionما هي النماذج التي يمكنني تشغيلها؟#

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

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

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

Link to this sectionهل يتم دعم الفيديو؟#

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

Link to this sectionماذا تفعل ميزتا annotate و visualize؟#

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

Link to this sectionأين أجد مرجع API الكامل؟#

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