Ultralytics Inference для Rust#

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

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

Почему инференс на Rust?#

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

Установка#

Требуется Rust 1.89 или новее. Для работы функции видео в системе также должен быть установлен 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 для управления пороговыми значениями, размером изображения, точностью и устройством с помощью 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, задача — детекция, сегментация, поиск поз, OBB, семантическая сегментация или оценка глубины, и модель использует входные данные 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.33", 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() в Python-пакете Ultralytics. Для сохранения аннотированных изображений и видео требуется функция annotate; для экспорта PNG-карт семантических классов — нет. Для ввода и вывода видео требуется функция video.

FAQ#

Нужно ли мне устанавливать Python?#

Нет. Крейт запускает экспортированные модели ONNX напрямую через ONNX Runtime. Python нужен только в том случае, если ты предварительно обучаешь или экспортируешь модели с помощью пакета Ultralytics.

Какие модели я могу запускать?#

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

Как мне получить файл модели?#

Выполни экспорт из пакета Python, например с помощью интеграции ONNX, или позволь CLI загрузить стандартную нано-модель для выбранной задачи при первом запуске.

Поддерживается ли видео?#

Да, если включена функция video и в системе установлен FFmpeg 7+. Это охватывает видеофайлы, веб-камеры и потоки RTSP/RTMP/HTTP.

Что делают функции annotate и visualize?#

Обе функции включены по умолчанию. annotate рисует рамки, маски, ключевые точки и метки классов на изображении и требуется для того, чтобы --save мог записывать аннотированные результаты. visualize открывает живое окно для --show. Для более компактной сборки без графического интерфейса, которая возвращает результаты только программным путем, отключи их с помощью cargo build --no-default-features (при необходимости добавь отдельные функции обратно).

Где находится полная справочная документация по API?#

Эта страница представляет собой общий обзор. Полная справочная документация по API для каждой публичной структуры, метода и параметра конфигурации опубликована на сайте docs.rs и генерируется непосредственно из исходного кода.