C# OnnxRuntime部署DocLayout-YOLO：从模型加载到推理接口实战

简介本资源面向需要在 C# 项目中落地文档版面分析的开发者提供基于 OnnxRuntime 部署 DocLayout-YOLO 的完整工程。DocLayout-YOLO 以 YOLO-v10 为基础通过 Mesh-candidate BestFit 合成大规模文档数据集 DocSynth-300K并引入全局到局部可控感知模块可对尺度差异明显的文档元素实现实时、鲁棒的检测适用于票据、论文、合同等版面解析场景。压缩包共 325 个文件约 463.21MB包含 64 个 dll、9 个 cs 源码、2 个 onnx 模型、3 个 onnxruntime 相关库以及 xml、h、lib、props、nupkg 等依赖与配置另有 jpg、png 示例图和 md 说明文档覆盖从模型推理到工程编译的完整链路。已有 329 人学习下载。读者可据此快速搭建 C# 推理环境理解模型加载、预处理与后处理流程并参考目录结构完成二次开发与排错。1. C# OnnxRuntime部署DocLayout-YOLO从模型文件到可调用推理接口手里拿到一个训练好的 DocLayout-YOLO 模型想把它塞进 C# 上位机里跑版面分析这件事听起来只是“加载模型、喂图、拿结果”三步实际动手会发现坑集中在三处模型导出时的输出节点名对不上、预处理和后处理必须和训练侧严格一致、OnnxRuntime 的会话配置直接决定推理耗时。DocLayout-YOLO 做的是文档版面元素检测能识别标题、正文、表格、图片、页眉页脚等区域适合扫描件结构化、PDF 版面还原、票据字段定位这类场景。用 C# 部署而不是 Python通常是因为最终交付物是桌面端或工控上位机不想在目标机器上再装一套 Python 环境。下面按“先跑通最小推理再补预处理和后处理最后调性能和排错”的顺序讲清楚。2. DocLayout-YOLO 的输入输出约定与 C# 侧选型2.1 先确认模型到底吃什么、吐什么DocLayout-YOLO 基于 YOLO 检测头导出 ONNX 后典型输入是[1, 3, H, W]的 float32 张量输出通常是[1, N, 6]或[1, 6, N]六个维度依次是x1, y1, x2, y2, score, class_id部分导出脚本会把 score 和 class_id 顺序调换。在写 C# 代码之前先用 Python 把 ONNX 的输入输出形状打印出来这一步不能省。import onnx model onnx.load(doclayout_yolo.onnx) for inp in model.graph.input: dims [d.dim_value for d in inp.type.tensor_type.shape.dim] print(input:, inp.name, dims) for out in model.graph.output: dims [d.dim_value for d in out.type.tensor_type.shape.dim] print(output:, out.name, dims)逻辑说明这段脚本只做一件事把 ONNX 计算图的输入输出名称和维度打印出来。参数说明dim_value为 0 表示该维度是动态的常见于 batch 维或 anchor 数量维如果输出第二维是动态的后处理里就不能写死循环上界要按实际返回的张量长度来遍历。拿到这些信息后再决定 C# 里怎么构造输入张量和解析输出。2.2 C# 侧依赖选型Microsoft.ML.OnnxRuntime 还是 OnnxRuntime.GpuC# 调 ONNX 最稳的是官方 NuGet 包Microsoft.ML.OnnxRuntimeCPU 版直接引用即可需要 GPU 就换成Microsoft.ML.OnnxRuntime.Gpu但要注意 CUDA 和 cuDNN 版本必须和包内 native 库匹配否则会在创建 Session 时抛DllNotFoundException或OnnxRuntimeException。选型判断很简单文档版面分析单页推理在 CPU 上通常几十到几百毫秒如果上位机是鲲鹏 920 这类 ARM 平台优先用 CPU 版并确认有对应架构的 native 库如果是 x64 加独立显卡且单页要求低于 50ms再上 GPU 版。dotnet add package Microsoft.ML.OnnxRuntime --version 1.17.0逻辑说明这条命令把 CPU 版推理库加入项目。参数说明版本号不要盲目追新要和目标运行环境的 glibc、VC 运行库匹配ARM64 平台要确认该版本是否提供linux-arm64或win-arm64的 native 资产没有就换版本或改用源码编译。2.3 用 InferenceSession 跑通第一张图最小可运行代码如下先不管预处理是否完美目标是让 Session 成功创建并完成一次推理。using Microsoft.ML.OnnxRuntime; using Microsoft.ML.OnnxRuntime.Tensors; var options new SessionOptions(); options.GraphOptimizationLevel GraphOptimizationLevel.ORT_ENABLE_ALL; options.IntraOpNumThreads Environment.ProcessorCount / 2; using var session new InferenceSession(doclayout_yolo.onnx, options); // 假设模型输入为 1x3x1024x1024 var inputTensor new DenseTensorfloat(new[] { 1, 3, 1024, 1024 }); var inputs new ListNamedOnnxValue { NamedOnnxValue.CreateFromTensor(images, inputTensor) }; using var results session.Run(inputs); var output results.First().AsTensorfloat(); Console.WriteLine($output dims: {string.Join(,, output.Dimensions)});逻辑说明SessionOptions里开了全图优化和线程数控制IntraOpNumThreads设成核数一半是经验值设满有时反而因为线程争抢变慢。参数说明NamedOnnxValue.CreateFromTensor的第一个参数必须和 2.1 步打印出的输入名完全一致大小写敏感output.Dimensions用来验证输出形状是否符合预期如果维度数和预期不符说明导出时输出节点选错了。3. 预处理与后处理的 C# 实现细节3.1 letterbox 缩放别直接用 Resize 拉伸DocLayout-YOLO 训练时用的是 letterbox即保持宽高比缩放后填充灰边。如果 C# 里直接拉伸到 1024x1024长宽比变化会让检测框整体偏移表格和正文的边界尤其明显。public static (float[] data, float scale, int padX, int padY) Letterbox( byte[] bgr, int srcW, int srcH, int dstW, int dstH) { float scale Math.Min((float)dstW / srcW, (float)dstH / srcH); int newW (int)(srcW * scale); int newH (int)(srcH * scale); int padX (dstW - newW) / 2; int padY (dstH - newH) / 2; var tensor new float[3 * dstW * dstH]; // 填充值 114/255与训练侧一致 for (int i 0; i tensor.Length; i) tensor[i] 114f / 255f; // 此处省略双线性插值缩放按 newW/newH 写入对应位置 // 归一化到 0~1BGR 转 RGB 后按 CHW 排列 return (tensor, scale, padX, padY); }逻辑说明先算缩放比和填充量再把缩放后的像素写到目标张量的居中区域四周保留 114 灰。参数说明scale和padX/padY必须保存下来后处理把框映射回原图时要用填充值 114 是 YOLO 系列惯例如果训练侧改了填充值这里必须同步改否则边缘区域会产生虚假检测。3.2 输出解析置信度过滤和 NMS 的 C# 写法拿到[1, N, 6]输出后先按置信度阈值过滤再做 NMS。注意坐标要先用scale和pad还原回原图尺度。public static ListBox Parse(float[] raw, int num, float confThres, float iouThres, float scale, int padX, int padY) { var boxes new ListBox(); for (int i 0; i num; i) { int o i * 6; float score raw[o 4]; if (score confThres) continue; float x1 (raw[o 0] - padX) / scale; float y1 (raw[o 1] - padY) / scale; float x2 (raw[o 2] - padX) / scale; float y2 (raw[o 3] - padY) / scale; boxes.Add(new Box { X1 x1, Y1 y1, X2 x2, Y2 y2, Score score, ClassId (int)raw[o 5] }); } return Nms(boxes, iouThres); }逻辑说明逐行读取六个值先过滤低置信度再把坐标从 letterbox 空间还原到原图空间最后做 NMS。参数说明confThres文档场景建议 0.25 起步表格密集时降到 0.15 减少漏检iouThres常用 0.45如果同类框重叠严重可降到 0.4。NMS 按类别分别做不同版面元素之间不应该互相抑制。3.3 类别映射要和训练配置对齐DocLayout-YOLO 的类别顺序取决于训练时的data.yaml常见顺序是 title、plain text、abandon、figure、figure caption、table、table caption、header、footer、reference、equation。C# 里必须维护一份同样的映射表否则会把表格标成正文。private static readonly string[] Labels { title, plain text, abandon, figure, figure caption, table, table caption, header, footer, reference, equation };逻辑说明数组下标即 class_id直接查表得到可读标签。参数说明如果训练时类别数不是 11以实际data.yaml的names为准类别顺序错位是部署后“结果看起来对但标签全错”的最常见原因。4. 性能调优与跨平台部署的注意点4.1 会话复用和输入尺寸的取舍每次推理都新建InferenceSession是新手最容易犯的错创建会话要加载模型、做图优化耗时可能是单次推理的几十倍。正确做法是把 session 做成单例或长期持有。输入尺寸方面1024x1024 精度好但慢768x768 在多数文档上够用速度能快近一倍。可以在配置里留一个尺寸参数按业务对精度和延迟的要求切换。// 单例持有避免重复加载 private static readonly LazyInferenceSession _session new(() new InferenceSession(doclayout_yolo.onnx, BuildOptions())); private static SessionOptions BuildOptions() { var o new SessionOptions(); o.GraphOptimizationLevel GraphOptimizationLevel.ORT_ENABLE_ALL; o.EnableCpuMemArena true; o.EnableMemoryPattern true; return o; }逻辑说明用LazyT保证线程安全的延迟初始化EnableCpuMemArena和EnableMemoryPattern减少重复内存分配。参数说明多线程调用同一个 session 时Run本身是线程安全的但要注意输入张量不要跨线程复用同一块内存。4.2 鲲鹏 920 等 ARM 平台的适配要点在 ARM64 上部署时NuGet 包必须包含对应架构的 native 库。如果运行时提示找不到onnxruntime动态库先检查输出目录下runtimes/linux-arm64/native/是否存在。另外 ARM 上线程数设置要保守IntraOpNumThreads设成物理核数而非超线程数否则可能因为调度开销导致性能下降。如果目标环境是特定 Linux 发行版还要确认 glibc 版本满足 native 库要求。4.3 批量推理与异步封装上位机通常要连续处理多页文档逐页同步调用会阻塞 UI 线程。可以把推理包在Task.Run里或者用InferenceSession.RunAsync部分版本支持。批量维度上ONNX 模型如果导出时 batch 维是动态的可以一次喂多张图但要注意显存或内存占用CPU 上批量收益不明显反而增加延迟。public async TaskListBox DetectAsync(byte[] image) { return await Task.Run(() { var (tensor, scale, padX, padY) Preprocess(image); var inputs new ListNamedOnnxValue { NamedOnnxValue.CreateFromTensor(images, tensor) }; using var results _session.Value.Run(inputs); var raw results.First().AsTensorfloat(); return Parse(raw.ToArray(), raw.Dimensions[1], 0.25f, 0.45f, scale, padX, padY); }); }逻辑说明把预处理、推理、后处理整体放到线程池执行避免阻塞调用方。参数说明raw.Dimensions[1]是检测框数量如果输出是[1, 6, N]则要取Dimensions[2]并调整解析顺序ToArray()会产生一次拷贝大输出时可以用Memoryfloat减少分配。5. 部署 DocLayout-YOLO 常见的五类翻车现场5.1 推理结果全为空或置信度极低现象模型能跑通但所有框的 score 都低于 0.1。原因预处理归一化方式不对训练侧可能是 0~255 直接输入而非 0~1或者 BGR/RGB 通道顺序反了。解决回看训练配置里的预处理确认是否除以 255、是否换通道用同一张图在 Python 侧跑一遍对比 score能快速定位是预处理还是后处理问题。5.2 检测框整体偏移或缩放错误现象框的位置看起来“差不多但就是不准”越靠边越偏。原因letterbox 的 scale 和 pad 没有正确还原或者后处理里用了拉伸后的坐标直接当原图坐标。解决检查Parse里是否做了(x - pad) / scale并确认scale用的是Math.Min而不是分别对宽高算。5.3 创建 Session 时报 DllNotFound 或版本冲突现象new InferenceSession抛异常提示找不到onnxruntime或onnxruntime_providers_shared。原因NuGet 包的 native 库没有复制到输出目录或 GPU 版缺少匹配的 CUDA/cuDNN。解决检查 bin 目录下 runtimes 文件夹是否完整GPU 版先确认 CUDA 版本再决定是否需要手动指定 provider。5.4 多线程下结果错乱或崩溃现象单线程正常多线程调用时偶发结果错乱或 access violation。原因多个线程共享了同一个输入张量或输出缓冲区或者 session 被释放后仍在使用。解决每次推理独立创建输入张量session 用单例且不要提前 Dispose如果用了AsTensor返回的视图注意其生命周期不能超过results。5.5 类别标签全部错位现象框的位置对但标签张冠李戴。原因C# 里的 Labels 数组顺序和训练data.yaml不一致。解决直接对照data.yaml的names逐项核对不要凭记忆写如果训练时类别有增删以最终导出模型对应的配置为准。6. 用一张对照图验证部署是否真的对齐部署完成后最有效的验证手段不是看单张图的输出而是做一次 Python 与 C# 的逐框对照。具体做法选一张包含表格、图片、标题的典型文档页在 Python 侧用同样的 ONNX 模型跑一遍把框坐标、score、class_id 导出成 CSVC# 侧对同一张图跑一遍也导出 CSV然后逐行比对坐标误差应在 1~2 像素内score 误差在 1e-3 内类别完全一致。如果坐标有系统性偏移问题在 letterbox如果 score 差异大问题在归一化如果只有个别框对不上检查 NMS 的阈值和排序稳定性。对比项允许误差超差时优先排查框坐标1~2 像素letterbox 的 scale/pad 还原置信度1e-3归一化方式、通道顺序类别 ID完全一致Labels 数组与 data.yaml框数量允许 NMS 边界差异iouThres 和排序规则我自己的习惯是每次换模型版本或改预处理参数这张对照表必须重新跑一遍不跑就不上线。文档版面分析这种任务肉眼看着“差不多”的框到了下游字段抽取环节可能就是整行错位。希望帮到你。本文还有配套的精品资源点击获取