Link to this sectionInferencia de Ultralytics para Rust#

Ultralytics Inference es una biblioteca de inferencia de 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 en cuanto a memoria en imágenes, vídeos, webcams y transmisiones, sin necesidad de un 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 una biblioteca integrada directamente en tu aplicación Rust. Es compatible con todas las tareas de Ultralytics y con una amplia gama de backends de hardware a través de una interfaz de dispositivo unificada.

Link to this section¿Por qué la inferencia en Rust?#

• Velocidad nativa y tamaño reducido. Se compila en un binario nativo sin intérprete, 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. Detección, segmentación, pose, OBB, clasificación y segmentación semántica desde una misma 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.

Link to this sectionInstalación#

Se requiere Rust 1.89 o superior. La función vídeo necesita además 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

Link to this sectionInicio 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

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

Link to this sectionInicio 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 umbrales, tamaño de imagen, precisión y dispositivo con una API de constructor:

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

Link to this sectionTareas admitidas#

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

Link to this sectionCompatibilidad de modelos#

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

La segmentación semántica (-sem) es exclusiva de YOLO26.

Link to this sectionFuentes 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:

Link to this sectionDispositivos y proveedores de ejecución#

La inferencia se ejecuta en la CPU por defecto. 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

Link to this sectionAceleración por GPU y preprocesamiento CUDA#

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

cuda-preprocess ejecuta el cambio de tamaño tipo letterbox, la normalización y la conversión de diseño HWC a CHW como un único núcleo CUDA fusionado, y luego envía el resultado al modelo como un tensor de dispositivo de copia cero. Esto elimina el coste de preprocesamiento en la CPU por imagen y la copia de host a dispositivo, lo cual es fundamental para lotes de alto rendimiento y flujos 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 característica está compilada, el dispositivo es CUDA o TensorRT, la tarea es detect, segment, pose, OBB o segmentación semántica, y el modelo utiliza entrada FP32. Está habilitada por defecto y se puede desactivar por modelo:

use ultralytics_inference::{Device, InferenceConfig};

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

Link to this sectionCaracterí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). Otros proveedores como nnapi, qnn, xnnpack, webgpu y otros también están disponibles.

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.18", features = ["video"] }

Link to this sectionSalida 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; usa --save-frames para escribir fotogramas individuales. Para la tarea semantic, --save-json escribe PNGs de mapas de clases por píxel en una subcarpeta results/. 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.

Link to this sectionFAQ#

Link to this section¿Necesito tener Python instalado?#

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

Link to this section¿Qué modelos puedo ejecutar?#

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

Link to this section¿Cómo obtengo un archivo de modelo?#

Expórtalo 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.

Link to this section¿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, webcams y flujos RTSP/RTMP/HTTP.

Link to this section¿Qué hacen las características annotate y visualize?#

Ambas están habilitadas por defecto. annotate dibuja cajas, 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 vivo para --show. Para una compilación más ligera y sin interfaz gráfica (headless) que solo devuelva resultados mediante programación, desactívalas con cargo build --no-default-features (vuelve a añadir las características individuales según sea necesario).

Link to this section¿Dónde está la referencia completa de la API?#

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