简介：面向C#开发者的完整光学字符识别示例工程，基于ONNX运行时调用飞桨OCR模型，实现中文文字识别。资源内置可直接运行的演示程序与配套模型文件，适合需要快速集成识别能力或学习C#端模型部署的技术人员，也适合作为课程设计与毕业设计的参考基座。压缩包共约338MB，包含2000个文件，其中6个onnx模型为识别核心，189个dll与27个nupkg支撑运行依赖，21个pdb便于调试定位，1117个xml、127个txt与18个cs文件分别承担配置说明、参数记录和源码示例，整体目录结构完整清晰，目前已有513人学习下载。学习时可对照源码、配置与模型文件，从加载模型、图像预处理到输出识别结果逐段理解完整调用链路，也可将演示工程直接作为基础，替换业务图片并调整参数，快速验证飞桨OCR在C#环境下的中文识别效果。对于希望研究C#与深度学习模型集成方式的开发者，这份示例能明显缩短环境配置与排错时间。
1. 在 C# 客户端里直接跑 OCR，RapidOCR 是目前最顺的一条路
接到这类需求通常是上位机或工具软件要离线识别：生产批号、序列号、单据上的金额。给客户机装 Python、起 FastAPI 服务在多数厂里不现实，甚至有些机器还是 32 位系统。RapidOCR 就是这个场景里最合适的 C# 本地部署方案——它是 PaddleOCR 模型的 ONNX 推理实现，只拿三个 onnx 模型文件加一个 NuGet 包，就能在 WinForm、WPF、控制台里完成从文本检测到识别的一整套流程。跟 Tesseract 比，它的中文和印刷汉字识别正确率不是一个量级；跟完整 PaddleOCR 比，它去掉了 Paddle 运行时，部署体积和依赖复杂度都低很多。下面按我搭过的流程，从最小代码到生产参数逐步讲。
2. 在 .NET 环境里跑通 RapidOCR：项目搭建、模型放置与第一个识别命令
2.1 依赖其实只有 NuGet 包加三个模型文件
RapidOCR 在 C# 里的运行依赖非常克制：一个 NuGet 包（自带 ONNX Runtime 与 OpenCvSharp 依赖），外加三个转换好的 onnx 模型文件。模型分别是 det（文本检测）、rec（文字识别）、cls（方向分类）。在 NuGet 搜索 RapidOCR，官方发布的包会把 OpenCvSharp4 一起带进来，不需要再手动逐项引用，但项目里如果已经存在 OpenCvSharp 的独立引用，版本必须对齐。
用命令行建项目：
dotnet new console -n RapidOcrDemo cd RapidOcrDemo dotnet add package RapidOCR逻辑说明：dotnet add package RapidOCR会把主包、OpenCvSharp4 和 Microsoft.ML.OnnxRuntime 一并拉进项目。如果项目目标框架是 .NET Framework 而不是 .NET 6+，建议改用 Package Manager Console 里的Install-Package RapidOCR，并确认包是否支持对应目标框架。
模型文件放置有个常见坑：直接把 onnx 文件拖进项目根目录，忘了把“复制到输出目录”改成“如果较新则复制”，程序在调试目录下运行时找不到模型。我的习惯是建一个models子目录，三个文件重命名为约定名称再引用，这样换模型版本时只覆盖文件不用动代码。下表是三个模型文件的职责：
| 模型文件 | 用途 | 是否必需 |
|---|---|---|
| det.onnx | 文本检测，输出候选框 | 必需 |
| rec.onnx | 文本识别，输出字符序列 | 必需 |
| cls.onnx | 方向分类，纠正 0/180 度翻转 | 建议 |
提示：三个模型加起来一般不到 20MB，打进离线安装包是划算的。cls 模型只在 UseCls=true 时才加载，如果场景全是正向印刷体，可以只放 det 和 rec 两个文件。
2.2 最小识别代码：一张图打印所有文本行
以下代码放进 Program.cs 即可跑通。
using OpenCvSharp; using RapidOcrOnnx; var options = new OnnxOcrOptions { NumThread = 4, UseDet = true, UseCls = true, UseRec = true }; using var ocr = new OnnxOcr("./models", options); using var mat = Cv2.ImRead("invoice.jpg", ImreadModes.Color); if (mat.Empty()) { Console.WriteLine("图片加载失败，检查路径和文件是否存在。"); return; } var result = ocr.GetText(mat); foreach (var block in result.TextBlocks) { Console.WriteLine($"置信度 {block.Score:F3} {block.Text}"); }逻辑说明：OnnxOcr是主识别引擎，构造函数第一个参数是模型目录；程序启动时按目录中的 onnx 文件加载模型。GetText接收 OpenCvSharp 的Mat，返回结果对象，TextBlocks里每项是检测并识别出的一行文本。Score是该行的平均置信度，通常大于 0.9；如果一批图的分值普遍低于 0.8，先检查图片清晰度，别急着调模型参数。
参数说明：NumThread决定 ONNX Runtime 推理线程数，注意它和 .NET 线程池没有关系，是会话内部的算子并行度，四核机器设 4 比较稳。UseCls打开方向分类，随手拍的单据常带 180 度翻转，开上省心；纯正向印刷体可以关。UseDet和UseRec默认保持 true，只做版面检测时可把UseRec关掉省时间。
跑通后输出大致是下面这种格式，代表模型已正确加载：
置信度 0.995 项目名称：系统标书 置信度 0.982 报价总额：人民币玖万捌仟元整2.3 注意返回框 Box 是四边形不是矩形
每个 TextBlock 的Box属性是四个角点，固定按左上、右上、右下、左下排列，坐标对应原图。做标注、裁剪或透视变换时可以直接用；但做阅读顺序重排时，如果直接拿Box[0].Y当排序键，倾斜文本会错位。正确做法是用四个点的 Y 中心值，第 5 章有一段现成的排序代码。
3. 理解检测、方向分类、识别三段流水线，再调 RapidOCR 参数
3.1 一次 GetText 调用内部发生了什么
RapidOCR 一次识别走三个模型，顺序是检测 → 方向分类 → 识别。检测模型是 DBNet 结构的卷积网络，输出一张概率图，经二值化、连通域分析得到若干文本框候选；方向分类器对每个候选框做 0 度和 180 度二分类；识别模型是 CRNN 结构，把文本框内的图像编码成字符序列，最后经 CTC 解码输出字符串。
这三段的职责边界很清楚：检测负责“字在哪”，识别负责“是什么”，两者误差不互相补偿。实际排错时，漏字大多是检测框没有完整包住文本，输出乱码大多是识别阶段对图像内容本身分辨失败。比如印刷体上盖了一个很大的红章，检测阶段很容易把红章边缘误判为文本区域，识别模型再努力也读不出有效字符，这种问题调识别相关参数没意义，先过滤红色通道或者降噪才是正道。
3.2 检测参数：漏字、多框分别调哪里
不同版本的 RapidOCR 包对检测参数的命名略有差异：有的把阈值放在DetParameter嵌套对象里，有的直接平铺在OnnxOcrOptions上。下表是常见实现里的名称和典型取值，调的时候按列出的作用来理解。
| 参数 | 典型值 | 调小的效果 | 调大的效果 |
|---|---|---|---|
| BoxThresh | 0.3 | 更容易产生候选框，适合低对比度 | 候选框变少，适合高噪点 |
| BoxScoreThresh | 0.3 | 保留更多低分框，减少漏检 | 去掉模糊残缺字产生的框 |
| MinArea | 3 | 保留小数点、小图标等碎片 | 过滤孤立噪点 |
| UnClipRatio | 1.6 | 框更紧贴文字，密集排版友好 | 避免行首尾字符被截断 |
实际调参顺序建议先调检测，再动识别。准备十张有代表性的图片，用同一份代码批量跑出框的可视化结果，肉眼确认每行字都被框完整套住，此时再去逻辑里看文本输出是否正常。调参的典型失误是发现识别结果少字，直接把识别模型重跑，其实多数情况是UnClipRatio太小，行尾字符被裁剪出框外，识别模型根本没看到那个字符。
3.3 识别前的图像预处理：RapidOCR 也要先放大
CRNN 识别模型的输入高度固定为 48 像素，宽度按比例自动缩放，RapidOCR 在内部会完成这一变换，所以调用方不需要手动 resize。但过小的原图救不回来：一个 200 像素宽的小缩略图，字符轮廓信息已经丢了，后面再放大也只是噪声放大。我一般会在调用GetText前加一个自适应缩放函数：
public static Mat PrepareForOcr(Mat src) { const double maxSide = 2400.0; double maxSideLen = Math.Max(src.Width, src.Height); double scale = maxSideLen > maxSide ? maxSide / maxSideLen : 1.0; if (scale < 1.0) { var resized = new Mat(); Cv2.Resize(src, resized, new Size(), scale, scale, InterpolationFlags.Area); return resized; } return src.Clone(); }逻辑说明：Cv2.Resize的目标尺寸传new Size()时用 fx/fy 等比缩放，scale小于 1 才对超大图做降采样，最大边控制在 2400 像素以内。这样 DBNet 阶段的 feature map 不会过大，内存占用和推理耗时可观地下降。返回的新 Mat 与输入不共享 buffer，调用方用完必须 Dispose。
方向分类器只处理 0 度与 180 度，解决不了 90 度旋转的竖排文字。遇到竖排单据，先在外部按版面检测的结果旋转原图 90 度，再进入 OCR 流程，这是很多人踩过的坑。
3.4 一条适合开始的参数快照
如果第一次跑出来的结果不稳定，不知道从哪里调起，可以先套用下面这组偏保守的值，然后逐步放宽：
var options = new OnnxOcrOptions { UseDet = true, UseCls = true, UseRec = true, NumThread = 4, BoxThresh = 0.4, BoxScoreThresh = 0.4, MinArea = 6, UnClipRatio = 1.8 };参数含义说明：BoxThresh和BoxScoreThresh双双提到 0.4，让检测框更挑，适合干净扫描件；MinArea提到 6，过滤掉小数点和噪点小框；UnClipRatio放大到 1.8，给行首尾留出余量。这组值会牺牲一小部分极端情况下的召回率，但换来的是结果干净。后续如果发现某一行被拆成了两段，把UnClipRatio调回 1.6；如果整张图几乎没有检测框，则把BoxThresh降到 0.25 再观察。
4. 生产环境的性能与并发：RapidOCR 会话复用、线程数设置与 GPU 加速
4.1 先用 Stopwatch 判断瓶颈在哪
优化之前先量化。用 Stopwatch 分别记录 GetText 整体耗时，以及单独构建 Mat 的时间。以常见的 1080p 发票扫描图为例，CPU 推理通常落在 400ms 到 1200ms 这个区间，检测阶段占大头，识别次之，方向分类最轻。如果你的耗时明显高于这个量级，大多不是模型选择问题，而是线程数或输入尺寸没控制好。
4.2 全局只保留一个 OnnxOcr 实例
OnnxOcr 构造时会加载三个模型文件并创建 ONNX Runtime 的 InferenceSession，这一步的耗时和内存开销都比较重。如果每张图片都 new 一个对象，耗时里会混入模型加载时间，还容易出现内存只涨不降。生产环境里的常见做法是用一个静态字段持有全局实例，或者在依赖注入容器里注册为单例。
4.3 CPU 线程数：不是越大越快
NumThread 会透传给 ONNX Runtime 的 SessionOptions，控制的是每个会话内部的算子并行度。从实际测试看，线程数超过物理核心数后，检测算子的收益就衰减了，甚至因为线程切换变慢。下面这组推荐值是从多台不同配置机器上整理的：
| CPU 逻辑核数 | 推荐 NumThread | 原因 |
|---|---|---|
| 4 | 4 | 检测和识别的并行度需求不高，4 已足够 |
| 8 | 6 | 留出 2 个核给主线程和 IO |
| 16+ | 8 | 推理内存占用和缓存命中率更优 |
注意UseCls开启时方向分类阶段的并行收益很小，它的耗时主要在一个很小的网络前向上，线程数对它的影响可以忽略。
4.4 GPU 加速要换 onnxruntime 的包
RapidOCR 的 NuGet 包默认依赖 CPU 版Microsoft.ML.OnnxRuntime。想用 GPU，正确操作是先移除 CPU 包，再添加 GPU 包：
dotnet remove package Microsoft.ML.OnnxRuntime dotnet add package Microsoft.ML.OnnxRuntime.Gpu逻辑说明：移除再添加是避免程序集冲突。GPU 包在加载时会尝试创建 CUDA 执行提供程序，如果机器缺少与版本匹配的 CUDA 和 cuDNN，运行时报DllNotFoundException之类错误。很多产线机器上的显卡驱动不可控，GPU 版和环境版本一旦匹配不上，会浪费大量排错时间；我的建议是先用 CPU 版把流程跑稳，GPU 加速作为后续优化项。
4.5 批量识别用信号量限流
高配机器上并行识别确实能提升吞吐，但“并行越多越快”是错觉。当并发任务数超过物理核数后，每个任务都在抢 CPU 时间片，总吞吐反而下降。我习惯用一个固定计数的信号量控制并发：
private static readonly SemaphoreSlim OcrGate = new(4); public static async Task<string> RecognizeAsync(Mat mat) { await OcrGate.WaitAsync(); try { var result = OcrInstance.GetText(mat); return string.Join("\n", result.TextBlocks.Select(b => b.Text)); } finally { OcrGate.Release(); } }逻辑说明：SemaphoreSlim(4)表示最多允许 4 个识别任务同时执行，其余任务在WaitAsync()处排队。OcrInstance是 4.2 节的全局单例。GetText本身是同步方法，放在 async 方法里，调用线程在等待 native 计算时会阻塞，但对批量任务而言，队列机制比无脑Parallel.For更可控，也方便后续加优先级。
4.6 内存回收：Mat 用 using 包裹
OpenCvSharp 的Mat持有的是 native 内存，.NET GC 管不到它。识别一张 4000 万像素的图，Mat 底层 buffer 可能有几十 MB 甚至上百 MB，不及时释放会导致内存曲线一路上涨。建议做一个封装方法，入口只接收路径，内部用完即释放：
public string RecognizeImage(string imagePath) { using var src = Cv2.ImRead(imagePath); using var prepared = PrepareForOcr(src); var result = OcrInstance.GetText(prepared); return string.Join("\n", result.TextBlocks.Select(b => b.Text)); }这样调用方不需要关心 Mat 生命周期，OCR 服务自己管理短生命周期副本。批量跑上千张图时，这个习惯比任何 GC 设置都管用。
5. 按阅读顺序重排 RapidOCR 结果：坐标聚类与表格对齐技巧
5.1 为什么 TextBlocks 的顺序不能直接用
RapidOCR 返回的 TextBlocks 顺序由检测阶段的得分和内部遍历方式决定，和版面上的阅读顺序没有必然关系。写合同审查、发票抽取这类工具时，直接string.Join拼接会出现跨栏乱序、表格行错位。解决办法是对检测框做“先分行、再分列”：每个框用四个角点的中心代表位置，按 Y 中心聚类成行，行内再按 X 中心排序。
5.2 坐标重排的可运行代码
public record BlockPos(TextBlock Block, double CenterX, double CenterY, double Height); public static List<TextBlock> SortByReadingOrder(List<TextBlock> blocks) { if (blocks.Count <= 1) return blocks; var items = blocks .Select(b => new BlockPos( b, b.Box.Average(p => p.X), b.Box.Average(p => p.Y), Math.Sqrt(Math.Pow(b.Box[0].X - b.Box[3].X, 2) + Math.Pow(b.Box[0].Y - b.Box[3].Y, 2)) )) .OrderBy(t => t.CenterY) .ToList(); var lines = new List<List<BlockPos>>(); foreach (var item in items) { if (lines.Count > 0 && item.CenterY - lines[^1].Average(x => x.CenterY) < item.Height * 0.6) { lines[^1].Add(item); } else { lines.Add(new List<BlockPos> { item }); } } return lines .SelectMany(line => line.OrderBy(t => t.CenterX)) .Select(x => x.Block) .ToList(); }逻辑说明：CenterY取四角平均，用来抵抗文本行的倾斜；Height用左侧边两个角点的欧氏距离估算，作为行间距比较的基准。判断阈值是自身高度的 60%，这个系数对 A4 扫描件比较合适：行距小就调小到 0.4，存在上下标就调大到 0.8。lines 列表里的每一项是一行中的所有检测框，最后用SelectMany把各行按 X 排序后依次展开，得到的就是阅读顺序。
5.3 表格场景怎么用
做表格识别时不要试图用坐标去猜单元格边界，OCR 给出的 Box 是文字区域，不是单元格线。更稳的做法是先按上节代码分好行，再对每一行按 X 中心排序，得到的顺序就是“从左到右的单元格内容”。需要输出二维数组时，把每一行转成一个List<string>，行的索引就是表格行号。
5.4 验证排序效果的方法
拿一张两栏文章的截图跑排序函数。如果输出的第一行是左栏第一条、第二行是右栏第一条，说明聚类阈值太大，把左右两栏并成了一个阅读行，把 0.6 改小到 0.4 再试；如果输出先是左栏全部、再接右栏全部，说明分行逻辑正常。这个验证过程对任何 RapidOCR 版本都成立，因为只依赖 TextBlocks 的公共字段，不依赖包内部私有 API。
本文还有配套的精品资源，点击获取
