InferenceInterface 1.0.33

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
• 异常检测
  • 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。

重点文档：

• 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，请按文档准备对应模型、图片和外部测试数据。