Ultralytics Inferenz für Rust#

Ultralytics Inference ist eine leistungsstarke YOLO-Inferenzbibliothek und ein Befehlszeilenprogramm, das in Rust geschrieben ist. Sie führt exportierte ONNX-Modelle über ONNX Runtime aus und liefert schnelle, speichersichere Vorhersagen für Bilder, Videos, Webcams und Streams, ohne dass zur Inferenzzeit eine Python-Laufzeitumgebung erforderlich ist.

Das Projekt wird als einzelnes Crate, ultralytics-inference, ausgeliefert, das du auf zwei Arten verwenden kannst: als CLI für schnelle Vorhersagen und Stapelverarbeitung oder als Bibliothek, die direkt in deine Rust-Anwendung eingebettet wird. Es unterstützt jede Ultralytics-Aufgabe sowie eine große Auswahl an Hardware-Backends über eine einheitliche Geräteschnittstelle.

Warum Inferenz mit Rust?#

• Native Geschwindigkeit und geringer Ressourcenbedarf. Wird ohne Interpreter zu einer nativen Binärdatei kompiliert – ideal für Server, Container und Edge-Geräte.
• Speichersicherheit. Das Besitzmodell von Rust verhindert ganze Klassen von Laufzeitfehlern, ohne dass ein Garbage Collector erforderlich ist.
• Alle YOLO-Aufgaben. Erkennung, Instanzsegmentierung, semantische Segmentierung, Tiefenschätzung, Klassifizierung, Pose und OBB über eine einzige API.
• Umfangreiche Hardwareunterstützung. CPU sowie CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm und XNNPACK als zur Build-Zeit ausgewählte Ausführungsanbieter.
• Vorverarbeitung auf der GPU. Ein optionaler fusionierter CUDA-Kernel führt Letterbox, Normalisierung und Layout-Konvertierung auf dem Gerät aus und ermöglicht so einen Eingabepfad ohne Kopieren.
• Automatischer Download. Bekannte YOLO-Modellnamen und Beispielressourcen werden bei der ersten Verwendung automatisch heruntergeladen.

Installation#

Rust 1.89 oder neuer ist erforderlich. Für die Funktion video muss außerdem FFmpeg 7+ auf dem System installiert sein.

# 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

CLI-Schnellstart#

Die CLI stellt ein Unterkommando predict bereit. Ohne Argumente lädt es ein Nano-Erkennungsmodell und Beispielbilder herunter, führt die Inferenz aus und speichert die annotierten Ergebnisse unter 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

Häufig verwendete Optionen:

Schnellstart für die Bibliothek#

Lade ein Modell und führe eine Vorhersage aus. Modellmetadaten wie Klassennamen, Aufgabentyp und Bildgröße werden automatisch aus der ONNX-Datei gelesen.

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

Verwende InferenceConfig, um Schwellenwerte, Bildgröße, Genauigkeit und Gerät über eine Builder-API zu steuern:

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

Jede Aufgabe befüllt ein anderes Feld in Results. Jeder Tab unten ist ein vollständiges, ausführbares Programm; das Modell und die Beispieleingaben werden beim ersten Ausführen automatisch heruntergeladen. Ersetze predict_default() durch predict("image.jpg"), um deine eigenen Dateien zu verarbeiten.

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

Unterstützte Aufgaben#

Alle Ultralytics-Aufgaben werden unterstützt. Wenn --model nicht angegeben ist, wird das passende Nano-Modell für die ausgewählte Aufgabe automatisch heruntergeladen.

Modellkompatibilität#

Jedes nach ONNX exportierte Ultralytics-Modell kann aus einer lokalen Datei geladen werden. Der automatische Download ist für standardmäßige YOLO26-, YOLO11- und YOLOv8-Modellnamen in den Größen n, s, m, l und x verfügbar:

Semantische Segmentierung (-sem) und Tiefenschätzung (-depth) sind nur für YOLO26 verfügbar.

Eingabequellen#

Das Argument --source (und der Typ Source in der Bibliothek) akzeptiert viele Eingabearten, die automatisch anhand der Zeichenfolge erkannt werden:

Geräte und Ausführungsanbieter#

Die Inferenz läuft standardmäßig auf der CPU. GPU- und Beschleuniger-Backends werden als Cargo-Funktionen einkompiliert und zur Laufzeit mit --device (CLI) oder Device (Bibliothek) ausgewählt.

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

GPU-Beschleunigung und CUDA-Vorverarbeitung#

Auf NVIDIA-Hardware aktiviert die Funktion cuda den CUDA-Ausführungsanbieter, während tensorrt den TensorRT-Anbieter für weitere Optimierungen hinzufügt. Für eine möglichst geringe Latenz verlagert die Funktion cuda-preprocess die Vorverarbeitung auf die GPU.

cuda-preprocess führt die Letterbox-Größenanpassung, Normalisierung und Layout-Konvertierung von HWC zu CHW als einen einzigen fusionierten CUDA-Kernel aus und übergibt das Ergebnis anschließend als Gerätetensor ohne Kopiervorgang an das Modell. Dadurch entfallen die CPU-Kosten der Vorverarbeitung pro Bild und das Kopieren vom Host zum Gerät, was besonders bei Stapeln mit hohem Durchsatz und Echtzeitstreams relevant ist.

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

Der schnelle Pfad wird automatisch und ohne Änderung an der API verwendet, wenn alle folgenden Bedingungen erfüllt sind: Die Funktion ist einkompiliert, das Gerät ist CUDA oder TensorRT, die Aufgabe ist detect, segment, pose, OBB, semantische Segmentierung oder Tiefenschätzung und das Modell verwendet FP32-Eingaben. Er ist standardmäßig aktiviert und kann für jedes Modell deaktiviert werden:

use ultralytics_inference::{Device, InferenceConfig};

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

Cargo-Funktionen#

Funktionen werden zur Build-Zeit aktiviert. Die Standardeinstellungen decken Annotation und Live-Anzeige ab.

Komfortgruppen bündeln verwandte Anbieter: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) und all (annotate, visualize, video). Weitere Anbieter wie nnapi, qnn, xnnpack, webgpu und andere sind ebenfalls verfügbar.

Aktiviere Funktionen bei der Installation der CLI oder beim Hinzufügen der Bibliothek:

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

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

Ausgabe und Speichern#

Standardmäßig werden Vorhersagen annotiert und in einem automatisch nummerierten Ausführungsverzeichnis gespeichert:

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

Der Unterordner entspricht der Aufgabe (runs/segment/, runs/pose/ usw.). Bei Videoquellen wird die annotierte Ausgabe als Videodatei geschrieben; übergib --save-frames, um stattdessen einzelne Frames zu schreiben. Für die Aufgabe semantic schreibt --save-json Pixel-genaue Klassenkarten als PNG-Dateien in einem Unterordner results/. Für die Aufgabe depth wird die eingefärbte Tiefenkarte über das Quellbild gelegt, entsprechend der Ausgabe plot() von Ultralytics Python. Zum Speichern annotierter Bilder und Videos ist die Funktion annotate erforderlich; der Export semantischer Klassenkarten als PNG-Dateien hingegen nicht. Für Videoeingabe und -ausgabe ist die Funktion video erforderlich.

FAQ#