开始使用

Rust 版 Ultralytics 推理

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

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() 生成的图像相同。
在寻找 Python 包?

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

安装#

需要 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, -myolo26n.onnxONNX 模型或 OpenVINO 导出的路径;已知的 YOLO 名称会自动下载。
--taskdetect可以是 detect、segment、semantic、depth、classify、pose、obb 之一;如果省略 --model,则选择 nano 模型。
--source, -s样例图像、目录、glob、视频、网络摄像头索引、流或 URL。
--conf0.25置信度阈值。
--iou0.5非极大值抑制的 IoU 阈值。
--max-det300每张图像的最大检测数量。
--imgsz模型元数据推理图像尺寸。
--rect [<BOOL>]true采用最小填充的矩形推理。
--tile [<TILE>]关闭用于重叠窗口推理的切片尺寸;单独指定 --tile 时使用 --imgsz。参见切片推理。
--retina-masksfalse以原始图像尺寸而非推理尺寸生成分割掩码。
--ocrfalse使用 PaddleOCR 读取每个框、定向框或掩码中的文本;如果不指定 --model,则运行 yolo26n-text.onnx。参见 OCR。
--batch1推理批次大小。
--quantize模型精度推理精度:8、16、32、int8、fp16、fp32、w8a8、w16a16、w32a32、w8a16 或 w8a32。
--save [<BOOL>]true将标注后的结果保存到 runs/<task>/predict。
--save-framesfalse对于视频输入,保存单独的帧,而不是视频文件。
--save-jsonfalse保存语义分割类别图 PNG 文件。
--showfalse在窗口中显示结果。
--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:

模型系列支持自动下载的变体
YOLO26yolo26{n,s,m,l,x}.onnx、-seg、-sem、-depth、-cls、-pose、-obb 和 -text
YOLO11yolo11{n,s,m,l,x}.onnx、-seg、-cls、-pose 和 -obb
YOLOv8yolov8{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/文件夹中的所有图像。
Globimages/*.jpgShell 风格的模式。
视频video.mp4需要 video 功能。
网络摄像头0需要 video 功能。
流rtsp://...需要 video 功能。
URLhttps://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 640
use 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 变体构建功能硬件
cpuDevice::Cpu内置任意 CPU
cuda:0Device::Cuda(0)cudaNVIDIA GPU
tensorrt:0Device::TensorRt(0)tensorrtNVIDIA GPU,优化版
coremlDevice::CoreMlcoremlApple Silicon / macOS
intel:cpuDevice::IntelCpuopenvino 或 openvino-nativeIntel CPU
intel:gpuDevice::IntelGpuopenvino 或 openvino-nativeIntel GPU
intel:npuDevice::IntelNpuopenvino 或 openvino-nativeIntel NPU
directml:0Device::DirectMl(0)directmlWindows GPU
rocm:0Device::Rocm(0)rocmAMD GPU
migraphx:0Device::MiGraphX(0)migraphxAMD GPU(Linux x64)
xnnpackDevice::Xnnpackxnnpack优化型 CPU
# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrt

OpenVINO 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:gpu

GPU 加速和 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 preprocessing
匹配你的 CUDA 工具包

cuda-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。

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

  • 从 Python 软件包导出,例如使用 ONNX 集成;或者让 CLI 在首次运行时下载所选任务对应的标准 nano 模型。

  • 可以。--ocr 使用 YOLO26-Text 检测器和 PaddleOCR 读取场景文本,与 Python OCR 解决方案类似,也适用于你自己的检测和分割模型生成的框或掩码。参见场景文本 OCR。

  • 使用切片推理:--tile 640 会将图像拆分为重叠的 640 px 窗口,并将检测结果合并为一个结果。

  • 可以,前提是启用了 video 功能,并且系统已安装 FFmpeg 6 到 9。此功能支持视频文件、网络摄像头以及 RTSP/RTMP/HTTP 流。

  • 这两项功能默认都已启用。annotate 会在图像上绘制边界框、掩码、关键点和类别标签,并且是通过 --save 写入带标注结果的必需功能。visualize 会为 --show 打开实时窗口。若要构建更小的无头版本,并且只以编程方式返回结果,请使用 cargo build --no-default-features 禁用这些功能(需要时再单独启用相应功能)。

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

评论

提出问题、分享结果,或帮助其他人。