Inferência Ultralytics para Rust#

Ultralytics Inference é uma biblioteca de inferência de alto desempenho para YOLO e uma ferramenta de linha de comandos, escrita em Rust. Executa modelos ONNX exportados através do ONNX Runtime para gerar previsões rápidas e seguras em termos de memória em imagens, vídeos, webcams e transmissões, sem precisar do runtime Python durante a inferência.

O projeto é distribuído como um único crate, ultralytics-inference, que podes usar de duas formas: como CLI para previsões rápidas e tarefas em lote, ou como biblioteca incorporada diretamente na tua aplicação Rust. Suporta todas as tarefas da Ultralytics e uma ampla variedade de backends de hardware através de uma interface de dispositivo uniforme. Para inferência no navegador, o mesmo repositório publica o pacote npm @ultralytics/yolo; consulta o guia de configuração.

Porquê inferência com Rust?#

• Velocidade nativa e dimensão reduzida. Compila para um binário nativo sem interpretador, ideal para servidores, contentores e dispositivos de ponta.
• Segurança da memória. O modelo de propriedade do Rust elimina categorias inteiras de erros em tempo de execução sem um coletor de lixo.
• Todas as tarefas YOLO. Deteta, segmenta, faz segmentação semântica, estima profundidade, classifica, estima pose e deteta OBB através de uma única API.
• Amplo suporte de hardware. CPU, além dos fornecedores de execução CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm e XNNPACK selecionados durante a compilação.
• Pré-processamento na GPU. Um kernel CUDA fundido opcional executa letterbox, normalização e conversão de layout na GPU e fornece o resultado ao modelo sem sair do dispositivo.
• 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 superior. A funcionalidade video também requer que o FFmpeg 6 a 9 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 de deteção nano 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 --quantize 16

Opções comuns:

Início rápido da biblioteca#

Carregue um modelo e execute uma previsão. Os metadados do modelo, como nomes das classes, tipo de tarefa e tamanho da imagem, são lidos automaticamente do arquivo 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(())
}

Use InferenceConfig para controlar os limites, o tamanho da imagem, a precisão e o dispositivo com uma API de construção:

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 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 baixados automaticamente na primeira execução. Substitua predict_default() por predict("image.jpg") para executar com seus próprios arquivos.

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 compatíveis#

Todas as tarefas da Ultralytics são compatíveis. Quando --model é omitido, o modelo nano correspondente à tarefa selecionada é baixado automaticamente.

Compatibilidade de modelos#

Qualquer modelo Ultralytics exportado para ONNX pode ser carregado de um arquivo local. O download automático está disponível para 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) estão disponíveis somente no YOLO26. Os modelos de detecção RT-DETR também são executados, mas não são baixados automaticamente: primeiro, exporte um modelo para ONNX.

Fontes de entrada#

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

Dispositivos e provedores de execuçã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). Sem um dispositivo especificado, os provedores compilados na versão são registrados em uma ordem fixa de preferência (TensorRT primeiro, depois CUDA e assim por diante); portanto, uma versão compilada apenas com os recursos padrão é executada na CPU.

# 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 obter a menor latência possível, o recurso cuda-preprocess transfere o pré-processamento para a GPU.

cuda-preprocess executa o redimensionamento letterbox, a normalização e a conversão de layout HWC para CHW em um único kernel CUDA fundido e, em seguida, fornece o resultado ao modelo como um tensor de dispositivo sem cópia. O quadro bruto de 8 bits ainda é enviado à GPU, por meio de um buffer de preparação fixado em GPUs discretas; o kernel elimina o redimensionamento, a normalização e a conversão de layout na CPU, além do envio separado do tensor pré-processado — algo especialmente importante para lotes de alta vazão e fluxos 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 (somente imagens únicas) ou estimativa de profundidade, e o modelo usa entrada FP32. Ele é ativado 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

Recursos do Cargo#

Os recursos são ativados durante a compilação. As opções padrão incluem anotação e exibição ao vivo.

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

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

Saída e salvamento#

Por padrão, as previsões são anotadas e salvas em um 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 arquivo de vídeo; passe --save-frames para gravar quadros individuais. Para a tarefa semantic, --save-json grava mapas de classes por pixel em PNG em uma subpasta results/. Para a tarefa depth, o mapa de profundidade colorido é mesclado à imagem de origem, como na saída plot() do Python da Ultralytics. O salvamento de imagens e vídeos anotados requer o recurso annotate; a exportação de mapas de classes semânticas em PNG não requer. A entrada e a saída de vídeo requerem o recurso video.

Perguntas frequentes#