Inférence Ultralytics pour Rust#

Ultralytics Inference est une bibliothèque d'inférence YOLO haute performance et un outil en ligne de commande écrits en Rust. Elle exécute des modèles ONNX exportés via ONNX Runtime afin de fournir des prédictions rapides et sûres pour la mémoire sur des images, des vidéos, des webcams et des flux, sans nécessiter l'environnement d'exécution Python au moment de l'inférence.

Le projet est distribué sous la forme d'un crate unique, ultralytics-inference, que tu peux utiliser de deux façons : comme CLI pour les prédictions rapides et les traitements par lots, ou comme bibliothèque intégrée directement à ton application Rust. Il prend en charge toutes les tâches Ultralytics ainsi qu'un large éventail de backends matériels via une interface de périphérique uniforme.

Pourquoi l'inférence avec Rust ?#

• Vitesse native et faible empreinte. Se compile en binaire natif sans interpréteur, ce qui est idéal pour les serveurs, les conteneurs et les appareils périphériques.
• Sûreté de la mémoire. Le modèle de propriété de Rust élimine toute une catégorie d'erreurs d'exécution sans ramasse-miettes.
• Toutes les tâches YOLO. Détection, segmentation, segmentation sémantique, estimation de profondeur, classification, pose et OBB depuis une seule API.
• Prise en charge matérielle étendue. Exécution sur CPU, ainsi qu'avec CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm et XNNPACK, les fournisseurs d'exécution étant sélectionnés au moment de la compilation.
• Prétraitement côté GPU. Un noyau CUDA fusionné facultatif maintient le letterbox, la normalisation et la conversion de disposition sur le périphérique pour un chemin d'entrée sans copie.
• Téléchargement automatique. Les noms de modèles YOLO connus et les ressources d'exemple sont téléchargés automatiquement lors de la première utilisation.

Installation#

Rust 1.89 ou une version ultérieure est requis. La fonctionnalité vidéo nécessite également l'installation de FFmpeg 7+ sur le système.

# 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

Démarrage rapide de la CLI#

La CLI expose une sous-commande predict. Sans argument, elle télécharge un modèle de détection nano et des images d'exemple, exécute l'inférence et enregistre les résultats annotés dans 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

Options courantes :

Démarrage rapide de la bibliothèque#

Charge un modèle et exécute une prédiction. Les métadonnées du modèle, telles que les noms de classes, le type de tâche et la taille des images, sont lues automatiquement depuis le fichier 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(())
}

Utilise InferenceConfig pour contrôler les seuils, la taille des images, la précision et le périphérique avec une API de construction :

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")?;

Chaque tâche renseigne un champ différent dans Results. Chaque onglet ci-dessous est un programme complet et exécutable ; le modèle et les entrées d'exemple sont téléchargés automatiquement lors de la première exécution. Remplace predict_default() par predict("image.jpg") pour exécuter le programme sur tes propres fichiers.

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(())
}

Tâches prises en charge#

Toutes les tâches Ultralytics sont prises en charge. Lorsque --model est omis, le modèle nano correspondant à la tâche sélectionnée est téléchargé automatiquement.

Compatibilité des modèles#

Tout modèle Ultralytics exporté vers ONNX peut être chargé depuis un fichier local. Le téléchargement automatique est disponible pour les noms de modèles YOLO26, YOLO11 et YOLOv8 standard dans les tailles n, s, m, l et x :

La segmentation sémantique (-sem) et l'estimation de profondeur (-depth) sont réservées à YOLO26.

Sources d'entrée#

L'argument --source (ainsi que le type Source dans la bibliothèque) accepte de nombreux types d'entrée, détectés automatiquement à partir de la chaîne :

Périphériques et fournisseurs d'exécution#

L'inférence s'exécute par défaut sur CPU. Les backends GPU et accélérateurs sont compilés sous forme de fonctionnalités Cargo et sélectionnés à l'exécution avec --device (CLI) ou Device (bibliothèque).

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

Accélération GPU et prétraitement CUDA#

Sur le matériel NVIDIA, la fonctionnalité cuda active le fournisseur d'exécution CUDA, tandis que tensorrt ajoute le fournisseur TensorRT pour une optimisation supplémentaire. Pour obtenir la latence la plus faible possible, la fonctionnalité cuda-preprocess déplace le prétraitement sur le GPU.

cuda-preprocess effectue le redimensionnement letterbox, la normalisation et la conversion de disposition HWC-vers-CHW en un seul noyau CUDA fusionné, puis transmet le résultat au modèle sous forme de tenseur de périphérique sans copie. Cela supprime le coût du prétraitement CPU par image ainsi que la copie de l'hôte vers le périphérique, ce qui est particulièrement important pour les lots à haut débit et les flux en temps réel.

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

Le chemin rapide est utilisé automatiquement, sans modification de l'API, lorsque toutes les conditions suivantes sont réunies : la fonctionnalité est compilée, le périphérique est CUDA ou TensorRT, la tâche est la détection, la segmentation, la pose, l'OBB, la segmentation sémantique ou l'estimation de profondeur, et le modèle utilise une entrée FP32. Il est activé par défaut et peut être désactivé pour chaque modèle :

use ultralytics_inference::{Device, InferenceConfig};

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

Fonctionnalités Cargo#

Les fonctionnalités sont activées au moment de la compilation. Les valeurs par défaut couvrent l'annotation et l'affichage en direct.

Les groupes pratiques regroupent les fournisseurs associés : nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) et all (annotate, visualize, video). Des fournisseurs supplémentaires tels que nnapi, qnn, xnnpack, webgpu et d'autres sont également disponibles.

Active les fonctionnalités lors de l'installation de la CLI ou de l'ajout de la bibliothèque :

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

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

Sortie et enregistrement#

Par défaut, les prédictions sont annotées et enregistrées dans un dossier d’exécution à numérotation automatique :

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

Le sous-dossier correspond à la tâche (runs/segment/, runs/pose/, etc.). Pour les sources vidéo, la sortie annotée est écrite dans un fichier vidéo ; passe --save-frames pour écrire des images individuelles à la place. Pour la tâche semantic, --save-json écrit des PNG de cartes de classes par pixel dans un sous-dossier results/. Pour la tâche depth, la carte de profondeur colorisée est superposée à l’image source, comme la sortie plot() de Ultralytics Python. L’enregistrement des images et vidéos annotées nécessite la fonctionnalité annotate ; l’export de PNG de cartes de classes sémantiques ne la nécessite pas. Les entrées et sorties vidéo nécessitent la fonctionnalité video.

FAQ#