Inferenza Ultralytics per Rust#

Ultralytics Inference è una libreria di inferenza YOLO ad alte prestazioni e uno strumento a riga di comando scritto in Rust. Esegue modelli ONNX esportati tramite ONNX Runtime per fornire previsioni rapide e sicure per la memoria su immagini, video, webcam e flussi, senza richiedere un runtime Python durante l'inferenza.

Il progetto è distribuito come un singolo crate, ultralytics-inference, utilizzabile in due modi: come CLI per previsioni rapide e processi in batch oppure come libreria integrata direttamente nella tua applicazione Rust. Supporta tutte le attività Ultralytics e un'ampia gamma di backend hardware tramite un'interfaccia uniforme per i dispositivi. Per l'inferenza nel browser, lo stesso repository pubblica il pacchetto npm @ultralytics/yolo; consulta la guida alla configurazione.

Perché usare Rust per l'inferenza?#

• Velocità nativa e ingombro ridotto. Viene compilato in un binario nativo senza interprete, ideale per server, container e dispositivi edge.
• Sicurezza della memoria. Il modello di proprietà di Rust elimina intere categorie di errori in fase di esecuzione senza un garbage collector.
• Tutte le attività YOLO. Rilevamento, segmentazione, segmentazione semantica, stima della profondità, classificazione, posa e OBB tramite un'unica API.
• Ampio supporto hardware. CPU più provider di esecuzione CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm e XNNPACK, selezionabili in fase di compilazione.
• Preelaborazione sulla GPU. Un kernel CUDA fuso facoltativo esegue letterbox, normalizzazione e conversione del layout sulla GPU e passa il risultato al modello senza uscire dal dispositivo.
• Download automatico. I nomi noti dei modelli YOLO e gli asset di esempio vengono scaricati automaticamente al primo utilizzo.

Installazione#

È richiesto Rust 1.89 o versione successiva. La funzionalità video richiede inoltre FFmpeg dalla versione 6 alla 9 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

Guida rapida alla CLI#

La CLI espone un sottocomando predict. Senza argomenti, scarica un modello di rilevamento nano 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 --quantize 16

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 attività e le dimensioni 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, dimensioni dell'immagine, precisione e dispositivo con un'API basata su builder:

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

Ogni attività popola un campo diverso in Results. Ogni scheda qui sotto è 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 lavorare con i 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(())
}

Attività supportate#

Sono supportate tutte le attività di Ultralytics. Se ometti --model, viene scaricato automaticamente il modello nano corrispondente all'attività selezionata.

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 con YOLO26. I modelli di rilevamento RT-DETR funzionano, ma non vengono scaricati automaticamente: prima esportane uno in ONNX.

Sorgenti di input#

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

Dispositivi e provider di esecuzione#

I backend GPU e acceleratori vengono compilati come funzionalità Cargo e selezionati in fase di esecuzione con --device (CLI) o Device (libreria). Se non specifichi un dispositivo, i provider compilati nella build vengono registrati seguendo un ordine di preferenza fisso (prima TensorRT, poi CUDA e così via); pertanto, una build con solo le funzionalità predefinite viene eseguita su CPU.

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

Accelerazione GPU e preelaborazione CUDA#

Sull'hardware NVIDIA, la funzionalità cuda abilita il provider di esecuzione CUDA, mentre tensorrt aggiunge il provider TensorRT per un'ulteriore ottimizzazione. Per ottenere la latenza più bassa possibile, la funzionalità cuda-preprocess trasferisce 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 passa il risultato al modello come tensore del dispositivo senza copie. Il fotogramma grezzo a 8 bit viene comunque caricato sulla GPU, attraverso un buffer di staging bloccato sulle GPU discrete; il kernel elimina il ridimensionamento, la normalizzazione e la conversione del layout sulla CPU, oltre al caricamento separato del tensore preelaborato, con vantaggi soprattutto 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 usato automaticamente, senza modifiche all'API, se sono soddisfatte tutte le seguenti condizioni: la funzionalità è compilata, il dispositivo è CUDA o TensorRT, l'attività è detect, segment, pose, OBB, segmentazione semantica (solo immagini singole) o stima della profondità e il modello usa input FP32. È abilitato per impostazione predefinita e può essere disattivato per ogni 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 includono l'annotazione e la visualizzazione dal vivo.

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

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

Output e salvataggio#

Per impostazione predefinita, le previsioni vengono annotate e salvate in una directory di esecuzione con numerazione incrementale 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 mappe di classe PNG per pixel in una sottocartella results/. Per l'attività depth, la mappa di profondità colorata viene sovrapposta all'immagine sorgente, come nell'output plot() di Ultralytics Python. Il salvataggio di immagini e video annotati richiede la funzionalità annotate; l'esportazione delle mappe di classe semantiche in PNG non la richiede. L'input e l'output video richiedono la funzionalità video.

Domande frequenti#