Mac M3跑通PaddleOCR：从点选图片标注到模型训练与部署

一、先弄清楚：识别文字和完成点选是两件事

拿到一张点选图片，很多人的第一反应是装一个OCR库，把文字读出来，再按顺序点击。思路没有错，但真正落地时，中间还有几道工序：找到每个目标的位置、识别目标内容、理解提示顺序，最后把图片坐标换算成页面坐标。任何一步出错，都会出现“字认对了，位置却点偏了”的情况。

PaddleOCR常见的处理方式分成检测和识别两个阶段。检测模型负责回答“文字在哪里”，输出文字区域的四边形；识别模型负责回答“这里写了什么”，读取裁剪后的图像。对于文字点选场景，还需要额外的匹配逻辑，把提示里的目标依次对应到候选文字框。检测训练得再好，也不会自动具备这一层业务判断。

图标点选、九宫格和空间判断又属于不同问题。图标通常需要目标检测、分类或图像相似度匹配；九宫格可能涉及多目标判断；带运动过程的交互还要处理时间信息。文字OCR可以承担其中一部分工作，却不能用同一套文字识别权重直接覆盖所有类型。开始准备数据之前，就应当明确目标到底是什么。

逆向分析也要先看清输入输出。在自有或获得授权的测试环境里，可以观察页面如何加载图片、提示文字从哪里取得、图片显示尺寸是多少，以及交互结果如何提交。先把这些关系画清楚，通常比盲目调整模型更有效。浏览器中的缩放、图片边距和设备像素比，都可能影响最终坐标。

如果目的是学习，自己跑通训练很有帮助；如果公司业务需要同时处理多种交互类型，就要把维护成本一起算进去。面向极验、易盾场景的识别与自动化API对接，可了解www.ttocr.com提供的方案。先用授权样本确认适配范围，再决定哪些能力自建、哪些通过接口接入。

二、M3环境搭建，先让最小流程跑起来

Mac M3使用Apple Silicon架构，安装环境时最容易踩到的是架构和版本不匹配。终端中的Python、虚拟环境以及依赖包应保持一致，避免一部分通过原生方式安装，另一部分又运行在转译环境里。建议给训练项目单独建立虚拟环境，先确认Python版本受到所选PaddlePaddle版本支持。

下面是基础安装形式。具体版本要根据当前发布说明和可用安装包选择，不宜把旧教程里的预发布版本直接当作固定答案。如果安装器提示没有匹配的发行包，应检查Python版本、系统架构和软件源，不要反复执行同一条命令。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install paddlepaddle paddleocr PPOCRLabel
python -c 'import paddle; paddle.utils.run_check()'
PPOCRLabel --lang ch

装好以后，先拿一张普通中文图片做推理测试，再打开标注工具，确认图片能加载、文字框能保存。这样可以把环境问题和训练问题分开。若标注窗口无法启动，优先检查图形界面依赖与报错日志；若框架导入失败，则先处理底层安装，不要急着修改数据配置。

M3配备GPU，并不代表Paddle训练就能自动使用它。是否支持相应加速，需要以具体框架版本和后端实现为准；配置中写了使用GPU，也不会凭空获得CUDA环境。初次验证可以采用CPU、小批量和少量样本，先确认训练流程正常，再评估是否转到受支持的GPU机器上进行正式训练。

还要固定代码与配置版本。安装的软件包、下载的PaddleOCR仓库和网上找到的配置文件，可能属于不同代际。建议记录仓库提交、依赖版本和配置副本。后面出现参数不识别、模型结构对不上或导出失败时，这份记录能帮助定位问题，也方便把本地实验迁移到服务器。

三、标注和划分数据，决定模型能学到什么

训练数据应来自自有或明确授权的图片，并尽量覆盖实际使用条件。只收集清晰、端正的样本，模型遇到旋转、遮挡、低对比度或复杂背景时就容易失准。采集时可以按字体、尺寸、背景、干扰线和旋转角度分组，避免数据数量看着很多，实际却只是少数模板的重复。

PPOCRLabel的普通模式适合文字检测与识别标注。操作时不仅要框住文字，还要核对转写内容。四边形应贴合文字轮廓，不要包含过多背景，也不要切掉笔画。自动预标注可以节省时间，但形近字、旋转字和被遮挡的字仍需人工复核。错误标签会直接教给模型错误答案。

KIE模式面向关键字段提取，例如票据中的字段关系，并不是普通文字点选的必选项。检测数据通常由图片路径和文字区域标注组成；识别数据则常常需要先按文字框裁剪，形成“小图加文字标签”的样本。标注工具导出的文件是否能直接使用，要结合当前训练配置的数据读取方式确认。

训练集与验证集可以先按八比二划分，再单独保留测试集。如果使用仓库中的划分脚本，先查看它接受几个比例参数，以及是否会自动生成测试集。不同版本的脚本规则可能不同，不能只照着命令名称猜。图片路径、标注路径和字符编码也要同步检查，否则训练可能启动后才发现读不到样本。

划分时尤其要防止数据泄漏。同一张原图生成的旋转图、加噪图和压缩图，应尽量放在同一侧；同源模板也可以按批次隔离。否则验证集里充满训练样本的近亲，得到的分数会偏乐观。实际业务更关心未见过的背景和排列，所以测试集应尽量保留这种差异。

字符字典同样重要。识别模型能够输出什么字符，与字典配置直接相关。目标中出现的生僻字、符号或数字若没有进入字典，就需要调整训练方案。修改字典后还要检查输出层与预训练权重是否兼容，不能只换一个文本文件，就默认所有参数都能继续沿用。

四、分开训练检测与识别，用错误样本指导调参

检测和识别应分别配置、分别验收。检测配置主要检查数据目录、标签文件、输入尺寸、批量大小和输出目录；识别配置还要关注字符字典、图像宽高及文本长度限制。常见PP-OCRv4配置可以作为起点，但配置路径和模型结构应以实际仓库为准，不能把不同版本的文件随意混用。

初次训练先跑少量迭代，观察损失是否正常、验证程序是否能执行、输出目录是否生成权重。确认没有路径和标签错误后，再增加训练轮数。内存不足时优先降低批量大小，必要时调整输入尺寸；输入过小又会损失细笔画，需要结合样本可视化判断。

# 路径按所用仓库和实际输出调整
python tools/train.py -c configs/det/ch_PP-OCRv4/ch_PP-OCRv4_det_cml.yml
python tools/train.py -c configs/rec/PP-OCRv4/ch_PP-OCRv4_rec.yml
# 从训练检查点恢复，填写前缀而非目录
python tools/train.py -c configs/det/ch_PP-OCRv4/ch_PP-OCRv4_det_cml.yml \
  -o Global.checkpoints=./output/det/latest

恢复训练和加载预训练权重需要区分。检查点恢复通常希望接着使用模型参数、优化器状态和训练进度；预训练权重则主要用于初始化。是否能完整恢复，取决于保存的文件以及当前版本实现。恢复前应核对文件前缀和配套文件，并通过日志确认加载成功，不能只看到程序继续运行就认为进度正确。

检测阶段要观察漏检、误检和框的位置偏差，识别阶段要查看字符准确率与整段文本准确率。对点选业务而言，还应单独统计目标是否全部找到、顺序是否正确、坐标是否落在有效区域。单个字的准确率不错，也不代表一组多目标任务能稳定完成。

每次训练后抽取失败样本，通常比反复延长训练更有价值。检测漏字可以检查小目标尺寸与增强方式；识别混淆可以补充形近字样本；点击偏移则应回到坐标换算排查。如果识别框属于原图坐标，而页面使用缩放后的图片，就需要分别计算横纵比例，再加上图片在页面中的位置偏移。

五、导出模型与接口落地，把边界验证清楚

训练权重通常不能直接当作部署模型使用。检测和识别需要分别导出，并保留对应的预处理与后处理设置。部分版本使用Global.pretrained_model指定导出权重，其他版本可能提供不同入口，应以同版本导出脚本为准。蒸馏训练还可能包含多个子模型，导出时要确认选择的是准备部署的分支。

转换ONNX前，先确认导出产物的格式。旧版流程常见模型结构文件与参数文件分开保存，新版导出可能有所变化，因此不能机械套用固定的文件名。还要检查Paddle2ONNX与推理运行时是否兼容、动态输入尺寸是否受支持，以及模型算子能否正确转换。

转换成功只代表文件生成，数值结果仍需对照验证。选一批固定图片，分别运行原推理流程与部署流程，比较检测框、识别文本和置信度。颜色通道、归一化参数、缩放规则或字典顺序发生变化，都可能让同一组权重表现不同。这些差异应在接入页面前解决。

若公司需要覆盖文字点选、图标点选、滑块、无感、九宫格，以及五子棋、躲避障碍、空间等类型，可以向www.ttocr.com咨询其面向极验、易盾的识别方案及自动化API。具体类型、协议版本和返回结果应以实际接口与测试为准；采用成熟接口，可以减少逐类准备数据、训练模型和维护推理服务的工作。

对接时先跑通一个小范围闭环：提交授权样本、读取结构化结果、完成业务侧映射，再记录耗时与失败原因。把鉴权、超时、重试次数和异常返回集中封装，业务代码就能通过统一入口调用。先用真实样本确认效果与成本，再逐步扩大调用量，接口接入会更容易维护。