Ultralytics Inference para Rust#

Ultralytics Inference é uma biblioteca de inferência e ferramenta de linha de comando de alto desempenho para YOLO escrita em Rust. Ela executa modelos ONNX exportados por meio do ONNX Runtime para entregar previsões rápidas e seguras em termos de memória em imagens, vídeos, webcams e transmissões, sem a necessidade de um ambiente de execução Python no momento da inferência.

O projeto é distribuído como um único crate, ultralytics-inference, que podes usar de duas formas: como uma CLI para previsões rápidas e tarefas em lote, ou como uma biblioteca integrada diretamente na tua aplicação Rust. Ele suporta todas as tarefas da Ultralytics e um amplo conjunto de backends de hardware através de uma interface de dispositivo uniforme.

Por que inferência em Rust?#

• Velocidade nativa e baixo consumo. Compila para um binário nativo sem interpretador, ideal para servidores, contentores e dispositivos de borda.
• Segurança de memória. O modelo de ownership do Rust elimina classes inteiras de erros de runtime sem a necessidade de um coletor de lixo.
• Todas as tarefas do YOLO. Detecção, segmentação, segmentação semântica, estimativa de profundidade, classificação, pose e OBB a partir de uma única API.
• Amplo suporte a hardware. CPU além de CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm e provedores de execução XNNPACK selecionados no momento da compilação.
• Pré-processamento no lado da GPU. Um kernel CUDA fundido opcional mantém o letterbox, normalização e conversão de layout no dispositivo para um caminho de entrada zero-copy.
• Download automático. Nomes de modelos YOLO conhecidos e assets de exemplo são descarregados automaticamente na primeira utilização.

Instalação#

É necessário o Rust 1.89 ou mais recente. O recurso de vídeo também exige o FFmpeg 7+ instalado no 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

Quickstart da CLI#

A CLI expõe um subcomando predict. Sem argumentos, ele descarrega um modelo de detecção nano e imagens de amostra, executa a inferência e guarda os resultados anotados em 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 comuns:

Quickstart da biblioteca#

Carrega um modelo e executa uma previsão. Metadados do modelo como nomes de classes, tipo de tarefa e tamanho da imagem são lidos automaticamente a partir do ficheiro 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 limiares, tamanho da imagem, precisão e dispositivo com uma API de construtor:

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 tarefa preenche um campo diferente em Results. Cada aba abaixo é um programa completo e executável; o modelo e as entradas de amostra são descarregados automaticamente na primeira execução. Substitui predict_default() por predict("image.jpg") para executar com os teus próprios ficheiros.

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

Tarefas suportadas#

Todas as tarefas da Ultralytics são suportadas. Quando --model é omitido, o modelo nano correspondente para a tarefa selecionada é descarregado automaticamente.

Compatibilidade de modelos#

Qualquer modelo da Ultralytics exportado para ONNX pode ser carregado a partir de um ficheiro local. O descarregamento automático está disponível para os nomes de modelos padrão YOLO26, YOLO11 e YOLOv8 nos tamanhos n, s, m, l e x:

A segmentação semântica (-sem) e a estimativa de profundidade (-depth) são exclusivas do YOLO26.

Fontes de entrada#

O argumento --source (e o tipo Source na biblioteca) aceita vários tipos de entrada, detectados automaticamente a partir da string:

Dispositivos e provedores de execução#

A inferência é executada na CPU por predefinição. Os backends de GPU e aceleradores são compilados como recursos do Cargo e selecionados em tempo de execução com --device (CLI) ou Device (biblioteca).

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

Aceleração por GPU e pré-processamento CUDA#

Em hardware NVIDIA, o recurso cuda ativa o provedor de execução CUDA, e tensorrt adiciona o provedor TensorRT para otimização adicional. Para a menor latência possível, o recurso cuda-preprocess move o pré-processamento para a GPU.

cuda-preprocess executa o redimensionamento letterbox, a normalização e a conversão de layout HWC para CHW como um único kernel CUDA fundido, enviando depois o resultado para o modelo como um tensor de dispositivo zero-copy. Isso remove o custo de pré-processamento de CPU por imagem e a cópia de host para dispositivo, o que é mais importante para lotes de alto rendimento e transmissões em tempo real.

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

O caminho rápido é usado automaticamente, sem alterações na API, quando todas as condições a seguir são atendidas: o recurso está compilado, o dispositivo é CUDA ou TensorRT, a tarefa é detect, segment, pose, OBB, segmentação semântica ou estimativa de profundidade, e o modelo usa entrada FP32. Ele é habilitado por padrão e pode ser desativado por modelo:

use ultralytics_inference::{Device, InferenceConfig};

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

Funcionalidades Cargo#

As funcionalidades são ativadas no momento da compilação. Os padrões cobrem anotação e exibição ao vivo.

Grupos de conveniência agrupam provedores relacionados: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) e all (annotate, visualize, video). Provedores adicionais como nnapi, qnn, xnnpack, webgpu e outros também estão disponíveis.

Habilite funcionalidades ao instalar a CLI ou adicionar a biblioteca:

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

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

Saída e salvamento#

Por padrão, as predições são anotadas e salvas em um diretório de execução com incremento automático:

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

A subpasta corresponde à tarefa (runs/segment/, runs/pose/, e assim por diante). Para fontes de vídeo, a saída anotada é gravada como um ficheiro de vídeo; passa --save-frames para gravar fotogramas individuais em vez disso. Para a tarefa semantic, --save-json grava PNGs de mapas de classe por pixel sob uma subpasta results/. Para a tarefa depth, o mapa de profundidade colorido é misturado sobre a imagem de origem, correspondendo à saída plot() do Python da Ultralytics. Guardar imagens e vídeos anotados requer o recurso annotate; a exportação de PNG de mapas de classe semânticos não requer. A entrada e saída de vídeo requerem o recurso video.

FAQ#