usls 库参考指南

项目概述

usls 是一个基于 Rust 和 ONNX Runtime 的跨平台机器学习推理库，专注于高效运行视觉和视觉语言模型（通常参数量小于 10 亿）。

核心特性

高性能: 多线程、SIMD 和 CUDA 加速处理
跨平台: 支持 Linux、macOS、Windows，可使用多种执行提供程序（CUDA、TensorRT、CoreML、OpenVINO、DirectML 等）
精度支持: FP32、FP16、INT8、UINT8、Q4、Q4F16、BNB4 等
全栈工具: 包含 DataLoader（数据加载）、Annotator（标注器）和 Viewer（查看器）
统一 API: 所有模型共享同一 Model trait，使用 run()/forward()/encode_images()/encode_texts() 等方法
自动管理: 自动从 HuggingFace/GitHub 下载模型、缓存和路径解析
多输入支持: 图片、目录、视频、摄像头、流及其组合
丰富的模型库: 支持 50+ SOTA 视觉和 VLM 模型

版本信息

当前版本: 0.2.0-alpha.4
最低 Rust 版本: 1.88
ONNX Runtime 版本: >= 1.22.0

核心架构

usls 库采用模块化设计，主要包含以下核心模块：

模块结构图

usls/
├── annotator/       # 图像标注和可视化工具
├── config/          # 配置管理和构建
├── dataloader/      # 数据加载（图像、视频等）
├── models/          # 模型实现
│   ├── vision/      # 视觉模型（45+ 模型）
│   ├── vlm/         # 视觉-语言模型（14+ 模型）
│   └── mot/         # 多目标跟踪
├── ort/             # ONNX Runtime 封装
├── perf/            # 性能分析
├── processor/       # 数据预处理
│   ├── image/       # 图像处理
│   └── text/        # 文本处理
├── results/         # 推理结果类型
│   ├── hbb/         # 水平边界框
│   ├── obb/         # 旋转边界框
│   ├── mask/        # 分割掩码
│   ├── keypoint/    # 关键点
│   ├── prob/        # 分类概率
│   └── text/        # 文本结果
├── tensor/          # 张量操作
├── utils/           # 工具函数
└── viewer/          # 图像/视频查看器

核心设计模式

1. Model Trait - 统一模型接口

所有模型都实现 Model trait，提供统一的推理接口：

pub trait Model: Sized {
    // 输入类型（生命周期关联）
    type Input<'a>;

    // 从配置创建运行时
    fn new(config: Config) -> Result<Runtime<Self>>;

    // 构建模型和引擎
    fn build(config: Config) -> Result<(Self, Engines)>;

    // 运行推理（核心方法）
    fn run(&mut self, engines: &mut Engines, input: Self::Input<'_>) -> Result<Vec<Y>>;

    // 编码相关方法
    fn encode(&mut self, engines: &mut Engines, input: Self::Input<'_>) -> Result<Y>;
    fn encode_images(&mut self, engines: &mut Engines, input: &[Image]) -> Result<Y>;
    fn encode_texts(&mut self, engines: &mut Engines, input: &[&str]) -> Result<Y>;

    // 元数据
    fn batch(&self) -> usize;
    fn spec(&self) -> &str;
}

2. Runtime - 模型运行时

Runtime<M> 将模型与引擎组合，是使用模型的主要入口点：

pub struct Runtime<M: Model> {
    inner: M,           // 模型实例
    engines: Engines,   // 推理引擎
}

// 实现 Deref/DerefMut，允许直接访问模型字段
impl<M: Model> Deref for Runtime<M> {
    type Target = M;
    // ...
}

使用示例：

// 创建模型
let mut model = YoloV8::new(config)?;

// 直接访问模型字段（通过 Deref）
let batch_size = model.batch;

// 运行推理
let results = model.run(&images)?;

3. Engines - 推理引擎管理

支持单引擎和多引擎模型：

// 单引擎模型（如 YOLO）
let engine = Engine::from_config(config)?;
let engines = Engines::from(engine);

// 多引擎模型（如 Florence2）
let engines = Engines::from(vec![
    (Module::ImageModel, image_engine),
    (Module::LanguageModel, language_engine),
]);

4. Y - 统一输出类型

所有模型输出 Y 类型，可以包含多种结果：

pub struct Y {
    // 检测框
    pub hbb: Option<Vec<Hbb>>,           // 水平边界框
    pub obb: Option<Vec<Obb>>,           // 旋转边界框

    // 分割
    pub mask: Option<Vec<Mask>>,         // 分割掩码
    pub contour: Option<Vec<Contour>>,   // 轮廓
    pub polygon: Option<Vec<Polygon>>,   // 多边形

    // 其他
    pub keypoint: Option<Vec<Keypoint>>, // 关键点
    pub prob: Option<Vec<Prob>>,         // 分类概率
    pub text: Option<Vec<Text>>,         // 文本结果
}

模块详解

1. config - 配置模块

提供类型安全的配置构建：

// 创建配置
let config = Config::new()
    .with_model("yolov8s", "detect")
    .with_device("cuda:0")
    .with_batch(1)
    .with_height(640)
    .with_width(640)
    .with_confidence_threshold(0.25)
    .build()?;

主要配置项：

model_name: 模型名称
model_task: 模型任务（detect/segment/pose/classify/obb 等）
device: 执行设备（cpu/cuda:0/tensorrt:0/coreml 等）
batch: 批处理大小
height/width: 输入尺寸
confidence_threshold: 置信度阈值

2. dataloader - 数据加载模块

支持多种数据源：

// 从单个图像
let images = DataLoader::try_new("path/to/image.jpg")?;

// 从目录
let images = DataLoader::try_new("path/to/images/")?;

// 从视频
let images = DataLoader::try_new("path/to/video.mp4")?;

// 从摄像头
let images = DataLoader::try_new(0)?;  // 0 = 摄像头索引

// 从多种源组合
let images = DataLoader::try_new(&["img1.jpg", "img2.png", "video.mp4"])?;

3. models - 模型模块

Vision 模型（45+）

包含以下类别：

目标检测：

YOLO 系列 (v5, v6, v7, v8, v11, v9, v10, v12, v13, v26)
RT-DETR (v1, v2, v4)
RF-DETR, D-FINE, DEIM, DEIMv2

图像分割：

SAM 系列 (SAM, SAM-HQ, MobileSAM, EdgeSAM, SAM2, SAM3)
FastSAM, YOLOE
BiRefNet 系列（多个变体）

图像分类：

BEiT, ConvNeXt, FastViT, MobileOne, DeiT
RAM, RAM++（图像标签）

姿态估计：

RTMPose, DWPose, RTMW, RTMO
MobileGaze（视线估计）

OCR：

检测: DB, FAST, LinkNet, DocLayout-YOLO, PP-DocLayout
识别: SVTR, TrOCR
表格: SLANet

超分辨率：

Swin2SR, APISR

深度估计：

DepthAnything (v1, v2), DepthPro, Depth-Anything-3

其他：

RMBG, BEN2（背景移除）
MODNet, MediaPipe Selfie（图像抠图）
Sapiens（人体视觉模型）
YOLOPv2（全景驾驶）

VLM 模型（14+）

CLIP 系列: CLIP, jina-clip, mobileclip, SigLIP, SigLIPv2
DINO: DINOv2, DINOv3
VLM: BLIP, Florence2, Moondream2, SmolVLM, SmolVLM2, FastVLM
开放词汇检测: GroundingDINO, MM-GDINO, LLMDet, OWLv2, YOLO-World

MOT 模型

ByteTrack（多目标跟踪）

4. results - 结果模块

定义所有模型输出类型：

// 水平边界框 (HBB)
pub struct Hbb {
    pub x: f32,      // 中心 x
    pub y: f32,      // 中心 y
    pub w: f32,      // 宽度
    pub h: f32,      // 高度
    pub label: u32,  // 类别 ID
    pub score: f32,  // 置信度
    pub class: String, // 类别名称
}

// 分割掩码
pub struct Mask {
    pub data: Vec<u8>,     // 掩码数据
    pub w: u32,            // 宽度
    pub h: u32,            // 高度
}

// 关键点
pub struct Keypoint {
    pub points: Vec<(f32, f32)>,  // (x, y) 坐标
    pub scores: Vec<f32>,         // 置信度
}

5. processor - 处理器模块

图像处理

支持 CPU 和 CUDA 加速：

调整大小 (Resize)
填充 (Pad)
归一化 (Normalize)
颜色空间转换

文本处理

Tokenization（使用 tokenizers crate）
Padding
Attention mask 生成

6. annotator - 标注模块

可视化工具，可在图像上绘制：

边界框
掩码
关键点
文本标签

7. tensor - 张量模块

张量操作和转换，支持：

与 ndarray 互操作
GPU 内存管理
数据类型转换（FP32/FP16/INT8）

模型生态系统

YOLO 系列支持

版本	任务	TensorRT	FP16	INT8	Q4
v5	检测/分割/分类	✅	✅	✅	❌
v8	检测/分割/分类/姿态/OBB	✅	✅	✅	❌
v11	检测/分割/分类/姿态/OBB	✅	✅	✅	❌
v26	检测/分割/分类/姿态/OBB	✅	✅	✅	✅

执行提供程序 (Execution Providers)

支持多种硬件加速：

NVIDIA: CUDA, TensorRT, TensorRT-RTX
Apple: CoreML
Intel: OpenVINO
AMD: ROCm, MIGraphX
移动端: NNAPI, QNN, RKNPU
其他: DirectML, XNNPACK, Vitis

快速上手

基础用法

use usls::{Config, DataLoader, YoloV8};

fn main() -> anyhow::Result<()> {
    // 1. 创建配置
    let config = Config::new()
        .with_model("yolov8s", "detect")
        .with_device("cpu")
        .build()?;

    // 2. 加载模型
    let mut model = YoloV8::new(config)?;

    // 3. 加载图像
    let images = DataLoader::try_new("test.jpg")?.load()?;

    // 4. 运行推理
    let results = model.run(&images)?;

    // 5. 处理结果
    for y in results {
        if let Some(detections) = y.hbb {
            for det in detections {
                println!("检测到: {} (置信度: {:.2})", det.class, det.score);
            }
        }
    }

    Ok(())
}

使用 CUDA 加速

let config = Config::new()
    .with_model("yolov8s", "detect")
    .with_device("cuda:0")           // CUDA 设备
    .with_processor_device("cuda:0")  // 图像处理器也用 CUDA
    .build()?;

使用 TensorRT

// 需要启用 tensorrt feature
let config = Config::new()
    .with_model("yolov8s", "detect")
    .with_device("tensorrt:0")
    .build()?;

VLM 模型示例

use usls::{Config, DataLoader, Florence2};

fn main() -> anyhow::Result<()> {
    let config = Config::new()
        .with_model("florence2", "caption")
        .with_device("cuda:0")
        .build()?;

    let mut model = Florence2::new(config)?;
    let images = DataLoader::try_new("test.jpg")?.load()?;

    // 使用文本提示
    let results = model.run((&images, "Generate a caption for this image"))?;

    Ok(())
}

关键概念

1. 生命周期参数

模型输入使用生命周期参数，允许零拷贝：

// Vision 模型
type Input<'a> = &'a [Image];

// VLM 模型
type Input<'a> = (&'a [Image], &'a str);

2. Device 配置

device: 推理执行设备
processor_device: 图像预处理设备

分离配置允许 CPU 预处理 + GPU 推理，或全 GPU 流水线。

3. Batch 处理

支持动态批处理：

// 设置批大小
let config = Config::new()
    .with_batch(8)
    .build()?;

// 批量推理
let results = model.run(&images)?;  // images 可以是任意数量

4. 模型自动下载

首次运行时，模型会自动从 HuggingFace/GitHub 下载并缓存：

~/.cache/usls/models/

5. 特性标志 (Feature Flags)

[features]
default = ["vision", "annotator"]
vision = []       # 视觉模型
vlm = ["vision"]  # 视觉-语言模型
mot = []          # 多目标跟踪

# 执行提供程序
cuda = ["ort/cuda"]
tensorrt = ["ort/tensorrt"]
coreml = ["ort/coreml"]

# 硬件加速
cuda-runtime = ["dep:cudarc"]

学习路径

入门阶段

理解基本流程
- 阅读 src/models/traits.rs 了解 Model trait
- 查看 examples/yolo 了解完整示例
- 运行基础目标检测示例
核心模块
- Config: 配置构建
- DataLoader: 数据加载
- Runtime: 模型运行
- Y: 结果处理

进阶阶段

多模型支持
- 尝试不同任务（分割、姿态估计、OCR）
- 理解不同模型的输出格式
- 使用 Annotator 可视化结果
性能优化
- 使用 CUDA/TensorRT 加速
- 调整批大小
- 选择合适的精度（FP16/INT8）
VLM 模型
- CLIP 嵌入
- Florence2 多任务
- 开放词汇检测

高级阶段

自定义模型
- 实现自己的 Model trait
- 添加新的后处理逻辑
- 集成新的 ONNX 模型
部署
- 交叉编译
- 移动端部署
- 生产环境优化

有用的资源

性能参考（RTX 3060Ti）

配置	预处理	推理	后处理	总计
TensorRT + CUDA + FP16	~233µs	~1.3ms	~14µs	~1.55ms
CUDA + CUDA + FP32	~233µs	~5.0ms	~17µs	~5.25ms
CPU + CPU + FP32	~970µs	~20.5ms	~14µs	~21.48ms

常见问题

Q: 如何选择合适的设备？

CPU: 通用，兼容性最好
CUDA: NVIDIA GPU，良好性能
TensorRT: 最佳性能，需要构建引擎
CoreML: Apple Silicon，低功耗

Q: FP16 vs FP32？

FP16: 更快，更少内存，精度略低
FP32: 最高精度，较慢
对于大多数检测任务，FP16 足够

Q: 如何加速批处理？

增加 batch 配置
使用 GPU 预处理
使用 FP16 精度

本参考指南基于 usls v0.2.0-alpha.4 编写

THE END