Ultralytics Inference für Rust#

Ultralytics Inference ist eine leistungsstarke Inferenzbibliothek und ein Befehlszeilenwerkzeug für YOLO, geschrieben in Rust. Das Werkzeug führt exportierte ONNX-Modelle über ONNX Runtime aus und ermöglicht so 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 namens ultralytics-inference bereitgestellt, das du auf zwei Arten verwenden kannst: als CLI für schnelle Vorhersagen und Stapelverarbeitung oder als Bibliothek, die direkt in deine Rust-Anwendung eingebunden wird. Es unterstützt alle Ultralytics-Aufgaben und eine breite Auswahl an Hardware-Backends über eine einheitliche Geräteschnittstelle. Für Inferenz im Browser veröffentlicht dasselbe Repository das npm-Paket @ultralytics/yolo; die Einrichtungsanleitung findest du hier.

Warum Inferenz mit Rust?#

• Native Geschwindigkeit und geringer Platzbedarf. 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 eine Garbage Collection erforderlich ist.
• Alle YOLO-Aufgaben. Erkennung, Instanzsegmentierung, semantische Segmentierung, Tiefenschätzung, Klassifizierung, Pose und OBB über eine einzige API.
• Breite 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 Layoutkonvertierung auf der GPU aus und übergibt das Ergebnis an das Modell, ohne das Gerät zu verlassen.
• Automatischer Download. Bekannte YOLO-Modellnamen und Beispielressourcen werden beim ersten Einsatz automatisch heruntergeladen.

Installation#

Rust 1.89 oder höher ist erforderlich. Für die Funktion video muss außerdem FFmpeg 6 bis 9 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 einen Unterbefehl predict bereit. Ohne Argumente lädt sie 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 --quantize 16

Gängige Flags:

Schnelleinstieg 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 festzulegen:

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

Jede Aufgabe befüllt ein anderes Feld in Results. Jeder Tab unten enthält ein vollständiges, ausführbares Programm; das Modell und die Beispieleingaben werden beim ersten Start automatisch heruntergeladen. Ersetze predict_default() durch predict("image.jpg"), um eigene 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 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 mit YOLO26 möglich. Erkennungsmodelle von RT-DETR funktionieren ebenfalls, werden aber nicht automatisch heruntergeladen: Exportiere zuerst eines nach ONNX.

Eingabequellen#

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

Geräte und Ausführungsprovider#

GPU- und Beschleuniger-Backends werden als Cargo-Features einkompiliert und zur Laufzeit mit --device (CLI) oder Device (Bibliothek) ausgewählt. Wenn kein Gerät angegeben ist, werden die in den Build einkompilierten Provider in einer festgelegten Prioritätsreihenfolge registriert (zuerst TensorRT, dann CUDA usw.). Ein Build mit ausschließlich den Standard-Features läuft daher auf der CPU.

# 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. tensorrt fügt den TensorRT-Provider für weitere Optimierungen hinzu. Für eine möglichst geringe Latenz verlagert das Feature cuda-preprocess die Vorverarbeitung auf die GPU.

cuda-preprocess führt das Letterbox-Resizing, die Normalisierung und die Layoutkonvertierung 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. Der rohe 8-Bit-Frame wird weiterhin auf die GPU hochgeladen, bei diskreten GPUs über einen gepinnten Staging-Puffer. Der Kernel übernimmt jedoch das Resizing, die Normalisierung und die Layoutkonvertierung auf der CPU sowie den separaten Upload des vorverarbeiteten Tensors. Das ist vor allem bei Batches mit hohem Durchsatz und Echtzeit-Streams wichtig.

# 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: Das Feature ist einkompiliert, das Gerät ist CUDA oder TensorRT, die Aufgabe ist detect, segment, pose, OBB, semantische Segmentierung (nur bei Einzelbildern) oder Tiefenschätzung, und das Modell verwendet eine FP32-Eingabe. Der schnelle Pfad 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-Features#

Features werden beim Build aktiviert. Die Standardeinstellungen umfassen Annotation und Live-Anzeige.

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

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

Ausgabe und Speichern#

Vorhersagen werden standardmäßig 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 speichern. Für die Aufgabe semantic schreibt --save-json PNG-Dateien mit Klassenkarten pro Pixel in einen Unterordner results/. Für die Aufgabe depth wird die farbige Tiefenkarte über das Quellbild gelegt, wie bei der Ausgabe plot() von Ultralytics Python. Das Speichern annotierter Bilder und Videos erfordert das Feature annotate; der Export semantischer Klassenkarten als PNG erfordert es nicht. Videoeingabe und -ausgabe erfordern das Feature video.

Häufig gestellte Fragen#