企业官网建设流程全解析

简介：面向 iOS 开发者的 Paddle OCR 移动端文字识别完整工程包，适合在文档扫描、图片取词等场景中快速集成免费 OCR 能力的技术人员。压缩包约 151.85MB，共 1107 个文件，包含 576 个 h、195 个 m、192 个 hpp 等源码，以及 Xcode 工程配置、plist/xcconfig、说明文档和图片资源。核心的 libpaddle_api_light_bundled.a 静态库与 ocr_db_post_process.cpp、ocr_crnn_process.cpp 等检测、识别前后处理代码也已一并提供，便于对照工程完成模型加载与二次开发。已有 808 人学习下载；借助该包可省去自行拉取编译的环节，重点理解 iOS 端 Paddle OCR 的工程结构、模型调用方式和预处理调优思路，快速搭建中英文识别应用。

1. iOS端跑通PaddleOCR：先从三段式流水线说起

做过移动端文字识别的开发者大多有同感：在服务端调通一个OCR不难，难的是把它塞进iPhone里，还要在中低端机型上跑出能用的帧率和内存占用。PaddleOCR是目前中文场景下开源方案里综合表现最稳的一套，它落到iOS端并不是直接把Python推理脚本搬过来，而是要经历模型导出、格式转换、端侧串联、后处理复刻这一整条链路。整条链路里最耗时间的往往不是模型本身，而是踩转换和图像处理的坑。

这篇文章从一个做iOS端OCR落地的实际视角出发，把PaddleOCR在移动端的推理流程拆开讲清楚：三段式模型各自做什么、怎么从Paddle格式转到端侧引擎能吃的格式、三套模型的输入输出如何串联、哪些参数真正影响识别率、哪些坑是网上没人明说的。目标读者是手里已经有一堆图片要识别、想在App里塞进OCR能力的iOS开发者和算法工程师。

2. 引擎选型与模型转换链路：从Paddle推理模型到ONNX再到Core ML

2.1 三段式流水线先立住：检测、方向分类、识别各管一段

PaddleOCR在端侧的完整推理由三个模型接力完成。第一个是文本检测模型，输入一整张图，输出所有文本行的四边形坐标；第二个是方向分类模型，对每个检测框单独判断是否需要旋转180度；第三个是文本识别模型，把旋转修正后的裁剪图转成字符串序列。

三个模型必须串行执行，检测框的数量决定了后续要跑多少次分类和识别。常见做法是检测跑一次，分类和识别在检测框上循环执行。这个流程本身不难理解，但到了iOS端会遇到一个现实问题：三个模型分别来自不同的导出文件，推理引擎要能同时加载三套网络，并且输入输出的张量形状必须和端侧代码完全对齐。

我一般把检测模型和识别模型分开看。检测模型输入是整张图，形状通常是1×3×H×W，H和W可以动态变化；识别模型输入是检测框裁剪出来的小图，固定高度、动态宽度。这种差异直接决定了转换时的shape处理策略，后面章节会具体展开。

2.2 为什么转ONNX是端侧部署的最稳路径

很多人第一反应是找Paddle官方提供的移动端推理库。实际做下来会发现，那个库在iOS上的维护状态已经不太跟得上新版本模型了，算子支持、位宽、内存管理都有历史包袱。社区里做iOS部署的主流路径是先把推理模型转成ONNX，再用ONNX Runtime的C++接口直接跑，或者再转成Core ML格式交给Apple框架加载。

先把结论说出来：我推荐ONNX Runtime方案，而不是Core ML方案。原因是Core ML的算子覆盖和动态shape支持在OCR这类输入尺寸频繁变化的场景里很容易翻车，每换一个模型版本就可能遇到不支持的算子。ONNX Runtime的iOS支持相对稳定，对动态shape的处理也更接近直觉。当然代价是要自己管理输入输出缓冲区和后处理内存，不过这部分本来就是端侧OCR工程化的必修课。

模型转换链路如下：先从PaddleOCR仓库里导出inference model，得到一个模型结构文件和一个参数文件；然后用paddle2onnx把这两个文件合并成一个ONNX文件；如果坚持用Core ML，再用coremltools把ONNX转成mlmodel或mlpackage。每一步都有参数要确认，核心是opset版本和输入shape。

2.3 用paddle2onnx导出ONNX：命令与三个必设参数

导出命令本身不复杂，容易出问题的是参数。常见的导出做法如下，注意det模型和rec模型输入形状的差异：

# 文本检测模型：动态shape，长边不超过960，短边不小于480 paddle2onnx \ --model_dir ./inference/det \ --model_filename inference.pdmodel \ --params_filename inference.pdiparams \ --save_file ./onnx/det.onnx \ --opset_version 11 \ --input_shape_dict "{'x':[-1,3,-1,-1]}" # 文本识别模型：固定高度48，宽度动态 paddle2onnx \ --model_dir ./inference/rec \ --model_filename inference.pdmodel \ --params_filename inference.pdiparams \ --save_file ./onnx/rec.onnx \ --opset_version 11 \ --input_shape_dict "{'x':[-1,3,48,-1]}"

第一个必设参数是opset_version，端侧ONNX Runtime对低版本opset支持得更好，11到13之间都有人用，我个人习惯锁在11，兼容性最省心。第二个是input_shape_dict，det模型的高宽都留成-1表示动态，rec模型把高固定成48，宽度留动态。第三个容易被忽略——输入的张量名，Paddle导出的输入名通常是x，但不同版本模型可能改名，转换前先打印一遍模型输入名，错了会报shape mismatch。

参数说明：动态shape意味着端侧推理时可以按实际图片宽高传入任意尺寸，但受限于模型本身的缩放倍数，宽高必须是32的整数倍才能被完整下采样。不是整数倍时图像边缘会有信息丢失，后面会讲怎么处理。

2.4 coremltools转换：能转但不建议用于检测模型

如果项目里已经重度依赖Core ML，转换命令也能跑通。核心做法是先转成ONNX再交给coremltools，关键一步是给每个输入指定确定的shape或EnumeratedShapes集合：

import coremltools as ct # 识别模型转换：宽度给一组枚举值，避免动态shape报错 model = ct.convert( "rec.onnx", convert_to="mlprogram", minimum_ios_deployment_target="15.0", compute_precision=ct.precision.FLOAT16, ) model.save("rec.mlpackage")

枚举shape的做法是把常见的识别宽度列出来，比如每32像素一个档位，从64到640全列进去。能转成功不代表能用，检测模型在Core ML上转完经常遇到动态shape支持缺陷，输入图稍微大一点就报错。我的经验是：识别模型用Core ML问题不大，检测模型老老实实走ONNX Runtime全流程，别两头折腾。

3. 检测、方向分类、识别三模型串联：iOS端工程实现

3.1 图片预处理：BGR/RGB顺序、归一化、letterbox三件事

iOS端拿到的图像通常是UIImage或CVPixelBuffer，PaddleOCR训练时用的是OpenCV的BGR顺序和特定归一化参数。常见做法是在预处理阶段先通过vImage或OpenCV把图像转成RGB或BGR的raw buffer，再做归一化，最后按模型要求resize。通道顺序错了是最隐蔽的坑，因为识别结果不会全错，只是精度莫名其妙掉几个点。

归一化参数需要严格对齐模型训练时的配置。旧版PP-OCR模型用ImageNet的均值和方差，新版本统一改成0.5均值0.5方差。填错一套参数，检测框还在，但识别结果会明显变差，而且这种问题用肉眼很难定位。

letterbox逻辑在处理宽高比差异大的图片时必须用。直接resize会把文字压扁，检测模型对这种形变非常敏感。做法是先按比例把长边缩到目标尺寸，短边补白到32的整数倍，白边填充的像素值用归一化后的均值0.5。补白相当于告诉模型“这里没内容”，比直接拉伸靠谱得多。

3.2 检测模型推理与DB后处理：从概率图到文本框

检测模型输出不是直接的框坐标，而是一个和输入等尺寸的概率图（probability map）。要拿到坐标必须复刻PaddleOCR的DB后处理逻辑，这一步很多人直接用简化版，导致框的准确度打折。完整后处理包含以下步骤：先对概率图做二值化，阈值一般在0.3附近；然后对二值图做轮廓查找；对每个轮廓求最小外接矩形；最后用unclip操作向外扩展矩形边界，扩展比例det_db_unclip_ratio默认1.5。

iOS端实现这段逻辑一般是先解出每个像素的score，再对score图做轮廓分析。OpenCV在iOS上可以用pod集成，轮廓查找和minAreaRect直接调C++接口，性能和稳定性都比自己造轮子好。需要注意概率图的尺寸和原图尺寸的对应关系，检测模型内部有下采样，输出概率图通常比输入小，直接用会得到偏移的框。

后处理完整代码如下，核心是contour和minAreaRect的组合：

// det后处理：从概率图得到文本框 cv::Mat binary_map; cv::threshold(prob_map, binary_map, 0.3, 255, cv::THRESH_BINARY); std::vector<std::vector<cv::Point>> contours; cv::findContours(binary_map, contours, cv::RETR_LIST, cv::CHAIN_APPROX_SIMPLE); std::vector<std::vector<cv::Point2f>> boxes; for (auto &contour : contours) { double area = cv::contourArea(contour); if (area < 10) continue; // 过滤噪声小框 cv::RotatedRect rect = cv::minAreaRect(contour); cv::Point2f vertices[4]; rect.points(vertices); std::vector<cv::Point2f> box(vertices, vertices + 4); // unclip扩展：按周长比例向外扩 boxes.push_back(box); }

这段代码里threshold的0.3对应det_db_thresh，area小于10的过滤条件是按经验加的，去掉后会出现大量噪声框。unclip操作在iOS端一般用扩大轮廓点的scale实现，捷径是调用cv::minAreaRect后直接把rect的width和height乘以1.5，效果接近但和Python端实现略有差异。建议在批量测试时用Python端跑一批图和端侧对比框坐标，差异过大的时候再逐段比后处理。

3.3 方向分类与识别：CTC解码与坐标映射回原图

拿到检测框后，按框的四个角点做透视变换，把框内文字裁正，裁剪图喂给方向分类模型。方向分类的输出是一个长度为2的概率向量，索引0表示不需要旋转，索引1表示需要旋转180度。这里有个常见的坑：部分模型版本的标签顺序是反的，上线前必须拿竖排和倒置的样张各验证一遍。

方向分类修正后，裁剪图进入识别模型。识别模型输出的是序列概率，要经过CTC解码才变成文本。解码规则是：沿时间步取最大概率索引，先去除相邻重复，再去除blank位。正则表达式简化描述为“去重去blank”，实际实现时注意CTC的去重是按相邻重复处理，不相邻的重复字要保留。比如“好好学学”在输出序列里如果分成两段出现，合并时不能把两个“好”合成一个。

坐标映射是串联环节里最容易乱的一步。检测模型输入的是缩放后的letterbox图，检测框坐标也是在这个坐标系下的，要映射回原图需要先去掉letterbox的偏移，再除以缩放比例。识别结果对应的是裁剪图，不需要映射回原图，但裁剪图必须保证从原图或letterbox图上取像素，不能从检测模型的概率图上取。

映射回原图的代码实现如下，注意偏移和缩放顺序不能反：

// 从letterbox坐标系映射回原图坐标系 // scale: 原图到letterbox图的缩放比例 // offset: letterbox在长边方向上的补白偏移 CGPoint mapToOriginal(CGPoint p, CGFloat scale, CGFloat offset) { return CGPointMake( (p.x - offset) / scale, (p.y - offset) / scale ); }

参数说明：scale和offset在预处理阶段算好存下来，分析检测框时统一用这组参数做逆变换。如果检测框坐标和原图对不上，八成是offset方向搞错或者漏了letterbox补白的那一段。

4. 让识别率过线的关键参数与调试点

4.1 检测阈值DB的三个关键参数

检测模型的召回和精度直接由后处理阈值控制，这三个参数是调识别率首先要碰的：det_db_thresh控制二值化阈值，默认0.3，调低能召回更多弱文本但噪声框变多；det_db_box_thresh控制框的置信度过滤，默认0.5，调低会保留更多低分框但容易把背景纹理当成文字；det_unclip_ratio控制框向外扩展比例，默认1.5，调大框范围变大，裁剪图包含更多上下文，识别有时反而更准。

这三个参数在服务端和端侧的调法不完全一样。端侧要优先考虑框的位置准确度，因为框偏了直接导致识别内容错位。我在端侧的习惯是det_db_box_thresh比服务端调高0.1到0.2，宁可漏掉一些模糊文字，也不要让框大面积飘移。det_unclip_ratio在中文场景下1.5够用，英文或数字场景可以降到1.3，因为英文字符间距更小，扩太宽容易把旁边字符包进来。

4.2 识别模型输入宽度与字符集

识别模型的输入宽度决定了它能“看”多长的文字。固定高度48，宽度动态，但宽度越大推理耗时越高。常见做法是限制宽度上限320或480，超过上限按比例缩小，同时为了保证高度不变，需要等比例缩放裁剪图而不是直接拉伸。宽度上限调低会省耗时，但长文本会被压缩丢细节，识别率肉眼可见下降。

字符集同样要确认对齐。PaddleOCR官方中文模型自带一个中文字典，但如果你接入的是按业务场景微调过的模型，必须使用配套字典文件。字典顺序直接影响CTC解码结果，字典错位会导致识别结果和业务预期完全对不上。验证方法很简单：拿一张内容固定的测试图，往复识别十次，结果稳定但内容不对，优先怀疑字典。

4.3 并发与内存：把延迟压到单帧300ms以内

三模型串行意味着一条文本线的总延迟是检测时间加上n次分类识别时间。要压低延迟，优先要控制的是并行粒度。常见做法是后端并发处理多个检测框的识别任务，框之间互不依赖，可以用并发队列同时跑四到八个识别任务。注意控制并发数，太多会造成CPU吃满反而更慢。

内存是个更容易被忽视的点。每帧图像从CVPixelBuffer转成模型输入buffer，转完如果不显式释放，内存会持续上升。iOS端处理图像的循环里要包autoreleasepool，并且尽量复用已经申请好的输入输出buffer，避免每帧都malloc新内存。跑一轮完整流程后内存增量控制在几MB内是正常水平，持续上涨说明有对象在泄漏。

调参阶段建议先每个模型独立测试。单独调det模型只看框的准确性，单独调rec模型用固定的裁剪图做输入。先定位是哪个阶段的问题，再动对应参数，否则三个模型混在一起试错，改了半天不知道是哪个参数起的作用。

5. iOS端PaddleOCR部署常见问题排查：5个踩坑记录

5.1 识别率整体偏低但检测框正常

现象：框得准，文字内容却错得一塌糊涂，中英文都乱。

原因：通常是预处理阶段通道顺序和归一化参数没对齐。最常见的是用UIImage CGImage转出的数据是RGBA顺序，模型要的却是RGB或BGR，通道顺序错位后模型输入的分布被打乱。

解决：打印预处理后的像素值和Python端预处理脚本的像素值逐一对比。用一张纯色图做输入，对比同一位置的三个通道数值，立刻能看到顺序对不对。归一化参数也要同步核对，新版模型用0.5均值0.5方差，旧版是三个通道各自的均值方差，混用会出莫名其妙的结果。

5.2 竖排文字完全识别不对

现象：横排文字没问题，竖排文字输出乱码或者顺序颠倒。

原因：方向分类模型对竖排的判定不稳定，或者裁出来的框本身就包含两侧排列的字符，误旋转了180度后内容直接乱掉。

解决：先确认是分类问题还是识别问题。把检测框保存成图片看旋转后的结果，如果旋转后是倒着的，就是CLS输出反了；如果旋转后文字方向正确但内容乱，是识别模型对竖排支持不够。前者在业务场景里可以按框宽高比判断，宽小于高时强制不旋转；后者需要针对竖排样本微调识别模型，仅靠后处理救不回来。

5.3 检测框在图片边缘处偏移严重

现象：图片四角区域的文字框位置不准，框出来的内容和实际文字有明显位移。

原因：letterbox补白导致的坐标偏移映射错误，或者模型输入尺寸在32对齐时做了拉伸，边缘区域的图像形变被放大了。

解决：先检查映射回原图的公式里是否去掉了letterbox的偏移量，这一步错得最多。然后检查预处理时是否严格做了等比缩放，如果用了直接resize，改成等比缩放加补白。边缘区域的框偏移还有个原因是检测模型在训练时的图像增强方式，推理时输入尺寸和训练尺寸差太远，边缘感受野不足，可以尝试把检测输入短边下限从480提到640。

5.4 内存持续上涨，最终被系统杀掉

现象：反复识别多张图后App内存越占越高，最后崩溃闪退。

原因：图像转换过程中的中间buffer没有释放，或者autoreleasepool的作用域没覆盖到图片处理循环。CVPixelBuffer转cv::Mat之后再转模型输入，多轮转换中间对象没释放。

解决：把每帧处理的完整逻辑包进@autoreleasepool块里，所有临时的图像对象设置为autorelease。复用固定的输入输出张量内存，避免每帧重新申请。另外检查是不是把整张高清原图一直持有，裁剪图使用完毕后要立即释放引用。处理完一张图后内存涨20MB以上偏多，5MB以内算正常。

5.5 同一张图两次识别结果不一致

现象：同一张图、同一模型、同一设备，多次识别结果偶尔不一样。

原因：大概率不是模型问题，而是输入图像经过了有损压缩或未对齐的resize。UIImage的scale属性或Orientation不一致时，同一张UIImage传给预处理拿到的像素数据不同。另一种可能是并发识别时共享了同一块输入缓冲区，相互覆盖。

解决：预处理前统一把图像转换为标准RGBA或BGR的raw buffer，转换过程中指定像素格式和方向，不能依赖UIImage的隐式处理。并发识别时为每个任务分配独立的输入输出缓冲，或者串行执行识别循环。

6. 一个提精度的实用技巧：与Python端基线对齐

端侧OCR调参最怕的就是“感觉识别率还行但不知道差在哪”。我目前在项目里保持的习惯是：每调整一轮参数，都用同一批测试图在Python端跑一遍官方推理脚本，把端侧结果和Python端结果逐图对比。Python端跑得更准说明模型转换没问题，问题出在端侧前后处理；两端结果一样差说明模型本身能力到顶了，该换模型或加训练数据。

具体的对齐做法是把一套测试图分为两组：一组是包含完整文档的单页图，用来对比端到端效果；另一组是预先裁好的单行文本图，只测识别模型。单行文本图不需要跑检测，直接测转换后模型的CTG解码结果，定位问题更精准。对齐时关注三个指标：检测框的IOU一致性、识别文本的字符准确率、单帧延迟。IOU差异大优先检查坐标映射和unclip参数，字符准确率差异大优先检查预处理和字典顺序。

这个习惯帮过我一次大忙。某次端侧识别率掉了三个点，排查了两天找不到原因，最后把同一张图在两端分别打印预处理后的数值，发现是iOS端把图像缩放到模型输入尺寸时用了固定尺寸拉伸，而Python端用了等比缩放加补白。换了预处理方式后精度立刻追平。从那以后我给自己定了一条规矩：端侧任何预处理改动，必须先过基线对比这关，不同时改两个变量，改完必须跑同一套回归图。希望这个习惯也能帮到你，至少能少走我走过的弯路。

本文还有配套的精品资源，点击获取