Inferencia de Ultralytics para Rust#

Ultralytics Inference es una biblioteca de inferencia de alto rendimiento para YOLO y una herramienta de línea de comandos escrita en Rust. Ejecuta modelos ONNX exportados mediante ONNX Runtime para ofrecer predicciones rápidas y seguras en cuanto a memoria sobre imágenes, vídeos, cámaras web y streams, sin necesidad del entorno de ejecución de Python durante la inferencia.

El proyecto se distribuye como un único crate, ultralytics-inference, que puedes utilizar de dos formas: como CLI para predicciones rápidas y trabajos por lotes, o como biblioteca integrada directamente en tu aplicación de Rust. Es compatible con todas las tareas de Ultralytics y con un amplio conjunto de backends de hardware mediante una interfaz de dispositivos uniforme.

¿Por qué inferencia con Rust?#

• Velocidad nativa y tamaño reducido. Se compila en un binario nativo sin intérprete, ideal para servidores, contenedores y dispositivos edge.
• Seguridad de memoria. El modelo de ownership de Rust elimina clases enteras de errores en tiempo de ejecución sin un recolector de basura.
• Todas las tareas de YOLO. Detecta, segmenta, realiza segmentación semántica, estima la profundidad, clasifica, detecta poses y OBB desde una única API.
• Amplia compatibilidad de hardware. Ejecución en CPU, además de CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm y XNNPACK, seleccionada durante la compilación.
• Preprocesamiento en la GPU. Un kernel CUDA fusionado opcional mantiene letterbox, la normalización y la conversión de formato en el dispositivo para ofrecer un flujo de entrada sin copias.
• Descarga automática. Los nombres de modelos YOLO conocidos y los recursos de ejemplo se descargan automáticamente durante el primer uso.

Instalación#

Se requiere Rust 1.89 o posterior. La función video también necesita tener FFmpeg 7+ instalado en el 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

Inicio rápido de la CLI#

La CLI expone un subcomando predict. Sin argumentos, descarga un modelo nano de detección y unas imágenes de ejemplo, ejecuta la inferencia y guarda los resultados anotados en 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

Opciones habituales:

Inicio rápido de la biblioteca#

Carga un modelo y ejecuta una predicción. Los metadatos del modelo, como los nombres de las clases, el tipo de tarea y el tamaño de imagen, se leen automáticamente del archivo 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 para controlar los umbrales, el tamaño de imagen, la precisión y el dispositivo con una API de tipo builder:

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

Cada tarea rellena un campo diferente en Results. Cada pestaña siguiente es un programa completo y ejecutable; el modelo y las entradas de ejemplo se descargan automáticamente durante la primera ejecución. Sustituye predict_default() por predict("image.jpg") para ejecutarlo con tus propios archivos.

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

Tareas compatibles#

Todas las tareas de Ultralytics son compatibles. Si se omite --model, el modelo nano correspondiente a la tarea seleccionada se descarga automáticamente.

Compatibilidad de modelos#

Cualquier modelo de Ultralytics exportado a ONNX puede cargarse desde un archivo local. La descarga automática está disponible para los nombres de modelo YOLO26, YOLO11 y YOLOv8 estándar en los tamaños n, s, m, l y x:

La segmentación semántica (-sem) y la estimación de profundidad (-depth) solo están disponibles para YOLO26.

Fuentes de entrada#

El argumento --source (y el tipo Source en la biblioteca) acepta muchos tipos de entrada, detectados automáticamente a partir de la cadena:

Dispositivos y proveedores de ejecución#

La inferencia se ejecuta en la CPU de forma predeterminada. Los backends de GPU y aceleradores se compilan como funciones de Cargo y se seleccionan en tiempo de ejecución con --device (CLI) o Device (biblioteca).

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

Aceleración de GPU y preprocesamiento CUDA#

En hardware NVIDIA, la función cuda habilita el proveedor de ejecución CUDA, y tensorrt añade el proveedor TensorRT para una mayor optimización. Para obtener la latencia más baja posible, la función cuda-preprocess traslada el preprocesamiento a la GPU.

cuda-preprocess ejecuta el redimensionado letterbox, la normalización y la conversión de formato de HWC a CHW como un único kernel CUDA fusionado, y después proporciona el resultado al modelo como un tensor del dispositivo sin copias. Esto elimina el coste de preprocesamiento en CPU por imagen y la copia del host al dispositivo, algo especialmente importante para lotes de gran rendimiento y streams en tiempo real.

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

La ruta rápida se utiliza automáticamente, sin cambios en la API, cuando se cumplen todas las condiciones siguientes: la función está compilada, el dispositivo es CUDA o TensorRT, la tarea es detect, segment, pose, OBB, segmentación semántica o estimación de profundidad, y el modelo utiliza una entrada FP32. Está habilitada de forma predeterminada y puede desactivarse por modelo:

use ultralytics_inference::{Device, InferenceConfig};

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

Funciones de Cargo#

Las funciones se habilitan durante la compilación. Las predeterminadas cubren la anotación y la visualización en directo.

Los grupos de conveniencia agrupan proveedores relacionados: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) y all (annotate, visualize, video). También hay disponibles proveedores adicionales como nnapi, qnn, xnnpack, webgpu, entre otros.

Activa las funciones al instalar la CLI o añadir la biblioteca:

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

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

Salida y guardado#

De forma predeterminada, las predicciones se anotan y se guardan en un directorio de ejecución cuyo número se incrementa automáticamente:

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

La subcarpeta coincide con la tarea (runs/segment/, runs/pose/, etc.). Para las fuentes de vídeo, la salida anotada se escribe como un archivo de vídeo; pasa --save-frames para escribir fotogramas individuales. Para la tarea semantic, --save-json escribe PNG de mapas de clases por píxel en una subcarpeta results/. Para la tarea depth, el mapa de profundidad coloreado se mezcla sobre la imagen de origen, igual que la salida plot() de Ultralytics Python. El guardado de imágenes y vídeos anotados requiere la función annotate; la exportación de PNG de mapas de clases semánticas no. La entrada y salida de vídeo requieren la función video.

Preguntas frecuentes#