Skip to content

Releases: lxw112190/lw.PPOCR.OpenCVDNN

Release list

v1.1.0 — PDF OCR & JSON CORS / PDF OCR 与 JSON 跨域配置

v1.1.0 — PDF OCR & JSON CORS / PDF OCR 与 JSON 跨域配置 Latest
Latest

Choose a tag to compare

View all tags
@lxw112190 lxw112190 released this 07 Aug 13:25
v1.1.0
b010f47

v1.1.0

本版本新增 PDF OCR 与 JSON 配置 CORS 支持，保持 C ABI v1、HTTP API v1 及配置 Schema v1 兼容。

主要更新

  • 新增 /api/pdf/ocr PDF OCR 接口，支持 application/pdf 二进制上传。

  • 支持 PDF 文字层提取、扫描页 OCR，以及 auto、text、ocr、hybrid 模式。

  • 新增 JSON CORS 配置：

    {
  "cors": {
    "enabled": true,
    "allowed_origins": [
      "https://your-site.example",
      "http://localhost:5173"
    ]
  }
}
Assets 4
Loading

v1.0.0 — lw.PPOCR.OpenCVDNN 首个正式版 / Stable Cross-Platform OpenCV DNN OCR Runtime

v1.0.0 — lw.PPOCR.OpenCVDNN 首个正式版 / Stable Cross-Platform OpenCV DNN OCR Runtime

Choose a tag to compare

View all tags
@lxw112190 lxw112190 released this 01 Aug 15:39
v1.0.0
f149558

v1.0.0 正式版

v1.0.0 是 lw.PPOCR.OpenCVDNN 的首个正式稳定版本。

项目仅使用 OpenCV DNN 5.0.0 进行 CPU 推理，提供精简、跨平台的 PP-OCR Runtime、稳定 C ABI、HTTP 服务、浏览器测试页面，以及 C、C#、Python 调用示例。

项目地址：https://github.com/lxw112190/lw.PPOCR.OpenCVDNN

主要功能

  • 完整 OCR：文字检测、可选方向分类、文字识别
  • 仅识别接口：支持客户传入已经裁剪好的文字区域
  • 单张与批量文字识别
  • 稳定 C ABI，方便 C#、Python 及其他语言调用
  • HTTP API 支持：
    • 图片二进制直传
    • JSON/Base64
    • 完整 OCR
    • 单张及批量仅识别
  • 浏览器体验页面：
    • 在原图绘制文字区域
    • 显示识别文本与置信度
    • 显示检测、分类、识别及总耗时
  • 可选 X-API-Key 认证
  • spdlog 运行日志与访问日志
  • Windows Service 管理脚本
  • Linux systemd 安装、启动、停止、重启和卸载脚本
  • Linux AMD64 Docker 与 Docker Compose 部署

正式冻结的 v1 契约

从 v1.0.0 开始，以下公共契约正式冻结：

  • C ABI v1
  • HTTP API v1
  • HTTP 服务配置 Schema v1
  • JSONL 访问日志 Schema v1
  • 模型清单 Schema v1
  • C ABI 导出符号白名单
  • 模型与字典 SHA-256 校验规则

整个 1.x 系列将保持向后兼容。

删除或重命名字段、修改字段类型或语义、破坏 ABI 等不兼容变更，必须进入新的主版本或单独版本化的 v2 契约。

生产环境保护

本版本提供以下生产部署保护：

  • HTTP 请求队列和 OCR 引擎等待队列均设置硬上限
  • 引擎等待队列已满时返回：
    • HTTP 429
    • error_code: queue_full
  • 等待 OCR 引擎超时时返回：
    • HTTP 503
    • error_code: engine_wait_timeout
  • 批量请求限制：
    • 最大图片数量
    • 累计像素数量
    • 累计解码内存
  • 批量识别分块处理，避免一次性保存过多解码图片
  • 异常输入处理后服务仍可继续正常 OCR
  • API Key、图片内容、Base64 和 OCR 文本默认不会写入日志
  • runtime/access 日志分离
  • 支持 JSONL 和人类可读 Text 访问日志
  • 日志包含请求 ID、响应状态、图片尺寸、结果数量与阶段耗时
  • 支持日志轮转、可信代理和请求开始 breadcrumb

发布附件

请根据操作系统和架构下载对应附件：

Windows x64

  • lw.PPOCR.OpenCVDNN-v1.0.0-windows-x64.zip
  • lw.PPOCR.OpenCVDNN-v1.0.0-windows-x64.zip.sha256

适用于受支持的 Windows 10/11 x64。

Linux x64

  • lw.PPOCR.OpenCVDNN-v1.0.0-linux-x64.tar.gz
  • lw.PPOCR.OpenCVDNN-v1.0.0-linux-x64.tar.gz.sha256

构建基线：

  • Ubuntu 20.04
  • x86-64
  • glibc 2.31

Linux ARM64 / 统信 UOS 20

  • lw.PPOCR.OpenCVDNN-v1.0.0-linux-arm64-uos20.tar.gz
  • lw.PPOCR.OpenCVDNN-v1.0.0-linux-arm64-uos20.tar.gz.sha256

构建基线：

  • AArch64 / ARMv8-A
  • Debian 10
  • glibc 2.28
  • GCC 8.3

该版本已经在统信 UOS 20 ARM64 实体机验证。

macOS ARM64

  • lw.PPOCR.OpenCVDNN-v1.0.0-macos-arm64.tar.gz
  • lw.PPOCR.OpenCVDNN-v1.0.0-macos-arm64.tar.gz.sha256

适用于 Apple Silicon，CI 部署目标为 macOS 12.0 及以上。

每个压缩包均包含：

  • OCR Runtime
  • OpenCV 5.0.0 运行库
  • PP-OCRv6 Tiny Chinese 模型
  • HTTP 服务
  • 浏览器测试页面
  • C、C#、Python 示例
  • 配置文件与 Schema
  • 服务管理脚本
  • 依赖锁
  • CycloneDX SBOM
  • LICENSE 与第三方许可证

请同时下载对应 .sha256 文件并校验附件完整性。

Linux/macOS：

sha256sum -c <附件名称>.sha256

Windows PowerShell：

Get-FileHash <附件名称> -Algorithm SHA256

Docker

Docker 不单独提供 Release 压缩附件，正式镜像发布到 GitHub Container Registry。

直接运行：

docker run -d \
  --name lw-ppocr \
  --restart unless-stopped \
  -p 8787:8787 \
  -v lw-ppocr-logs:/data/logs \
  ghcr.io/lxw112190/lw.ppocr.opencvdnn:1.0.0

同时提供以下镜像标签：

  • 1.0.0
  • 1.0
  • latest

Docker Compose 文件已经包含在项目仓库中：

cp .env.example .env
docker compose up -d
docker compose ps

在 .env 中设置 PPOCR_API_KEY 可以启用 API Key 认证。

快速启动

Windows

解压后运行：

.\lw-ppocr-http-service.exe

Linux

chmod +x run-http-service.sh
./run-http-service.sh

macOS Apple Silicon

chmod +x run-http-service.sh
./run-http-service.sh

服务启动后访问：

http://127.0.0.1:8787/

健康检查：

GET http://127.0.0.1:8787/health

HTTP API 示例

推荐使用二进制图片接口，避免 Base64 大约 33% 的体积膨胀。

完整 OCR：

curl http://127.0.0.1:8787/api/ocr \
  -H "Content-Type: image/jpeg" \
  --data-binary @image.jpg

仅识别已经裁剪好的文字行：

curl http://127.0.0.1:8787/api/recognize \
  -H "Content-Type: image/png" \
  --data-binary @text-line.png

启用 API Key 后：

curl http://127.0.0.1:8787/api/ocr \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: image/jpeg" \
  --data-binary @image.jpg

验证情况

本版本发布前已完成：

  • 全部 GitHub Actions CI
  • Windows x64 构建、打包和真实 OCR
  • Linux x64 构建、打包和真实 OCR
  • Linux ARM64 构建、打包和真实 OCR
  • macOS ARM64 构建、打包和真实 OCR
  • Docker 非 root、Compose、健康检查和 API Key 测试
  • OpenCV 5.0.0 版本与依赖检查
  • 模型和字典 SHA-256 校验
  • C ABI 导出符号检查
  • 黄金正确性回归
  • JSON/Base64 与二进制 HTTP 接口测试
  • 单张与批量仅识别测试
  • API Key 正确、缺失和错误场景
  • 配置 Schema 与未知字段拒绝测试
  • 43 组异常输入及错误后恢复测试
  • 429 queue_full 与 503 engine_wait_timeout 测试
  • ASan/UBSan
  • 多尺寸图片并发测试
  • RSS 内存增长检查
  • Windows 本机 1000 次长时间稳定性测试
  • CI 定时 5000 次稳定性测试能力
  • 统信 UOS 20 ARM64 实体机验证
  • 发布包解压后的真实图片 OCR 验证

性能参考

Windows 本机测试环境：

  • AMD Ryzen 7 7735H
  • 8 核 16 线程
  • 16 GB 内存
  • Windows 10 22H2
  • OpenCV DNN 5.0.0 CPU
  • HTTP keep-alive 与二进制图片请求

部分测试结果：

场景 引擎数/并发 吞吐 客户端 P95 热身后 RSS
完整 OCR 1/1 6.17 req/s 177.97 ms 约 151 MB
完整 OCR 2/2 6.98 req/s 336.50 ms 约 284 MB
仅识别 1/1 126.14 req/s 9.39 ms 约 154 MB
仅识别 2/2 172.69 req/s 13.68 ms 约 287 MB
仅识别 4/4 199.80 req/s 24.32 ms 约 551 MB

1000 次多尺寸、并发 4 稳定性测试全部成功，RSS 净增长约 2.32 MB，异常输入后正常 OCR 可以恢复。

性能与图片尺寸、文字区域数量、CPU、内存、并发数和日志配置有关，请在实际部署机器上压测后调整 engine_instances。

完整 OCR 建议从以下配置开始：

{
  "engine_instances": 1,
  "worker_threads": 4,
  "max_queued_requests": 32,
  "engine_wait_timeout_ms": 5000
}

已经裁剪好的文字行识别可以从 2 个引擎开始评估。

从 RC.3 升级

请使用完整的 v1.0.0 发布包升级，不建议只替换 EXE、DLL 或 SO。

升级步骤：

  1. 停止现有服务
  2. 备份 http-service.json 和需要保留的日志
  3. 将 v1.0.0 解压到新目录
  4. 迁移监听地址、端口、API Key、队列限制和日志路径等本地配置
  5. 重新安装或启动服务
  6. 验证 /health
  7. 使用真实图片执行完整 OCR 和仅识别测试
  8. 确认稳定后再删除旧 RC.3 目录

回滚验证完成前请保留原 RC.3 目录。

已知限制

  • 仅支持 OpenCV 5，不支持 OpenCV 4.x
  • 当前正式包仅提供 CPU 推理
  • Linux 包不包含 glibc 和 ELF 加载器
  • Linux 目标机 glibc 不能低于对应发布包的构建基线
  • macOS 包使用 ad-hoc 签名，未经过 Apple 公证
  • HTTP 服务本身不提供 TLS
  • 公网部署建议使用 Nginx、Caddy 等反向代理提供 HTTPS
  • API Key 只提供基础访问控制，不能替代网络隔离、TLS 和完整身份认证系统
  • 性能数据仅用于配置参考，不是所有硬件和图片的性能承诺

License 与联系方式

项目代码采用 MIT License。第三方依赖与模型许可证请查看发布包中的：

  • THIRD-PARTY-NOTICES.md
  • licenses/
  • dependencies.lock.json
  • sbom/lw.PPOCR.OpenCVDNN.cdx.json

联系方式：

感谢所有参与测试、反馈和部署验证的用户。

English summary

v1.0.0 is the first stable release of lw.PPOCR.OpenCVDNN: a compact, cross-platform PP-OCR runtime powered exclusively by OpenCV DNN 5.0.0 on CPU.

It provides full OCR, recognition-only inference, a stable C ABI, binary and JSON/Base64 HTTP APIs, a browser test page, optional API Key authentication, structured logging, service-management scripts, Docker deployment, and ready-to-run packages for Windows x64, Linux x64, Linux ARM64/UOS 20, and macOS ARM64.

C ABI v1, HTTP API v1, configuration Schema v1, JSONL log Schema v1, and model-manifest Schema v1 are formally frozen and remain backward compatible throughout the 1.x line.

Docker images are published through GHCR:

ghcr.io/lxw112190/lw.ppocr.opencvdnn:1.0.0
Loading