MVP 聚技站｜不刻意追求快，先把 OCR 做稳：lw.PPOCR.OpenCVDNN v1.0.0 正式开源
作者：天天代码码天天 - 微软最有价值专家（MVP）
排版：Alan Wang
做 OCR 推理项目时，我们经常看到这样的介绍：
“性能提升多少倍”“单张图片只需多少毫秒”“支持各种推理后端”……
但在实际交付中，客户真正关心的往往不只是一次测试有多快，而是：
能不能在不同操作系统上稳定运行？
服务连续运行几天后会不会内存不断上涨？
高并发时会不会把机器拖垮？
输入异常图片后，服务还能不能继续工作？
接口升级后，原来的程序还能不能调用？
下载发布包后，能不能直接启动？
出现问题时，有没有日志可以定位？
基于这些实际需求，我们开发并正式开源了：lw.PPOCR.OpenCVDNN
项目地址：
https://github.com/lxw112190/lw.PPOCR.OpenCVDNN
当前正式版本：v1.1.0
我们不刻意追求“最快”
lw.PPOCR.OpenCVDNN 不以某一张图片、某一台机器上的极限跑分作为首要目标。
我们更关心的是：
在明确的硬件和系统范围内，持续、稳定、可重复地完成 OCR 推理。
项目采用 OpenCV DNN 5.0.0 CPU作为唯一推理后端，没有同时塞入 ONNX Runtime、DirectML、OpenVINO、TensorRT 等多套运行时。
这样做的目的很简单：
减少依赖；
降低部署复杂度；
保持代码精简；
更容易排查问题；
更容易跨平台构建；
让客户拿到发布包后尽快运行起来。
它不一定适合所有场景，但它努力把自己承诺支持的事情做好。
这不是“只上传源码”的开源
我们理解的真开源，不只是把代码上传到 GitHub。
项目采用 MIT License，同时公开提供：
完整 C++ 源代码；
CMake 构建配置；
Windows、Linux、Linux ARM64 和 macOS CI；
OpenCV 5 构建与缓存流程；
HTTP 服务完整源码；
浏览器测试页面；
C、C#、Python 调用示例；
Docker 与 Docker Compose 配置；
Windows Service 和 Linux systemd 管理脚本；
HTTP API、配置文件和日志 Schema；
正确性、异常输入、并发及稳定性测试；
依赖锁定和 CycloneDX SBOM；
模型、字典和依赖文件的 SHA-256 校验；
可以直接下载使用的部署包。
构建过程、测试方法、兼容边界和已知限制，都可以在仓库中查看。
用户既可以直接使用发布包，也可以从源码重新构建和验证。
一套核心代码，支持多个平台
当前项目提供以下构建目标：
Windows 10/11 x64；
Linux x64；
Linux ARM64；
统信 UOS 20 ARM64 兼容构建；
macOS Apple Silicon ARM64；
Linux AMD64 Docker 镜像。
其中，Linux ARM64 发布包采用 Debian 10、glibc 2.28、GCC 8.3 兼容基线构建，并已经在统信 UOS 20 ARM64 实体机上完成验证。
需要说明的是，跨平台并不等于一个二进制文件可以在所有系统上运行。不同操作系统和 CPU 架构仍然需要下载对应的发布包。
例如：
Linux x64 发布包要求 glibc 2.31 或更高；
Linux ARM64 和 Linux x64 不能混用；
macOS 版本目前经过 CI 验证并采用 ad-hoc 签名，尚未进行 Apple 公证；
当前正式发布包只使用 CPU 推理。
我们会明确写出兼容边界，而不是笼统地宣传“支持所有平台”。
项目提供两种常见调用方式。
第一种是完整 OCR：
对应 HTTP 接口：
有些客户已经通过摄像头 SDK、业务算法或其他技术裁剪好了文字区域，不需要再次进行文字检测，可以直接调用：
这样能够跳过检测步骤，降低单个文字区域的处理耗时。
接口同时支持：
单张完整 OCR；
图片二进制直接上传；
JSON/Base64 兼容调用。
对于单张图片，我们推荐直接上传二进制内容，避免 Base64 大约 33% 的体积膨胀。
内置 HTTP 服务和 Web 测试页面
发布包内置基于 cpp-httplib 开发的 HTTP 服务。
解压并启动程序后，浏览器访问：
即可打开测试页面。
页面支持：
选择或拖入图片；
调用完整 OCR；
在原图上绘制文字区域；
填写可选的 API Key。
HTTP Web 效果截图展示
这套网页主要用于快速体验和接口验证，不需要额外安装前端运行环境。
下载后即可启动
Windows 发布包解压后运行：
Linux 发布包解压后运行：
macOS Apple Silicon 运行：
项目也提供 Docker 和 Docker Compose 部署方式。
发布包中已经尽量包含：
OCR Runtime；
OpenCV 运行库；
PP-OCR 模型和字典；
HTTP 服务；
Web 测试页面；
默认配置；
C、C#、Python 示例；
API 与 Schema 文档；
服务安装和管理脚本；
许可证、依赖清单和 SBOM。
目标是让用户下载对应平台的发布包后，按照说明即可启动，而不是先处理一长串依赖问题。
稳定不是一句口号
为了验证长期运行和异常情况下的表现，项目建立了多层测试：
固定样本正确性回归；
二进制上传和 JSON/Base64 测试；
多线程并发测试；
RSS 内存增长检查；
1000 次本机稳定性测试；
Windows 定时执行 5000 次长时间测试；
Linux ASan/UBSan 检测；
损坏图片、空图片、超大图片和非法 JSON 测试；
异常请求后的正常 OCR 恢复测试；
C ABI 导出符号检查；
发布包解压后的实际启动和调用测试。
在高并发情况下，服务不会允许请求无限排队：
请求超过队列容量时返回 429 Too Many Requests；
等待 OCR 引擎超时时返回 503 Service Unavailable；
大批量图片采用分块处理，避免一次性占用过多内存。
我们不会用一句“没有内存泄漏”代替测试证据。RSS 检查、长时间运行测试和 ASan/UBSan 会结合使用，同时仍建议用户在自己的真实业务环境中继续验证。
面向生产环境的日志
HTTP 服务使用 spdlog 记录运行日志和访问日志，并将两者分开管理：
runtime.log：记录启动、模型加载、警告和异常；
access.log：记录每次请求的状态、耗时、尺寸、结果数量和错误码。
每个请求都有独立的 Request ID，可以在响应头、JSON 响应和日志之间进行关联。
默认日志不会记录：
API Key；
Authorization 请求头；
图片二进制内容；
Base64 数据；
请求正文；
日志可以帮助定位问题，但不能完全代替崩溃转储。生产环境仍建议在 Windows 上配置 WER 或 ProcDump，在 Linux 上配合 coredumpctl。
v1.0.0 冻结了什么？
从 v1.0.0 开始，项目正式冻结以下 v1 契约：
C ABI v1；
HTTP API v1；
HTTP 服务配置 Schema v1；
JSONL 访问日志 Schema v1；
模型清单 Schema v1。
整个 1.x 系列将保持向后兼容。
字段删除、重命名、类型变化、语义变化或 ABI 破坏性修改，需要进入新的主版本或者单独定义 v2 契约。
这意味着客户可以更放心地进行 C、C#、Python 或 HTTP 集成，而不必担心小版本升级后公共接口随意变化。
这个项目适合谁？
lw.PPOCR.OpenCVDNN 比较适合：
希望快速部署本地 OCR 服务的团队；
需要 Windows、Linux 或 ARM64 跨平台运行的项目；
使用 C、C#、Python 或 HTTP 对接 OCR 的开发者；
不希望引入复杂推理框架的应用；
重视稳定运行、错误恢复和问题定位的生产项目；
需要私有化、离线或内网部署的客户。
如果你的核心目标是 GPU 极限吞吐、多模型动态调度或特定硬件加速，那么其他推理后端可能更加合适。
这个项目选择的是另一条路线：
不刻意追求某一次测试最快，而是努力做到源码真实可见、构建可以复现、平台边界清楚、接口长期稳定、发布包方便部署。
欢迎体验和参与
项目地址：
https://github.com/lxw112190/lw.PPOCR.OpenCVDNN
欢迎大家：
下载对应平台的发布包；
在真实图片和业务场景中测试；
提交 Issue；
完善文档和示例；
反馈不同系统上的兼容情况；
为项目点一个 Star。
天天代码码天天
微软最有价值专家（MVP）
架构师，主要研究计算机视觉、机器学习、人工智能，主要语言 C#、C++、Python，喜欢使用 C# 实现各种模型推理！
微软最有价值专家（MVP）
微软最有价值专家是微软公司授予第三方技术专业人士的一个全球奖项。30 多年来，世界各地的技术社区领导者，因其在线上和线下的技术社区中分享专业知识和经验而获得此奖项。
MVP 是经过严格挑选的专家团队，他们代表着技术最精湛且最具智慧的人，是对社区投入极大的热情并乐于助人的专家。MVP 致力于通过演讲、论坛问答、创建网站、撰写博客、分享视频、开源项目、组织会议等方式来帮助他人，并最大程度地帮助微软技术社区用户使用 Microsoft 技术。