Начать

Инференс Ultralytics для Rust

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

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().
Ищешь пакет для Python?

На этой странице описан автономный крейт 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, -myolo26n.onnxПуть к модели ONNX или экспорту OpenVINO; модель с известным именем YOLO загружается автоматически.
--taskdetectОдно из значений detect, segment, semantic, depth, classify, pose, obb; если --model не задан, выбирает nano-модель.
--source, -sобразецИзображение, каталог, шаблон glob, видео, индекс веб-камеры, поток или URL.
--conf0.25Порог уверенности.
--iou0.5Порог IoU для подавления немаксимумов.
--max-det300Максимальное число обнаружений на изображение.
--imgszметаданные моделиРазмер изображения для инференса.
--rect [<BOOL>]trueПрямоугольный инференс с минимальным дополнением.
--tile [<TILE>]выкл.Размер тайла для инференса с перекрывающимися окнами; если указать --tile без значения, используется --imgsz. См. тайловый инференс.
--retina-masksfalseСоздавать маски сегментации в исходном размере изображения, а не в размере инференса.
--ocrfalseСчитывать текст в каждом боксе, ориентированном боксе или маске с помощью PaddleOCR; если не указан --model, запускается yolo26n-text.onnx. См. OCR.
--batch1Размер пакета для инференса.
--quantizeточность моделиТочность инференса: 8, 16, 32, int8, fp16, fp32, w8a8, w16a16, w32a32, w8a16 или w8a32.
--save [<BOOL>]trueСохранять результаты с аннотациями в runs/<task>/predict.
--save-framesfalseСохранять отдельные кадры для видео вместо видеофайла.
--save-jsonfalseСохранять PNG-карты классов для семантической сегментации.
--showfalseПоказывать результаты в окне.
--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:

Семейство моделейВарианты с автоматической загрузкой
YOLO26yolo26{n,s,m,l,x}.onnx, -seg, -sem, -depth, -cls, -pose, -obb и -text
YOLO11yolo11{n,s,m,l,x}.onnx, -seg, -cls, -pose и -obb
YOLOv8yolov8{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/Все изображения в папке.
Globimages/*.jpgШаблон в стиле оболочки.
Видеоvideo.mp4Требуется функция video.
Веб-камера0Требуется функция video.
Потокrtsp://...Требуется функция video.
URLhttps://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 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 текста в сценах#

Детекторы 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Функция сборкиОборудование
cpuDevice::CpuвстроеноЛюбой CPU
cuda:0Device::Cuda(0)cudaGPU NVIDIA
tensorrt:0Device::TensorRt(0)tensorrtОптимизированный GPU NVIDIA
coremlDevice::CoreMlcoremlApple Silicon / macOS
intel:cpuDevice::IntelCpuopenvino или openvino-nativeCPU Intel
intel:gpuDevice::IntelGpuopenvino или openvino-nativeGPU Intel
intel:npuDevice::IntelNpuopenvino или openvino-nativeNPU Intel
directml:0Device::DirectMl(0)directmlGPU Windows
rocm:0Device::Rocm(0)rocmGPU AMD
migraphx:0Device::MiGraphX(0)migraphxGPU AMD (Linux x64)
xnnpackDevice::XnnpackxnnpackОптимизированный 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 preprocessing
Подбери версию под свой CUDA Toolkit

cuda-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.

  • Любую модель Ultralytics YOLO, экспортированную в ONNX, включая YOLO26, YOLO11 и YOLOv8. Известные имена моделей загружаются автоматически; также можно указать в --model путь к любому локальному файлу .onnx.

  • Экспортируй модель из пакета 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 и генерируется непосредственно из исходного кода.

Комментарии

Задай вопрос, поделись результатами или помоги кому-нибудь.