Começar

Inferência Ultralytics para Rust

Ultralytics Inference GitHub Ultralytics Inference Crates.io Ultralytics Inference docs.rs Ultralytics Inference Downloads Ultralytics Inference MSRV

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. Detecta, segmenta, faz segmentação semântica, estima profundidade, classifica, estima poses e deteta OBB com uma única API, além de executar OCR de texto em cenas e inferência em blocos para imagens grandes.
  • Amplo suporte de hardware. CPU e provedores de execução CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm, MIGraphX e XNNPACK, selecionados no momento da compilação, além de modelos OpenVINO IR nativos.
  • 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. Nomes conhecidos de modelos YOLO, os modelos OCR e os recursos de exemplo são transferidos automaticamente na primeira utilização.
  • A mesma saída que em Python. As máscaras, os contornos das máscaras e os resultados desenhados seguem o pacote Ultralytics para Python, pelo que --save gera a mesma imagem que plot().
À procura do pacote Python?

Esta página aborda o crate Rust autónomo. Para o fluxo de trabalho Python (treinamento, validação, exportação e previsão), consulta o Início rápido e o modo de previsão principais. Exporta qualquer modelo Ultralytics para ONNX com a integração ONNX e executa-o aqui.

Instalação#

É necessário ter Rust 1.92 ou mais recente. O recurso de vídeo 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

O binário é colocado em ~/.cargo/bin/ultralytics-inference (Linux e macOS) ou %USERPROFILE%\.cargo\bin\ no Windows.

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

# Tile a large aerial image into overlapping 640 px windows to find small objects
ultralytics-inference predict --model yolo26n-obb.onnx --source aerial.jpg --tile 640

# Read scene text (auto-downloads yolo26n-text.onnx and the PaddleOCR models)
ultralytics-inference predict --ocr --source sign.jpg

# Thicker lines, no confidences in labels
ultralytics-inference predict --source image.jpg --line-width 4 --show-conf false

Todas as flags de predict:

OpçãoPadrãoDescrição
--model, -myolo26n.onnxCaminho para um modelo ONNX ou uma exportação OpenVINO; um nome conhecido de YOLO é transferido automaticamente.
--taskdetectUm de detect, segment, semantic, depth, classify, pose, obb; seleciona o modelo nano quando --model é omitido.
--source, -samostraImagem, diretório, padrão glob, vídeo, índice da webcam, stream ou URL.
--conf0.25Limite de confiança.
--iou0.5Limite de IoU para supressão não máxima.
--max-det300Número máximo de detecções por imagem.
--imgszmetadados do modeloTamanho da imagem de inferência.
--rect [<BOOL>]trueInferência retangular com preenchimento mínimo.
--tile [<TILE>]desativadoTamanho dos blocos para inferência com janelas sobrepostas; --tile sem valor usa --imgsz. Consulta inferência em blocos.
--retina-masksfalseCria máscaras de segmentação no tamanho original da imagem em vez de no tamanho de inferência.
--ocrfalseLê o texto em cada caixa, caixa orientada ou máscara com PaddleOCR; sem --model, executa yolo26n-text.onnx. Consulta OCR.
--batch1Tamanho do lote para inferência.
--quantizeprecisão do modeloPrecisão da inferência: 8, 16, 32, int8, fp16, fp32, w8a8, w16a16, w32a32, w8a16 ou w8a32.
--save [<BOOL>]trueSalvar os resultados anotados em runs/<task>/predict.
--save-framesfalseSalvar quadros individuais para entradas de vídeo em vez de um arquivo de vídeo.
--save-jsonfalseSalvar mapas de classes de segmentação semântica em PNG.
--showfalseExibir os resultados em uma janela.
--show-labels [<BOOL>]trueMostra os nomes das classes nos rótulos das caixas.
--show-conf [<BOOL>]trueMostra as confianças nos rótulos das caixas.
--show-boxes [<BOOL>]trueDesenha as caixas e os respetivos rótulos.
--line-widthdo tamanho da imagemLargura da linha das caixas em píxeis, que também determina o tamanho dos rótulos.
--deviceautomáticoDispositivo de execução, por exemplo, cpu, cuda:0, tensorrt:0, coreml, intel:gpu, directml:0, rocm:0, migraphx:0, xnnpack.
--verbose [<BOOL>]trueImprimir resultados por imagem e tempos.
--classestodosFiltra deteções por IDs de classe, por exemplo, 0, "0,1,2" ou "[0, 1, 2]".

[<BOOL>] indica uma flag cujo valor é opcional: se a passares sem valor (--rect), define-a como true, e --rect false desativa-a. A flag antiga --half continua a ser aceite, é mapeada para --quantize 16 e apresenta o mesmo aviso de descontinuação que o pacote Python.

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.

Tarefa--taskSaídaModelo padrão
DeteçãodetectCaixas delimitadoras e classesyolo26n.onnx
Segmentação de instânciassegmentCaixas e máscaras por instânciayolo26n-seg.onnx
Segmentação semânticasemanticMapa de classes por pixelyolo26n-sem.onnx
Estimativa de profundidadedepthMapa de profundidade por pixel em metrosyolo26n-depth.onnx
ClassificaçãoclassifyProbabilidades das classesyolo26n-cls.onnx
PoseposeCaixas e pontos-chaveyolo26n-pose.onnx
Caixas orientadasobbCaixas delimitadoras rotacionadasyolo26n-obb.onnx

--ocr adiciona a leitura de texto em cenas a qualquer modelo de deteção, segmentação ou OBB; sem --model, executa o detetor de texto yolo26n-text.onnx. Consulta OCR de texto em cenas.

Compatibilidade de modelos#

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

Família do modeloVariantes disponíveis para download automático
YOLO26yolo26{n,s,m,l,x}.onnx, -seg, -sem, -depth, -cls, -pose, -obb e -text
YOLO11yolo11{n,s,m,l,x}.onnx, -seg, -cls, -pose e -obb
YOLOv8yolov8{n,s,m,l,x}.onnx, -seg, -cls, -pose e -obb

A segmentação semântica (-sem), a estimativa de profundidade (-depth) e os detetores de texto em cenas -text estão disponíveis apenas no YOLO26. O reconhecedor PaddleOCR PP-OCRv6_medium_rec.onnx e o classificador de orientação PP-LCNet_x0_25_textline_ori.onnx usados por --ocr (Apache-2.0) também são transferidos automaticamente. Os modelos de deteção RT-DETR também são executados, mas não são transferidos automaticamente: primeiro, exporta um para ONNX. As exportações nativas OpenVINO IR são executadas com a funcionalidade openvino-native; consulta Modelos OpenVINO IR.

Fontes de entrada#

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

FonteExemploObservações
Imagemimage.jpgArquivo único.
Diretórioimages/Todas as imagens na pasta.
Globimages/*.jpgPadrão no estilo do shell.
Vídeovideo.mp4Requer o recurso video.
Webcam0Requer o recurso video.
Fluxortsp://...Requer o recurso video.
URLhttps://example.com/image.jpgDownload de imagem remota.

Inferência em blocos#

Imagens grandes com objetos pequenos, como fotografias aéreas ou de satélite, podem ser divididas em janelas sobrepostas e combinadas novamente num único resultado, tal como com o argumento tile de Python. As janelas sobrepõem-se em 20%, as caixas são mapeadas de volta para a imagem de origem e as duplicadas são removidas por classe. Com uma exportação de lote dinâmico, --batch processa várias janelas numa única chamada de inferência. Todas as tarefas são suportadas.

# 640 px windows; a bare --tile uses --imgsz
ultralytics-inference predict --model yolo26n-obb.onnx --source aerial.jpg --tile 640
use ultralytics_inference::{InferenceConfig, YOLOModel};

// with_tile(0) uses the inference size
let config = InferenceConfig::new().with_tile(640);
let mut model = YOLOModel::load_with_config("yolo26n.onnx", config)?;
let results = model.predict("aerial.jpg")?;

OCR de texto em cenas#

Os detetores YOLO26-Text encontram palavras em caixas orientadas e TextRecognizer lê-as com o PP-OCRv6 do PaddleOCR, o mesmo reconhecedor usado pela solução de OCR Python. Também funcionam caixas de modelos de deteção e máscaras de modelos de segmentação: a máscara é lida a partir do retângulo de área mínima em torno do seu contorno e mantém o contorno como polígono. Cada recorte é rodado para ficar na vertical; se o classificador de orientação detetar texto invertido, este é lido novamente depois de rodado. Os textos são devolvidos pela ordem de leitura. O reconhecedor é executado no dispositivo do detetor.

# Auto-downloads yolo26n-text.onnx and the PaddleOCR models
ultralytics-inference predict --ocr --source sign.jpg

# Any size of the text detector, on the GPU
ultralytics-inference predict --ocr --model yolo26x-text.onnx --source sign.jpg --device cuda:0

O exemplo da biblioteca carrega a imagem com o crate image; por isso, adiciona-o junto ao pacote com cargo add image.

use ultralytics_inference::YOLOModel;
use ultralytics_inference::ocr::{DEFAULT_ORIENTATION, DEFAULT_RECOGNIZER, TextRecognizer};

let mut detector = YOLOModel::load("yolo26n-text.onnx")?;
let mut ocr = TextRecognizer::new(&detector, DEFAULT_RECOGNIZER, DEFAULT_ORIENTATION)?;
let image = image::open("sign.jpg")?;
let result = detector.predict_image(&image, "sign.jpg".into())?.remove(0);
for text in ocr.read(&image, &result)? {
    println!("{} {:.2} {:?}", text.text, text.confidence, text.polygon);
}

predict --ocr desenha cada texto como a solução para Python, e --line-width, --show-labels e --show-conf também se aplicam ao texto.

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.

Identificador do dispositivoVariante DeviceRecurso de compilaçãoHardware
cpuDevice::CpuintegradoQualquer CPU
cuda:0Device::Cuda(0)cudaGPU NVIDIA
tensorrt:0Device::TensorRt(0)tensorrtGPU NVIDIA, otimizada
coremlDevice::CoreMlcoremlApple Silicon / macOS
intel:cpuDevice::IntelCpuopenvino ou openvino-nativeCPU Intel
intel:gpuDevice::IntelGpuopenvino ou openvino-nativeGPU Intel
intel:npuDevice::IntelNpuopenvino ou openvino-nativeNPU Intel
directml:0Device::DirectMl(0)directmlGPU Windows
rocm:0Device::Rocm(0)rocmGPU AMD
migraphx:0Device::MiGraphX(0)migraphxGPU AMD (Linux x64)
xnnpackDevice::XnnpackxnnpackCPU otimizada
# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrt

Modelos OpenVINO IR#

Com a funcionalidade openvino-native, --model também aceita uma exportação nativa OpenVINO, o ficheiro .xml ou a pasta de yolo export format=openvino, e executa-a através do runtime OpenVINO em vez do ONNX Runtime. Todas as tarefas são executadas em intel:cpu, intel:gpu e intel:npu, e a biblioteca carrega o modelo com YOLOModel::load("yolo26n_openvino_model"). Não é necessário instalar o OpenVINO para compilar; o runtime é carregado quando o primeiro modelo é aberto. Consulta o guia do OpenVINO para saber como configurar.

yolo export model=yolo26n.pt format=openvino # add quantize=16, quantize=8, dynamic=True, or batch=4
ultralytics-inference predict --model yolo26n_openvino_model --source bus.jpg --device intel:gpu

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

Em hardware NVIDIA, a funcionalidade cuda ativa o provedor de execução CUDA, e tensorrt adiciona o provedor TensorRT para otimização adicional (inclui cuda, que também executa o reconhecedor OCR). Para obter a menor latência de inferência possível, a funcionalidade 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 à API, quando se verificam todas as condições seguintes: a funcionalidade está incluída na compilação; o dispositivo é CUDA, TensorRT ou não está definido; a tarefa é deteção, segmentação, segmentação semântica (apenas imagens individuais), estimativa de profundidade, estimativa de poses ou OBB; e o modelo usa 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
Use o toolkit CUDA correspondente

cuda-preprocess requer um toolkit CUDA correspondente durante a compilação e usa NVRTC em tempo de execução para o kernel de pré-processamento fundido. Consulte o guia de aceleração CUDA e TensorRT para ver os requisitos de versão e solucionar problemas.

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.

FuncionalidadePadrãoFinalidade
annotatesimDesenha caixas, máscaras, pontos-chave, rótulos e textos OCR; necessário para --save.
visualizesimExibição em janela em tempo real para --show.
videonãoLer e gravar arquivos de vídeo (requer FFmpeg 6 a 9).
cudanãoProvedor de execução NVIDIA CUDA.
tensorrtnãoProvedor de execução NVIDIA TensorRT (inclui cuda).
cuda-preprocessnãoPré-processamento combinado na GPU (implica cuda, tensorrt; requer o toolkit CUDA).
coremlnãoProvedor de execução Apple CoreML.
openvinonãoProvedor de execução Intel OpenVINO (Linux e Windows x64).
openvino-nativenãoModelos OpenVINO IR nativos (.xml) através do runtime OpenVINO.
rocmnãoProvedor de execução AMD ROCm (requer a tua própria compilação do ONNX Runtime).
migraphxnãoProvedor de execução AMD MIGraphX (Linux x64).
directmlnãoProvedor de execução Windows DirectML.
xnnpacknãoProvedor de execução XNNPACK para inferência otimizada na CPU.

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). Também estão disponíveis os provedores adicionais onednn, nnapi, qnn, acl, tvm, rknpu, cann, webgpu e azure.

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.58", 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.

O desenho segue o Results.plot() para Python: a largura da linha é, por predefinição, 0,3% da média dos lados da imagem (no mínimo 2 px), os rótulos ficam acima de cada caixa ou dentro dela quando não há espaço, e as máscaras de instância são combinadas da mesma forma, para que as imagens guardadas correspondam às geradas em Python. --line-width, --show-labels, --show-conf e --show-boxes funcionam como os argumentos homónimos de Python. Na biblioteca, passa-os através de AnnotateOptions:

use ultralytics_inference::annotate::{AnnotateOptions, annotate_image_with_options};

let options = AnnotateOptions {
    line_width: Some(3),
    show_conf: false,
    ..Default::default()
};
let annotated = annotate_image_with_options(&image, &results[0], &options);

As máscaras de segmentação são criadas no tamanho de inferência, tal como em Python; passa --retina-masks (ou InferenceConfig::with_retina_masks(true)) para as criar no tamanho original da imagem.

Perguntas frequentes#

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

  • Qualquer modelo YOLO da Ultralytics 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.

  • Exporte usando o 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.

  • Sim. --ocr lê texto em cenas com um detetor YOLO26-Text e PaddleOCR, tal como a solução de OCR para Python, e também funciona com as caixas ou máscaras dos teus próprios modelos de deteção e segmentação. Consulta OCR de texto em cenas.

  • Usa a inferência em blocos: --tile 640 divide a imagem em janelas sobrepostas de 640 px e combina novamente as deteções num único resultado.

  • Sim, com o recurso video ativado e o FFmpeg 6 a 9 instalado no sistema. Isso abrange arquivos de vídeo, webcams e transmissões RTSP/RTMP/HTTP.

  • Ambos estão ativados por padrão. annotate desenha caixas, máscaras, pontos-chave e rótulos de classe na imagem e é necessário para que --save grave resultados anotados. visualize abre uma janela ao vivo para --show. Para uma compilação menor e sem interface gráfica que retorne apenas resultados de forma programática, desative-os com cargo build --no-default-features (reative recursos individuais conforme necessário).

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

Comentários

Faz uma pergunta, partilha os teus resultados ou ajuda alguém.