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

Ultralytics Inference — высокопроизводительная библиотека инференса YOLO и инструмент командной строки, написанные на Rust. Она запускает экспортированные модели ONNX через ONNX Runtime, обеспечивая быстрые предсказания с безопасным управлением памятью для изображений, видео, веб-камер и потоков; среда выполнения Python для инференса не требуется.

Проект поставляется в виде единственного крейта ultralytics-inference, который можно использовать двумя способами: как CLI для быстрых предсказаний и пакетной обработки или как библиотеку, встроенную непосредственно в приложение на Rust. Он поддерживает все задачи Ultralytics и широкий набор аппаратных бэкендов через единый интерфейс устройств. Для инференса в браузере тот же репозиторий публикует npm-пакет @ultralytics/yolo; см. руководство по настройке.

Зачем использовать Rust для инференса?#

• Нативная скорость и компактность. Компилируется в нативный двоичный файл без интерпретатора — идеальный вариант для серверов, контейнеров и периферийных устройств.
• Безопасность памяти. Модель владения Rust устраняет целые классы ошибок времени выполнения без сборщика мусора.
• Все задачи YOLO. Детекция, сегментация, семантическая сегментация, оценка глубины, классификация, определение позы и OBB доступны через один API.
• Широкая поддержка оборудования. CPU, а также провайдеры выполнения CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm и XNNPACK, выбираемые во время сборки.
• Предобработка на GPU. Дополнительное объединённое ядро CUDA выполняет letterbox, нормализацию и преобразование формата данных на GPU и передаёт результат модели, не покидая устройство.
• Автоматическая загрузка. Известные названия моделей YOLO и примеры ресурсов автоматически загружаются при первом использовании.

Установка#

Требуется Rust версии 1.89 или новее. Для функции video также необходимо установить в системе 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

Краткое руководство по 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

Общие флаги:

Краткое руководство по библиотеке#

Загрузи модель и запусти предсказание. Метаданные модели, такие как названия классов, тип задачи и размер изображения, автоматически считываются из файла 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-модель для выбранной задачи.

Совместимость моделей#

Любую модель Ultralytics, экспортированную в ONNX, можно загрузить из локального файла. Автоматическая загрузка доступна для стандартных моделей YOLO26, YOLO11 и YOLOv8 размеров n, s, m, l и x:

Семантическая сегментация (-sem) и оценка глубины (-depth) доступны только в YOLO26. Модели обнаружения RT-DETR тоже работают, но автоматически не загружаются: сначала экспортируй модель в ONNX.

Источники входных данных#

Аргумент --source (и тип Source в библиотеке) поддерживает множество типов входных данных, которые автоматически определяются по строке:

Устройства и провайдеры выполнения#

Поддержка GPU и ускорителей компилируется в виде функций Cargo и выбирается во время выполнения с помощью --device (CLI) или Device (библиотека). Если устройство не указано, провайдеры, скомпилированные в сборку, регистрируются в фиксированном порядке предпочтения (сначала TensorRT, затем CUDA и так далее), поэтому сборка только с функциями по умолчанию запускается на CPU.

# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrt

Ускорение на GPU и предобработка с помощью CUDA#

На оборудовании NVIDIA функция cuda включает провайдер выполнения CUDA, а tensorrt добавляет провайдер TensorRT для дополнительной оптимизации. Для минимально возможной задержки функция 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, задача — detect, segment, pose, OBB, semantic segmentation (только для одиночных изображений) или depth estimation, а модель принимает данные в формате FP32. Эта возможность включена по умолчанию, но её можно отключить для каждой модели:

use ultralytics_inference::{Device, InferenceConfig};

let config = InferenceConfig::new()
    .with_device(Device::TensorRt(0))
    .with_cuda_preprocess(false); // force CPU preprocessing

Функции Cargo#

Функции включаются во время сборки. По умолчанию доступны аннотирование и отображение в реальном времени.

Группы функций для удобства объединяют связанные провайдеры: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) и all (annotate, visualize, video). Доступны и другие провайдеры, например nnapi, qnn, xnnpack, webgpu и другие.

Включи функции при установке CLI или добавлении библиотеки:

cargo install ultralytics-inference --features video
cargo install ultralytics-inference --features cuda,tensorrt

[dependencies]
ultralytics-inference = { version = "0.0.50", 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.

Часто задаваемые вопросы#