InferenceInterface 1.0.39

InferenceInterface

InferenceInterface 是一个面向视觉模型部署的 .NET 10 推理库，统一封装 ONNX Runtime 与 OpenVINO，支持普通 ONNX 模型与 CXDL .qdl/.enc 加密模型。

项目目标是提供一套可复用、可计时、可批处理、可多后端切换的推理接口，并尽量减少前处理、输入张量构造、输出读取和后处理中的托管分配。

当前状态

近期重点完成了 fast path 优化和真实资产验证：

• YOLO11n 单图性能已经与 YoloSharpOnnx 接近，本项目在多数 CPU/DML/部分 CUDA 组合上具备竞争力。
• YOLO11n OpenVINO CPU 与 TensorRT 路径已接入同一套 fast path，并与旧结果做了参考对比。
• YOLO truebatch 已验证：YOLO 的 batch 维由导出模型决定，batch=8 模型只能吃 8 张输入。
• OCR、PatchCore、DINOv2 Global KNN 均已用本机真实模型完成 smoke / benchmark。
• 大图切片、micro-batch、结果投影和全局 NMS/融合 pipeline 已可用。

代表性结论：

详细数据见 文档入口。

能力概览

支持后端：

• ONNX Runtime
  • CPU
  • CUDA
  • DirectML
  • TensorRT
• OpenVINO
  • CPU
  • GPU
  • AUTO

GPU 选择：

• ONNX Runtime CUDA / TensorRT 使用 GpuDeviceId 作为 CUDA device id。
• ONNX Runtime DirectML 使用 GpuDeviceId 作为 DirectML adapter id。
• OpenVINO GPU 支持 GpuDeviceId > 0 时编译到 GPU.{id}；0 保持 OpenVINO 默认 GPU 选择。
• 多 GPU 场景下可以为不同模型实例设置不同 GpuDeviceId，每个实例会加载到对应设备。

支持模型 / 任务：

• YOLO 系列
  • YOLOv5 / YOLOv6 / YOLOv7
  • YOLOv8 / YOLOv9 / YOLOv10
  • YOLOv11 / YOLOv12 / YOLOv13
  • YOLOv26
  • 检测、实例分割、OBB、姿态、分类、语义分割
• 检测模型
  • RT-DETR
  • RF-DETR
  • PP-YOLOE
  • DEIMv2
• OCR
  • PaddleOCR / PP-OCRv5
  • OneOCR（完整图片检测、文字系统分类、识别、拒识、置信度校准及行布局）
• 交互分割
  • SAM 2.1（small、base+ 内置 FP32 模型，按需选择）
• 异常检测
  • Anomalib / PatchCore
  • DINOv2 Global KNN
  • DINOv2 Patch KNN
  • DINOv2 PCA Mahalanobis
• 注册学习
  • 注册分类
  • 注册异常检测
  • 注册异常粗分割
  • 固定尺度注册检测

核心特性：

• Predict
• PredictAsync
• PredictBatch
• PredictBatchAsync
• fast path 直接写入可复用输入 buffer
• ONNX Runtime / OpenVINO reusable runner 池
• CPU 输出 view 借用，减少输出复制
• 模型级 resize workspace 复用
• 前处理 / 推理 / 后处理分段计时
• 并发上限控制
• 全局 GPU 推理调度器（默认关闭，可按后端、设备和 GPU id 显式限流）
• QDL 文件头元数据读取
• 大图切片、micro-batch、结果投影、全局合并

目录结构

InferenceInterface/
├── Configuration/      # 后端枚举、fallback、运行时配置、QDL 加载
├── Data/               # 图像预处理、NMS、结果结构和池化辅助
├── Engine/             # ONNX Runtime / OpenVINO 引擎与 reusable runner
├── Memory/             # 输入/输出张量内存封装和 buffer 池
├── Models/             # 模型配置、模型实现、模型工厂
├── Pipeline/           # 大图切片、投影、合并和语义融合 pipeline
├── Result/             # 统一结果接口和速度统计结构
├── Utils/              # 计时器、Profiler、调度器等辅助工具
├── OcrTest/            # OCR 并发和 batch 测试项目
├── LargeImageDetTest/  # 大图检测测试项目
├── AnomalyTest/        # 异常检测测试项目
├── Benchmark/          # 对比 benchmark 工具
├── artifacts/          # 临时 smoke/benchmark runner 源码，输出不入库
├── tools/runtime/      # 运行时收集、验证和安装包脚本
└── docs/               # 中文方案文档和 benchmark 记录

快速开始

安装依赖

项目目标框架是 .NET 10。

pwsh -NoLogo -NoProfile -Command "& { [Console]::InputEncoding=[System.Text.Encoding]::UTF8; [Console]::OutputEncoding=[System.Text.Encoding]::UTF8; dotnet restore InferenceInterface.sln; dotnet build InferenceInterface.sln -c Release --no-restore }"

当前仓库不提交本机生成的 runtime payload、大模型、TensorRT cache、benchmark 原始输出和外部对比仓库。需要运行 Benchmark/YoloSharpComparison 时，请先按其 README 克隆 YoloSharpOnnx 到 external/YoloSharpOnnx。

YOLO 检测

using InferenceInterface.Configuration;
using InferenceInterface.Models;
using OpenCvSharp;

using var model = ModelFactory.CreateYolov11Det(
    modelPath: @"C:\models\yolo11n.onnx",
    backend: BackendType.OnnxRuntime,
    device: DeviceType.GPU,
    provider: OnnxRuntimeProvider.CUDA,
    confidence: 0.25f,
    nms: 0.45f,
    inputWidth: 640,
    inputHeight: 640);

using var image = Cv2.ImRead(@"C:\images\test.jpg");
var results = model.Predict(image);

指定 GPU

推荐使用统一入口：

using InferenceInterface.Configuration;
using InferenceInterface.Models;
using InferenceInterface.Models.Config;

using var session = InferenceSessionFactory.Create(new InferenceSessionOptions
{
    ModelPath = @"C:\models\yolo11n.onnx",
    Architecture = ModelArchitecture.Yolov11,
    Task = ModelTask.Detect,
    Backend = BackendType.OnnxRuntime,
    Provider = OnnxRuntimeProvider.CUDA,
    Device = DeviceType.GPU,
    GpuDeviceId = 1
});

也可以直接用具体模型配置：

using var model = new Yolov11DetModel(new Yolov11DetConfig(@"C:\models\yolo11n.onnx")
{
    Backend = BackendType.OnnxRuntime,
    Provider = OnnxRuntimeProvider.DML,
    Device = DeviceType.GPU,
    GpuDeviceId = 1
});

OpenVINO GPU 指定方式：

using var session = InferenceSessionFactory.Create(new InferenceSessionOptions
{
    ModelPath = @"C:\models\yolo11n.onnx",
    Architecture = ModelArchitecture.Yolov11,
    Task = ModelTask.Detect,
    Backend = BackendType.OpenVINO,
    Device = DeviceType.GPU,
    GpuDeviceId = 1
});

全局 GPU 调度器

多模型、多 session 共享同一块 GPU 时，可以显式开启全局 GPU 调度器，限制同一 Backend + Device + Provider + GpuDeviceId 桶内同时进入 GPU 推理段的数量。调度器默认关闭，避免给现有单模型或 DirectML 高并发路径引入额外开销。

using var session = InferenceSessionFactory.Create(new InferenceSessionOptions
{
    ModelPath = @"C:\models\yolo11n.onnx",
    Architecture = ModelArchitecture.Yolov11,
    Task = ModelTask.Detect,
    Backend = BackendType.OnnxRuntime,
    Provider = OnnxRuntimeProvider.CUDA,
    Device = DeviceType.GPU,
    GpuDeviceId = 0,
    EnableGlobalGpuScheduler = true,
    GlobalGpuConcurrency = 4
});

GlobalGpuConcurrency = 0 时使用后端默认预算；如果业务中不同模型耗时差异很大，可以用 GpuSchedulerWeight 让重模型占用更多令牌。

批量推理

YOLO 的 truebatch 取决于导出模型的输入 batch 维。如果模型输入是 [8,3,640,640]，就需要传入 8 张图；如果模型输入是 [1,3,640,640]，PredictBatch 会按模型支持的 batch 拆分执行。

using var image1 = Cv2.ImRead(@"C:\images\a.jpg");
using var image2 = Cv2.ImRead(@"C:\images\b.jpg");

var batchResults = model.PredictBatch([image1, image2]);

QDL 加密模型

加载 CXDL 导出的 .qdl 或旧 .enc(.json) 模型时，直接传入模型路径即可：

using var model = ModelFactory.CreateYolov8Det(
    modelPath: @"C:\models\model.qdl",
    backend: BackendType.OnnxRuntime,
    device: DeviceType.GPU,
    provider: OnnxRuntimeProvider.TensorRT);

支持：

• AES-256-GCM
• 编译进库内的产品密钥
• 新 .qdl 文件头元数据
• 旧 .enc(.json) 侧车元数据

TensorRT 后端冷构建可能分钟级，建议启用预构建并使用异步入口。当前版本建议显式提供 profile：

using InferenceInterface.Configuration;
using InferenceInterface.Configuration.TensorRt;
using InferenceInterface.Models;

var options = new InferenceSessionOptions
{
    ModelPath = modelPath,
    Backend = BackendType.OnnxRuntime,
    Device = DeviceType.GPU,
    Provider = OnnxRuntimeProvider.TensorRT
};
options.TensorRtPrebuild.EnablePrebuild = true;
options.TensorRtPrebuild.ProfileShape = new TensorRtProfileShape
{
    InputName = "images",
    Channels = 3,
    MinBatch = 1,
    OptBatch = 1,
    MaxBatch = 1,
    MinHeight = 640,
    OptHeight = 640,
    MaxHeight = 640,
    MinWidth = 640,
    OptWidth = 640,
    MaxWidth = 640
};

using var session = await InferenceSessionFactory.CreateAsync(options, cancellationToken);

QDL 感知大图检测

如果 .qdl 文件头包含 cxdl_infer_config，可以使用 QDL 感知入口自动选择整图或切图推理：

using InferenceInterface.Configuration;
using InferenceInterface.Models;
using OpenCvSharp;

using var pipeline = ModelFactory.CreateQdlAwareYolov8DetPipeline(
    modelPath: @"C:\models\model.qdl",
    backend: BackendType.OnnxRuntime,
    device: DeviceType.GPU,
    provider: OnnxRuntimeProvider.CUDA,
    confidence: 0.25f,
    nms: 0.45f);

using var image = Cv2.ImRead(@"C:\images\large.jpg");
var result = await pipeline.PredictAsync(image);

tiling.mode=off 时走整图推理，tile 时固定切图，auto 时按 large_image_threshold 判断。tile_size 会映射为切片宽高，stride 会映射为 overlap = tile_size - stride。

手动大图 pipeline

using InferenceInterface.Configuration;
using InferenceInterface.Models;
using InferenceInterface.Pipeline.LargeImage;
using OpenCvSharp;

var options = new LargeImageInferenceOptions
{
    TileWidth = 640,
    TileHeight = 640,
    OverlapX = 64,
    OverlapY = 64,
    MicroBatchSize = 2,
    PreferTrueBatch = true,
    FilterByTileCore = true,
    EnableGlobalNms = true,
    GlobalNmsThreshold = 0.45f
};

using var pipeline = ModelFactory.CreateLargeImageYolov8DetPipeline(
    modelPath: @"C:\models\yolov8s.onnx",
    options: options,
    backend: BackendType.OnnxRuntime,
    device: DeviceType.GPU,
    provider: OnnxRuntimeProvider.CUDA,
    confidence: 0.25f,
    nms: 0.45f,
    inputWidth: 640,
    inputHeight: 640);

using var image = Cv2.ImRead(@"C:\images\large.jpg");
var result = await pipeline.PredictAsync(image);

YOLOv8 实例分割、OBB、姿态和语义分割也提供对应的大图入口：

using var segPipeline = ModelFactory.CreateQdlAwareYolov8SegPipeline(@"C:\models\seg.qdl");
using var obbPipeline = ModelFactory.CreateQdlAwareYolov8ObbPipeline(@"C:\models\obb.qdl");
using var posePipeline = ModelFactory.CreateQdlAwareYolov8PosePipeline(@"C:\models\pose.qdl");
using var semPipeline = ModelFactory.CreateQdlAwareSemanticSegPipeline(@"C:\models\semantic.qdl");
using var yoloSemPipeline = ModelFactory.CreateQdlAwareYolov26SemPipeline(@"C:\models\yolo-sem.qdl");

测试项目

文档入口

完整索引见 docs/README.md。

重点文档：

• SAM 2.1 交互分割

• fast path 优化记录

• YoloSharpOnnx yolo11n 单图对比

• OpenVINO / TensorRT fast path 对比

• YOLO11n 多 batch / truebatch 对比

• OCR PP-OCRv5 benchmark

• PatchCore / DINOv2 KNN 测试记录

• YOLO11n 全局 GPU 调度器 benchmark

• 大图检测流水线设计

• 历史对比测试汇总

推荐默认值

OCR：

大图检测：

YOLO batch：

• 低延迟或 CPU 场景优先使用 batch=1 模型。
• GPU 吞吐场景可以导出固定 batch=8 truebatch 模型。
• TensorRT truebatch benchmark 需要隔离 engine cache，避免不同 batch 模型共用 trt_cache 引发 shape mismatch。

仓库说明

本仓库提交源码、测试项目、benchmark runner 源码和中文文档，不提交以下本机产物：

• bin/obj
• external/YoloSharpOnnx
• Benchmark/YoloSharpComparison/results
• AnomalyTest/output
• OcrTest/output
• .nupkg-test
• trt_cache
• tools/runtime/payload
• 大模型、运行时 payload、TensorRT engine cache

如需复现 benchmark，请按文档准备对应模型、图片和外部测试数据。

平面 RGB 指针输入

普通矩形 ROI 可通过 PlanarRgbImage 直接传入三个 RGB8 通道指针、原始 ROI 宽高和原图行跨度，绕过大图 BGR 转换。支持同步、异步及详细结果重载，调用方须持有源图至调用最终完成。详见平面 RGB 指针推理。

OneOCR 补充 OCR

现已提供独立的 OneOCR det、cls、9 个语言 rec 和完整图片 OCR 接口，并补充拒识、逐词置信度校准和行布局分类，通过显式 ModelArchitecture.OneOcr 使用，与 PaddleOCR 并存。支持 ORT CPU、CUDA、TensorRT/CUDA 混合路径及 OpenVINO CPU；模型、商品图性能、公开语料验证、精度限制与用法见 OneOCR 文档。

OCR 逐字符定位（1.0.39）

PaddleOCR 和 OneOCR 可通过 PredictOptions.Ocr 开启 CTC 初始框或边界优化，返回原图字符四边形。支持按业务行选择亮暗、字体和字宽配方，识别后无需重跑网络即可调参重分框、从原图裁剪字符。默认关闭；详见 OCR 字符定位 和 1.0.39 发布说明。

兼容性变化：PaddleOCR 修复了 blank 分隔重复字符被错误合并的问题，例如 A–blank–A 现在输出 AA；关闭字符定位时同样生效。分框状态不代表正确率，也不直接判定字符缺陷。