Инференс Ultralytics для Rust
Ultralytics Inference — высокопроизводительная библиотека инференса YOLO и инструмент командной строки, написанные на Rust. Она запускает экспортированные модели ONNX через ONNX Runtime, обеспечивая быстрые предсказания с безопасным управлением памятью для изображений, видео, веб-камер и потоков; среда выполнения Python для инференса не требуется.
Проект поставляется в виде единственного крейта ultralytics-inference, который можно использовать двумя способами: как CLI для быстрых предсказаний и пакетной обработки или как библиотеку, встроенную непосредственно в приложение на Rust. Он поддерживает все задачи Ultralytics и широкий набор аппаратных бэкендов через единый интерфейс устройств. Для инференса в браузере тот же репозиторий публикует npm-пакет @ultralytics/yolo; см. руководство по настройке.
Зачем использовать Rust для инференса?#
- Нативная скорость и компактность. Компилируется в нативный двоичный файл без интерпретатора — идеальный вариант для серверов, контейнеров и периферийных устройств.
- Безопасность памяти. Модель владения Rust устраняет целые классы ошибок времени выполнения без сборщика мусора.
- Все задачи YOLO. Детекция, сегментация, семантическая сегментация, оценка глубины, классификация, определение позы и OBB через единый API, а также OCR текста в сценах и тайловый инференс для больших изображений.
- Широкая поддержка оборудования. CPU, а также провайдеры выполнения CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm, MIGraphX и XNNPACK, выбираемые при сборке, и модели OpenVINO IR в нативном формате.
- Предобработка на GPU. Дополнительное объединённое ядро CUDA выполняет letterbox, нормализацию и преобразование формата данных на GPU и передаёт результат модели, не покидая устройство.
- Автоматическая загрузка. Известные имена моделей YOLO, модели OCR и примеры ресурсов загружаются автоматически при первом использовании.
- Такой же результат, как в Python. Маски, контуры масок и визуализированные результаты соответствуют пакету Ultralytics для Python, поэтому
--saveсоздаёт такое же изображение, какplot().
На этой странице описан автономный крейт Rust. Информацию о рабочем процессе Python (обучение, валидация, экспорт и предсказание) см. в основном разделе Краткое руководство и в разделе Режим предсказания. Экспортируй любую модель Ultralytics в ONNX с помощью интеграции ONNX, а затем запускай её здесь.
Установка#
Требуется Rust версии 1.92 или новее. Для функции видео дополнительно нужно установить в системе FFmpeg версий с 6 по 9.
# 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Двоичный файл размещается по пути ~/.cargo/bin/ultralytics-inference (Linux и macOS) или %USERPROFILE%\.cargo\bin\ в Windows.
Краткое руководство по CLI#
CLI предоставляет подкоманду predict. Если не указать аргументы, она загружает нано-модель детекции и примеры изображений, запускает инференс и сохраняет изображения с аннотациями в 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Все флаги predict:
| Флаг | По умолчанию | Описание |
|---|---|---|
--model, -m | yolo26n.onnx | Путь к модели ONNX или экспорту OpenVINO; модель с известным именем YOLO загружается автоматически. |
--task | detect | Одно из значений detect, segment, semantic, depth, classify, pose, obb; если --model не задан, выбирает nano-модель. |
--source, -s | образец | Изображение, каталог, шаблон glob, видео, индекс веб-камеры, поток или URL. |
--conf | 0.25 | Порог уверенности. |
--iou | 0.5 | Порог IoU для подавления немаксимумов. |
--max-det | 300 | Максимальное число обнаружений на изображение. |
--imgsz | метаданные модели | Размер изображения для инференса. |
--rect [<BOOL>] | true | Прямоугольный инференс с минимальным дополнением. |
--tile [<TILE>] | выкл. | Размер тайла для инференса с перекрывающимися окнами; если указать --tile без значения, используется --imgsz. См. тайловый инференс. |
--retina-masks | false | Создавать маски сегментации в исходном размере изображения, а не в размере инференса. |
--ocr | false | Считывать текст в каждом боксе, ориентированном боксе или маске с помощью PaddleOCR; если не указан --model, запускается yolo26n-text.onnx. См. OCR. |
--batch | 1 | Размер пакета для инференса. |
--quantize | точность модели | Точность инференса: 8, 16, 32, int8, fp16, fp32, w8a8, w16a16, w32a32, w8a16 или w8a32. |
--save [<BOOL>] | true | Сохранять результаты с аннотациями в runs/<task>/predict. |
--save-frames | false | Сохранять отдельные кадры для видео вместо видеофайла. |
--save-json | false | Сохранять PNG-карты классов для семантической сегментации. |
--show | false | Показывать результаты в окне. |
--show-labels [<BOOL>] | true | Показывать названия классов в метках боксов. |
--show-conf [<BOOL>] | true | Показывать значения уверенности в метках боксов. |
--show-boxes [<BOOL>] | true | Рисовать боксы и их метки. |
--line-width | от размера изображения | Толщина линий боксов в пикселях; она также определяет размер меток. |
--device | авто | Устройство для выполнения, например cpu, cuda:0, tensorrt:0, coreml, intel:gpu, directml:0, rocm:0, migraphx:0, xnnpack. |
--verbose [<BOOL>] | true | Выводить результаты и время выполнения для каждого изображения. |
--classes | все | Фильтровать детекции по ID классов, например 0, "0,1,2" или "[0, 1, 2]". |
[<BOOL>] обозначает флаг с необязательным значением: если указать его без значения (--rect), он получает значение true, а --rect false отключает его. Устаревший флаг --half по-прежнему поддерживается, преобразуется в --quantize 16 и выводит такое же предупреждение об устаревании, как пакет для Python.
Краткое руководство по библиотеке#
Загрузи модель и запусти предсказание. Метаданные модели, такие как названия классов, тип задачи и размер изображения, автоматически считываются из файла 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(())
}Используй InferenceConfig, чтобы задавать пороги, размер изображения, точность и устройство с помощью builder API:
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")?;Каждая задача заполняет отдельное поле в Results. Каждая вкладка ниже содержит полноценную программу, готовую к запуску; модель и примеры входных данных автоматически загружаются при первом запуске. Замени predict_default() на predict("image.jpg"), чтобы запустить программу на собственных файлах.
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(())
}Поддерживаемые задачи#
Поддерживаются все задачи Ultralytics. Если --model не указан, автоматически загружается подходящая nano-модель для выбранной задачи.
| Задача | --task | Результат | Модель по умолчанию |
|---|---|---|---|
| Обнаружение | detect | Ограничивающие рамки и классы | yolo26n.onnx |
| Сегментация экземпляров | segment | Рамки и маски для каждого экземпляра | yolo26n-seg.onnx |
| Семантическая сегментация | semantic | Карта классов для каждого пикселя | yolo26n-sem.onnx |
| Оценка глубины | depth | Карта глубины для каждого пикселя в метрах | yolo26n-depth.onnx |
| Классификация | classify | Вероятности классов | yolo26n-cls.onnx |
| Поза | pose | Рамки и ключевые точки | yolo26n-pose.onnx |
| Ориентированные рамки | obb | Повернутые ограничивающие рамки | yolo26n-obb.onnx |
--ocr добавляет распознавание текста в сценах к любой модели детекции, сегментации или OBB; если не указан --model, запускается детектор текста yolo26n-text.onnx. См. OCR текста в сценах.
Совместимость моделей#
Любую модель Ultralytics, экспортированную в ONNX, можно загрузить из локального файла. Автоматическая загрузка доступна для стандартных моделей YOLO26, YOLO11 и YOLOv8 с размерами n, s, m, l и x:
| Семейство моделей | Варианты с автоматической загрузкой |
|---|---|
| YOLO26 | yolo26{n,s,m,l,x}.onnx, -seg, -sem, -depth, -cls, -pose, -obb и -text |
| YOLO11 | yolo11{n,s,m,l,x}.onnx, -seg, -cls, -pose и -obb |
| YOLOv8 | yolov8{n,s,m,l,x}.onnx, -seg, -cls, -pose и -obb |
Семантическая сегментация (-sem), оценка глубины (-depth) и детекторы текста в сценах -text доступны только в YOLO26. Распознаватель PaddleOCR PP-OCRv6_medium_rec.onnx и классификатор ориентации PP-LCNet_x0_25_textline_ori.onnx, используемые в --ocr (Apache-2.0), также загружаются автоматически. Модели детекции RT-DETR тоже работают, но не загружаются автоматически: сначала экспортируй модель в ONNX. Нативные экспорты OpenVINO IR запускаются с функцией openvino-native; см. модели OpenVINO IR.
Источники входных данных#
Аргумент --source (и тип Source в библиотеке) поддерживает множество типов входных данных, которые автоматически определяются по строке:
| Источник | Пример | Примечания |
|---|---|---|
| Изображение | image.jpg | Один файл. |
| Каталог | images/ | Все изображения в папке. |
| Glob | images/*.jpg | Шаблон в стиле оболочки. |
| Видео | video.mp4 | Требуется функция video. |
| Веб-камера | 0 | Требуется функция video. |
| Поток | rtsp://... | Требуется функция video. |
| URL | https://example.com/image.jpg | Загрузка удалённого изображения. |
Тайловый инференс#
Большие изображения с мелкими объектами, например аэрофотоснимки или спутниковые снимки, можно разбить на перекрывающиеся окна, а затем объединить результаты — так же, как это делает аргумент tile в Python. Окна перекрываются на 20%, боксы проецируются обратно на исходное изображение, а дубликаты удаляются отдельно для каждого класса. При экспорте с динамическим размером батча --batch обрабатывает несколько окон за один вызов инференса. Поддерживаются все задачи.
# 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 текста в сценах#
Детекторы YOLO26-Text находят слова в виде ориентированных рамок, а TextRecognizer считывает их с помощью PP-OCRv6 из PaddleOCR — того же распознавателя, что используется в Python решении для OCR. Подходят также рамки моделей обнаружения и маски моделей сегментации: маска считывается по прямоугольнику минимальной площади, охватывающему ее контур, и сохраняет контур в виде полигона. Каждый фрагмент поворачивается в правильное положение; текст, который классификатор ориентации определяет как перевернутый, считывается повторно после разворота, а результаты возвращаются в порядке чтения. Распознаватель работает на устройстве детектора.
# 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В примере библиотеки изображение загружается с помощью крейта image, поэтому добавь его рядом с пакетом, используя 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 рисует каждый текст так же, как решение для Python; к нему также применяются --line-width, --show-labels и --show-conf.
Устройства и провайдеры выполнения#
Поддержка GPU и ускорителей компилируется в виде функций Cargo и выбирается во время выполнения с помощью --device (CLI) или Device (библиотека). Если устройство не указано, провайдеры, скомпилированные в сборку, регистрируются в фиксированном порядке предпочтения (сначала TensorRT, затем CUDA и так далее), поэтому сборка только с функциями по умолчанию запускается на CPU.
| Строка устройства | Вариант Device | Функция сборки | Оборудование |
|---|---|---|---|
cpu | Device::Cpu | встроено | Любой CPU |
cuda:0 | Device::Cuda(0) | cuda | GPU NVIDIA |
tensorrt:0 | Device::TensorRt(0) | tensorrt | Оптимизированный GPU NVIDIA |
coreml | Device::CoreMl | coreml | Apple Silicon / macOS |
intel:cpu | Device::IntelCpu | openvino или openvino-native | CPU Intel |
intel:gpu | Device::IntelGpu | openvino или openvino-native | GPU Intel |
intel:npu | Device::IntelNpu | openvino или 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 |
# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrtМодели OpenVINO IR#
С функцией openvino-native в --model можно также использовать нативный экспорт OpenVINO — файл .xml или каталог из yolo export format=openvino — и запускать его через среду выполнения OpenVINO вместо ONNX Runtime. Все задачи выполняются на intel:cpu, intel:gpu и intel:npu, а библиотека загружает модель с помощью YOLOModel::load("yolo26n_openvino_model"). Для сборки установка OpenVINO не нужна; среда выполнения загружается при открытии первой модели. Инструкции по настройке см. в руководстве по OpenVINO.
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Ускорение на GPU и предобработка с помощью CUDA#
На оборудовании NVIDIA функция cuda включает провайдер выполнения CUDA, а tensorrt добавляет провайдер TensorRT для дальнейшей оптимизации (в него входит cuda, который также запускает распознаватель OCR). Чтобы добиться минимальной задержки инференса, функция cuda-preprocess переносит предобработку на GPU.
cuda-preprocess выполняет изменение размера с letterbox, нормализацию и преобразование формата HWC в CHW одним объединённым ядром CUDA, а затем передаёт результат модели как тензор устройства без копирования. Исходный 8-битный кадр всё равно передаётся на GPU, а на дискретных GPU — через закреплённый буфер промежуточного хранения; ядро позволяет обойтись без изменения размера, нормализации и преобразования формата на CPU, а также без отдельной передачи предобработанного тензора. Это особенно важно для пакетов с высокой пропускной способностью и потоков реального времени.
# Build with fused GPU preprocessing (implies cuda + tensorrt)
cargo build --release --features cuda-preprocessУскоренный путь включается автоматически без изменений API, если выполняются все следующие условия: функция включена при сборке; устройство — CUDA, TensorRT или не задано; задача — детекция, сегментация, семантическая сегментация (только для отдельных изображений), оценка глубины, определение позы или OBB; модель использует входные данные FP32. По умолчанию он включён; его можно отключить для каждой модели отдельно:
use ultralytics_inference::{Device, InferenceConfig};
let config = InferenceConfig::new()
.with_device(Device::TensorRt(0))
.with_cuda_preprocess(false); // force CPU preprocessingcuda-preprocess требует соответствующий CUDA Toolkit во время сборки и использует NVRTC во время выполнения для объединённого ядра предобработки. Требования к версиям и советы по устранению неполадок см. в руководстве по ускорению CUDA и TensorRT.
Функции Cargo#
Функции включаются во время сборки. По умолчанию доступны аннотирование и отображение в реальном времени.
| Характеристика | По умолчанию | Назначение |
|---|---|---|
annotate | да | Рисовать боксы, маски, ключевые точки, метки и распознанный OCR-текст; требуется для --save. |
visualize | да | Отображение в окне в реальном времени для --show. |
video | нет | Чтение и запись видеофайлов (требуется FFmpeg 6–9). |
cuda | нет | Провайдер выполнения NVIDIA CUDA. |
tensorrt | нет | Провайдер выполнения NVIDIA TensorRT (включает cuda). |
cuda-preprocess | нет | Объединённая предобработка на GPU (подразумевает cuda, tensorrt; требуется набор инструментов CUDA). |
coreml | нет | Провайдер выполнения Apple CoreML. |
openvino | нет | Провайдер выполнения Intel OpenVINO (Linux и Windows x64). |
openvino-native | нет | Модели OpenVINO IR в нативном формате (.xml) через среду выполнения OpenVINO. |
rocm | нет | Провайдер выполнения AMD ROCm (требуется собственная сборка ONNX Runtime). |
migraphx | нет | Провайдер выполнения AMD MIGraphX (Linux x64). |
directml | нет | Провайдер выполнения Windows DirectML. |
xnnpack | нет | Провайдер выполнения XNNPACK для оптимизированного инференса на CPU. |
Группы для удобства объединяют связанные провайдеры: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) и all (annotate, visualize, video). Также доступны дополнительные провайдеры: onednn, nnapi, qnn, acl, tvm, rknpu, cann, webgpu и azure.
Включи функции при установке CLI или добавлении библиотеки:
cargo install ultralytics-inference --features video
cargo install ultralytics-inference --features cuda,tensorrt[dependencies]
ultralytics-inference = { version = "0.0.58", features = ["video"] }Вывод и сохранение#
По умолчанию предсказания аннотируются и сохраняются в папку запуска с автоматически увеличиваемым номером:
runs/
└── detect/
└── predict/ # then predict2, predict3, ...
└── image.jpg # annotated resultИмя подпапки соответствует задаче (runs/segment/, runs/pose/ и так далее). Для видеоисточников аннотированный результат записывается в видеофайл; укажи --save-frames, чтобы вместо этого сохранять отдельные кадры. Для задачи semantic параметр --save-json сохраняет PNG-карты классов для каждого пикселя в подпапке results/. Для задачи depth цветная карта глубины накладывается на исходное изображение, как и в выводе plot() из Ultralytics Python. Для сохранения аннотированных изображений и видео требуется функция annotate; экспорт PNG-карт классов для семантической сегментации от неё не зависит. Для ввода и вывода видео требуется функция video.
Отрисовка соответствует Python Results.plot(): толщина линии по умолчанию составляет 0.3% от средней стороны изображения (не менее 2 px), метки располагаются над каждым боксом или внутри него, если сверху недостаточно места, а маски объектов накладываются таким же образом, поэтому сохранённые изображения совпадают с результатами Python. Параметры --line-width, --show-labels, --show-conf и --show-boxes работают так же, как одноимённые аргументы Python. В библиотеке передавай их через 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);Маски сегментации, как и в Python, создаются в размере инференса; передай --retina-masks (или InferenceConfig::with_retina_masks(true)), чтобы создавать их в исходном размере изображения.
Часто задаваемые вопросы#
Нет. Crate напрямую запускает экспортированные модели ONNX через ONNX Runtime. Python нужен только в том случае, если ты заранее обучаешь или экспортируешь модели с помощью пакета Ultralytics.
Экспортируй модель из пакета Python, например с помощью интеграции ONNX, или при первом запуске позволь CLI загрузить стандартную nano-модель для выбранной задачи.
Да.
--ocrраспознаёт текст в сценах с помощью детектора YOLO26-Text и PaddleOCR, как и решение OCR для Python, а также работает с боксами и масками твоих собственных моделей детекции и сегментации. См. OCR текста в сценах.Используй тайловый инференс:
--tile 640разбивает изображение на перекрывающиеся окна размером 640 px и объединяет детекции в один результат.Да, если включена функция
videoи в системе установлена FFmpeg версии 6–9. Поддерживаются видеофайлы, веб-камеры и потоки RTSP/RTMP/HTTP.Обе функции включены по умолчанию.
annotateнаносит на изображение рамки, маски, ключевые точки и метки классов; эта функция необходима, чтобы--saveсохраняла результаты с аннотациями.visualizeоткрывает окно трансляции для--show. Чтобы получить более компактную сборку без графического интерфейса, которая только программно возвращает результаты, отключи эти функции с помощьюcargo build --no-default-features(при необходимости снова включи отдельные функции).На этой странице приведён общий обзор. Полная справка по API для каждого публичного типа структуры, метода и параметра конфигурации опубликована на сайте docs.rs и генерируется непосредственно из исходного кода.
Комментарии
Задай вопрос, поделись результатами или помоги кому-нибудь.