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 a través de ONNX Runtime para ofrecer predicciones rápidas y seguras para la memoria en imágenes, vídeos, cámaras web y flujos, sin necesidad de un entorno de ejecución de Python en el momento de la inferencia.

El proyecto se distribuye como un único crate, ultralytics-inference, que puedes usar de dos formas: como una CLI para predicciones rápidas y trabajos por lotes, o como una 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 a través de una interfaz de dispositivos uniforme.

¿Por qué la inferencia en Rust?#

• Velocidad nativa y huella reducida. Se compila en un binario nativo sin intérprete, lo que resulta ideal para servidores, contenedores y dispositivos de borde.
• Seguridad de memoria. El modelo de propiedad de Rust elimina clases 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, estimación de profundidad, clasifica, estima poses y OBB desde una única API.
• Amplio soporte de hardware. CPU además de proveedores de ejecución CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm y XNNPACK seleccionados en el momento de la compilación.
• Preprocesamiento en GPU. Un kernel de CUDA fusionado opcional mantiene el letterbox, la normalización y la conversión de diseño en el dispositivo para una ruta de entrada sin copia.
• Descarga automática. Los nombres conocidos de modelos YOLO y los recursos de muestra se descargan automáticamente en el primer uso.

Instalación#

Se requiere Rust 1.89 o posterior. La función de vídeo también necesita que FFmpeg 7+ 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 CLI#

La CLI expone un subcomando predict. Sin argumentos, descarga un modelo de detección nano e imágenes de muestra, 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

Flags comunes:

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 la 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 la imagen, la precisión y el dispositivo con una API de creación (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 a continuación es un programa completo y ejecutable; el modelo y las entradas de muestra 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 admitidas#

Se admiten todas las tareas de Ultralytics. Cuando se omite --model, el modelo nano correspondiente para la tarea seleccionada se descarga automáticamente.

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 estándar de YOLO26, YOLO11 y YOLOv8 en los tamaños n, s, m, l y x:

La segmentación semántica (-sem) y la estimación de profundidad (-depth) son exclusivas de YOLO26.

Fuentes de entrada#

El argumento --source (y el tipo Source en la biblioteca) acepta muchos tipos de entrada, que se detectan 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 características 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 por GPU y preprocesamiento CUDA#

En hardware de NVIDIA, la característica cuda habilita el proveedor de ejecución CUDA, y tensorrt añade el proveedor de TensorRT para una mayor optimización. Para obtener la menor latencia posible, la característica cuda-preprocess traslada el preprocesamiento a la GPU.

cuda-preprocess ejecuta el redimensionamiento tipo letterbox, la normalización y la conversión de diseño HWC a CHW como un solo kernel CUDA fusionado, y luego envía el resultado al modelo como un tensor de dispositivo de copia cero. Esto elimina el coste de preprocesamiento de la CPU por imagen y la copia de host a dispositivo, lo cual es fundamental para lotes de alto rendimiento y transmisiones en tiempo real.

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

La vía 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 entrada FP32. Está habilitada por defecto 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

Características de Cargo#

Las características se habilitan en tiempo de compilación. Las opciones por defecto cubren la anotación y la visualización en vivo.

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 están disponibles otros proveedores adicionales como nnapi, qnn, xnnpack, webgpu, entre otros.

Habilita las características al instalar la CLI o al añadir la librería:

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

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

Salida y guardado#

Por defecto, las predicciones se anotan y se guardan en un directorio de ejecución con incremento automático:

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

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

FAQ#

¿Necesito tener Python instalado?#

¿No. El crate ejecuta modelos ONNX exportados directamente a través de ONNX Runtime. Python solo es necesario si entrenas o exportas modelos con el paquete de Ultralytics de antemano.

¿Qué modelos puedo ejecutar?#

Cualquier modelo YOLO de Ultralytics exportado a ONNX, incluidos YOLO26, YOLO11 y YOLOv8. Los nombres de modelos conocidos se descargan automáticamente; también puedes apuntar --model a cualquier archivo local .onnx.

¿Cómo obtengo un archivo de modelo?#

Exporta desde el paquete de Python, por ejemplo con la integración de ONNX, o deja que la CLI descargue un modelo nano estándar para la tarea elegida en la primera ejecución.

¿Es compatible con vídeo?#

Sí, con la característica video habilitada y FFmpeg 7+ instalado en el sistema. Esto cubre archivos de vídeo, cámaras web y flujos RTSP/RTMP/HTTP.

¿Qué hacen las características annotate y visualize?#

Ambas están habilitadas de forma predeterminada. annotate dibuja cuadros, máscaras, puntos clave y etiquetas de clase en la imagen y es necesario para que --save escriba los resultados anotados. visualize abre una ventana en directo para --show. Para una compilación más pequeña y sin interfaz que solo devuelva resultados de forma programática, desactívalas con cargo build --no-default-features (añade de nuevo las características individuales según sea necesario).

¿Dónde está la referencia completa de la API?#

Esta página es una descripción general de alto nivel. La referencia de la API completa y tipo por tipo para cada estructura, método y opción de configuración públicos se publica en docs.rs, generada directamente desde el código fuente.