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. 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
--savegera a mesma imagem queplot().
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,tensorrtO 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 falseTodas as flags de predict:
| Opção | Padrão | Descrição |
|---|---|---|
--model, -m | yolo26n.onnx | Caminho para um modelo ONNX ou uma exportação OpenVINO; um nome conhecido de YOLO é transferido automaticamente. |
--task | detect | Um de detect, segment, semantic, depth, classify, pose, obb; seleciona o modelo nano quando --model é omitido. |
--source, -s | amostra | Imagem, diretório, padrão glob, vídeo, índice da webcam, stream ou URL. |
--conf | 0.25 | Limite de confiança. |
--iou | 0.5 | Limite de IoU para supressão não máxima. |
--max-det | 300 | Número máximo de detecções por imagem. |
--imgsz | metadados do modelo | Tamanho da imagem de inferência. |
--rect [<BOOL>] | true | Inferência retangular com preenchimento mínimo. |
--tile [<TILE>] | desativado | Tamanho dos blocos para inferência com janelas sobrepostas; --tile sem valor usa --imgsz. Consulta inferência em blocos. |
--retina-masks | false | Cria máscaras de segmentação no tamanho original da imagem em vez de no tamanho de inferência. |
--ocr | false | Lê o texto em cada caixa, caixa orientada ou máscara com PaddleOCR; sem --model, executa yolo26n-text.onnx. Consulta OCR. |
--batch | 1 | Tamanho do lote para inferência. |
--quantize | precisão do modelo | Precisão da inferência: 8, 16, 32, int8, fp16, fp32, w8a8, w16a16, w32a32, w8a16 ou w8a32. |
--save [<BOOL>] | true | Salvar os resultados anotados em runs/<task>/predict. |
--save-frames | false | Salvar quadros individuais para entradas de vídeo em vez de um arquivo de vídeo. |
--save-json | false | Salvar mapas de classes de segmentação semântica em PNG. |
--show | false | Exibir os resultados em uma janela. |
--show-labels [<BOOL>] | true | Mostra os nomes das classes nos rótulos das caixas. |
--show-conf [<BOOL>] | true | Mostra as confianças nos rótulos das caixas. |
--show-boxes [<BOOL>] | true | Desenha as caixas e os respetivos rótulos. |
--line-width | do tamanho da imagem | Largura da linha das caixas em píxeis, que também determina o tamanho dos rótulos. |
--device | automático | Dispositivo de execução, por exemplo, cpu, cuda:0, tensorrt:0, coreml, intel:gpu, directml:0, rocm:0, migraphx:0, xnnpack. |
--verbose [<BOOL>] | true | Imprimir resultados por imagem e tempos. |
--classes | todos | Filtra 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 | --task | Saída | Modelo padrão |
|---|---|---|---|
| Deteção | detect | Caixas delimitadoras e classes | yolo26n.onnx |
| Segmentação de instâncias | segment | Caixas e máscaras por instância | yolo26n-seg.onnx |
| Segmentação semântica | semantic | Mapa de classes por pixel | yolo26n-sem.onnx |
| Estimativa de profundidade | depth | Mapa de profundidade por pixel em metros | yolo26n-depth.onnx |
| Classificação | classify | Probabilidades das classes | yolo26n-cls.onnx |
| Pose | pose | Caixas e pontos-chave | yolo26n-pose.onnx |
| Caixas orientadas | obb | Caixas delimitadoras rotacionadas | yolo26n-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 modelo | Variantes disponíveis para download automático |
|---|---|
| YOLO26 | yolo26{n,s,m,l,x}.onnx, -seg, -sem, -depth, -cls, -pose, -obb e -text |
| YOLO11 | yolo11{n,s,m,l,x}.onnx, -seg, -cls, -pose e -obb |
| YOLOv8 | yolov8{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:
| Fonte | Exemplo | Observações |
|---|---|---|
| Imagem | image.jpg | Arquivo único. |
| Diretório | images/ | Todas as imagens na pasta. |
| Glob | images/*.jpg | Padrão no estilo do shell. |
| Vídeo | video.mp4 | Requer o recurso video. |
| Webcam | 0 | Requer o recurso video. |
| Fluxo | rtsp://... | Requer o recurso video. |
| URL | https://example.com/image.jpg | Download 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 640use 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:0O 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 dispositivo | Variante Device | Recurso de compilação | Hardware |
|---|---|---|---|
cpu | Device::Cpu | integrado | Qualquer CPU |
cuda:0 | Device::Cuda(0) | cuda | GPU NVIDIA |
tensorrt:0 | Device::TensorRt(0) | tensorrt | GPU NVIDIA, otimizada |
coreml | Device::CoreMl | coreml | Apple Silicon / macOS |
intel:cpu | Device::IntelCpu | openvino ou openvino-native | CPU Intel |
intel:gpu | Device::IntelGpu | openvino ou openvino-native | GPU Intel |
intel:npu | Device::IntelNpu | openvino ou openvino-native | NPU Intel |
directml:0 | Device::DirectMl(0) | directml | GPU Windows |
rocm:0 | Device::Rocm(0) | rocm | GPU AMD |
migraphx:0 | Device::MiGraphX(0) | migraphx | GPU AMD (Linux x64) |
xnnpack | Device::Xnnpack | xnnpack | CPU otimizada |
# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrtModelos 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:gpuAceleraçã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-preprocessO 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 preprocessingcuda-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.
| Funcionalidade | Padrão | Finalidade |
|---|---|---|
annotate | sim | Desenha caixas, máscaras, pontos-chave, rótulos e textos OCR; necessário para --save. |
visualize | sim | Exibição em janela em tempo real para --show. |
video | não | Ler e gravar arquivos de vídeo (requer FFmpeg 6 a 9). |
cuda | não | Provedor de execução NVIDIA CUDA. |
tensorrt | não | Provedor de execução NVIDIA TensorRT (inclui cuda). |
cuda-preprocess | não | Pré-processamento combinado na GPU (implica cuda, tensorrt; requer o toolkit CUDA). |
coreml | não | Provedor de execução Apple CoreML. |
openvino | não | Provedor de execução Intel OpenVINO (Linux e Windows x64). |
openvino-native | não | Modelos OpenVINO IR nativos (.xml) através do runtime OpenVINO. |
rocm | não | Provedor de execução AMD ROCm (requer a tua própria compilação do ONNX Runtime). |
migraphx | não | Provedor de execução AMD MIGraphX (Linux x64). |
directml | não | Provedor de execução Windows DirectML. |
xnnpack | não | Provedor 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 resultA 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.
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.
--ocrlê 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 640divide a imagem em janelas sobrepostas de 640 px e combina novamente as deteções num único resultado.Sim, com o recurso
videoativado 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.
annotatedesenha caixas, máscaras, pontos-chave e rótulos de classe na imagem e é necessário para que--savegrave resultados anotados.visualizeabre 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 comcargo 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.