Ultralytics Inference für Rust#

Ultralytics Inference ist eine leistungsstarke YOLO Inferenzbibliothek und ein Kommandozeilenwerkzeug, geschrieben in Rust. Sie führt exportierte ONNX Modelle über die ONNX Runtime aus, um schnelle, speichersichere Vorhersagen für Bilder, Videos, Webcams und Streams zu liefern – ganz ohne Python zur Inferenzzeit.

Das Projekt wird als einzelnes Crate, ultralytics-inference, ausgeliefert, das du auf zwei Arten nutzen kannst: als CLI für schnelle Vorhersagen und Batch-Jobs oder als Bibliothek, die direkt in deine Rust-Anwendung eingebettet ist. Es unterstützt alle Ultralytics Aufgaben und eine Vielzahl von Hardware-Backends über eine einheitliche Geräteschnittstelle.

Warum Rust-Inference?#

• Native Geschwindigkeit und geringer Fußabdruck. Kompiliert zu einer nativen Binärdatei ganz ohne Interpreter – ideal für Server, Container und Edge-Geräte.
• Speichersicherheit. Das Ownership-Modell von Rust eliminiert ganze Klassen von Laufzeitfehlern ohne Garbage Collector.
• Alle YOLO-Aufgaben. Erkennung, Segmentierung, semantische Segmentierung, Tiefenschätzung, Klassifizierung, Pose und OBB über eine einzige API.
• Breite Hardware-Unterstützung. CPU sowie CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm und XNNPACK Execution Provider, die zum Build-Zeitpunkt ausgewählt werden.
• GPU-seitige Vorverarbeitung. Ein optionaler, verschmolzener CUDA-Kernel hält Letterbox-, Normalisierungs- und Layout-Konvertierungen auf dem Gerät für einen Zero-Copy-Eingabepfad.
• Auto-Download. Bekannte YOLO-Modellnamen und Beispiel-Assets werden bei der ersten Verwendung automatisch heruntergeladen.

Installation#

Rust 1.89 oder neuer ist erforderlich. Die Video-Funktion benötigt zusätzlich FFmpeg 7+ auf dem System.

# 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 den Unterbefehl predict bereit. Ohne Argumente lädt sie ein Nano-Detektionsmodell 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 Flags:

Bibliothek-Schnellstart#

Lade ein Modell und führe eine Vorhersage aus. Modell-Metadaten 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, Präzision 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 füllt ein anderes Feld in Results. Jeder Reiter unten zeigt ein vollständiges, ausführbares Programm; das Modell und die Eingabebeispiele werden beim ersten Start automatisch heruntergeladen. Tausche predict_default() gegen predict("image.jpg") aus, um deine eigenen Dateien zu verwenden.

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 weggelassen wird, 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. Ein automatischer Download ist für Standardnamen von YOLO26-, YOLO11- und YOLOv8-Modellen in den Größen n, s, m, l und x verfügbar:

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

Eingabequellen#

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

Geräte und Execution Provider#

Die Inferenz läuft standardmäßig auf der CPU. GPU- und Beschleuniger-Backends werden als Cargo Features 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 das Feature cuda den CUDA-Ausführungsprovider, und tensorrt fügt den TensorRT-Provider für weitere Optimierungen hinzu. Für die geringstmögliche Latenz verlagert das Feature cuda-preprocess die Vorverarbeitung auf die GPU.

cuda-preprocess führt Letterbox-Skalierung, Normalisierung und die HWC-zu-CHW-Layoutkonvertierung als einzigen, fusionierten CUDA-Kernel aus und übergibt das Ergebnis anschließend als Zero-Copy-Gerätetensor an das Modell. Dies eliminiert die CPU-Vorverarbeitungskosten pro Bild sowie das Kopieren vom Host zum Gerät, was insbesondere für Batches mit hohem Durchsatz und Echtzeit-Streams wichtig ist.

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

Der schnelle Pfad wird automatisch ohne API-Änderung verwendet, wenn alle folgenden Bedingungen erfüllt sind: Das Feature ist kompiliert, 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 pro 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-Features#

Features werden zur Build-Zeit aktiviert. Die Standardeinstellungen decken Annotationen und Live-Anzeige ab.

Komfortgruppen bündeln zusammengehörige Provider: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) und all (annotate, visualize, video). Zusätzliche Provider wie nnapi, qnn, xnnpack, webgpu und weitere sind ebenfalls verfügbar.

Aktiviere Features 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.33", 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; übergebe --save-frames, um stattdessen einzelne Frames zu schreiben. Für die Aufgabe semantic schreibt --save-json pixelgenaue Klassen-Map-PNGs in einen Unterordner results/. Für die Aufgabe depth wird die eingefärbte Tiefenkarte über das Quellbild gelegt, passend zur Python-Ausgabe plot() von Ultralytics. Das Speichern von annotierten Bildern und Videos erfordert das Feature annotate; der Export von semantischen Klassen-Map-PNGs nicht. Videoeingabe und -ausgabe erfordern das Feature video.

FAQ#

Muss ich Python installiert haben?#

Nein. Das Crate führt exportierte ONNX-Modelle direkt über die ONNX Runtime aus. Python wird nur benötigt, wenn du Modelle vorher mit dem Ultralytics-Paket trainierst oder exportierst.

Welche Modelle kann ich ausführen?#

Jedes nach ONNX exportierte Ultralytics YOLO-Modell, einschließlich YOLO26, YOLO11 und YOLOv8. Bekannte Modellnamen werden automatisch heruntergeladen; du kannst --model auch auf eine beliebige lokale .onnx-Datei verweisen.

Wie erhalte ich eine Modelldatei?#

Exportiere aus dem Python-Paket, zum Beispiel mit der ONNX-Integration, oder lasse die CLI beim ersten Start ein Standard-Nano-Modell für die gewählte Aufgabe herunterladen.

Wird Video unterstützt?#

Ja, mit aktiviertem Feature video und installiertem FFmpeg 7+ auf dem System. Dies umfasst Videodateien, Webcams sowie RTSP/RTMP/HTTP-Streams.

Was bewirken die Features annotate und visualize?#

Beide sind standardmäßig aktiviert. annotate zeichnet Boxen, Masken, Schlüsselpunkte und Klassenlabels in das Bild und wird von --save benötigt, um annotierte Ergebnisse zu schreiben. visualize öffnet ein Live-Fenster für --show. Für einen kleineren, headless Build, der Ergebnisse nur programmatisch zurückgibt, kannst du sie mit cargo build --no-default-features deaktivieren (einzelne Features bei Bedarf wieder hinzufügen).

Wo finde ich die vollständige API-Referenz?#

Diese Seite bietet eine Übersicht auf hoher Ebene. Die vollständige, typgenaue API-Referenz für jede öffentliche Struktur, Methode und Konfigurationsoption wird direkt aus dem Quellcode generiert auf docs.rs veröffentlicht.