Inferenza Ultralytics per Rust#

Ultralytics Inference è una libreria di inferenza YOLO ad alte prestazioni e uno strumento da riga di comando scritto in Rust. Esegue modelli ONNX esportati tramite ONNX Runtime per fornire predizioni rapide e sicure rispetto alla memoria su immagini, video, webcam e stream, senza richiedere il runtime Python durante l'inferenza.

Il progetto viene distribuito come un unico crate, ultralytics-inference, che puoi usare in due modi: come CLI per predizioni rapide e processi batch oppure come libreria incorporata direttamente nella tua applicazione Rust. Supporta ogni task Ultralytics e un'ampia gamma di backend hardware tramite un'interfaccia uniforme per i dispositivi.

Perché l'inferenza in Rust?#

• Velocità nativa e footprint ridotto. Viene compilato in un binario nativo senza interprete, ideale per server, container e dispositivi edge.
• Sicurezza della memoria. Il modello di ownership di Rust elimina intere categorie di errori a runtime senza un garbage collector.
• Tutti i task YOLO. Rilevamento, segmentazione, segmentazione semantica, stima della profondità, classificazione, posa e OBB da un'unica API.
• Ampio supporto hardware. Esecuzione su CPU e tramite CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm e XNNPACK, con gli execution provider selezionati in fase di build.
• Preprocessing sulla GPU. Un kernel CUDA fuso opzionale mantiene letterbox, normalizzazione e conversione del layout sul dispositivo, per un percorso di input a copia zero.
• Download automatico. I nomi dei modelli YOLO conosciuti e gli asset di esempio vengono scaricati automaticamente al primo utilizzo.

Installazione#

È richiesto Rust 1.89 o versione successiva. La funzionalità video richiede inoltre che FFmpeg 7+ sia installato nel sistema.

# 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

Quickstart della CLI#

La CLI espone un sottocomando predict. Senza argomenti, scarica un modello nano per il rilevamento e immagini di esempio, esegue l'inferenza e salva i risultati annotati in 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

Flag comuni:

Quickstart della libreria#

Carica un modello ed esegui una predizione. I metadati del modello, come i nomi delle classi, il tipo di task e la dimensione dell'immagine, vengono letti automaticamente dal file 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(())
}

Usa InferenceConfig per controllare soglie, dimensione dell'immagine, precisione e dispositivo tramite un'API builder:

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

Ogni task valorizza un campo diverso in Results. Ogni scheda seguente è un programma completo ed eseguibile; il modello e gli input di esempio vengono scaricati automaticamente alla prima esecuzione. Sostituisci predict_default() con predict("image.jpg") per eseguire l'inferenza sui tuoi file.

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

Task supportati#

Sono supportati tutti i task Ultralytics. Quando --model viene omesso, il modello nano corrispondente al task selezionato viene scaricato automaticamente.

Compatibilità dei modelli#

Qualsiasi modello Ultralytics esportato in ONNX può essere caricato da un file locale. Il download automatico è disponibile per i nomi standard dei modelli YOLO26, YOLO11 e YOLOv8 nelle dimensioni n, s, m, l e x:

La segmentazione semantica (-sem) e la stima della profondità (-depth) sono disponibili solo per YOLO26.

Sorgenti di input#

L'argomento --source (e il tipo Source nella libreria) accetta molti tipi di input, rilevati automaticamente dalla stringa:

Dispositivi ed execution provider#

L'inferenza viene eseguita per impostazione predefinita sulla CPU. I backend GPU e degli acceleratori vengono compilati come funzionalità Cargo e selezionati a runtime con --device (CLI) o Device (libreria).

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

Accelerazione GPU e preprocessing CUDA#

Su hardware NVIDIA, la funzionalità cuda abilita l'execution provider CUDA, mentre tensorrt aggiunge l' execution provider TensorRT per un'ulteriore ottimizzazione. Per ottenere la latenza più bassa possibile, la funzionalità cuda-preprocess sposta il preprocessing sulla GPU.

cuda-preprocess esegue il ridimensionamento letterbox, la normalizzazione e la conversione del layout da HWC a CHW come un unico kernel CUDA fuso, quindi fornisce il risultato al modello come tensore del dispositivo a copia zero. In questo modo elimina il costo del preprocessing CPU per ogni immagine e della copia dall'host al dispositivo, un aspetto particolarmente importante per i batch ad alto throughput e gli stream in tempo reale.

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

Il percorso rapido viene utilizzato automaticamente, senza modifiche all'API, quando sono vere tutte le seguenti condizioni: la funzionalità è compilata, il dispositivo è CUDA o TensorRT, il task è detect, segment, pose, OBB, segmentazione semantica o stima della profondità e il modello usa input FP32. È abilitato per impostazione predefinita e può essere disattivato per singolo modello:

use ultralytics_inference::{Device, InferenceConfig};

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

Funzionalità Cargo#

Le funzionalità vengono abilitate in fase di build. Le impostazioni predefinite supportano l'annotazione e la visualizzazione dal vivo.

I gruppi di convenienza raggruppano provider correlati: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) e all (annotate, visualize, video). Sono disponibili anche provider aggiuntivi come nnapi, qnn, xnnpack, webgpu e altri.

Abilita le funzionalità durante l'installazione della CLI o l'aggiunta della libreria:

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

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

Output e salvataggio#

Per impostazione predefinita, le predizioni vengono annotate e salvate in una directory di esecuzione con numerazione progressiva automatica:

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

La sottocartella corrisponde all'attività (runs/segment/, runs/pose/ e così via). Per le sorgenti video, l'output annotato viene scritto come file video; passa --save-frames per scrivere invece i singoli fotogrammi. Per l'attività semantic, --save-json scrive PNG della mappa delle classi per pixel in una sottocartella results/. Per l'attività depth, la mappa di profondità colorizzata viene sovrapposta all'immagine sorgente, in modo analogo all'output plot() di Ultralytics Python. Il salvataggio di immagini e video annotati richiede la funzionalità annotate; l'esportazione PNG della mappa semantica delle classi non la richiede. L'input e l'output video richiedono la funzionalità video.

FAQ#