Ultralytics YOLO27：
Get Started

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。
  • 广泛的硬件支持。支持 CPU，以及 CUDA、TensorRT、CoreML、OpenVINO、DirectML、ROCm 和 XNNPACK 执行提供程序；可在构建时选择。
  • GPU 端预处理。可选的融合 CUDA 内核会在 GPU 上执行 letterbox、归一化和布局转换，并将结果直接传递给模型，全程无需离开设备。
  • 自动下载。首次使用时会自动下载已知的 YOLO 模型名称和示例资源。
在寻找 Python 包？

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

安装#

需要 Rust 1.89 或更高版本。video 功能还需要在系统上安装 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

常用标志：

标志默认值说明
--model, -myolo26n.onnxONNX 模型的路径；已知的 YOLO 名称会自动下载。
--taskdetectdetect、segment、semantic、depth、classify、pose 或 obb 之一。
--source, -s样例图像、目录、glob、视频、摄像头索引或 URL。
--conf0.25置信度阈值。
--iou0.7非极大值抑制的 IoU 阈值。
--imgsz模型元数据推理图像尺寸。
--device自动执行设备，例如 cuda:0、coreml、tensorrt:0。
--max-det300每张图像的最大检测数量。
--recttrue采用最小填充的矩形推理。
--batch1推理批次大小。
--quantize模型默认值推理精度：8/int8、16/fp16、32/fp32、w8a16 或 w8a32。
--savetrue将标注后的结果保存到 runs/<task>/predict。
--save-framesfalse对于视频输入，保存单独的帧，而不是视频文件。
--save-jsonfalse保存语义分割类别图 PNG 文件。
--showfalse在窗口中显示结果。
--verbosetrue打印每张图像的结果和耗时。
--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, 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

模型兼容性#

任何导出为 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。RT-DETR 检测模型也可以运行，但不会自动下载：请先将模型导出为 ONNX。

输入源#

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

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

设备和执行提供程序#

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::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 会通过单个融合 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是绘制边界框、掩码、关键点和标签；--save 需要此功能。
visualize是--show 的实时窗口显示功能。
video否读取和写入视频文件（需要 FFmpeg 6 到 9）。
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.50", 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 功能。

常见问题#

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

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

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

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

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

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

贡献者
ONonuralpszr15GLglenn-jocher3RAraimbekovm1

评论