Ultralytics YOLO27：

适用于 Rust 的 Ultralytics 推理#

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

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

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

为什么选择 Rust 推理？#

  • 原生速度和小巧的体积。 编译为无需解释器的原生二进制文件，非常适合服务器、容器和边缘设备。
  • 内存安全。 Rust 的所有权模型无需垃圾回收器即可消除整类运行时错误。
  • 支持所有 YOLO 任务。 通过一个 API 完成检测、实例分割、语义分割、深度估计、分类、姿态估计和 OBB。
  • 广泛的硬件支持。 支持 CPU，以及 CUDA、TensorRT、CoreML、OpenVINO、DirectML、ROCm 和 XNNPACK 执行提供程序，这些提供程序在构建时选择。
  • GPU 端预处理。 可选的融合 CUDA 内核会在设备上完成 letterbox、归一化和布局转换，从而实现零拷贝输入路径。
  • 自动下载。 已知的 YOLO 模型名称和示例资源会在首次使用时自动下载。
在找 Python 包？

本页介绍独立的 Rust crate。关于 Python 工作流（训练、验证、导出和预测），请参阅主 快速入门 和预测模式。使用 ONNX 集成将任意 Ultralytics 模型导出为 ONNX，然后在此处运行。

安装#

需要 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

二进制文件位于 ~/.cargo/bin/ultralytics-inference（Linux 和 macOS）或 Windows 上的 %USERPROFILE%\.cargo\bin\。

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

常用标志：

标志默认值描述
--model、-myolo26n.onnxONNX 模型的路径；已知的 YOLO 名称会自动下载。
--taskdetect可选值为 detect、segment、pose、obb、classify、semantic、depth 之一。
--source、-ssample图像、目录、glob、视频、摄像头索引或 URL。
--conf0.25置信度阈值。
--iou0.7用于非极大值抑制的 IoU 阈值。
--imgsz模型元数据推理图像尺寸。
--devicecpu执行设备，例如 cuda:0、coreml、tensorrt:0。
--halffalseFP16 半精度推理。
--savetrue将标注结果保存到 runs/<task>/predict。
--showfalse在窗口中显示结果。
--classes全部按类别 ID 筛选检测结果，例如 "0,1,2"。

库快速入门#

加载模型并运行预测。模型元数据（例如类别名称、任务类型和图像尺寸）会自动从 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 模型。

任务--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

模型兼容性#

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

模型系列可自动下载的变体
YOLO26yolo26{n,s,m,l,x}.onnx、-seg、-pose、-obb、-cls、-sem 和 -depth
YOLO11yolo11{n,s,m,l,x}.onnx、-seg、-pose、-obb 和 -cls
YOLOv8yolov8{n,s,m,l,x}.onnx、-seg、-pose、-obb 和 -cls

语义分割（-sem）和深度估计（-depth）仅支持 YOLO26。

输入源#

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

来源示例备注
图像image.jpg单个文件。
目录images/文件夹中的所有图像。
Globimages/*.jpgShell 风格的模式。
视频video.mp4需要 video 功能。
网络摄像头0需要 video 功能。
流rtsp://...需要 video 功能。
URLhttps://example.com/image.jpg远程图像下载。

设备和执行提供程序#

默认情况下，推理在 CPU 上运行。GPU 和加速器后端会作为 Cargo 功能编译进去，并通过 CLI 中的 --device 或库中的 Device 在运行时选择。

设备字符串Device 变体构建功能硬件
cpuDevice::Cpu内置任意 CPU
cuda:0Device::Cuda(0)cudaNVIDIA GPU
tensorrt:0Device::TensorRt(0)tensorrtNVIDIA GPU，已优化
coremlDevice::CoreMlcoremlApple Silicon / macOS
intel:cpuDevice::IntelCpuopenvinoIntel CPU
intel:gpuDevice::IntelGpuopenvinoIntel GPU
intel:npuDevice::IntelNpuopenvinoIntel NPU
directml:0Device::DirectMl(0)directmlWindows GPU
rocm:0Device::Rocm(0)rocmAMD GPU
xnnpackDevice::Xnnpackxnnpack优化的 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 内核运行，然后将结果作为零拷贝设备张量传递给模型。这消除了逐图像 CPU 预处理开销和主机到设备的拷贝，对于高吞吐量批处理和实时流而言尤其重要。

# Build with fused GPU preprocessing (implies cuda + tensorrt)
cargo build --release --features cuda-preprocess

满足以下所有条件时会自动使用快速路径，无需更改 API：该功能已编译进程序，设备为 CUDA 或 TensorRT，任务为 detect、segment、pose、OBB、语义分割或深度估计，并且模型使用 FP32 输入。该功能默认启用，也可以针对每个模型关闭：

use ultralytics_inference::{Device, InferenceConfig};

let config = InferenceConfig::new()
    .with_device(Device::TensorRt(0))
    .with_cuda_preprocess(false); // force CPU preprocessing
匹配你的 CUDA 工具包

cuda-preprocess 要求在构建时使用匹配的 CUDA 工具包，并在运行时使用 NVRTC 执行融合预处理内核。有关版本要求和故障排除，请参阅 CUDA 和 TensorRT 加速指南。

Cargo 功能#

功能在构建时启用。默认功能涵盖标注和实时显示。

特性默认值用途
annotate是绘制边界框、掩码、关键点和标签；--save 必需。
visualize是--show 的实时窗口显示。
video否读取和写入视频文件（需要 FFmpeg 7+）。
cuda否NVIDIA CUDA 执行提供程序。
tensorrt否NVIDIA TensorRT 执行提供程序。
cuda-preprocess否采用零拷贝输入的融合 GPU 预处理（隐式包含 cuda、tensorrt）。
coreml否Apple CoreML 执行提供程序。
openvino否Intel OpenVINO 执行提供程序。
rocm否AMD ROCm 执行提供程序。
directml否Windows DirectML 执行提供程序。

便捷组合会捆绑相关提供程序：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 任务，--save-json 会将逐像素类别图 PNG 写入 results/ 子文件夹。对于 depth 任务，彩色深度图会叠加到源图像上，效果与 Ultralytics Python 的 plot() 输出一致。保存带标注的图像和视频需要启用 annotate 功能；导出语义类别图 PNG 则不需要。视频输入和输出需要启用 video 功能。

常见问题#

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

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

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

  • 支持，但需要启用 video 功能，并在系统中安装 FFmpeg 7+。这包括视频文件、摄像头以及 RTSP/RTMP/HTTP 流。

  • 两者默认都已启用。annotate 会在图像上绘制边界框、掩码、关键点和类别标签，并且 --save 要写入带标注的结果时必须启用它。visualize 会为 --show 打开实时窗口。要构建更小的无头版本，并且只通过程序返回结果，可以使用 cargo build --no-default-features 禁用它们（根据需要重新添加单个功能）。

  • 本页面是高层概览。每个公共结构体、方法和配置选项的完整 API 参考均已发布在 docs.rs 上，并直接从源代码生成。

贡献者
ONonuralpszr14GLglenn-jocher2

评论