端侧 OCR 的实践：PP-OCRv5 在 Android 上的原生部署

说明

本篇博文

封面：基于 Google Nano Banana 2 生成，无版权所有。
项目源代码：已开源至 GitHub，请访问 PPOCRv5-Android 获取。

声明：

笔者（Fleey）非 AI 领域从业者，纯属兴趣使然。文中如有疏漏与错误，望读者谅解与及时指正！

开篇

2024 年，Google 将 TensorFlow Lite 更名为 LiteRT，这不仅是一次品牌重塑，更标志着端侧 AI 从「移动优先」向「边缘优先」的范式转变¹。在这个背景下，OCR（光学字符识别）作为最具实用价值的端侧 AI 应用之一，正在经历一场静默的革命。

百度的 PaddleOCR 团队在 2025 年发布了 PP-OCRv5，这是一个支持简体中文、繁体中文、英文、日文等多语言的统一 OCR 模型²。它的移动端版本仅有约 70MB，却能在单一模型中实现 18,383 个字符的识别。这个数字背后，是检测与识别两个深度神经网络的协同工作。

但问题在于：PP-OCRv5 基于 PaddlePaddle 框架训练，而 Android 设备上最成熟的推理引擎是 LiteRT。如何跨越这道鸿沟？

让我们从模型转换开始，逐步揭开端侧 OCR 的工程面纱。

1
flowchart TB
2
    subgraph E2E["端到端 OCR 流程"]
3
        direction TB
4

5
        subgraph Input["输入"]
6
            IMG[原始图像<br/>任意尺寸]
7
        end
8

9
        subgraph Detection["文本检测 - DBNet"]
10
            DET_PRE[预处理<br/>Resize 640x640<br/>ImageNet Normalize]
11
            DET_INF[DBNet 推理<br/>~45ms GPU]
12
            DET_POST[后处理<br/>二值化 - 轮廓 - 旋转矩形]
13
        end
14

15
        subgraph Recognition["文本识别 - SVTRv2"]
16
            REC_CROP[透视变换裁剪<br/>48xW 自适应宽度]
17
            REC_INF[SVTRv2 推理<br/>~15ms/行 GPU]
18
            REC_CTC[CTC 解码<br/>合并重复 + 移除空白]
19
        end
20

21
        subgraph Output["输出"]
22
            RES[OCR Results<br/>文本 + 置信度 + 位置]
23
        end
24
    end
25

26
    IMG --> DET_PRE --> DET_INF --> DET_POST
27
    DET_POST -->|N 个文本框| REC_CROP
28
    REC_CROP --> REC_INF --> REC_CTC --> RES

模型转换：从 PaddlePaddle 到 TFLite 的漫长旅途

深度学习框架的碎片化是行业的痛点。PyTorch、TensorFlow、PaddlePaddle、ONNX，每个框架都有自己的模型格式和算子实现。ONNX（Open Neural Network Exchange）试图成为通用的中间表示，但现实往往比理想骨感。

PP-OCRv5 的模型转换路径如下：

1
flowchart LR
2
    subgraph PaddlePaddle["PaddlePaddle Framework"]
3
        PM[inference.json<br/>inference.pdiparams]
4
    end
5

6
    subgraph ONNX["ONNX Intermediate"]
7
        OM[model.onnx<br/>opset 14]
8
    end
9

10
    subgraph Optimization["Graph Optimization"]
11
        GS[onnx-graphsurgeon<br/>算子分解]
12
    end
13

14
    subgraph TFLite["LiteRT Format"]
15
        TM[model.tflite<br/>FP16 Quantized]
16
    end
17

18
    PM -->|paddle2onnx| OM
19
    OM -->|HardSigmoid 分解<br/>Resize 模式修改| GS
20
    GS -->|onnx2tf| TM

这条路径看似简单，实则暗藏玄机。

第一道坎：paddle2onnx 的算子兼容性

paddle2onnx 是 PaddlePaddle 官方提供的模型转换工具。理论上，它能将 PaddlePaddle 模型转换为 ONNX 格式。但 PP-OCRv5 使用了一些特殊的算子，这些算子在 ONNX 中的映射并非一一对应。

paddle2onnx --model_dir PP-OCRv5_mobile_det \
  --model_filename inference.json \
  --params_filename inference.pdiparams \
  --save_file ocr_det_v5.onnx \
  --opset_version 14

这里有一个关键细节：PP-OCRv5 的模型文件名是 inference.json 而非传统的 inference.pdmodel。这是 PaddlePaddle 新版本的模型格式变化，许多开发者在这里踩坑³。

第二道坎：HardSigmoid 与 GPU 兼容性

转换后的 ONNX 模型包含 HardSigmoid 算子。这个算子在数学上定义为：

\text{HardSigmoid}(x) = \max(0, \min(1, \alpha x + \beta))

其中 $\alpha = 0.2$ ， $\beta = 0.5$ 。

问题在于：LiteRT 的 GPU Delegate 不支持 HardSigmoid。当模型包含不支持的算子时，GPU Delegate 会将整个子图回退到 CPU 执行，这会导致严重的性能损失。

解决方案是将 HardSigmoid 分解为基本算子。使用 onnx-graphsurgeon 库，我们可以在计算图级别进行手术：

1
import onnx_graphsurgeon as gs
2
import numpy as np
3

4
def decompose_hardsigmoid(graph: gs.Graph) -> gs.Graph:
5
    """
6
    将 HardSigmoid 分解为 GPU 友好的基本算子
7
    HardSigmoid(x) = max(0, min(1, alpha*x + beta))
8
    分解为: Mul -> Add -> Clip
9
    """
10
    for node in graph.nodes:
11
        if node.op == "HardSigmoid":
12
            # 获取 HardSigmoid 的参数
13
            alpha = node.attrs.get("alpha", 0.2)
14
            beta = node.attrs.get("beta", 0.5)
15

16
            input_tensor = node.inputs[0]
17
            output_tensor = node.outputs[0]
18

19
            # 创建常量张量
20
            alpha_const = gs.Constant(
21
                name=f"{node.name}_alpha",
22
                values=np.array([alpha], dtype=np.float32)
23
            )
24
            beta_const = gs.Constant(
25
                name=f"{node.name}_beta",
26
                values=np.array([beta], dtype=np.float32)
27
            )
28

29
            # 创建中间变量
30
            mul_out = gs.Variable(name=f"{node.name}_mul_out")
31
            add_out = gs.Variable(name=f"{node.name}_add_out")
32

33
            # 构建分解后的子图: x -> Mul(alpha) -> Add(beta) -> Clip(0,1)
34
            mul_node = gs.Node(
35
                op="Mul",
36
                inputs=[input_tensor, alpha_const],
37
                outputs=[mul_out]
38
            )
39
            add_node = gs.Node(
40
                op="Add",
41
                inputs=[mul_out, beta_const],
42
                outputs=[add_out]
43
            )
44
            clip_node = gs.Node(
45
                op="Clip",
46
                inputs=[add_out],
47
                outputs=[output_tensor],
48
                attrs={"min": 0.0, "max": 1.0}
49
            )
50

51
            # 替换原节点
52
            graph.nodes.remove(node)
53
            graph.nodes.extend([mul_node, add_node, clip_node])
54

55
    graph.cleanup().toposort()
56
    return graph

这种分解的关键在于：Mul、Add、Clip 都是 LiteRT GPU Delegate 完全支持的算子。分解后，整个子图可以在 GPU 上连续执行，避免了 CPU-GPU 数据传输的开销。

TIP

为什么不直接修改模型训练代码？因为 HardSigmoid 在训练时的梯度计算与 Clip 不同。分解只应在推理阶段进行，保持训练时的数值稳定性。

第三道坎：Resize 算子的坐标变换模式

ONNX 的 Resize 算子有一个 coordinate_transformation_mode 属性，它决定了如何将输出坐标映射到输入坐标。PP-OCRv5 使用的是 half_pixel 模式，但 LiteRT GPU Delegate 对这种模式的支持有限。

将其改为 asymmetric 模式可以获得更好的 GPU 兼容性：

1
for node in graph.nodes:
2
    if node.op == "Resize":
3
        node.attrs["coordinate_transformation_mode"] = "asymmetric"

WARNING

这种修改可能会导致微小的数值差异。在实际测试中，这种差异对 OCR 精度的影响可以忽略不计，但在其他任务中可能需要仔细评估。

最后一步：onnx2tf 与 FP16 量化

onnx2tf 是将 ONNX 模型转换为 TFLite 格式的工具。FP16（半精度浮点）量化是移动端部署的常见选择，它在精度损失可接受的前提下，将模型大小减半，并能利用移动 GPU 的 FP16 计算单元。

onnx2tf -i ocr_det_v5_fixed.onnx -o converted_det \
  -b 1 -ois x:1,3,640,640 -n

这里的 -ois 参数指定了输入的静态形状。静态形状对于 GPU 加速至关重要，动态形状会导致每次推理都需要重新编译 GPU 程序，严重影响性能。

文本检测：DBNet 的可微分二值化

PP-OCRv5 的检测模块基于 DBNet（Differentiable Binarization Network）⁴。传统的文本检测方法使用固定阈值进行二值化，而 DBNet 的创新在于：让网络自己学习每个像素的最优阈值。

1
flowchart TB
2
    subgraph DBNet["DBNet 架构"]
3
        direction TB
4
        IMG[输入图像<br/>H x W x 3]
5
        BB[Backbone<br/>MobileNetV3]
6
        FPN[FPN 特征金字塔<br/>多尺度融合]
7

8
        subgraph Heads["双分支输出"]
9
            PH[概率图分支<br/>P: H x W x 1]
10
            TH[阈值图分支<br/>T: H x W x 1]
11
        end
12

13
        DB["可微分二值化<br/>B = sigmoid k * P-T"]
14
    end
15

16
    IMG --> BB --> FPN
17
    FPN --> PH
18
    FPN --> TH
19
    PH --> DB
20
    TH --> DB

标准二值化 vs 可微分二值化

标准二值化是一个阶跃函数：

B_{i,j} = \begin{cases} 1 & \text{if } P_{i,j} \geq t \\ 0 & \text{otherwise} \end{cases}

这个函数不可微，无法通过反向传播进行端到端训练。DBNet 提出了一个近似函数：

\hat{B}_{i,j} = \frac{1}{1 + e^{-k(P_{i,j} - T_{i,j})}}

其中 $P$ 是概率图， $T$ 是阈值图（由网络学习）， $k$ 是放大因子（训练时设为 50）。

TIP

这个公式本质上是一个 Sigmoid 函数，只是输入变成了 $P - T$ 。当 $k$ 足够大时，它的行为接近阶跃函数，但保持了可微性。

后处理流程的工程实现

在 PPOCRv5-Android 项目中，后处理流程在 postprocess.cpp 中实现。核心流程包括：

1
flowchart LR
2
    subgraph Input["模型输出"]
3
        PM[概率图 P<br/>640 x 640]
4
    end
5

6
    subgraph Binary["二值化"]
7
        BT[阈值过滤<br/>threshold=0.1]
8
        BM[二值图<br/>640 x 640]
9
    end
10

11
    subgraph Contour["轮廓检测"]
12
        DS[4x 降采样<br/>160 x 160]
13
        CC[连通域分析<br/>BFS 遍历]
14
        BD[边界点提取]
15
    end
16

17
    subgraph Geometry["几何计算"]
18
        CH[凸包计算<br/>Graham Scan]
19
        RR[旋转卡壳<br/>最小外接矩形]
20
        UC[Unclip 扩展<br/>ratio=1.5]
21
    end
22

23
    subgraph Output["输出"]
24
        TB[RotatedRect<br/>center, size, angle]
25
    end
26

27
    PM --> BT --> BM
28
    BM --> DS --> CC --> BD
29
    BD --> CH --> RR --> UC --> TB

实际代码中，TextDetector::Impl::Detect 方法展示了完整的检测流程：

1
std::vector<RotatedRect> Detect(const uint8_t *image_data,
2
                                int width, int height, int stride,
3
                                float *detection_time_ms) {
4
    // 1. 计算缩放比例
5
    scale_x_ = static_cast<float>(width) / kDetInputSize;
6
    scale_y_ = static_cast<float>(height) / kDetInputSize;
7

8
    // 2. 双线性插值缩放到 640x640
9
    image_utils::ResizeBilinear(image_data, width, height, stride,
10
                                resized_buffer_.data(), kDetInputSize, kDetInputSize);
11

12
    // 3. ImageNet 标准化
13
    PrepareFloatInput();
14

15
    // 4. 推理
16
    auto run_result = compiled_model_->Run(input_buffers_, output_buffers_);
17

18
    // 5. 二值化
19
    BinarizeOutput(prob_map, total_pixels);
20

21
    // 6. 轮廓检测
22
    auto contours = postprocess::FindContours(binary_map_.data(),
23
                                              kDetInputSize, kDetInputSize);
24

25
    // 7. 最小外接矩形 + Unclip
26
    for (const auto &contour : contours) {
27
        RotatedRect rect = postprocess::MinAreaRect(contour);
28
        UnclipBox(rect, kUnclipRatio);
29
        // 坐标映射回原图
30
        rect.center_x *= scale_x_;
31
        rect.center_y *= scale_y_;
32
        // ...
33
    }
34
}

这个流程的关键在于「最小外接旋转矩形」。与轴对齐的边界框不同，旋转矩形可以紧密贴合任意角度的文本，这对于自然场景中的倾斜文本至关重要。

Unclip：文本框的膨胀算法

DBNet 输出的文本区域通常比实际文本略小，因为网络学习的是文本的「核心区域」。为了获得完整的文本边界，需要对检测到的多边形进行膨胀（Unclip）操作。

Unclip 的数学原理基于 Vatti 多边形裁剪算法的逆操作。给定一个多边形 $P$ 和膨胀距离 $d$ ，膨胀后的多边形 $P'$ 满足：

$d = \frac{A \times r}{L}$

其中 $A$ 是多边形面积， $L$ 是周长， $r$ 是膨胀比例（通常设为 1.5）。

在 postprocess.cpp 中，UnclipBox 函数实现了这一逻辑：

1
void UnclipBox(RotatedRect &box, float unclip_ratio) {
2
    // 计算膨胀距离
3
    float area = box.width * box.height;
4
    float perimeter = 2.0f * (box.width + box.height);
5

6
    if (perimeter < 1e-6f) return;  // 防止除零
7

8
    // d = A * r / L
9
    float distance = area * unclip_ratio / perimeter;
10

11
    // 向外膨胀：宽高各增加 2d
12
    box.width += 2.0f * distance;
13
    box.height += 2.0f * distance;
14
}

这个简化版本假设文本框是矩形。对于更复杂的多边形，需要使用完整的 Clipper 库实现多边形偏移：

1
// 完整的多边形 Unclip（使用 Clipper 库）
2
ClipperLib::Path polygon;
3
for (const auto& pt : contour) {
4
    polygon.push_back(ClipperLib::IntPoint(
5
        static_cast<int>(pt.x * 1000),  // 放大以保持精度
6
        static_cast<int>(pt.y * 1000)
7
    ));
8
}
9

10
ClipperLib::ClipperOffset offset;
11
offset.AddPath(polygon, ClipperLib::jtRound, ClipperLib::etClosedPolygon);
12

13
ClipperLib::Paths solution;
14
offset.Execute(solution, distance * 1000);  // 膨胀

NOTE

PPOCRv5-Android 选择了简化的矩形膨胀，而非完整的多边形偏移。这是因为：

大多数文本框接近矩形
完整的 Clipper 库会增加较多二进制体积
简化版本的性能更好。

文本识别：SVTRv2 与 CTC 解码

如果说检测是「找到文字在哪里」，那么识别就是「读出文字是什么」。PP-OCRv5 的识别模块基于 SVTRv2（Scene Text Recognition with Visual Transformer v2）⁵。

SVTRv2 的架构创新

SVTRv2 相比前代 SVTR 有三个关键改进：

1
flowchart TB
2
    subgraph SVTRv2["SVTRv2 架构"]
3
        direction TB
4

5
        subgraph Encoder["视觉编码器"]
6
            PE[Patch Embedding<br/>4x4 卷积]
7

8
            subgraph Mixing["混合注意力块 x12"]
9
                LA[Local Attention<br/>7x7 窗口]
10
                GA[Global Attention<br/>全局感受野]
11
                FFN[Feed Forward<br/>MLP]
12
            end
13
        end
14

15
        subgraph Decoder["CTC 解码器"]
16
            FC[全连接层<br/>D -> 18384]
17
            SM[Softmax]
18
            CTC[CTC Decode]
19
        end
20
    end
21

22
    PE --> LA --> GA --> FFN
23
    FFN --> FC --> SM --> CTC

混合注意力机制：交替使用局部注意力（捕捉笔画细节）和全局注意力（理解字符结构）。局部注意力使用 7x7 的滑动窗口，计算复杂度从 $O(n^2)$ 降到 $O(n \times 49)$ 。
多尺度特征融合：不同于 ViT 的单一分辨率，SVTRv2 在不同深度使用不同的特征图分辨率，类似于 CNN 的金字塔结构。
语义引导模块（Semantic Guidance Module）：在编码器末端添加了一个轻量级的语义分支，帮助模型理解字符的语义关系，而不仅仅是视觉特征。

这些改进使得 SVTRv2 在保持 CTC 解码简单性的同时，达到了与 Attention-based 方法相当的精度⁶。

为什么是 CTC 而不是 Attention？

文本识别有两种主流范式：

CTC（Connectionist Temporal Classification）：将识别视为序列标注问题，输出与输入对齐
Attention-based Decoder：使用注意力机制逐字符生成输出

Attention 方法通常精度更高，但 CTC 方法更简单、更快。SVTRv2 的贡献在于：通过改进视觉编码器，让 CTC 方法达到甚至超越 Attention 方法的精度⁶。

CTC 解码的核心是「合并重复」和「移除空白」：

1
flowchart LR
2
    subgraph Input["模型输出"]
3
        L["Logits<br/>[T, 18384]"]
4
    end
5

6
    subgraph Argmax["Argmax NEON"]
7
        A1["t=0: blank"]
8
        A2["t=1: H"]
9
        A3["t=2: H"]
10
        A4["t=3: blank"]
11
        A5["t=4: e"]
12
        A6["t=5: l"]
13
        A7["t=6: l"]
14
        A8["t=7: l"]
15
        A9["t=8: o"]
16
    end
17

18
    subgraph Merge["合并重复"]
19
        M["blank, H, blank, e, l, o"]
20
    end
21

22
    subgraph Remove["移除空白"]
23
        R["H, e, l, o"]
24
    end
25

26
    subgraph Output["输出"]
27
        O["Helo - 错误"]
28
    end
29

30
    L --> A1 & A2 & A3 & A4 & A5 & A6 & A7 & A8 & A9
31
    A1 & A2 & A3 & A4 & A5 & A6 & A7 & A8 & A9 --> Merge --> Remove --> Output

等等，这里有问题。如果原始文本是 “Hello”，两个 ‘l’ 被错误地合并了。CTC 的解决方案是：在重复字符之间插入 blank token。

1
正确编码: [blank, H, e, l, blank, l, o]
2
解码结果: "Hello"

NEON 优化的 CTC 解码

PPOCRv5-Android 的 CTC 解码使用 NEON 优化的 Argmax。在 text_recognizer.cpp 中：

1
inline void ArgmaxNeon8(const float *__restrict__ data, int size,
2
                        int &max_idx, float &max_val) {
3
    if (size < 16) {
4
        // 标量回退
5
        max_idx = 0;
6
        max_val = data[0];
7
        for (int i = 1; i < size; ++i) {
8
            if (data[i] > max_val) {
9
                max_val = data[i];
10
                max_idx = i;
11
            }
12
        }
13
        return;
14
    }
15

16
    // NEON 向量化：一次处理 4 个 float
17
    float32x4_t v_max = vld1q_f32(data);
18
    int32x4_t v_idx = {0, 1, 2, 3};
19
    int32x4_t v_max_idx = v_idx;
20
    const int32x4_t v_four = vdupq_n_s32(4);
21

22
    int i = 4;
23
    for (; i + 4 <= size; i += 4) {
24
        float32x4_t v_curr = vld1q_f32(data + i);
25
        v_idx = vaddq_s32(v_idx, v_four);
26

27
        // 向量化比较和条件选择
28
        uint32x4_t cmp = vcgtq_f32(v_curr, v_max);
29
        v_max = vbslq_f32(cmp, v_curr, v_max);        // 选择较大值
30
        v_max_idx = vbslq_s32(cmp, v_idx, v_max_idx); // 选择对应索引
31
    }
32

33
    // 水平归约：找到 4 个候选中的最大值
34
    float max_vals[4];
35
    int32_t max_idxs[4];
36
    vst1q_f32(max_vals, v_max);
37
    vst1q_s32(max_idxs, v_max_idx);
38
    // ... 最终比较
39
}

对于 18,384 个类别的 Argmax，NEON 优化可以带来约 3 倍的加速。

CTC 损失函数与解码的数学原理

CTC 的核心思想是：给定输入序列 $X$ 和所有可能的对齐路径 $\pi$ ，计算目标序列 $Y$ 的概率：

$P(Y|X) = \sum_{\pi \in \mathcal{B}^{-1}(Y)} P(\pi|X)$

其中 $\mathcal{B}$ 是「多对一映射函数」，它将路径 $\pi$ 映射到输出序列 $Y$ （通过合并重复和移除空白）。

在推理时，我们使用贪心解码（Greedy Decoding）而非完整的 Beam Search：

1
std::string CTCGreedyDecode(const float* logits, int time_steps, int num_classes,
2
                            const std::vector<std::string>& dictionary) {
3
    std::string result;
4
    int prev_idx = -1;  // 用于合并重复
5

6
    for (int t = 0; t < time_steps; ++t) {
7
        // 找到当前时间步的最大概率类别
8
        int max_idx = 0;
9
        float max_val = logits[t * num_classes];
10

11
        for (int c = 1; c < num_classes; ++c) {
12
            if (logits[t * num_classes + c] > max_val) {
13
                max_val = logits[t * num_classes + c];
14
                max_idx = c;
15
            }
16
        }
17

18
        // CTC 解码规则：
19
        // 1. 跳过 blank token (index 0)
20
        // 2. 合并连续重复的字符
21
        if (max_idx != 0 && max_idx != prev_idx) {
22
            result += dictionary[max_idx - 1];  // -1 因为 blank 占用了 index 0
23
        }
24

25
        prev_idx = max_idx;
26
    }
27

28
    return result;
29
}

贪心解码的时间复杂度是 $O(T \times C)$ ，其中 $T$ 是时间步数， $C$ 是类别数。对于 PP-OCRv5， $T \approx 80$ ， $C = 18384$ ，每次解码需要约 150 万次比较。这就是为什么 NEON 优化如此重要。

TIP

Beam Search 可以提高解码精度，但计算量是贪心解码的 $k$ 倍（ $k$ 是 beam width）。在移动端，贪心解码通常是更好的选择。

字符字典：18,383 个字符的挑战

PP-OCRv5 支持 18,383 个字符，包括：

简体中文常用字
繁体中文常用字
英文字母和数字
日文平假名、片假名
常用标点符号和特殊字符

这个字典存储在 keys_v5.txt 文件中，每行一个字符。CTC 解码时，模型输出的 logits 形状为 [1, T, 18384]，其中 T 是时间步数，18384 = 18383 个字符 + 1 个 blank token。

LiteRT C++ API：2024 年重构后的现代接口

PPOCRv5-Android 使用 LiteRT 2024 年重构后的 C++ API，这套 API 提供了更现代的接口设计。与传统的 TFLite C API 相比，新 API 具有更好的类型安全性和资源管理能力。

新旧 API 对比

LiteRT 2024 重构带来了显著的 API 变化：

特性	旧 API (TFLite)	新 API (LiteRT)
命名空间	`tflite::`	`litert::`
错误处理	返回 `TfLiteStatus` 枚举	返回 `Expected<T>` 类型
内存管理	手动管理	RAII 自动管理
Delegate 配置	分散的 API	统一的 `Options` 类
张量访问	指针 + 手动类型转换	类型安全的 `TensorBuffer`

新 API 的核心优势是类型安全和资源自动管理。以错误处理为例：

1
// 旧 API：需要手动检查每个返回值
2
TfLiteStatus status = TfLiteInterpreterAllocateTensors(interpreter);
3
if (status != kTfLiteOk) {
4
    // 错误处理
5
}
6

7
// 新 API：使用 Expected 类型，支持链式调用
8
auto model_result = litert::CompiledModel::Create(env, model_path, options);
9
if (!model_result) {
10
    LOGE(TAG, "Error: %s", model_result.Error().Message().c_str());
11
    return false;
12
}
13
auto model = std::move(*model_result);  // 自动管理生命周期

环境与模型初始化

在 text_detector.cpp 中，初始化流程如下：

1
bool Initialize(const std::string &model_path, AcceleratorType accelerator_type) {
2
    // 1. 创建 LiteRT 环境
3
    auto env_result = litert::Environment::Create({});
4
    if (!env_result) {
5
        LOGE(TAG, "Failed to create LiteRT environment: %s",
6
             env_result.Error().Message().c_str());
7
        return false;
8
    }
9
    env_ = std::move(*env_result);
10

11
    // 2. 配置硬件加速器
12
    auto options_result = litert::Options::Create();
13
    auto hw_accelerator = ToLiteRtAccelerator(accelerator_type);
14
    options.SetHardwareAccelerators(hw_accelerator);
15

16
    // 3. 编译模型
17
    auto model_result = litert::CompiledModel::Create(*env_, model_path, options);
18
    if (!model_result) {
19
        LOGW(TAG, "Failed to create CompiledModel with accelerator %d: %s",
20
             static_cast<int>(accelerator_type),
21
             model_result.Error().Message().c_str());
22
        return false;
23
    }
24
    compiled_model_ = std::move(*model_result);
25

26
    // 4. 调整输入张量形状
27
    std::vector<int> input_dims = {1, kDetInputSize, kDetInputSize, 3};
28
    compiled_model_->ResizeInputTensor(0, absl::MakeConstSpan(input_dims));
29

30
    // 5. 创建托管 Buffer
31
    CreateBuffersWithCApi();
32

33
    return true;
34
}

Managed Tensor Buffer：零拷贝推理的关键

LiteRT 的 Managed Tensor Buffer 是实现高性能推理的关键。它允许 GPU Delegate 直接访问 Buffer，无需 CPU-GPU 数据传输：

1
bool CreateBuffersWithCApi() {
2
    LiteRtCompiledModel c_model = compiled_model_->Get();
3
    LiteRtEnvironment c_env = env_->Get();
4

5
    // 获取输入 Buffer 需求
6
    LiteRtTensorBufferRequirements input_requirements = nullptr;
7
    LiteRtGetCompiledModelInputBufferRequirements(
8
        c_model, /*signature_index=*/0, /*input_index=*/0,
9
        &input_requirements);
10

11
    // 获取张量类型信息
12
    auto input_type = compiled_model_->GetInputTensorType(0, 0);
13
    LiteRtRankedTensorType tensor_type =
14
        static_cast<LiteRtRankedTensorType>(*input_type);
15

16
    // 创建托管 Buffer
17
    LiteRtTensorBuffer input_buffer = nullptr;
18
    LiteRtCreateManagedTensorBufferFromRequirements(
19
        c_env, &tensor_type, input_requirements, &input_buffer);
20

21
    // 包装为 C++ 对象，自动管理生命周期
22
    input_buffers_.push_back(
23
        litert::TensorBuffer::WrapCObject(input_buffer,
24
                                          litert::OwnHandle::kYes));
25
    return true;
26
}

这种设计的优势在于：

零拷贝推理：GPU Delegate 可以直接访问 Buffer，无需 CPU-GPU 数据传输
自动内存管理：OwnHandle::kYes 确保 Buffer 在 C++ 对象析构时自动释放
类型安全：编译时检查张量类型匹配

GPU 加速：OpenCL 的选择与权衡

LiteRT 提供了多种硬件加速选项：

1
flowchart TB
2
    subgraph Delegates["LiteRT Delegate 生态"]
3
        direction TB
4
        GPU_CL[GPU Delegate<br/>OpenCL Backend]
5
        GPU_GL[GPU Delegate<br/>OpenGL ES Backend]
6
        NNAPI[NNAPI Delegate<br/>Android HAL]
7
        XNN[XNNPACK Delegate<br/>CPU Optimized]
8
    end
9

10
    subgraph Hardware["硬件映射"]
11
        direction TB
12
        ADRENO[Adreno GPU<br/>Qualcomm]
13
        MALI[Mali GPU<br/>ARM]
14
        NPU[NPU/DSP<br/>厂商特定]
15
        CPU[ARM CPU<br/>NEON]
16
    end
17

18
    GPU_CL --> ADRENO
19
    GPU_CL --> MALI
20
    GPU_GL --> ADRENO
21
    GPU_GL --> MALI
22
    NNAPI --> NPU
23
    XNN --> CPU

加速器	后端	优点	缺点
GPU	OpenCL	广泛支持，性能好	不是 Android 标准组件
GPU	OpenGL ES	Android 标准组件	性能不如 OpenCL
NPU	NNAPI	最高性能	设备兼容性差
CPU	XNNPACK	最广泛兼容	性能最低

PPOCRv5-Android 选择了 OpenCL 作为主要加速后端。Google 在 2020 年发布了 TFLite 的 OpenCL 后端，相比 OpenGL ES 后端，它在 Adreno GPU 上实现了约 2 倍的加速⁷。

OpenCL 的优势来自几个方面：

设计初衷：OpenCL 从一开始就为通用计算设计，而 OpenGL 是图形渲染 API，后来才添加了计算着色器支持
常量内存：OpenCL 的常量内存对神经网络的权重访问非常高效
FP16 支持：OpenCL 原生支持半精度浮点，而 OpenGL 的支持较晚

但 OpenCL 有一个致命缺陷：它不是 Android 的标准组件。不同厂商的 OpenCL 实现质量参差不齐，有些设备甚至完全不支持。

OpenCL vs OpenGL ES：性能深度对比

为了理解 OpenCL 的优势，我们需要深入到 GPU 架构层面。以高通 Adreno 640 为例：

1
flowchart TB
2
    subgraph Adreno["Adreno 640 架构"]
3
        direction TB
4

5
        subgraph SP["Shader Processors x2"]
6
            ALU1[ALU Array<br/>256 FP32 / 512 FP16]
7
            ALU2[ALU Array<br/>256 FP32 / 512 FP16]
8
        end
9

10
        subgraph Memory["内存层次"]
11
            L1[L1 Cache<br/>16KB per SP]
12
            L2[L2 Cache<br/>1MB Shared]
13
            GMEM[Global Memory<br/>LPDDR4X]
14
        end
15

16
        subgraph Special["专用单元"]
17
            TMU[Texture Unit<br/>双线性插值]
18
            CONST[Constant Cache<br/>权重加速]
19
        end
20
    end
21

22
    ALU1 --> L1
23
    ALU2 --> L1
24
    L1 --> L2 --> GMEM
25
    TMU --> L1
26
    CONST --> ALU1 & ALU2

OpenCL 的性能优势来自：

特性	OpenCL	OpenGL ES Compute
常量内存	原生支持，硬件加速	需要模拟，通过 UBO
工作组大小	灵活配置	受限于着色器模型
内存屏障	细粒度控制	粗粒度
FP16 计算	`cl_khr_fp16` 扩展	需要 `mediump` 精度
调试工具	Snapdragon Profiler	有限支持

在卷积运算中，权重通常是常量。OpenCL 可以将权重放入常量内存，享受硬件级别的广播优化。而 OpenGL ES 需要将权重作为 Uniform Buffer Object (UBO) 传递，增加了内存访问开销。

NOTE

Google 在 Android 7.0 后限制了应用直接加载 OpenCL 库。但 LiteRT 的 GPU Delegate 通过 dlopen 动态加载系统的 OpenCL 实现，绕过了这一限制。这也是为什么 GPU Delegate 需要在运行时检测 OpenCL 可用性。

优雅降级策略

PPOCRv5-Android 实现了一个优雅降级策略：

1
constexpr AcceleratorType kFallbackChain[] = {
2
    AcceleratorType::kGpu,  // 首选 GPU
3
    AcceleratorType::kCpu,  // 回退 CPU
4
};
5

6
std::unique_ptr<OcrEngine> OcrEngine::Create(
7
        const std::string &det_model_path,
8
        const std::string &rec_model_path,
9
        const std::string &keys_path,
10
        AcceleratorType accelerator_type) {
11

12
    auto engine = std::unique_ptr<OcrEngine>(new OcrEngine());
13
    int start_index = GetFallbackStartIndex(accelerator_type);
14

15
    for (int i = start_index; i < kFallbackChainSize; ++i) {
16
        AcceleratorType current = kFallbackChain[i];
17

18
        auto detector = TextDetector::Create(det_model_path, current);
19
        if (!detector) continue;
20

21
        auto recognizer = TextRecognizer::Create(rec_model_path, keys_path, current);
22
        if (!recognizer) continue;
23

24
        engine->detector_ = std::move(detector);
25
        engine->recognizer_ = std::move(recognizer);
26
        engine->active_accelerator_ = current;
27

28
        engine->WarmUp();
29
        return engine;
30
    }
31
    return nullptr;
32
}

这种策略确保了应用在任何设备上都能运行，只是性能有所不同。

原生层：C++ 与 NEON 优化

为什么要用 C++ 而不是 Kotlin？

答案很简单：性能。图像预处理涉及大量的像素级操作，这些操作在 JVM 上的开销是不可接受的。更重要的是，C++ 可以直接使用 ARM NEON SIMD 指令，实现向量化计算。

NEON：ARM 的 SIMD 指令集

NEON 是 ARM 处理器的 SIMD（Single Instruction, Multiple Data）扩展。它允许一条指令同时处理多个数据元素。

1
flowchart LR
2
    subgraph NEON["128-bit NEON Register"]
3
        direction TB
4
        F4["4x float32"]
5
        I8["8x int16"]
6
        B16["16x int8"]
7
    end
8

9
    subgraph Operations["向量化操作"]
10
        direction TB
11
        LD["vld1q_f32<br/>加载 4 个 float"]
12
        SUB["vsubq_f32<br/>4 路并行减法"]
13
        MUL["vmulq_f32<br/>4 路并行乘法"]
14
        ST["vst1q_f32<br/>存储 4 个 float"]
15
    end
16

17
    subgraph Speedup["性能提升"]
18
        S1["标量: 4 条指令"]
19
        S2["NEON: 1 条指令"]
20
        S3["理论加速: 4x"]
21
    end
22

23
    F4 --> LD
24
    LD --> SUB --> MUL --> ST
25
    ST --> S3

PPOCRv5-Android 在多个关键路径使用 NEON 优化。以二值化为例（text_detector.cpp）：

1
void BinarizeOutput(const float *prob_map, int total_pixels) {
2
#if defined(__ARM_NEON) || defined(__ARM_NEON__)
3
    const float32x4_t v_threshold = vdupq_n_f32(kBinaryThreshold);
4
    const uint8x16_t v_255 = vdupq_n_u8(255);
5
    const uint8x16_t v_0 = vdupq_n_u8(0);
6

7
    int i = 0;
8
    for (; i + 16 <= total_pixels; i += 16) {
9
        // 一次处理 16 个像素
10
        float32x4_t f0 = vld1q_f32(prob_map + i);
11
        float32x4_t f1 = vld1q_f32(prob_map + i + 4);
12
        float32x4_t f2 = vld1q_f32(prob_map + i + 8);
13
        float32x4_t f3 = vld1q_f32(prob_map + i + 12);
14

15
        // 向量化比较
16
        uint32x4_t cmp0 = vcgtq_f32(f0, v_threshold);
17
        uint32x4_t cmp1 = vcgtq_f32(f1, v_threshold);
18
        uint32x4_t cmp2 = vcgtq_f32(f2, v_threshold);
19
        uint32x4_t cmp3 = vcgtq_f32(f3, v_threshold);
20

21
        // 窄化到 uint8
22
        uint16x4_t n0 = vmovn_u32(cmp0);
23
        uint16x4_t n1 = vmovn_u32(cmp1);
24
        uint16x8_t n01 = vcombine_u16(n0, n1);
25
        // ... 合并并存储
26
    }
27
    // 标量回退处理剩余像素
28
    for (; i < total_pixels; ++i) {
29
        binary_map_[i] = (prob_map[i] > kBinaryThreshold) ? 255 : 0;
30
    }
31
#else
32
    // 纯标量实现
33
    for (int i = 0; i < total_pixels; ++i) {
34
        binary_map_[i] = (prob_map[i] > kBinaryThreshold) ? 255 : 0;
35
    }
36
#endif
37
}

这段代码的关键优化点：

批量加载：vld1q_f32 一次加载 4 个 float，减少内存访问次数
向量化比较：vcgtq_f32 同时比较 4 个值，生成掩码
类型窄化：vmovn_u32 将 32 位结果压缩为 16 位，最终到 8 位

相比标量实现，NEON 优化可以带来 3-4 倍的加速⁸。

ImageNet 归一化的 NEON 实现

图像归一化是预处理的关键步骤。ImageNet 标准化使用以下公式：

$x_{normalized} = \frac{x - \mu}{\sigma}$

其中 $\mu = [0.485, 0.456, 0.406]$ ， $\sigma = [0.229, 0.224, 0.225]$ （RGB 三通道）。

在 image_utils.cpp 中，NEON 优化的归一化实现如下：

1
void NormalizeImageNet(const uint8_t* src, int width, int height, int stride,
2
                       float* dst) {
3
    // ImageNet 归一化参数
4
    constexpr float kMeanR = 0.485f, kMeanG = 0.456f, kMeanB = 0.406f;
5
    constexpr float kStdR = 0.229f, kStdG = 0.224f, kStdB = 0.225f;
6
    constexpr float kInvStdR = 1.0f / kStdR;
7
    constexpr float kInvStdG = 1.0f / kStdG;
8
    constexpr float kInvStdB = 1.0f / kStdB;
9
    constexpr float kScale = 1.0f / 255.0f;
10

11
#if defined(__ARM_NEON) || defined(__ARM_NEON__)
12
    // 预计算: (1/255) / std = 1 / (255 * std)
13
    const float32x4_t v_scale_r = vdupq_n_f32(kScale * kInvStdR);
14
    const float32x4_t v_scale_g = vdupq_n_f32(kScale * kInvStdG);
15
    const float32x4_t v_scale_b = vdupq_n_f32(kScale * kInvStdB);
16

17
    // 预计算: -mean / std
18
    const float32x4_t v_bias_r = vdupq_n_f32(-kMeanR * kInvStdR);
19
    const float32x4_t v_bias_g = vdupq_n_f32(-kMeanG * kInvStdG);
20
    const float32x4_t v_bias_b = vdupq_n_f32(-kMeanB * kInvStdB);
21

22
    for (int y = 0; y < height; ++y) {
23
        const uint8_t* row = src + y * stride;
24
        float* dst_row = dst + y * width * 3;
25

26
        int x = 0;
27
        for (; x + 4 <= width; x += 4) {
28
            // 加载 4 个 RGBA 像素 (16 bytes)
29
            uint8x16_t rgba = vld1q_u8(row + x * 4);
30

31
            // 解交织: RGBARGBARGBARGBA -> RRRR, GGGG, BBBB, AAAA
32
            uint8x16x4_t channels = vld4q_u8(row + x * 4);
33

34
            // uint8 -> uint16 -> uint32 -> float32
35
            uint16x8_t r16 = vmovl_u8(vget_low_u8(channels.val[0]));
36
            uint16x8_t g16 = vmovl_u8(vget_low_u8(channels.val[1]));
37
            uint16x8_t b16 = vmovl_u8(vget_low_u8(channels.val[2]));
38

39
            float32x4_t r_f = vcvtq_f32_u32(vmovl_u16(vget_low_u16(r16)));
40
            float32x4_t g_f = vcvtq_f32_u32(vmovl_u16(vget_low_u16(g16)));
41
            float32x4_t b_f = vcvtq_f32_u32(vmovl_u16(vget_low_u16(b16)));
42

43
            // 归一化: (x / 255 - mean) / std = x * (1/255/std) + (-mean/std)
44
            r_f = vmlaq_f32(v_bias_r, r_f, v_scale_r);  // fused multiply-add
45
            g_f = vmlaq_f32(v_bias_g, g_f, v_scale_g);
46
            b_f = vmlaq_f32(v_bias_b, b_f, v_scale_b);
47

48
            // 交织存储: RRRR, GGGG, BBBB -> RGBRGBRGBRGB
49
            float32x4x3_t rgb = {r_f, g_f, b_f};
50
            vst3q_f32(dst_row + x * 3, rgb);
51
        }
52

53
        // 标量处理剩余像素
54
        for (; x < width; ++x) {
55
            const uint8_t* px = row + x * 4;
56
            float* dst_px = dst_row + x * 3;
57
            dst_px[0] = (px[0] * kScale - kMeanR) * kInvStdR;
58
            dst_px[1] = (px[1] * kScale - kMeanG) * kInvStdG;
59
            dst_px[2] = (px[2] * kScale - kMeanB) * kInvStdB;
60
        }
61
    }
62
#else
63
    // 标量实现（略）
64
#endif
65
}

这段代码的关键优化技巧：

预计算常量：将 (x - mean) / std 变换为 x * scale + bias，减少运行时除法
Fused Multiply-Add：vmlaq_f32 在单条指令中完成乘法和加法
解交织加载：vld4q_u8 自动将 RGBA 分离为四个通道
交织存储：vst3q_f32 将 RGB 三通道交织写入内存

零 OpenCV 依赖

许多 OCR 项目依赖 OpenCV 进行图像预处理。OpenCV 功能强大，但它也带来了巨大的包体积，Android 上的 OpenCV 库通常超过 10MB。

PPOCRv5-Android 选择了「零 OpenCV 依赖」的路线。所有图像预处理操作都在 image_utils.cpp 中用纯 C++ 实现：

双线性插值缩放：手写实现，支持 NEON 优化
归一化：ImageNet 标准化和识别标准化
透视变换：从原图裁剪任意角度的文本区域

双线性插值的 NEON 实现

双线性插值是图像缩放的核心算法。给定源图像坐标 $(x, y)$ ，双线性插值计算目标像素值：

$f(x, y) = (1-\alpha)(1-\beta)f_{00} + \alpha(1-\beta)f_{10} + (1-\alpha)\beta f_{01} + \alpha\beta f_{11}$

其中 $\alpha = x - \lfloor x \rfloor$ ， $\beta = y - \lfloor y \rfloor$ ， $f_{ij}$ 是四个邻近像素的值。

1
void ResizeBilinear(const uint8_t* src, int src_w, int src_h, int src_stride,
2
                    uint8_t* dst, int dst_w, int dst_h) {
3
    const float scale_x = static_cast<float>(src_w) / dst_w;
4
    const float scale_y = static_cast<float>(src_h) / dst_h;
5

6
    for (int dy = 0; dy < dst_h; ++dy) {
7
        const float sy = (dy + 0.5f) * scale_y - 0.5f;
8
        const int y0 = std::max(0, static_cast<int>(std::floor(sy)));
9
        const int y1 = std::min(src_h - 1, y0 + 1);
10
        const float beta = sy - y0;
11
        const float inv_beta = 1.0f - beta;
12

13
        const uint8_t* row0 = src + y0 * src_stride;
14
        const uint8_t* row1 = src + y1 * src_stride;
15
        uint8_t* dst_row = dst + dy * dst_w * 4;
16

17
#if defined(__ARM_NEON) || defined(__ARM_NEON__)
18
        // NEON: 一次处理 4 个目标像素
19
        const float32x4_t v_beta = vdupq_n_f32(beta);
20
        const float32x4_t v_inv_beta = vdupq_n_f32(inv_beta);
21

22
        int dx = 0;
23
        for (; dx + 4 <= dst_w; dx += 4) {
24
            // 计算 4 个源坐标
25
            float sx[4];
26
            for (int i = 0; i < 4; ++i) {
27
                sx[i] = ((dx + i) + 0.5f) * scale_x - 0.5f;
28
            }
29

30
            // 加载 alpha 权重
31
            float alpha[4], inv_alpha[4];
32
            int x0[4], x1[4];
33
            for (int i = 0; i < 4; ++i) {
34
                x0[i] = std::max(0, static_cast<int>(std::floor(sx[i])));
35
                x1[i] = std::min(src_w - 1, x0[i] + 1);
36
                alpha[i] = sx[i] - x0[i];
37
                inv_alpha[i] = 1.0f - alpha[i];
38
            }
39

40
            // 对每个通道进行双线性插值
41
            for (int c = 0; c < 4; ++c) {  // RGBA
42
                float32x4_t f00, f10, f01, f11;
43

44
                // 收集 4 个像素的邻近值
45
                f00 = vsetq_lane_f32(row0[x0[0] * 4 + c], f00, 0);
46
                f00 = vsetq_lane_f32(row0[x0[1] * 4 + c], f00, 1);
47
                f00 = vsetq_lane_f32(row0[x0[2] * 4 + c], f00, 2);
48
                f00 = vsetq_lane_f32(row0[x0[3] * 4 + c], f00, 3);
49
                // ... f10, f01, f11 类似
50

51
                // 双线性插值公式
52
                float32x4_t v_alpha = vld1q_f32(alpha);
53
                float32x4_t v_inv_alpha = vld1q_f32(inv_alpha);
54

55
                float32x4_t top = vmlaq_f32(
56
                    vmulq_f32(f00, v_inv_alpha),
57
                    f10, v_alpha
58
                );
59
                float32x4_t bottom = vmlaq_f32(
60
                    vmulq_f32(f01, v_inv_alpha),
61
                    f11, v_alpha
62
                );
63
                float32x4_t result = vmlaq_f32(
64
                    vmulq_f32(top, v_inv_beta),
65
                    bottom, v_beta
66
                );
67

68
                // 转换回 uint8 并存储
69
                uint32x4_t result_u32 = vcvtq_u32_f32(result);
70
                // ... 存储
71
            }
72
        }
73
#endif
74
        // 标量处理剩余像素（略）
75
    }
76
}

TIP

双线性插值的 NEON 优化比较复杂，因为四个邻近像素的地址是不连续的。一个更高效的方法是使用分离式双线性插值：先在水平方向插值，再在垂直方向插值。这样可以更好地利用缓存局部性。

这种选择的代价是更多的开发工作，但收益是显著的：

APK 体积减少约 10MB
完全控制预处理逻辑，便于优化
避免 OpenCV 版本兼容性问题

透视变换：从旋转矩形到标准文本行

文本识别模型期望输入是水平的文本行图像。但检测到的文本框可能是任意角度的旋转矩形。透视变换负责将旋转矩形区域「拉直」。

在 text_recognizer.cpp 中，CropAndRotate 方法实现了这一功能：

1
void CropAndRotate(const uint8_t *__restrict__ image_data,
2
                   int width, int height, int stride,
3
                   const RotatedRect &box, int &target_width) {
4
    // 计算旋转矩形的四个角点
5
    const float cos_angle = std::cos(box.angle * M_PI / 180.0f);
6
    const float sin_angle = std::sin(box.angle * M_PI / 180.0f);
7
    const float half_w = box.width / 2.0f;
8
    const float half_h = box.height / 2.0f;
9

10
    float corners[8];  // 4 个角点的 (x, y) 坐标
11
    corners[0] = box.center_x + (-half_w * cos_angle - (-half_h) * sin_angle);
12
    corners[1] = box.center_y + (-half_w * sin_angle + (-half_h) * cos_angle);
13
    // ... 计算其他角点
14

15
    // 自适应目标宽度：保持宽高比
16
    const float aspect_ratio = src_width / std::max(src_height, 1.0f);
17
    target_width = static_cast<int>(kRecInputHeight * aspect_ratio);
18
    target_width = std::clamp(target_width, 1, kRecInputWidth);  // 48x[1, 320]
19

20
    // 仿射变换矩阵
21
    const float a00 = (x1 - x0) * inv_dst_w;
22
    const float a01 = (x3 - x0) * inv_dst_h;
23
    const float a10 = (y1 - y0) * inv_dst_w;
24
    const float a11 = (y3 - y0) * inv_dst_h;
25

26
    // 双线性插值采样 + 归一化（NEON 优化）
27
    for (int dy = 0; dy < kRecInputHeight; ++dy) {
28
        for (int dx = 0; dx < target_width; ++dx) {
29
            float sx = base_sx + a00 * dx;
30
            float sy = base_sy + a10 * dx;
31
            BilinearSampleNeon(image_data, stride, sx, sy, dst_row + dx * 3);
32
        }
33
    }
34
}

这个实现的关键优化：

自适应宽度：根据文本框宽高比动态调整输出宽度，避免过度拉伸或压缩
仿射变换近似：对于近似平行四边形的文本框，使用仿射变换代替透视变换，减少计算量
NEON 双线性插值：采样和归一化在一个 pass 中完成，减少内存访问

JNI：Kotlin 与 C++ 的桥梁

JNI（Java Native Interface）是 Kotlin/Java 与 C++ 通信的桥梁。但 JNI 调用有开销，频繁的跨语言调用会严重影响性能。

PPOCRv5-Android 的设计原则是：最小化 JNI 调用次数。整个 OCR 流程只需要一次 JNI 调用：

1
sequenceDiagram
2
    participant K as Kotlin Layer
3
    participant J as JNI Bridge
4
    participant N as Native Layer
5
    participant G as GPU
6

7
    K->>J: process(bitmap)
8
    J->>N: 传递 RGBA 指针
9

10
    Note over N,G: Native 层完成所有工作
11

12
    N->>N: 图像预处理 NEON
13
    N->>G: 文本检测推理
14
    G-->>N: 概率图
15
    N->>N: 后处理 轮廓检测
16

17
    loop 每个文本框
18
        N->>N: 透视变换裁剪
19
        N->>G: 文本识别推理
20
        G-->>N: logits
21
        N->>N: CTC 解码
22
    end
23

24
    N-->>J: OCR Results
25
    J-->>K: List OcrResult

在 ppocrv5_jni.cpp 中，核心的 nativeProcess 函数展示了这种设计：

1
JNIEXPORT jobjectArray JNICALL
2
Java_me_fleey_ppocrv5_ocr_OcrEngine_nativeProcess(
3
        JNIEnv *env, jobject thiz, jlong handle, jobject bitmap) {
4

5
    auto *engine = reinterpret_cast<ppocrv5::OcrEngine *>(handle);
6

7
    // 锁定 Bitmap 像素
8
    void *pixels = nullptr;
9
    AndroidBitmap_lockPixels(env, bitmap, &pixels);
10

11
    // 一次 JNI 调用完成所有 OCR 工作
12
    auto results = engine->Process(
13
            static_cast<const uint8_t *>(pixels),
14
            static_cast<int>(bitmap_info.width),
15
            static_cast<int>(bitmap_info.height),
16
            static_cast<int>(bitmap_info.stride));
17

18
    AndroidBitmap_unlockPixels(env, bitmap);
19

20
    // 构造 Java 对象数组返回
21
    // ...
22
}

这种设计避免了在检测和识别之间来回传递数据的开销。

架构设计：模块化与可测试性

PPOCRv5-Android 的架构遵循「关注点分离」原则：

1
flowchart TB
2
    subgraph UI["Jetpack Compose UI Layer"]
3
        direction LR
4
        CP[CameraPreview]
5
        GP[GalleryPicker]
6
        RO[ResultOverlay]
7
    end
8

9
    subgraph VM["ViewModel Layer"]
10
        OVM[OCRViewModel<br/>State Management]
11
    end
12

13
    subgraph Native["Native Layer - C++"]
14
        OE[OcrEngine<br/>Orchestration]
15

16
        subgraph Detection["Text Detection"]
17
            TD[TextDetector]
18
            DB[DBNet FP16]
19
        end
20

21
        subgraph Recognition["Text Recognition"]
22
            TR[TextRecognizer]
23
            SVTR[SVTRv2 + CTC]
24
        end
25

26
        subgraph Preprocessing["Image Processing"]
27
            IP[ImagePreprocessor<br/>NEON Optimized]
28
            PP[PostProcessor<br/>Contour Detection]
29
        end
30

31
        subgraph Runtime["LiteRT Runtime"]
32
            GPU[GPU Delegate<br/>OpenCL]
33
            CPU[CPU Fallback<br/>XNNPACK]
34
        end
35
    end
36

37
    CP --> OVM
38
    GP --> OVM
39
    OVM --> RO
40
    OVM <-->|JNI| OE
41
    OE --> TD
42
    OE --> TR
43
    TD --> DB
44
    TR --> SVTR
45
    TD --> IP
46
    TR --> IP
47
    DB --> PP
48
    DB --> GPU
49
    SVTR --> GPU
50
    GPU -.->|Fallback| CPU

这种分层架构的好处是：

UI 层：纯 Kotlin/Compose，专注于用户交互
ViewModel 层：管理状态和业务逻辑
Native 层：高性能计算，与 UI 完全解耦

每一层都可以独立测试。Native 层可以用 Google Test 进行单元测试，ViewModel 层可以用 JUnit + MockK 进行测试。

Kotlin 层的封装

在 OcrEngine.kt 中，Kotlin 层提供了简洁的 API：

1
class OcrEngine private constructor(
2
    private var nativeHandle: Long,
3
) : Closeable {
4

5
    companion object {
6
        init {
7
            System.loadLibrary("ppocrv5_jni")
8
        }
9

10
        fun create(
11
            context: Context,
12
            acceleratorType: AcceleratorType = AcceleratorType.GPU,
13
        ): Result<OcrEngine> = runCatching {
14
            initializeCache(context)
15

16
            val detModelPath = copyAssetToCache(context, "$MODELS_DIR/$DET_MODEL_FILE")
17
            val recModelPath = copyAssetToCache(context, "$MODELS_DIR/$REC_MODEL_FILE")
18
            val keysPath = copyAssetToCache(context, "$MODELS_DIR/$KEYS_FILE")
19

20
            val handle = OcrEngine(0).nativeCreate(
21
                detModelPath, recModelPath, keysPath,
22
                acceleratorType.value,
23
            )
24

25
            if (handle == 0L) {
26
                throw OcrException("Failed to create native OCR engine")
27
            }
28

29
            OcrEngine(handle)
30
        }
31
    }
32

33
    fun process(bitmap: Bitmap): List<OcrResult> {
34
        check(nativeHandle != 0L) { "OcrEngine has been closed" }
35
        return nativeProcess(nativeHandle, bitmap)?.toList() ?: emptyList()
36
    }
37

38
    override fun close() {
39
        if (nativeHandle != 0L) {
40
            nativeDestroy(nativeHandle)
41
            nativeHandle = 0
42
        }
43
    }
44
}

这种设计的优点：

使用 Result 类型处理初始化错误
实现 Closeable 接口，支持 use 块自动释放资源
模型文件自动从 assets 复制到缓存目录

冷启动优化

首次推理（冷启动）通常比后续推理（热启动）慢很多。这是因为：

GPU Delegate 需要编译 OpenCL 程序
模型权重需要从 CPU 内存传输到 GPU 内存
各种缓存需要预热

PPOCRv5-Android 通过 Warm-up 机制来缓解冷启动问题：

1
void OcrEngine::WarmUp() {
2
    LOGD(TAG, "Starting warm-up (%d iterations)...", kWarmupIterations);
3

4
    // 创建一个小的测试图像
5
    std::vector<uint8_t> dummy_image(kWarmupImageSize * kWarmupImageSize * 4, 128);
6
    for (int i = 0; i < kWarmupImageSize * kWarmupImageSize; ++i) {
7
        dummy_image[i * 4 + 0] = static_cast<uint8_t>((i * 7) % 256);
8
        dummy_image[i * 4 + 1] = static_cast<uint8_t>((i * 11) % 256);
9
        dummy_image[i * 4 + 2] = static_cast<uint8_t>((i * 13) % 256);
10
        dummy_image[i * 4 + 3] = 255;
11
    }
12

13
    // 执行几次推理来预热
14
    for (int iter = 0; iter < kWarmupIterations; ++iter) {
15
        float detection_time_ms = 0.0f;
16
        detector_->Detect(dummy_image.data(), kWarmupImageSize, kWarmupImageSize,
17
                          kWarmupImageSize * 4, &detection_time_ms);
18
    }
19

20
    LOGD(TAG, "Warm-up completed (accelerator: %s)", AcceleratorName(active_accelerator_));
21
}

内存对齐优化

在 TextDetector::Impl 中，所有预分配的 buffer 都使用 64 字节对齐：

1
// Pre-allocated buffers with cache-line alignment
2
alignas(64) std::vector<uint8_t> resized_buffer_;
3
alignas(64) std::vector<float> normalized_buffer_;
4
alignas(64) std::vector<uint8_t> binary_map_;
5
alignas(64) std::vector<float> prob_map_;

64 字节对齐是现代 ARM 处理器的缓存行大小。对齐的内存访问可以避免缓存行分裂，提高内存访问效率。

内存池与对象复用

频繁的内存分配和释放是性能杀手。PPOCRv5-Android 使用预分配策略，在初始化时一次性分配所有需要的内存：

1
class TextDetector::Impl {
2
    // 预分配的 buffer，生命周期与 Impl 相同
3
    alignas(64) std::vector<uint8_t> resized_buffer_;      // 640 * 640 * 4 = 1.6MB
4
    alignas(64) std::vector<float> normalized_buffer_;     // 640 * 640 * 3 * 4 = 4.9MB
5
    alignas(64) std::vector<uint8_t> binary_map_;          // 640 * 640 = 0.4MB
6
    alignas(64) std::vector<float> prob_map_;              // 640 * 640 * 4 = 1.6MB
7

8
    bool Initialize(...) {
9
        // 一次性分配，避免运行时 malloc
10
        resized_buffer_.resize(kDetInputSize * kDetInputSize * 4);
11
        normalized_buffer_.resize(kDetInputSize * kDetInputSize * 3);
12
        binary_map_.resize(kDetInputSize * kDetInputSize);
13
        prob_map_.resize(kDetInputSize * kDetInputSize);
14
        return true;
15
    }
16
};

这种设计的好处：

避免内存碎片：所有大块内存在启动时分配，运行时不会产生碎片
减少系统调用：malloc 可能触发系统调用，预分配避免了这一开销
缓存友好：连续分配的内存更可能在物理上连续，提高缓存命中率

分支预测优化

现代 CPU 使用分支预测来提高流水线效率。错误的分支预测会导致流水线刷新，损失 10-20 个时钟周期。

在热路径上，我们使用 __builtin_expect 提示编译器：

1
// 大多数像素不会超过阈值
2
if (__builtin_expect(prob_map[i] > kBinaryThreshold, 0)) {
3
    binary_map_[i] = 255;
4
} else {
5
    binary_map_[i] = 0;
6
}

__builtin_expect(expr, val) 告诉编译器 expr 的值很可能是 val。编译器会据此调整代码布局，将「不太可能」的分支放到远离主路径的位置。

循环展开与软件流水线

对于计算密集型循环，手动展开可以减少循环开销并暴露更多的指令级并行：

1
// 未展开版本
2
for (int i = 0; i < n; ++i) {
3
    dst[i] = src[i] * scale + bias;
4
}
5

6
// 4x 展开版本
7
int i = 0;
8
for (; i + 4 <= n; i += 4) {
9
    dst[i + 0] = src[i + 0] * scale + bias;
10
    dst[i + 1] = src[i + 1] * scale + bias;
11
    dst[i + 2] = src[i + 2] * scale + bias;
12
    dst[i + 3] = src[i + 3] * scale + bias;
13
}
14
for (; i < n; ++i) {
15
    dst[i] = src[i] * scale + bias;
16
}

展开后，CPU 可以同时执行多条独立的乘加指令，充分利用超标量架构的多个执行单元。

Prefetch 优化

在透视变换的内层循环中，使用 __builtin_prefetch 提前加载下一行的数据：

1
for (int dy = 0; dy < kRecInputHeight; ++dy) {
2
    // 预取下一行数据
3
    if (dy + 1 < kRecInputHeight) {
4
        const float next_sy = y0 + a11 * (dy + 1);
5
        const int next_y = static_cast<int>(next_sy);
6
        if (next_y >= 0 && next_y < height) {
7
            __builtin_prefetch(image_data + next_y * stride, 0, 1);
8
        }
9
    }
10
    // ... 处理当前行
11
}

这种优化可以隐藏内存延迟，在处理当前行时，下一行的数据已经在 L1 缓存中了。

后处理的工程细节

连通域分析与轮廓检测

在 postprocess.cpp 中，FindContours 函数实现了高效的连通域分析：

1
std::vector<std::vector<Point>> FindContours(const uint8_t *binary_map,
2
                                             int width, int height) {
3
    // 1. 4x 降采样减少计算量
4
    int ds_width = (width + kDownsampleFactor - 1) / kDownsampleFactor;
5
    int ds_height = (height + kDownsampleFactor - 1) / kDownsampleFactor;
6

7
    std::vector<uint8_t> ds_map(ds_width * ds_height);
8
    downsample_binary_map(binary_map, width, height,
9
                          ds_map.data(), ds_width, ds_height, kDownsampleFactor);
10

11
    // 2. BFS 遍历连通域
12
    std::vector<int> labels(ds_width * ds_height, 0);
13
    int current_label = 0;
14

15
    for (int y = 0; y < ds_height; ++y) {
16
        for (int x = 0; x < ds_width; ++x) {
17
            if (pixel_at(ds_map.data(), x, y, ds_width) > 0 &&
18
                labels[y * ds_width + x] == 0) {
19
                current_label++;
20
                std::vector<Point> boundary;
21
                std::queue<std::pair<int, int>> queue;
22
                queue.push({x, y});
23

24
                while (!queue.empty()) {
25
                    auto [cx, cy] = queue.front();
26
                    queue.pop();
27

28
                    // 检测边界像素
29
                    if (is_boundary_pixel(ds_map.data(), cx, cy, ds_width, ds_height)) {
30
                        boundary.push_back({
31
                            static_cast<float>(cx * kDownsampleFactor + kDownsampleFactor / 2),
32
                            static_cast<float>(cy * kDownsampleFactor + kDownsampleFactor / 2)
33
                        });
34
                    }
35

36
                    // 4-邻域扩展
37
                    for (int d = 0; d < 4; ++d) {
38
                        int nx = cx + kNeighborDx4[d];
39
                        int ny = cy + kNeighborDy4[d];
40
                        // ...
41
                    }
42
                }
43

44
                if (boundary.size() >= 4) {
45
                    contours.push_back(std::move(boundary));
46
                }
47
            }
48
        }
49
    }
50
    return contours;
51
}

关键优化点：

4x 降采样：将 640x640 的二值图降采样到 160x160，减少 16 倍的计算量
边界检测：只保留边界像素，而不是整个连通域
最大轮廓数限制：kMaxContours = 100，防止极端情况下的性能问题

凸包与旋转卡壳算法

最小外接旋转矩形的计算分为两步：首先计算凸包，然后使用旋转卡壳算法找到最小面积的外接矩形。

Graham Scan 凸包算法

Graham Scan 是计算凸包的经典算法，时间复杂度 $O(n \log n)$ ：

1
std::vector<Point> ConvexHull(std::vector<Point> points) {
2
    if (points.size() < 3) return points;
3

4
    // 1. 找到最下方的点（y 最小，x 最小）
5
    auto pivot = std::min_element(points.begin(), points.end(),
6
        [](const Point& a, const Point& b) {
7
            return a.y < b.y || (a.y == b.y && a.x < b.x);
8
        });
9
    std::swap(points[0], *pivot);
10
    Point p0 = points[0];
11

12
    // 2. 按极角排序
13
    std::sort(points.begin() + 1, points.end(),
14
        [&p0](const Point& a, const Point& b) {
15
            float cross = CrossProduct(p0, a, b);
16
            if (std::abs(cross) < 1e-6f) {
17
                // 共线时，距离近的排前面
18
                return DistanceSquared(p0, a) < DistanceSquared(p0, b);
19
            }
20
            return cross > 0;  // 逆时针方向
21
        });
22

23
    // 3. 构建凸包
24
    std::vector<Point> hull;
25
    for (const auto& p : points) {
26
        // 移除导致顺时针转向的点
27
        while (hull.size() > 1 &&
28
               CrossProduct(hull[hull.size()-2], hull[hull.size()-1], p) <= 0) {
29
            hull.pop_back();
30
        }
31
        hull.push_back(p);
32
    }
33

34
    return hull;
35
}
36

37
// 叉积：判断转向方向
38
float CrossProduct(const Point& o, const Point& a, const Point& b) {
39
    return (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
40
}

旋转卡壳算法

旋转卡壳（Rotating Calipers）算法遍历凸包的每条边，计算以该边为底的外接矩形面积：

1
RotatedRect MinAreaRect(const std::vector<Point>& hull) {
2
    if (hull.size() < 3) return {};
3

4
    float min_area = std::numeric_limits<float>::max();
5
    RotatedRect best_rect;
6

7
    int n = hull.size();
8
    int right = 1, top = 1, left = 1;  // 三个「卡壳」的位置
9

10
    for (int i = 0; i < n; ++i) {
11
        int j = (i + 1) % n;
12

13
        // 当前边的方向向量
14
        float edge_x = hull[j].x - hull[i].x;
15
        float edge_y = hull[j].y - hull[i].y;
16
        float edge_len = std::sqrt(edge_x * edge_x + edge_y * edge_y);
17

18
        // 单位向量
19
        float ux = edge_x / edge_len;
20
        float uy = edge_y / edge_len;
21

22
        // 垂直方向
23
        float vx = -uy;
24
        float vy = ux;
25

26
        // 找到最右点（沿边方向投影最大）
27
        while (Dot(hull[(right + 1) % n], ux, uy) > Dot(hull[right], ux, uy)) {
28
            right = (right + 1) % n;
29
        }
30

31
        // 找到最上点（沿垂直方向投影最大）
32
        while (Dot(hull[(top + 1) % n], vx, vy) > Dot(hull[top], vx, vy)) {
33
            top = (top + 1) % n;
34
        }
35

36
        // 找到最左点
37
        while (Dot(hull[(left + 1) % n], ux, uy) < Dot(hull[left], ux, uy)) {
38
            left = (left + 1) % n;
39
        }
40

41
        // 计算矩形尺寸
42
        float width = Dot(hull[right], ux, uy) - Dot(hull[left], ux, uy);
43
        float height = Dot(hull[top], vx, vy) - Dot(hull[i], vx, vy);
44
        float area = width * height;
45

46
        if (area < min_area) {
47
            min_area = area;
48
            // 更新最优矩形参数
49
            best_rect.width = width;
50
            best_rect.height = height;
51
            best_rect.angle = std::atan2(uy, ux) * 180.0f / M_PI;
52
            // 计算中心点...
53
        }
54
    }
55

56
    return best_rect;
57
}

旋转卡壳的关键洞察是：当底边旋转时，三个「卡壳」（最右、最上、最左点）只会单调前进，不会后退。因此总时间复杂度是 $O(n)$ ，而非 $O(n^2)$ 。

最小外接旋转矩形

MinAreaRect 函数使用旋转卡壳算法计算最小外接旋转矩形：

1
RotatedRect MinAreaRect(const std::vector<Point> &contour) {
2
    // 1. 子采样减少点数
3
    std::vector<Point> points = subsample_points(contour, kMaxBoundaryPoints);
4

5
    // 2. 快速路径：高宽高比的文本框直接使用 AABB
6
    float aspect = std::max(aabb_width, aabb_height) /
7
                   std::max(1.0f, std::min(aabb_width, aabb_height));
8
    if (aspect > 2.0f && points.size() > 50) {
9
        // 直接返回轴对齐边界框
10
        RotatedRect rect;
11
        rect.center_x = (min_x + max_x) / 2.0f;
12
        rect.center_y = (min_y + max_y) / 2.0f;
13
        rect.width = aabb_width;
14
        rect.height = aabb_height;
15
        rect.angle = 0.0f;
16
        return rect;
17
    }
18

19
    // 3. 凸包计算
20
    std::vector<Point> hull = convex_hull(std::vector<Point>(points));
21

22
    // 4. 旋转卡壳：遍历凸包的每条边
23
    float min_area = std::numeric_limits<float>::max();
24
    RotatedRect best_rect;
25

26
    for (size_t i = 0; i < hull.size(); ++i) {
27
        // 以当前边为基准，计算外接矩形
28
        float edge_x = hull[j].x - hull[i].x;
29
        float edge_y = hull[j].y - hull[i].y;
30

31
        // 投影所有点到边的方向和垂直方向
32
        project_points_onto_axis(hull, axis1_x, axis1_y, min1, max1);
33
        project_points_onto_axis(hull, axis2_x, axis2_y, min2, max2);
34

35
        float area = (max1 - min1) * (max2 - min2);
36
        if (area < min_area) {
37
            min_area = area;
38
            // 更新最优矩形
39
        }
40
    }
41

42
    return best_rect;
43
}

这个算法的时间复杂度是 $O(n log n)$ （凸包计算）+ $O(n)$ （旋转卡壳），其中 $n$ 是边界点数量。通过子采样将 $n$ 限制在 200 以内，确保了实时性能。

实时相机 OCR：CameraX 与帧分析

实时 OCR 的挑战在于：如何在保持流畅预览的同时，尽可能快地处理每一帧？

1
flowchart TB
2
    subgraph Camera["CameraX Pipeline"]
3
        direction TB
4
        CP[CameraProvider]
5
        PV[Preview UseCase<br/>30 FPS]
6
        IA[ImageAnalysis UseCase<br/>STRATEGY_KEEP_ONLY_LATEST]
7
    end
8

9
    subgraph Analysis["帧分析流程"]
10
        direction TB
11
        IP[ImageProxy<br/>YUV_420_888]
12
        BM[Bitmap 转换<br/>RGBA_8888]
13
        JNI[JNI 调用<br/>单次跨语言]
14
    end
15

16
    subgraph Native["Native OCR"]
17
        direction TB
18
        DET[TextDetector<br/>~45ms GPU]
19
        REC[TextRecognizer<br/>~15ms/行]
20
        RES[OCR Results]
21
    end
22

23
    subgraph UI["UI 更新"]
24
        direction TB
25
        VM[ViewModel<br/>StateFlow]
26
        OV[ResultOverlay<br/>Canvas 绘制]
27
    end
28

29
    CP --> PV
30
    CP --> IA
31
    IA --> IP --> BM --> JNI
32
    JNI --> DET --> REC --> RES
33
    RES --> VM --> OV

CameraX 的 ImageAnalysis

CameraX 是 Android Jetpack 的相机库，它提供了 ImageAnalysis 用例，允许我们对相机帧进行实时分析：

1
val imageAnalysis = ImageAnalysis.Builder()
2
    .setTargetResolution(Size(1280, 720))
3
    .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
4
    .build()
5

6
imageAnalysis.setAnalyzer(executor) { imageProxy ->
7
    val bitmap = imageProxy.toBitmap()
8
    val result = ocrEngine.process(bitmap)
9
    // 更新 UI
10
    imageProxy.close()
11
}

关键配置是 STRATEGY_KEEP_ONLY_LATEST：当分析器处理速度跟不上相机帧率时，丢弃旧帧，只保留最新帧。这确保了 OCR 结果的时效性。

帧率与延迟的权衡

在 GPU 加速的设备上（我目前手上的骁龙 870 似乎有问题，始终无法做到把大部分计算交给 GPU 加速），PPOCRv5-Android 理论可以达到较高的处理速度。但这并不意味着我们应该处理每一帧。

考虑这样一个场景：用户将相机对准一段文字，文字内容在短时间内不会变化。如果我们每帧都进行完整的 OCR，会浪费大量计算资源。

一个优化策略是「变化检测」：只有当画面发生显著变化时，才触发 OCR。这可以通过比较连续帧的直方图或特征点来实现。

未来展望：NPU 与量化

端侧 AI 的未来在于 NPU（Neural Processing Unit）。与 GPU 相比，NPU 专为神经网络推理设计，能效比更高。

但 NPU 的挑战在于碎片化。每个芯片厂商都有自己的 NPU 架构和 SDK：

高通：Hexagon DSP + AI Engine
联发科：APU
三星：Exynos NPU
Google：Tensor TPU

Android 的 NNAPI（Neural Networks API）试图提供统一的抽象层，但实际效果参差不齐。许多 NPU 功能无法通过 NNAPI 暴露，开发者不得不使用厂商特定的 SDK。

INT8 量化：一场未竟的战役

FP16 量化是一个保守的选择，它几乎不损失精度。但如果追求极致性能，INT8 量化是下一步。

INT8 量化将权重和激活从 32 位浮点压缩到 8 位整数，理论上可以带来：

4 倍的模型压缩
2-4 倍的推理加速（取决于硬件）
在高通 Hexagon DSP 上可实现 10 倍以上的加速

这个诱惑太大了。于是我开始了一段漫长的 INT8 量化之旅。

第一次尝试：合成数据校准

INT8 量化需要校准数据集来确定量化参数（Scale 和 Zero Point）。最初，我偷懒使用了随机生成的「类文字」图像：

1
# 错误示范：使用随机噪声做校准
2
img = np.ones((h, w, 3), dtype=np.float32) * 0.9
3
for _ in range(num_lines):
4
    gray_val = np.random.uniform(0.05, 0.3)
5
    img[y:y+line_h, x:x+line_w] = gray_val

结果是灾难性的。模型输出全为 0：

Raw FLOAT32 output range: min=0.0000, max=0.0000
Prob map stats: min=0.0000, max=0.0000, mean=0.000000

量化工具根据随机噪声计算出了错误的量化参数，导致真实图像的激活值被截断。

第二次尝试：真实图片校准

我改用真实的 OCR 数据集图片：ICDAR2015、TextOCR、PaddleOCR 官方示例图。同时实现了 Letterbox 预处理，确保校准时的图像分布与推理时一致：

1
def letterbox_image(image, target_size):
2
    """保持长宽比缩放，不足部分填充灰色"""
3
    ih, iw = image.shape[:2]
4
    h, w = target_size
5
    scale = min(w / iw, h / ih)
6
    # ... 居中粘贴

模型不再输出全 0，但识别结果仍然是乱码。

第三次尝试：修复 C++ 端的类型处理

我发现 C++ 代码在处理 INT8 输入时存在问题。INT8 模型期望的是原始像素值（0-255），而我还在做 ImageNet 归一化（减均值除方差）。

1
if (input_is_int8_) {
2
    // INT8 模型：直接输入原始像素，归一化已融合到第一层
3
    dst[i * 3 + 0] = static_cast<int8_t>(src[i * 4 + 0] ^ 0x80);
4
} else {
5
    // FP32 模型：需要手动归一化
6
    // (pixel - mean) / std
7
}

同时，我实现了动态读取量化参数的逻辑，而不是硬编码：

1
bool GetQuantizationParams(LiteRtTensor tensor, float* scale, int32_t* zero_point) {
2
    LiteRtQuantization quant;
3
    LiteRtGetTensorQuantization(tensor, &quant);
4
    // ...
5
}

最终结果：妥协

经过数天的调试，INT8 模型仍然无法正常工作。问题可能出在：

onnx2tf 的量化实现：PP-OCRv5 使用了一些特殊的算子组合，onnx2tf 在量化时可能没有正确处理
DBNet 的输出特性：DBNet 输出的是概率图，值域在 0-1 之间，INT8 量化对这种小范围值特别敏感
多阶段模型的误差累积：检测和识别两个模型串联，量化误差会累积放大

让我们深入分析第二点。DBNet 的输出经过 Sigmoid 激活，值域被压缩到 [0, 1]。INT8 量化使用以下公式：

$x_{quantized} = \text{round}\left(\frac{x_{float}}{scale}\right) + zero\_point$

对于 [0, 1] 范围的值，如果 scale 设置不当，量化后的值可能只占用 INT8 范围 [-128, 127] 的一小部分，导致严重的精度损失。

1
# 假设 scale = 0.00784 (1/127), zero_point = 0
2
# 输入 0.5 -> round(0.5 / 0.00784) + 0 = 64
3
# 输入 0.1 -> round(0.1 / 0.00784) + 0 = 13
4
# 输入 0.01 -> round(0.01 / 0.00784) + 0 = 1
5
# 输入 0.001 -> round(0.001 / 0.00784) + 0 = 0  # 精度丢失！

DBNet 的阈值通常设为 0.1-0.3，这意味着大量有意义的概率值（0.1-0.3）在量化后只能用 13-38 这 25 个整数表示，分辨率严重不足。

WARNING

PP-OCRv5 的 INT8 量化是一个已知的难题。如果你也在尝试，建议先确认 FP32 模型能正常工作，再逐步排查量化问题。或者，考虑使用 PaddlePaddle 官方的 Paddle Lite 框架，它对 PaddleOCR 的支持更好。

量化感知训练：正确的解决方案

如果必须使用 INT8 量化，正确的方法是量化感知训练（Quantization-Aware Training, QAT），而非训练后量化（Post-Training Quantization, PTQ）。

QAT 在训练过程中模拟量化误差，让模型学会适应低精度表示：

1
# PyTorch QAT 示例
2
import torch.quantization as quant
3

4
model = DBNet()
5
model.qconfig = quant.get_default_qat_qconfig('fbgemm')
6
model_prepared = quant.prepare_qat(model)
7

8
# 正常训练，但前向传播中插入了伪量化节点
9
for epoch in range(num_epochs):
10
    for images, labels in dataloader:
11
        outputs = model_prepared(images)  # 包含量化模拟
12
        loss = criterion(outputs, labels)
13
        loss.backward()
14
        optimizer.step()
15

16
# 转换为真正的量化模型
17
model_quantized = quant.convert(model_prepared)

遗憾的是，PP-OCRv5 官方没有提供 QAT 训练的模型。这意味着要获得高质量的 INT8 模型，需要从头进行 QAT 训练，这超出了本项目的范围。

最终，我选择了妥协：使用 FP16 量化 + GPU 加速，而不是 INT8 + DSP。

这个决定的代价是：

模型体积是 INT8 的 2 倍
无法利用 Hexagon DSP 的超低功耗
推理速度比理论最优慢 2-3 倍

但收益是：

模型精度与 FP32 几乎一致
开发周期大幅缩短
代码复杂度降低

工程的本质是权衡。有时候，「足够好」比「理论最优」更重要。

结语

从 PaddlePaddle 到 TFLite，从 DBNet 到 SVTRv2，从 OpenCL 到 NEON，端侧 OCR 的工程实践涉及深度学习、编译器、GPU 编程、移动开发等多个领域的知识。

这个项目的核心教训是：端侧 AI 不仅仅是「把模型放到手机上」。它需要：

深入理解模型架构，才能正确转换
熟悉硬件特性，才能充分利用加速器
掌握系统编程，才能实现高性能原生代码
关注用户体验，才能在性能和功耗之间找到平衡

PPOCRv5-Android 是一个开源项目，它展示了如何将现代的 OCR 模型部署到实际的移动应用中。希望这篇文章能为有类似需求的开发者提供一些参考。

正如 Google 在 LiteRT 发布时所说：「Maximum performance, simplified.」⁹ 端侧 AI 的目标不是复杂，而是让复杂变得简单。

后话

老实讲，我（在工作与兴趣领域）其实已经淡出 Android 有至少两年了，而这是我首次在 GitHub 小号上（我已经把大号交给了同事，以表我离开的决心）公开一个较为成熟的库。

这些年来我的工作重点其实并不是 Android 领域，具体情况不便透露，但日后有机会会展开讲讲。总之，我或许很难再在 Android 上再多建树了。

这次发布该项目源于我兴趣使然，正构建的一个早期基于 Android 端侧的工具——而 OCR 只是其中底层的一小部分，后期（应该很快了）也将完整开放源代码，暂时也不便透露。

总之，感谢你看到这里，也期待你能给我的仓库点上 Star，感谢！

参考文献

Google AI Edge. “LiteRT: Maximum performance, simplified.” 2024. https://developers.googleblog.com/litert-maximum-performance-simplified/ ↩
PaddleOCR Team. “PaddleOCR 3.0 Technical Report.” arXiv:2507.05595, 2025. https://arxiv.org/abs/2507.05595 ↩
GitHub Discussion. “Problem while deploying the newest official PP-OCRv5.” PaddleOCR #16100, 2025. https://github.com/PaddlePaddle/PaddleOCR/discussions/16100 ↩
Liao, M., et al. “Real-time Scene Text Detection with Differentiable Binarization.” Proceedings of the AAAI Conference on Artificial Intelligence, 2020. https://arxiv.org/abs/1911.08947 ↩
Du, Y., et al. “SVTR: Scene Text Recognition with a Single Visual Model.” IJCAI, 2022. https://arxiv.org/abs/2205.00159 ↩
Du, Y., et al. “SVTRv2: CTC Beats Encoder-Decoder Models in Scene Text Recognition.” ICCV, 2025. https://arxiv.org/abs/2411.15858 ↩ ↩²
TensorFlow Blog. “Even Faster Mobile GPU Inference with OpenCL.” 2020. https://blog.tensorflow.org/2020/08/faster-mobile-gpu-inference-with-opencl.html ↩
ARM Developer. “Neon Intrinsics on Android.” ARM Documentation, 2024. https://developer.arm.com/documentation/101964/latest/ ↩
Google AI Edge. “LiteRT Documentation.” 2024. https://ai.google.dev/edge/litert ↩

mobile/ppocrv5-android.md

# 端侧 OCR 的实践：PP-OCRv5 在 Android 上的原生部署

说明

开篇

模型转换：从 PaddlePaddle 到 TFLite 的漫长旅途

第一道坎：paddle2onnx 的算子兼容性

第二道坎：HardSigmoid 与 GPU 兼容性

第三道坎：Resize 算子的坐标变换模式

最后一步：onnx2tf 与 FP16 量化

文本检测：DBNet 的可微分二值化

标准二值化 vs 可微分二值化

后处理流程的工程实现

Unclip：文本框的膨胀算法

文本识别：SVTRv2 与 CTC 解码

SVTRv2 的架构创新

为什么是 CTC 而不是 Attention？

NEON 优化的 CTC 解码

CTC 损失函数与解码的数学原理

字符字典：18,383 个字符的挑战

LiteRT C++ API：2024 年重构后的现代接口

新旧 API 对比

环境与模型初始化

Managed Tensor Buffer：零拷贝推理的关键

GPU 加速：OpenCL 的选择与权衡

OpenCL vs OpenGL ES：性能深度对比

优雅降级策略

原生层：C++ 与 NEON 优化

NEON：ARM 的 SIMD 指令集

ImageNet 归一化的 NEON 实现

零 OpenCV 依赖

双线性插值的 NEON 实现

透视变换：从旋转矩形到标准文本行

JNI：Kotlin 与 C++ 的桥梁

架构设计：模块化与可测试性

Kotlin 层的封装

冷启动优化

内存对齐优化

内存池与对象复用

分支预测优化

循环展开与软件流水线

Prefetch 优化

后处理的工程细节

连通域分析与轮廓检测

凸包与旋转卡壳算法

Graham Scan 凸包算法

旋转卡壳算法

最小外接旋转矩形

实时相机 OCR：CameraX 与帧分析

CameraX 的 ImageAnalysis

帧率与延迟的权衡

未来展望：NPU 与量化

INT8 量化：一场未竟的战役

第一次尝试：合成数据校准

第二次尝试：真实图片校准

第三次尝试：修复 C++ 端的类型处理

最终结果：妥协

量化感知训练：正确的解决方案

结语

后话

参考文献

Footnotes