Inferência Ultralytics para Rust#

A Inferência Ultralytics é uma biblioteca de inferência YOLO de alto desempenho e uma ferramenta de linha de comandos escrita em Rust. Executa modelos ONNX exportados através do ONNX Runtime para fornecer predições rápidas e seguras em termos de memória em imagens, vídeos, webcams e streams, sem necessidade de um runtime Python no momento da inferência.

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

Porquê inferência em Rust?#

• Velocidade nativa e footprint reduzido. Compila para um binário nativo sem interpretador, ideal para servidores, contentores e dispositivos edge.
• Segurança de memória. O modelo de ownership do Rust elimina classes inteiras de erros em runtime sem um garbage collector.
• Todas as tarefas YOLO. Deteção, segmentação, segmentação semântica, estimativa de profundidade, classificação, pose e OBB através de uma única API.
• Amplo suporte de hardware. CPU, além de CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm e fornecedores 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, a normalização e a conversão de layout no dispositivo, permitindo um fluxo de entrada sem cópia.
• Transferência automática. Os nomes conhecidos de modelos YOLO e os recursos de exemplo são transferidos automaticamente na primeira utilização.

Instalação#

É necessário Rust 1.89 ou posterior. A funcionalidade video também requer que o FFmpeg 7+ esteja 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

Início rápido da CLI#

A CLI disponibiliza um subcomando predict. Sem argumentos, transfere um modelo nano de deteção e imagens de exemplo, 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

Opções comuns:

Início rápido da biblioteca#

Carrega um modelo e executa uma predição. Os metadados do modelo, como nomes das classes, tipo de tarefa e tamanho da imagem, são lidos automaticamente 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 através de uma API de 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 tarefa preenche um campo diferente em Results. Cada separador abaixo é um programa completo e executável; o modelo e as entradas de exemplo são transferidos automaticamente na primeira execução. Substitui predict_default() por predict("image.jpg") para executar nos 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 à tarefa selecionada é transferido automaticamente.

Compatibilidade dos modelos#

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

A segmentação semântica (-sem) e a estimativa de profundidade (-depth) estão disponíveis apenas no YOLO26.

Fontes de entrada#

O argumento --source (e o tipo Source na biblioteca) aceita muitos tipos de entrada, detetados automaticamente a partir da string:

Dispositivos e fornecedores de execução#

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

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

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

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

cuda-preprocess executa o redimensionamento letterbox, a normalização e a conversão de layout de HWC para CHW como um único kernel CUDA fundido, e depois envia o resultado para o modelo como um tensor de dispositivo sem cópia. Isto elimina o custo do pré-processamento de cada imagem na CPU e da cópia do host para o dispositivo, algo especialmente importante para lotes de alto débito e streams em tempo real.

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

O caminho rápido é utilizado automaticamente, sem alterações à API, quando todas as condições seguintes se verificam: a funcionalidade está compilada, o dispositivo é CUDA ou TensorRT, a tarefa é detect, segment, pose, OBB, segmentação semântica ou estimativa de profundidade, e o modelo utiliza entrada FP32. Está ativado por predefiniçã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 do Cargo#

As funcionalidades são ativadas no momento da compilação. As predefinições abrangem a anotação e a apresentação em tempo real.

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

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

Saída e gravação#

Por predefinição, as previsões são anotadas e guardadas num diretório de execução com numeração automática:

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; passe --save-frames para gravar fotogramas individuais. Para a tarefa semantic, --save-json grava PNGs de mapas de classes por píxel numa subpasta results/. Para a tarefa depth, o mapa de profundidade colorido é combinado com a imagem de origem, correspondendo à saída plot() do Ultralytics Python. A gravação de imagens e vídeos anotados requer a funcionalidade annotate; a exportação de PNGs de mapas de classes semânticas não requer essa funcionalidade. A entrada e a saída de vídeo requerem a funcionalidade video.

Perguntas frequentes#