用于 Rust 的 Ultralytics Inference#

Ultralytics Inference 是一个用 Rust 编写的高性能 YOLO 推理库和命令行工具。它通过 ONNX Runtime 运行导出的 ONNX 模型，在图像、视频、网络摄像头和流媒体上提供快速、内存安全的预测，推理时无需 Python 运行时。

该项目发布为一个单独的 Crate ultralytics-inference，你可以通过两种方式使用它：作为用于快速预测和批处理作业的 CLI，或作为直接嵌入你的 Rust 应用程序中的 Library。它通过统一的设备接口支持所有 Ultralytics 任务和广泛的硬件后端。

为什么要选择 Rust 进行推理？#

• 原生速度与小巧体积。 编译为没有解释器的原生二进制文件，非常适合服务器、容器和边缘设备。
• 内存安全。 Rust 的所有权模型无需垃圾回收器即可消除各类运行时错误。
• 所有 YOLO 任务。 通过一个 API 即可实现检测、分割、语义分割、深度估计、分类、姿态估计和 OBB。
• 广泛的硬件支持。 支持 CPU 以及在构建时选择的 CUDA、TensorRT、CoreML、OpenVINO、DirectML、ROCm 和 XNNPACK 执行提供程序。
• GPU 端预处理。 可选的融合 CUDA 内核将 letterbox、归一化和布局转换保留在设备上，实现零拷贝输入路径。
• 自动下载。 已知的 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 子命令。如果不带参数，它会下载一个 Nano 检测模型和示例图像，运行推理，并将带注释的结果保存到 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 时，将自动下载所选任务的匹配 Nano 模型。

模型兼容性#

导出为 ONNX 的任何 Ultralytics 模型都可以从本地文件加载。标准 YOLO26、YOLO11 和 YOLOv8 模型名称提供自动下载，尺寸包括 n、s、m、l 和 x：

语义分割（-sem）和深度估计（-depth）仅适用于 YOLO26。

输入源#

--source 参数（以及库中的 Source 类型）接受多种输入类型，从字符串中自动检测：

设备和执行提供程序#

推理默认在 CPU 上运行。GPU 和加速器后端作为 Cargo 特性编译，并在运行时通过 --device（CLI）或 Device（Library）进行选择。

# 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 在 results/ 子文件夹下写入逐像素类别映射 PNG。对于 depth 任务，彩色深度图与源图像混合，匹配 Ultralytics Python plot() 输出。注释图像和视频保存需要 annotate 特性；语义类别映射 PNG 导出则不需要。视频输入和输出需要 video 特性。

常见问题解答#

我需要安装 Python 吗？#

不需要。Crate 直接通过 ONNX Runtime 运行导出的 ONNX 模型。只有在你事先使用 Ultralytics 软件包训练或导出模型时才需要 Python。

我可以运行哪些模型？#

导出到 ONNX 的任何 Ultralytics YOLO 模型，包括 YOLO26、YOLO11 和 YOLOv8。已知模型名称会自动下载；你也可以将 --model 指向任何本地 .onnx 文件。

我该如何获取模型文件？#

从 Python 软件包导出，例如通过 ONNX 集成，或者让 CLI 在首次运行时为所选任务下载标准的 Nano 模型。

支持视频吗？#

可以，前提是启用了 video 特性并在系统上安装了 FFmpeg 7+。这涵盖视频文件、网络摄像头以及 RTSP/RTMP/HTTP 流。

annotate 和 visualize 特性有什么作用？#

两者默认均已启用。annotate 在图像上绘制方框、掩码、关键点和类别标签，是 --save 写入注释结果所必需的。visualize 为 --show 打开一个实时窗口。对于仅以编程方式返回结果的较小无头构建，请使用 cargo build --no-default-features 禁用它们（根据需要重新添加各个特性）。

完整的 API 参考在哪里？#

本页是一个高层概述。每个公共结构体、方法和配置选项的完整、按类型分类的 API 参考发布在 docs.rs 上，直接从源码生成。