Inferencia de Ultralytics para Rust#

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

El proyecto se distribuye como un único crate, ultralytics-inference, que puedes usar de dos maneras: como CLI para predicciones rápidas y trabajos por lotes, o como biblioteca integrada directamente en tu aplicación Rust. Admite todas las tareas de Ultralytics y una amplia variedad de backends de hardware mediante una interfaz de dispositivo uniforme. Para la inferencia en navegador, el mismo repositorio publica el paquete npm @ultralytics/yolo; consulta su guía de configuración.

¿Por qué usar Rust para la inferencia?#

• Rendimiento nativo y tamaño reducido. Se compila en un binario nativo sin intérprete, ideal para servidores, contenedores y dispositivos periféricos.
• Seguridad de memoria. El modelo de propiedad de Rust elimina categorías enteras de errores en tiempo de ejecución sin necesidad de un recolector de basura.
• Todas las tareas de YOLO. Detecta, segmenta, realiza segmentación semántica y estimación de profundidad, clasifica, estima poses y detecta OBB desde una sola API.
• Amplia compatibilidad de hardware. CPU y proveedores de ejecución CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm y XNNPACK seleccionados en el momento de la compilación.
• Preprocesamiento en la GPU. Un kernel CUDA fusionado opcional ejecuta letterbox, normalización y conversión del formato de datos en la GPU, y pasa el resultado al modelo sin sacarlo del dispositivo.
• Descarga automática. Los nombres de modelos YOLO conocidos y los recursos de ejemplo se descargan automáticamente en el primer uso.

Instalación#

Se requiere Rust 1.89 o una versión posterior. La función video también necesita que FFmpeg 6 a 9 esté 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 ofrece un subcomando predict. Si no se indican argumentos, descarga un modelo de detección nano 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 --quantize 16

Indicadores comunes:

Guía de 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 basada en un generador:

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

Cada tarea rellena un campo distinto de Results. Cada pestaña de abajo contiene un programa completo y ejecutable; el modelo y las entradas de ejemplo se descargan automáticamente en 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#

Se admiten todas las tareas de Ultralytics. Si omites --model, se descarga automáticamente el modelo nano correspondiente a la tarea seleccionada.

Compatibilidad de modelos#

Cualquier modelo de Ultralytics exportado a ONNX se puede cargar desde un archivo local. La descarga automática está disponible para los nombres de modelos 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 en YOLO26. Los modelos de detección RT-DETR también se ejecutan, pero no se descargan automáticamente: primero debes exportar uno a ONNX.

Fuentes de entrada#

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

Dispositivos y proveedores de ejecución#

Los backends de GPU y aceleradores se compilan como características de Cargo y se seleccionan en tiempo de ejecución con --device (CLI) o Device (biblioteca). Si no especificas un dispositivo, los proveedores compilados se registran en un orden de preferencia fijo (primero TensorRT, luego CUDA, etc.), por lo que una compilación con solo las características predeterminadas se ejecuta en CPU.

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

Aceleración de GPU y preprocesamiento con CUDA#

En hardware NVIDIA, la característica cuda habilita el proveedor de ejecución de CUDA, y tensorrt añade el proveedor de TensorRT para optimizar aún más el rendimiento. Para conseguir la latencia más baja posible, la característica cuda-preprocess traslada el preprocesamiento a la GPU.

cuda-preprocess ejecuta el redimensionamiento letterbox, la normalización y la conversión de disposición de HWC a CHW como un único kernel CUDA fusionado; después, pasa el resultado al modelo como un tensor del dispositivo sin copia. El fotograma sin procesar de 8 bits se sigue transfiriendo a la GPU mediante un búfer de preparación fijado en las GPU discretas; el kernel elimina el redimensionamiento, la normalización y la conversión de disposición en la CPU, así como la transferencia independiente del tensor preprocesado, algo especialmente importante para los lotes de alto rendimiento y los flujos en tiempo real.

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

La ruta rápida se usa automáticamente, sin cambios en la API, cuando se cumplen todas estas condiciones: la característica está compilada, el dispositivo es CUDA o TensorRT, la tarea es detect, segment, pose, OBB, segmentación semántica (solo imágenes individuales) o estimación de profundidad, y el modelo usa una entrada FP32. Está habilitada de forma predeterminada y se puede desactivar para cada modelo:

use ultralytics_inference::{Device, InferenceConfig};

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

Características de Cargo#

Las características se habilitan en tiempo de compilación. Las características 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 otros proveedores disponibles, como nnapi, qnn, xnnpack, webgpu, entre otros.

Habilita las características 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.50", features = ["video"] }

Salida y guardado#

De forma predeterminada, las predicciones se anotan y se guardan en un directorio de ejecución cuyo nombre 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 guarda como archivo de vídeo; pasa --save-frames para guardar fotogramas individuales. Para la tarea semantic, --save-json guarda PNG de mapas de clases por píxel en una subcarpeta results/. Para la tarea depth, el mapa de profundidad coloreado se superpone a la imagen de origen, igual que en la salida plot() de Ultralytics Python. Para guardar imágenes y vídeos anotados se requiere la característica annotate; la exportación de PNG de mapas de clases semánticas no la requiere. La entrada y salida de vídeo requieren la característica video.

Preguntas frecuentes#