Ultralytics Inference для Rust#

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

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

Зачем нужен инференс на Rust?#

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

Установка#

Требуется Rust 1.89 или новее. Для функции video также необходимо установить FFmpeg 7+ в системе.

# 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 --half

Распространённые флаги:

Быстрый старт библиотеки#

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

let config = InferenceConfig::new()
    .with_confidence(0.5)
    .with_iou(0.45)
    .with_imgsz(640, 640)
    .with_device(Device::Cuda(0))
    .with_half(true);

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

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

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

Семантическая сегментация (-sem) и оценка глубины (-depth) доступны только в YOLO26.

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

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

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

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

# 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, а затем передаёт результат модели в виде тензора устройства без копирования. Это устраняет затраты 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.35", features = ["video"] }

Вывод и сохранение#

По умолчанию предсказания получают аннотации и сохраняются в каталог запусков с автоматически увеличивающимся номером:

runs/
└── detect/
    └── predict/          # then predict2, predict3, ...
        └── image.jpg     # annotated result

Имя подпапки соответствует задаче (runs/segment/, runs/pose/ и так далее). Для видеоисточников аннотированный результат записывается в видеофайл; передай --save-frames, чтобы вместо этого сохранить отдельные кадры. Для задачи semantic PNG-файлы карт классов для каждого пикселя записываются в подпапку results/ с помощью --save-json. Для задачи depth цветная карта глубины накладывается на исходное изображение, как в результате plot() Ultralytics Python. Для сохранения аннотированных изображений и видео требуется функция annotate; экспорт PNG-карт семантических классов этого не требует. Для ввода и вывода видео требуется функция video.

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