Link to this sectionUltralytics Inference para Rust#

O Ultralytics Inference é uma biblioteca de inferência de alto desempenho para YOLO e uma ferramenta de linha de comando escrita em Rust. Ela executa modelos ONNX exportados através do ONNX Runtime para entregar previsões rápidas e com segurança de memória em imagens, vídeos, webcams e fluxos, sem a 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 uma CLI para previsões rápidas e jobs em lote, ou como uma 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 dispositivo unificada.

Link to this sectionPor que inferência em Rust?#

• Velocidade nativa e um tamanho reduzido. Compila para um binário nativo sem interpretador, ideal para servidores, containers e dispositivos de edge.
• 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 YOLO. Deteção, segmentação, pose, OBB, classificação e segmentação semântica 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.

Link to this sectionInstalação#

É necessário Rust 1.89 ou superior. A funcionalidade video necessita adicionalmente do 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

Link to this sectionQuickstart da CLI#

A CLI expõe um subcomando predict. Sem argumentos, descarrega 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

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

Link to this sectionQuickstart 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 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 descarregados 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(())
}

Link to this sectionTarefas suportadas#

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

Link to this sectionCompatibilidade de modelos#

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

A segmentação semântica (-sem) é exclusiva do YOLO26.

Link to this sectionFontes de entrada#

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

Link to this sectionDispositivos e provedores de execução#

A inferência é executada na CPU por padrão. Backends de GPU e aceleradores são compilados como funcionalidades 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

Link to this sectionAceleração por GPU e pré-processamento CUDA#

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

cuda-preprocess executa redimensionamento letterbox, normalização e a conversão de layout HWC para CHW como um único kernel CUDA fundido, enviando então o resultado para o modelo como um tensor de dispositivo zero-copy. Isso elimina o custo de pré-processamento na CPU por imagem e a cópia de host para dispositivo, o que é crucial para lotes de alto rendimento e streams 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: a funcionalidade está compilada, o dispositivo é CUDA ou TensorRT, a tarefa é detect, segment, pose, OBB ou segmentação semântica, 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

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

Link to this sectionSaí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 é escrita como um arquivo de vídeo; passe --save-frames para gravar quadros individuais. Para a tarefa semantic, --save-json grava PNGs de mapa de classes por pixel em uma subpasta results/. O salvamento de imagens e vídeos anotados requer a funcionalidade annotate; a exportação de PNG de mapa de classes semânticas, não. A entrada e saída de vídeo requerem a funcionalidade video.

Link to this sectionFAQ#

Link to this sectionPreciso ter Python instalado?#

Não. O crate executa modelos ONNX exportados diretamente através do ONNX Runtime. Python só é necessário se você treinar ou exportar modelos com o pacote Ultralytics previamente.

Link to this sectionQuais modelos posso executar?#

Qualquer modelo Ultralytics YOLO exportado para ONNX, incluindo YOLO26, YOLO11 e YOLOv8. Nomes de modelos conhecidos são baixados automaticamente; você também pode apontar --model para qualquer arquivo .onnx local.

Link to this sectionComo obtenho um arquivo de modelo?#

Exporte a partir do pacote Python, por exemplo com a integração ONNX, ou deixe a CLI baixar um modelo nano padrão para a tarefa escolhida na primeira execução.

Link to this sectionVídeo é suportado?#

Sim, com a funcionalidade video ativada e FFmpeg 7+ instalado no sistema. Isso cobre arquivos de vídeo, webcams e streams RTSP/RTMP/HTTP.

Link to this sectionO que as funcionalidades annotate e visualize fazem?#

Ambas estão ativadas por padrão. annotate desenha caixas, máscaras, pontos-chave e rótulos de classe na imagem e é necessário para --save gravar resultados anotados. visualize abre uma janela ao vivo para --show. Para uma compilação menor e sem interface gráfica que apenas retorna resultados programaticamente, desative-as com cargo build --no-default-features (adicione de volta funcionalidades individuais conforme necessário).

Link to this sectionOnde está a referência completa da API?#

Esta página é uma visão geral de alto nível. A referência completa da API, tipo por tipo, para cada struct, método e opção de configuração pública é publicada no docs.rs, gerada diretamente a partir do código-fonte.