Inférence Ultralytics pour Rust#

Ultralytics Inference est une bibliothèque d’inférence YOLO hautes performances et un outil en ligne de commande écrits en Rust. Il exécute des modèles ONNX exportés via ONNX Runtime pour produire rapidement des prédictions sécurisées en mémoire sur des images, des vidéos, des webcams et des flux, sans nécessiter d’environnement d’exécution Python au moment de l’inférence.

Le projet est distribué sous la forme d’une crate unique, ultralytics-inference, que tu peux utiliser de deux façons : comme CLI pour des prédictions rapides et des traitements par lots, ou comme bibliothèque intégrée directement à ton application Rust. Elle prend en charge toutes les tâches Ultralytics et un large éventail de backends matériels via une interface de périphérique uniforme. Pour l’inférence dans le navigateur, le même référentiel publie le package npm @ultralytics/yolo ; consulte son guide de configuration.

Pourquoi l’inférence avec Rust ?#

• Performances natives et faible encombrement. Compile en binaire natif sans interpréteur, idéal pour les serveurs, les conteneurs et les appareils en périphérie.
• Sécurité 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 étendue du matériel. CPU, ainsi que CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm et XNNPACK comme fournisseurs d’exécution sélectionnés à la compilation.
• Prétraitement sur GPU. Un noyau CUDA fusionné facultatif exécute le letterboxing, la normalisation et la conversion de disposition sur le GPU, puis transmet le résultat au modèle sans quitter le périphérique.
• Téléchargement automatique. Les noms de modèles YOLO connus et les ressources d’exemple sont téléchargés automatiquement à la première utilisation.

Installation#

Rust 1.89 ou version ultérieure est requis. La fonctionnalité video nécessite également l’installation de FFmpeg 6 à 9 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 --quantize 16

Options courantes :

Démarrage rapide de la bibliothèque#

Charge un modèle et lance une prédiction. Les métadonnées du modèle, comme les noms des classes, le type de tâche et la taille de l'image, sont lues automatiquement dans 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 de l'image, la précision et le périphérique à l'aide d'une API à chaînage de méthodes :

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

Chaque tâche renseigne un champ différent de Results. Chaque onglet ci-dessous présente un programme complet et exécutable ; le modèle et les exemples d'entrée 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. Si --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é au format 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. Les modèles de détection RT-DETR fonctionnent également, mais ne sont pas téléchargés automatiquement : exporte-en un au format ONNX au préalable.

Sources d'entrée#

L'argument --source (et 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#

Les moteurs 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). Si aucun périphérique n'est spécifié, les fournisseurs compilés dans le build sont enregistrés selon un ordre de priorité fixe (TensorRT d'abord, puis CUDA, etc.), de sorte qu'un build utilisant uniquement les fonctionnalités par défaut s'exécute sur CPU.

# 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, et tensorrt ajoute le fournisseur TensorRT pour une optimisation plus poussée. 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 dans un seul noyau CUDA fusionné, puis transmet le résultat au modèle sous forme de tenseur de périphérique sans copie. L'image brute de 8 bits est toujours transférée vers le GPU, via un tampon intermédiaire épinglé sur les GPU discrets ; le noyau évite le redimensionnement et la normalisation sur CPU, la conversion de disposition ainsi que le transfert séparé du tenseur prétraité, 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 detect, segment, pose, OBB, la segmentation sémantique (images uniques uniquement) ou l'estimation de profondeur, et le modèle utilise une entrée FP32. Cette fonctionnalité est activée par défaut et peut être désactivée 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 du build. Les fonctionnalités par défaut couvrent l'annotation et l'affichage en direct.

Les groupes pratiques regroupent des fournisseurs associés : nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) et all (annotate, visualize, video). D'autres fournisseurs, tels que nnapi, qnn, xnnpack, webgpu, ainsi que 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.50", features = ["video"] }

Sortie et enregistrement#

Par défaut, les prédictions sont annotées et enregistrées dans un répertoire d'exécution dont le nom s'incrémente automatiquement :

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 fichiers PNG de carte 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 dans la sortie plot() de l'API Python d'Ultralytics. L'enregistrement des images et vidéos annotées nécessite la fonctionnalité annotate ; l'exportation des cartes PNG de classes sémantiques ne la nécessite pas. L'entrée et la sortie vidéo nécessitent la fonctionnalité video.

FAQ#