Link to this sectionUltralytics Inference für Rust#

Ultralytics Inference ist eine leistungsstarke YOLO Inference-Bibliothek und ein Befehlszeilentool, geschrieben in Rust. Es führt exportierte ONNX-Modelle über ONNX Runtime aus, um schnelle, speichersichere Vorhersagen für Bilder, Videos, Webcams und Streams zu liefern, ohne dass zur Inference-Zeit eine Python-Laufzeitumgebung erforderlich ist.

Das Projekt wird als einzelner Crate ultralytics-inference ausgeliefert, den du auf zwei Arten verwenden kannst: als CLI für schnelle Vorhersagen und Batch-Jobs oder als Bibliothek, die direkt in deine Rust-Anwendung eingebettet wird. Es unterstützt jede Ultralytics-Aufgabe sowie eine breite Palette an Hardware-Backends über eine einheitliche Geräteschnittstelle.

Link to this sectionWarum Rust-Inference?#

• Native Geschwindigkeit und kleiner Fußabdruck. Kompiliert zu einer nativen Binärdatei 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. Objekterkennung (Detect), Segmentierung, Pose-Estimation, OBB, Klassifizierung und semantische Segmentierung ü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.

Link to this sectionInstallation#

Rust 1.89 oder neuer ist erforderlich. Das Feature video benötigt zusätzlich ein installiertes 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

Link to this sectionCLI-Schnellstart#

Die CLI stellt ein predict-Unterkommando bereit. Ohne Argumente lädt sie ein Nano-Erkennungsmodell und Beispielbilder herunter, führt die Inference 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

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

Link to this sectionBibliothek-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 mit einer 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 aus. Jeder Tab unten ist ein vollständiges, ausführbares Programm; das Modell und die Beispiel-Eingabedaten werden beim ersten Start automatisch heruntergeladen. Ersetze predict_default() durch predict("image.jpg"), um sie mit deinen eigenen Dateien auszuführen.

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 sectionUnterstützte Aufgaben#

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

Link to this sectionModellkompatibilität#

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

Semantische Segmentierung (-sem) ist nur für YOLO26 verfügbar.

Link to this sectionEingabequellen#

Das --source-Argument (und der Source-Typ in der Bibliothek) akzeptiert viele Arten von Eingaben, die automatisch aus dem String erkannt werden:

Link to this sectionGeräte und Execution Provider#

Inference 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

Link to this sectionGPU-Beschleunigung und CUDA-Vorverarbeitung#

Auf NVIDIA-Hardware aktiviert das Feature cuda den CUDA Execution Provider, 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-Layout-Konvertierung als einen einzigen, kombinierten CUDA-Kernel aus und übergibt das Ergebnis als Zero-Copy-Device-Tensor an das Modell. Dies eliminiert den CPU-Vorverarbeitungsaufwand pro Bild sowie das Kopieren vom Host zum Device, was besonders bei 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 und ohne API-Änderung verwendet, wenn alle folgenden Bedingungen erfüllt sind: Das Feature ist einkompiliert, das Gerät ist CUDA oder TensorRT, die Aufgabe ist detect, segment, pose, OBB oder semantische Segmentierung, 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

Link to this sectionCargo-Features#

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

Praktische Gruppen bündeln zugehö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 andere 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.18", features = ["video"] }

Link to this sectionAusgabe 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; verwende --save-frames, um stattdessen einzelne Frames zu schreiben. Bei der Aufgabe semantic schreibt --save-json pro-Pixel Klassen-Map-PNGs in einen results/-Unterordner. Das Speichern annotierter Bilder und Videos erfordert das Feature annotate; der Export von semantischen Klassen-Map-PNGs nicht. Videoeingabe und -ausgabe erfordern das Feature video.

Link to this sectionFAQ#

Link to this sectionMuss ich Python installiert haben?#

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

Link to this sectionWelche Modelle kann ich ausführen?#

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

Link to this sectionWie erhalte ich eine Modelldatei?#

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

Link to this sectionWird Video unterstützt?#

Ja, wenn das Feature video aktiviert ist und FFmpeg 7+ auf dem System installiert ist. Dies umfasst Videodateien, Webcams und RTSP/RTMP/HTTP-Streams.

Link to this sectionWas bewirken die Features annotate und visualize?#

Beide sind standardmäßig aktiviert. annotate zeichnet Boxen, Masken, Keypoints und Klassenbeschriftungen auf das Bild und ist erforderlich, damit --save annotierte Ergebnisse schreibt. visualize öffnet ein Live-Fenster für --show. Für einen schlankeren, Headless-Build, der Ergebnisse nur programmgesteuert zurückgibt, deaktiviere sie mit cargo build --no-default-features (füge einzelne Features bei Bedarf wieder hinzu).

Link to this sectionWo finde ich die vollständige API-Referenz?#

Diese Seite bietet einen groben Überblick. Die vollständige, typbasierte API-Referenz für jede öffentliche Struktur, Methode und Konfigurationsoption ist auf docs.rs veröffentlicht und wird direkt aus dem Quellcode generiert.