泰山派 RK3566 离线 OCR 服务：tspi-ocr-web 实战

在边缘嵌入式开发板上部署深度学习应用时，往往受限于CPU 算力弱、内存容量小（通常仅 1GB ~ 2GB）、无独立显卡等瓶颈。如果在 RK3566 这类入门级嵌入式板卡上直接运行未经优化的大型 OCR 模型，往往会遭遇延迟高达数秒、内存频频 OOM、甚至导致板载系统假死的窘境。

为了解决低功耗嵌入式平台上的本地文字识别痛点，我开发并开源了针对立创·泰山派打造的高性能离线 OCR 服务项目：tspi-ocr-web。

本项目充分挖掘了 RK3566 芯片的硬件潜能，实现了 多引擎自动分级切换（RKNN NPU / NCNN NEON / ONNX），结合 Rockchip RGA 2D 硬件图形加速 与 零服务端绘图开销的纯前端标注 架构，整图识别耗时直接从数秒级压缩至 ~150ms。

💡 架构设计与核心思路

1
2
3
4
5
                            ┌──> [检测到 RKNN 模型] ──> NPU 硬件加速推理 (0.8 TOPS RKNNLite, ~80ms)
                            │
上传图片 ──> 启动自动检测 ──┼──> [检测到 NCNN 模型] ──> NCNN 极速引擎 (PP-OCRv5 + NEON FP16, ~150ms) ⭐推荐
                            │
                            └──> [回退 ONNX 引擎] ──> ONNX 引擎 (4核 CPU 并行 + RGA 硬件缩放, ~1.5s)

1. 三引擎智能分级与平滑回退

不同用户手头的模型格式和硬件驱动准备情况不同。项目通过全局配置 OCR_ENGINE=auto 实现了模型自动扫描与分级调度：

  1. 第一优先级（RKNN NPU 加速）：检测到 models/ocr/ppocrv4-rknn/ 下存在 det.rknn 与 rec.rknn 时，自动调用板载 0.8 TOPS NPU 执行硬件推理，耗时仅需 ~80ms；
  2. 第二优先级（NCNN NEON 极速引擎，开箱推荐）：搭载基于 PP-OCRv5 的移动端精简模型，深度启用 ARM NEON FP16 汇编级指令加速。模型总体量仅 11MB（识别模型仅 7.9MB），相比传统 90MB 的 ONNX 模型大幅节省 2GB 紧缺内存，推理耗时压制在 120~180ms；
  3. 第三优先级（ONNX 保底回退）：在无定制模型时自动回退到通用 ONNX 引擎，结合 RGA 硬件等比缩放，确保 100% 可用性。

2. 纯前端标注渲染：卸下服务端的绘图包袱

传统 OCR Web 服务在后端识别出文字框后，通常会在服务端使用 Python PIL / OpenCV 读取图片、解析字体、逐像素绘制矩形框和半透明文本标签，然后再对大图二次编码为 JPEG 返回。

在 RK3566 这类嵌入式 CPU 上，画图与大图重编码的耗时往往比模型推理本身还要耗时，且极易导致瞬时内存暴涨。

tspi-ocr-web 的优化方案：

  • 后端专注推理：API 仅返回纯净、轻量的 JSON 结构体（包含 8 点坐标 bbox、文本及置信度）；
  • 前端负责渲染：Web UI 基于 gr.AnnotatedImage 动态渲染组件，直接调用客户端设备（用户的浏览器/手机）的 Canvas 与 DOM 绘制交互式高亮线框与悬停标签。
  • 收益：板端服务端实现 零 CPU 画图耗时、零字体库常驻开销、零二次图像编码开销。

3. RGA 2D 硬件缩放与 DRM DMA-BUF 显存直通

在图像输入前处理（Padding、等比缩放、色彩空间转换）阶段，项目编写了 C 语言底层扩展 services/rga_helper.c，基于 Rockchip 官方 librga 的 c_RkRgaGetAllocBuffer + wrapbuffer_fd_t 实现 DRM DMA-BUF 连续物理内存分配，完美契合 Linux 6.1 内核标准，零 CPU 占用完成大图缩放。

🚀 快速上手与板端部署

1. 准备 Python 3.12 虚拟环境

为了避免污染或破坏 Ubuntu 底层系统 Python（如 apt 等守护进程），建议使用独立编译部署的 Python 3.12 虚拟环境：

👉 部署方法详见前文：RK3566 Ubuntu26.04 安装 Python3.12（多版本共存与隔离）

1
2
3
4
5
6
7
8
9
# 克隆项目仓库
git clone https://github.com/bubao/tspi-ocr-web.git
cd tspi-ocr-web

# 激活 Python 3.12 虚拟环境
source /path/to/py312_env/bin/activate

# 安装板端运行时依赖
pip install -r requirements.txt

⚠️ 踩坑注意：嵌入式开发板通常没有安装桌面图形库（如 X11/Wayland），依赖中必须安装无头版本 opencv-python-headless，切勿安装桌面版 opencv-python，否则会引发 libGL.so.1: cannot open shared object file 错误。

2. 一键下载极速模型（~11MB）

运行内置下载脚本，自动从国内镜像源拉取经过 NEON FP16 优化的 PP-OCRv5 NCNN 官方开源权重（出处源自 Hugging Face 社区 qefro/pp-OCRv5-6-ncnn）：

1
2
# 默认拉取 PP-OCRv5 NCNN 推荐模型 (~11MB)
python scripts/download_models.py

💡 原理深入：想了解如何使用 pnnx 手动将 PaddleOCR 导出为 NCNN FP16 模型及底层性能评测，详见专题博文：
👉 泰山派 RK3566 部署 NCNN 极速推理实践

3. 配置 RGA 驱动权限（可选，提升预处理性能）

若需开启 RGA 2D 硬件缩放加速，需确保普通用户拥有 /dev/rga 访问权限：

👉 驱动原理与 udev 规则详见前文：Rockchip 平台 librga 安装部署与权限问题排坑指南

1
2
3
# 永久规则（推荐）
echo 'KERNEL=="rga", MODE="0666"' | sudo tee /etc/udev/rules.d/99-rga.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

4. 启动服务

项目实现了 FastAPI 后端路由与 Gradio 交互式前端的单端口共用挂载：

1
2
# 单端口启动 API + Gradio Web UI（默认 8002 端口）
python main.py

终端将打印：

1
2
INFO:     [自动检测] 发现 NCNN 极速模型，启用 PP-OCRv5 (NEON FP16)
INFO:     Uvicorn running on http://0.0.0.0:8002 (Press CTRL+C to quit)
  • Web UI 左右分栏工作台：http://<泰山派IP>:8002/gradio/
  • Swagger API 在线文档：http://<泰山派IP>:8002/docs
  • 服务健康监控探针：http://<泰山派IP>:8002/health

📡 RESTful API 调用实战

1. 包含坐标元数据的完整 OCR 识别

1
2
3
curl -X POST "http://localhost:8002/api/v1/ocr/recognize" \
  -F "file=@demo.png" \
  -F "language=ch"

响应 JSON 结构体：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "success": true,
  "text": "泰山派 RK3566",
  "results": [
    {
      "bbox": [20.0, 30.0, 180.0, 30.0, 180.0, 65.0, 20.0, 65.0],
      "text": "泰山派 RK3566",
      "confidence": 0.985
    }
  ],
  "processing_time": 0.148,
  "image_size": { "width": 640, "height": 480 },
  "engine": "PP-OCRv5 (NCNN)",
  "backend": "CPU (NCNN NEON FP16)"
}

2. 纯文本提取接口（适合管道重定向）

1
2
curl -X POST "http://localhost:8002/api/v1/ocr/text" \
  -F "file=@demo.png"

⚡ 进阶：启用 RKNN NPU 硬件加速

若希望追求极致的低功耗与约 80ms 的推理响应，可以开启板载 NPU 硬件加速：

  1. PC 端导出 RKNN 模型：
    在 x86 电脑中配置 rknn-toolkit2（参考前文：RK3566 搭建 RKNN-Toolkit2 环境笔记），导出指定目标为 target_platform="rk3566" 的 det.rknn 和 rec.rknn；
  2. 放置模型：
    将转换好的文件放入开发板的 models/ocr/ppocrv4-rknn/ 目录；
  3. 重启服务：
    服务启动时将自动识别并切入 NPU 推理分支：
    1
    🚀 [自动检测] 发现 RKNN 模型 (det.rknn, rec.rknn)，已自动启用 NPU 硬件加速推理

🛠️ Systemd 守护进程与开机自启

生产环境下，推荐将服务托付给 Systemd 守护进程。仓库中提供了自适应绝对路径与用户名的安装脚本：

1
2
3
4
5
6
7
8
9
# 一键自动探测路径并配置开机自启
sudo ./scripts/install_service.sh

# 管理服务
sudo systemctl start tspi-ocr
sudo systemctl status tspi-ocr

# 实时查看日志
sudo journalctl -u tspi-ocr -f

结语与项目开源地址

在资源紧缺的嵌入式边缘设备上运行深度学习，核心思路是因地制宜、物尽其用：

  • 用 NCNN NEON FP16 / RKNN NPU 榨干计算硬件；
  • 用 RGA 分担图像格式转换与缩放计算；
  • 用 浏览器前端 Canvas 渲染 规避服务端低效的画图开销；
  • 全流程内存直通，杜绝磁盘 IO 磨损闪存。

欢迎在泰山派、鲁班猫等 RK3566 / RK3568 开发板上体验并提出宝贵建议！

嵌入式 > 开源项目
#RK3566 #Python #泰山派 #RKNN #RGA #OCR #NCNN
泰山派 RK3566 离线 OCR 服务：tspi-ocr-web 实战
https://bubao.github.io/posts/f6340cce.html
作者
一念
发布于
2026年11月1日
许可协议