Link to this sectionUltralytics 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 fornire previsioni rapide e sicure per la memoria su immagini, video, webcam e flussi, senza richiedere il runtime Python al momento dell'inferenza.

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

Link to this sectionPerché l'inferenza con Rust?#

• Velocità nativa e ingombro ridotto. Si compila in un binario nativo senza interprete, ideale per server, container 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, pose, OBB, classificazione e segmentazione semantica da un'unica 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.

Link to this sectionInstallazione#

È richiesto Rust 1.89 o superiore. La funzionalità video richiede inoltre che FFmpeg 7+ sia 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

Link to this sectionGuida rapida 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

# 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:

Link to this sectionGuida 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 le soglie, la dimensione dell'immagine, la precisione e il dispositivo con una builder API:

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 popola un campo diverso su Results. Ogni scheda qui sotto è 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 il programma 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(())
}

Link to this sectionTask supportati#

Tutti i task di Ultralytics sono supportati. Quando --model viene omesso, il modello nano corrispondente per il task selezionato viene scaricato automaticamente.

Link to this sectionCompatibilità del modello#

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) è solo per YOLO26.

Link to this sectionFonti di input#

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

Link to this sectionDispositivi e provider di esecuzione#

L'inferenza viene eseguita su CPU per impostazione predefinita. I backend GPU e acceleratore vengono compilati come funzionalità Cargo e selezionati in fase di runtime con --device (CLI) o Device (libreria).

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

Link to this sectionAccelerazione GPU e pre-elaborazione CUDA#

Su 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 pre-elaborazione sulla GPU.

cuda-preprocess esegue il ridimensionamento letterbox, la normalizzazione e la conversione del layout da HWC a CHW come un singolo kernel CUDA fuso, quindi invia il risultato al modello come tensore di dispositivo zero-copy. Questo rimuove il costo di pre-elaborazione della CPU per immagine e la copia da host a dispositivo, il che è 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 rapido viene utilizzato automaticamente, senza modifiche all'API, quando sono vere tutte le seguenti condizioni: la funzionalità è compilata, il dispositivo è CUDA o TensorRT, l'attività è detect, segment, pose, OBB o segmentazione semantica e il modello utilizza un input FP32. È abilitato per impostazione predefinita e può essere disattivato per ogni singolo modello:

use ultralytics_inference::{Device, InferenceConfig};

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

Link to this sectionFunzionalità Cargo#

Le funzionalità vengono abilitate in fase di compilazione. Le impostazioni predefinite coprono l'annotazione e la visualizzazione in tempo reale.

Gruppi di convenienza raggruppano i provider correlati: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) e all (annotate, visualize, video). Sono disponibili anche ulteriori provider 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.18", features = ["video"] }

Link to this sectionOutput 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 sorgenti video, l'output annotato viene scritto come file video; passa --save-frames per scrivere i singoli frame. Per l'attività semantic, --save-json scrive file PNG di mappe di classe per pixel in una sottocartella results/. Il salvataggio di immagini e video annotati richiede la funzionalità annotate; l'esportazione di PNG di mappe di classe semantiche no. L'input e l'output video richiedono la funzionalità video.

Link to this sectionFAQ#

Link to this sectionHo bisogno di Python installato?#

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

Link to this sectionQuali modelli posso eseguire?#

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

Link to this sectionCome ottengo un file del modello?#

Esporta dal pacchetto Python, ad esempio con l'integrazione ONNX, oppure lascia che la CLI scarichi un modello nano standard per l'attività scelta al primo avvio.

Link to this sectionIl video è supportato?#

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

Link to this sectionCosa fanno le funzionalità annotate e visualize?#

Both are enabled by default. annotate draws boxes, masks, keypoints, and class labels onto the image and is required for --save to write annotated results. visualize opens a live window for --show. For a smaller, headless build that only returns results programmatically, disable them with cargo build --no-default-features (add back individual features as needed).

Link to this sectionDove si trova il riferimento completo dell'API?#

Questa pagina è una panoramica di alto livello. Il riferimento completo dell'API, tipo per tipo, per ogni struct pubblica, metodo e opzione di configurazione è pubblicato su docs.rs, generato direttamente dal codice sorgente.