Rust 版 Ultralytics 推理
Ultralytics Inference 是一款用 Rust 编写的高性能 YOLO 推理库和命令行工具。它通过 ONNX Runtime 运行导出的 ONNX 模型,可对图像、视频、网络摄像头和流进行快速且内存安全的预测,推理时无需 Python 运行时。
该项目以单个 crate 的形式发布:ultralytics-inference。你可以通过两种方式使用它:将其作为 CLI 执行快速预测和批处理任务,或作为 库 直接嵌入 Rust 应用程序。它支持所有 Ultralytics 任务,并通过统一的设备接口支持多种硬件后端。同一代码库还会发布用于浏览器推理的 @ultralytics/yolo npm 包;请参阅其设置指南。
为什么选择 Rust 推理?#
- 原生速度,占用空间小。编译为原生二进制文件,无需解释器,非常适合服务器、容器和边缘设备。
- 内存安全。Rust 的所有权模型无需垃圾回收器,就能消除整类运行时错误。
- 支持所有 YOLO 任务。通过一个 API 实现检测、实例分割、语义分割、深度估计、分类、姿态估计和 OBB,还支持场景文本 OCR 和大型图像的切片推理。
- 广泛的硬件支持。支持 CPU,以及 CUDA、TensorRT、CoreML、OpenVINO、DirectML、ROCm、MIGraphX 和 XNNPACK 执行提供程序(在构建时选择),还支持原生 OpenVINO IR 模型。
- GPU 端预处理。可选的融合 CUDA 内核会在 GPU 上执行 letterbox、归一化和布局转换,并将结果直接传递给模型,全程无需离开设备。
- 自动下载。首次使用时会自动下载已知的 YOLO 模型名称对应的模型、OCR 模型和示例资源。
- 输出与 Python 相同。掩码、掩码轮廓和绘制结果均与 Ultralytics Python 包一致,因此
--save生成的图像与plot()生成的图像相同。
安装#
需要 Rust 1.92 或更高版本。要使用视频功能,系统还需要安装 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二进制文件位于 ~/.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 --quantize 16
# Tile a large aerial image into overlapping 640 px windows to find small objects
ultralytics-inference predict --model yolo26n-obb.onnx --source aerial.jpg --tile 640
# Read scene text (auto-downloads yolo26n-text.onnx and the PaddleOCR models)
ultralytics-inference predict --ocr --source sign.jpg
# Thicker lines, no confidences in labels
ultralytics-inference predict --source image.jpg --line-width 4 --show-conf false所有 predict 标志:
| 标志 | 默认值 | 说明 |
|---|---|---|
--model, -m | yolo26n.onnx | ONNX 模型或 OpenVINO 导出的路径;已知的 YOLO 名称会自动下载。 |
--task | detect | 可以是 detect、segment、semantic、depth、classify、pose、obb 之一;如果省略 --model,则选择 nano 模型。 |
--source, -s | 样例 | 图像、目录、glob、视频、网络摄像头索引、流或 URL。 |
--conf | 0.25 | 置信度阈值。 |
--iou | 0.5 | 非极大值抑制的 IoU 阈值。 |
--max-det | 300 | 每张图像的最大检测数量。 |
--imgsz | 模型元数据 | 推理图像尺寸。 |
--rect [<BOOL>] | true | 采用最小填充的矩形推理。 |
--tile [<TILE>] | 关闭 | 用于重叠窗口推理的切片尺寸;单独指定 --tile 时使用 --imgsz。参见切片推理。 |
--retina-masks | false | 以原始图像尺寸而非推理尺寸生成分割掩码。 |
--ocr | false | 使用 PaddleOCR 读取每个框、定向框或掩码中的文本;如果不指定 --model,则运行 yolo26n-text.onnx。参见 OCR。 |
--batch | 1 | 推理批次大小。 |
--quantize | 模型精度 | 推理精度:8、16、32、int8、fp16、fp32、w8a8、w16a16、w32a32、w8a16 或 w8a32。 |
--save [<BOOL>] | true | 将标注后的结果保存到 runs/<task>/predict。 |
--save-frames | false | 对于视频输入,保存单独的帧,而不是视频文件。 |
--save-json | false | 保存语义分割类别图 PNG 文件。 |
--show | false | 在窗口中显示结果。 |
--show-labels [<BOOL>] | true | 在框标签中显示类别名称。 |
--show-conf [<BOOL>] | true | 在框标签中显示置信度。 |
--show-boxes [<BOOL>] | true | 绘制框及其标签。 |
--line-width | 按图像尺寸计算 | 框线宽度(像素),也决定标签大小。 |
--device | 自动 | 执行设备,例如 cpu、cuda:0、tensorrt:0、coreml、intel:gpu、directml:0、rocm:0、migraphx:0、xnnpack。 |
--verbose [<BOOL>] | true | 打印每张图像的结果和耗时。 |
--classes | 全部 | 按类别 ID 筛选检测结果,例如 0、"0,1,2" 或 "[0, 1, 2]"。 |
[<BOOL>] 表示该标志的值可选:单独传入该标志(--rect)时会将其设为 true,而 --rect false 会将其关闭。旧版 --half 标志仍可用,会映射到 --quantize 16,并打印与 Python 包相同的弃用警告。
库快速入门#
加载模型并运行预测。模型元数据(例如类别名称、任务类型和图像尺寸)会从 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, 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 模型。
| 任务 | --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 |
--ocr 可在任何检测、分割或 OBB 模型的基础上添加场景文本识别;如果不指定 --model,则运行 yolo26n-text.onnx 文本检测器。参见场景文本 OCR。
模型兼容性#
任何导出为 ONNX 的 Ultralytics 模型都可以从本地文件加载。标准 YOLO26、YOLO11 和 YOLOv8 模型名称支持自动下载,尺寸包括 n、s、m、l 和 x:
| 模型系列 | 支持自动下载的变体 |
|---|---|
| YOLO26 | yolo26{n,s,m,l,x}.onnx、-seg、-sem、-depth、-cls、-pose、-obb 和 -text |
| YOLO11 | yolo11{n,s,m,l,x}.onnx、-seg、-cls、-pose 和 -obb |
| YOLOv8 | yolov8{n,s,m,l,x}.onnx、-seg、-cls、-pose 和 -obb |
语义分割(-sem)、深度估计(-depth)和 -text 场景文本检测器仅支持 YOLO26。--ocr 使用的 PaddleOCR PP-OCRv6_medium_rec.onnx 识别器和 PP-LCNet_x0_25_textline_ori.onnx 方向分类器(Apache-2.0)也会自动下载。RT-DETR 检测模型也可以运行,但不会自动下载:请先将其导出为 ONNX。原生 OpenVINO IR 导出模型可通过 openvino-native 功能运行,参见 OpenVINO IR 模型。
输入源#
--source 参数(以及库中的 Source 类型)接受多种输入类型,并会根据字符串自动检测:
| 数据源 | 示例 | 备注 |
|---|---|---|
| 图像 | image.jpg | 单个文件。 |
| 目录 | images/ | 文件夹中的所有图像。 |
| Glob | images/*.jpg | Shell 风格的模式。 |
| 视频 | video.mp4 | 需要 video 功能。 |
| 网络摄像头 | 0 | 需要 video 功能。 |
| 流 | rtsp://... | 需要 video 功能。 |
| URL | https://example.com/image.jpg | 远程图像下载。 |
切片推理#
对于包含小目标的大型图像(例如航空或卫星照片),可以将图像拆分为重叠窗口,再合并为一个结果;这与 Python 的 tile 参数效果相同。窗口之间重叠 20%,检测框会映射回源图像,并按类别去除重复框。使用动态批次导出模型时,--batch 会在一次推理调用中处理多个窗口。所有任务均受支持。
# 640 px windows; a bare --tile uses --imgsz
ultralytics-inference predict --model yolo26n-obb.onnx --source aerial.jpg --tile 640use ultralytics_inference::{InferenceConfig, YOLOModel};
// with_tile(0) uses the inference size
let config = InferenceConfig::new().with_tile(640);
let mut model = YOLOModel::load_with_config("yolo26n.onnx", config)?;
let results = model.predict("aerial.jpg")?;场景文本 OCR#
YOLO26-Text 检测器会将词语检测为旋转框,TextRecognizer 则使用 PaddleOCR PP-OCRv6 读取这些词语,该识别器与 Python OCR 解决方案使用的识别器相同。检测模型的框和分割模型的掩码也都适用:掩码的读取区域取自其轮廓周围的最小面积矩形,同时会将轮廓保留为多边形。每个裁剪图都会转正;如果方向分类器判定文本上下颠倒,就会将其翻转后重新读取;最终文本会按阅读顺序返回。识别器在检测器所用设备上运行。
# Auto-downloads yolo26n-text.onnx and the PaddleOCR models
ultralytics-inference predict --ocr --source sign.jpg
# Any size of the text detector, on the GPU
ultralytics-inference predict --ocr --model yolo26x-text.onnx --source sign.jpg --device cuda:0库示例使用 image crate 加载图像,因此请使用 cargo add image 将它与该包一同添加。
use ultralytics_inference::YOLOModel;
use ultralytics_inference::ocr::{DEFAULT_ORIENTATION, DEFAULT_RECOGNIZER, TextRecognizer};
let mut detector = YOLOModel::load("yolo26n-text.onnx")?;
let mut ocr = TextRecognizer::new(&detector, DEFAULT_RECOGNIZER, DEFAULT_ORIENTATION)?;
let image = image::open("sign.jpg")?;
let result = detector.predict_image(&image, "sign.jpg".into())?.remove(0);
for text in ocr.read(&image, &result)? {
println!("{} {:.2} {:?}", text.text, text.confidence, text.polygon);
}predict --ocr 会像 Python 解决方案一样绘制每段文本,--line-width、--show-labels 和 --show-conf 也同样适用于文本。
设备和执行提供程序#
GPU 和加速器后端会作为 Cargo 功能编译进程序,并在运行时通过 --device(CLI)或 Device(库)进行选择。如果未指定设备,编译进构建版本的提供程序会按固定的优先级顺序注册(先 TensorRT,再 CUDA,依此类推),因此仅启用默认功能的构建版本会在 CPU 上运行。
| 设备字符串 | Device 变体 | 构建功能 | 硬件 |
|---|---|---|---|
cpu | Device::Cpu | 内置 | 任意 CPU |
cuda:0 | Device::Cuda(0) | cuda | NVIDIA GPU |
tensorrt:0 | Device::TensorRt(0) | tensorrt | NVIDIA GPU,优化版 |
coreml | Device::CoreMl | coreml | Apple Silicon / macOS |
intel:cpu | Device::IntelCpu | openvino 或 openvino-native | Intel CPU |
intel:gpu | Device::IntelGpu | openvino 或 openvino-native | Intel GPU |
intel:npu | Device::IntelNpu | openvino 或 openvino-native | Intel NPU |
directml:0 | Device::DirectMl(0) | directml | Windows GPU |
rocm:0 | Device::Rocm(0) | rocm | AMD GPU |
migraphx:0 | Device::MiGraphX(0) | migraphx | AMD GPU(Linux x64) |
xnnpack | Device::Xnnpack | xnnpack | 优化型 CPU |
# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrtOpenVINO IR 模型#
启用 openvino-native 功能后,--model 还可以加载原生 OpenVINO 导出模型,即 yolo export format=openvino 中的 .xml 文件或文件夹,并通过 OpenVINO 运行时而非 ONNX Runtime 运行模型。所有任务都可以在 intel:cpu、intel:gpu 和 intel:npu 上运行,库使用 YOLOModel::load("yolo26n_openvino_model") 加载模型。构建时无需安装 OpenVINO;首次打开模型时才会加载运行时。有关设置,请参阅 OpenVINO 指南。
yolo export model=yolo26n.pt format=openvino # add quantize=16, quantize=8, dynamic=True, or batch=4
ultralytics-inference predict --model yolo26n_openvino_model --source bus.jpg --device intel:gpuGPU 加速和 CUDA 预处理#
在 NVIDIA 硬件上,cuda 功能会启用 CUDA 执行提供程序,而 tensorrt 会添加 TensorRT 提供程序以进一步优化(其中包含 cuda,该功能也会运行 OCR 识别器)。如需尽可能降低推理延迟,cuda-preprocess 功能会将预处理移至 GPU 上执行。
cuda-preprocess 会通过单个融合 CUDA 内核执行 letterbox 缩放、归一化以及 HWC 到 CHW 的布局转换,然后将结果作为零拷贝设备张量传给模型。原始 8 位帧仍会上传到 GPU;在独立 GPU 上,这一过程会通过固定内存暂存缓冲区完成。该内核省去了 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 preprocessingcuda-preprocess 需要在构建时使用匹配的 CUDA 工具包,并在运行时使用 NVRTC 执行融合预处理内核。有关版本要求和故障排除,请参阅 CUDA 和 TensorRT 加速指南。
Cargo 功能#
功能需要在构建时启用。默认功能涵盖标注和实时显示。
| 特性 | 默认值 | 用途 |
|---|---|---|
annotate | 是 | 绘制框、掩码、关键点、标签和 OCR 文本;--save 必须启用此功能。 |
visualize | 是 | --show 的实时窗口显示功能。 |
video | 否 | 读取和写入视频文件(需要 FFmpeg 6 到 9)。 |
cuda | 否 | NVIDIA CUDA 执行提供程序。 |
tensorrt | 否 | NVIDIA TensorRT 执行提供程序(包含 cuda)。 |
cuda-preprocess | 否 | 融合 GPU 预处理(隐含启用 cuda、tensorrt;需要 CUDA 工具包)。 |
coreml | 否 | Apple CoreML 执行提供程序。 |
openvino | 否 | Intel OpenVINO 执行提供程序(Linux 和 Windows x64)。 |
openvino-native | 否 | 通过 OpenVINO 运行时运行原生 OpenVINO IR(.xml)模型。 |
rocm | 否 | AMD ROCm 执行提供程序(需要你自行构建 ONNX Runtime)。 |
migraphx | 否 | AMD MIGraphX 执行提供程序(Linux x64)。 |
directml | 否 | Windows DirectML 执行提供程序。 |
xnnpack | 否 | 用于优化 CPU 推理的 XNNPACK 执行提供程序。 |
便捷功能组会捆绑相关提供程序:nvidia(cuda、tensorrt)、amd(rocm、migraphx)、intel(openvino、onednn)、mobile(nnapi、coreml、qnn)和 all(annotate、visualize、video)。还提供其他提供程序:onednn、nnapi、qnn、acl、tvm、rknpu、cann、webgpu 和 azure。
安装 CLI 或添加库时启用相应功能:
cargo install ultralytics-inference --features video
cargo install ultralytics-inference --features cuda,tensorrt[dependencies]
ultralytics-inference = { version = "0.0.58", 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 的 Results.plot() 一致:线宽默认为图像平均边长的 0.3%(至少 2 px),标签位于每个框上方,空间不足时则显示在框内;实例掩码也以相同方式混合,因此保存的图像与 Python 的结果一致。--line-width、--show-labels、--show-conf 和 --show-boxes 的用法与同名 Python 参数相同。在库中,通过 AnnotateOptions 传入这些参数:
use ultralytics_inference::annotate::{AnnotateOptions, annotate_image_with_options};
let options = AnnotateOptions {
line_width: Some(3),
show_conf: false,
..Default::default()
};
let annotated = annotate_image_with_options(&image, &results[0], &options);分割掩码与 Python 一样,会按推理尺寸生成;传入 --retina-masks(或 InferenceConfig::with_retina_masks(true))即可按原始图像尺寸生成掩码。
常见问题#
不需要。该 crate 可通过 ONNX Runtime 直接运行导出的 ONNX 模型。只有在你事先使用 Ultralytics 软件包训练或导出模型时才需要 Python。
从 Python 软件包导出,例如使用 ONNX 集成;或者让 CLI 在首次运行时下载所选任务对应的标准 nano 模型。
使用切片推理:
--tile 640会将图像拆分为重叠的 640 px 窗口,并将检测结果合并为一个结果。可以,前提是启用了
video功能,并且系统已安装 FFmpeg 6 到 9。此功能支持视频文件、网络摄像头以及 RTSP/RTMP/HTTP 流。这两项功能默认都已启用。
annotate会在图像上绘制边界框、掩码、关键点和类别标签,并且是通过--save写入带标注结果的必需功能。visualize会为--show打开实时窗口。若要构建更小的无头版本,并且只以编程方式返回结果,请使用cargo build --no-default-features禁用这些功能(需要时再单独启用相应功能)。本页是高层概览。每个公共结构体、方法和配置选项的完整 API 参考均按类型发布在 docs.rs,内容直接从源代码生成。
评论
提出问题、分享结果,或帮助其他人。