Ultralytics Inference 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 offrire previsioni veloci e sicure per la memoria su immagini, video, webcam e flussi, senza richiedere alcun runtime Python al momento dell'inferenza.

Il progetto viene distribuito come un singolo crate, ultralytics-inference, che puoi usare in due modi: come CLI per previsioni rapide e operazioni in batch, o come libreria integrata direttamente nella tua applicazione Rust. Supporta ogni attività di Ultralytics e un'ampia gamma di backend hardware tramite un'interfaccia di dispositivo uniforme.

Perché l'inferenza con Rust?#

• Velocità nativa e un ingombro ridotto. Compila in un eseguibile nativo senza interprete, ideale per server, contenitori e dispositivi edge.
• Sicurezza della memoria. Il modello di ownership di Rust rimuove intere classi di errori di runtime senza bisogno di un garbage collector.
• Tutti i task YOLO. Rilevamento, segmentazione, segmentazione semantica, stima della profondità, classificazione, pose e OBB da una singola API.
• Ampio supporto hardware. CPU più provider di esecuzione CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm e XNNPACK selezionati in fase di build.
• Pre-elaborazione lato GPU. Un kernel CUDA fuso opzionale mantiene il letterbox, la normalizzazione e la conversione del layout sul dispositivo per un percorso di input a zero copie.
• Download automatico. I nomi dei modelli YOLO noti e gli asset di esempio vengono scaricati automaticamente al primo utilizzo.

Installazione#

È richiesto Rust 1.89 o successivo. La funzionalità video richiede inoltre FFmpeg 7+ installato sul 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

Guida rapida CLI#

La CLI espone un sottocomando predict. Senza argomenti, scarica un modello di rilevamento nano e immagini di campione, 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:

Guida rapida alla libreria#

Carica un modello ed esegui una previsione. 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 con 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 attività popola un campo diverso su Results. Ogni scheda sottostante è un programma completo ed eseguibile; il modello e gli input di esempio vengono scaricati automaticamente al primo avvio. Sostituisci predict_default() con predict("image.jpg") per eseguire l'operazione 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#

Tutte le attività di Ultralytics sono supportate. Quando --model viene omesso, il modello nano corrispondente per l'attività selezionata viene scaricato automaticamente.

Compatibilità del modello#

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

La segmentazione semantica (-sem) e la stima della profondità (-depth) sono esclusive di YOLO26.

Fonti di input#

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

Dispositivi e provider di esecuzione#

L'inferenza viene eseguita su CPU per impostazione predefinita. I backend GPU e acceleratori sono 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 pre-elaborazione CUDA#

Sulle hardware NVIDIA, la funzionalità cuda abilita il provider di esecuzione CUDA e tensorrt aggiunge il provider TensorRT per un'ulteriore ottimizzazione. Per la latenza più bassa possibile, la funzionalità cuda-preprocess sposta la preelaborazione 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 invia il risultato al modello come un tensore di dispositivo a zero copie. Ciò elimina il costo di preelaborazione CPU per immagine e la copia da host a dispositivo, aspetto fondamentale per batch ad alto throughput e flussi in tempo reale.

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

Il percorso veloce viene utilizzato automaticamente, senza modifiche all'API, quando sono soddisfatte 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 utilizza 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 compilazione. Le impostazioni predefinite coprono l'annotazione e la visualizzazione in tempo reale.

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

Output e salvataggio#

Per impostazione predefinita, le predizioni vengono annotate e salvate in una directory di esecuzione a incremento automatico:

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

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

FAQ#

Ho bisogno di Python installato?#

No. Il crate esegue modelli ONNX esportati direttamente tramite ONNX Runtime. Python è necessario solo se addestri o esporti prima i modelli con il pacchetto Ultralytics.

Quali modelli posso eseguire?#

Qualsiasi modello Ultralytics YOLO esportato in ONNX, inclusi YOLO26, YOLO11 e YOLOv8. I nomi di modelli noti vengono scaricati automaticamente; puoi anche puntare --model a qualsiasi file .onnx locale.

Come ottengo un file del modello?#

Esporta dal pacchetto Python, ad esempio con l'integrazione ONNX, o consenti alla CLI di scaricare un modello nano standard per l'attività scelta al primo avvio.

Il video è supportato?#

Sì, con la funzionalità video abilitata e FFmpeg 7+ installato sul sistema. Questo copre file video, webcam e flussi RTSP/RTMP/HTTP.

Cosa fanno le funzionalità annotate e visualize?#

Entrambe sono abilitate per impostazione predefinita. annotate disegna riquadri, maschere, punti chiave ed etichette di classe sull'immagine ed è richiesto affinché --save scriva i risultati annotati. visualize apre una finestra in tempo reale per --show. Per una build più piccola e headless che restituisce solo i risultati in modo programmatico, disattivale con cargo build --no-default-features (aggiungi nuovamente le singole funzionalità secondo necessità).

Dove si trova il riferimento completo dell'API?#

Questa pagina è una panoramica di alto livello. La documentazione di riferimento API completa e dettagliata per ogni struct, metodo e opzione di configurazione pubblica è pubblicata su docs.rs, generata direttamente dal codice sorgente.