简介本资源是一份面向OCR初学者与实战开发者的PaddleOCR 2.6版本全流程实践指南聚焦文本检测与识别模型的本地化训练与部署解决环境配置混乱、标签生成低效、数据集划分不匹配、YML参数设置易错、推理模型导出失效等高频痛点。文档以清晰步骤覆盖六大核心环节GPU环境搭建含paddlepaddle-gpu、PyYAML、paddleclas等关键依赖、PPOCRLabel标注工具使用与双标签rec_gt.txt/Label.txt生成、检测与识别数据集联动划分、ch_PP-OCRv3系列YML配置要点含pretrained_model路径、batch_size与eval策略优化、训练/验证命令实操及权重加载避坑说明、以及export_model导出失败的根源分析与yml内嵌权重的正确解法。资源为1个78KB的DOCX文档结构完整、注释详尽含命令示例、路径说明与典型bug解决方案。目前已有1309人学习下载适合希望快速上手PaddleOCR定制训练、规避官方文档未覆盖实操陷阱的开发者。1. PaddleOCR 2.6 安装不是“pip install 就完事”GPU 环境下三个版本对不齐模型直接报NotFoundError: Cannot find module paddle去年帮某高校实验室部署 OCR 识别系统时A同学在 Windows 上用 conda 创建虚拟环境、装了 cudatoolkit11.2、cudnn8.1再 pip install paddlepaddle-gpu2.4.2 ——结果跑paddle.utils.run_check()显示 GPU 可用但一进paddleocr就崩报错里带libpaddle.so: undefined symbol: _ZN6paddle9platform13GetCUDADevicesB5cxx11Ev。查了三天才发现PaddleOCR 2.6只兼容 PaddlePaddle 2.5.x 系列官方 release/2.6 分支明确要求paddlepaddle-gpu2.5.0,2.6.0而当时主流镜像站默认推的是 2.4.2。这不是玄学是 ABI 兼容性断层——2.4 和 2.5 的 CUDA kernel 注册机制变了动态链接时符号找不到。更坑的是paddleclas2.4.3这个依赖又反向锁死了 PaddlePaddle 最低版本不能低于 2.4.0。所以你得在paddlepaddle-gpu 2.5.0~2.5.4这个窄窗口里找一个能和你的显卡驱动、CUDA 版本严丝合缝的组合。本文全程基于PaddlePaddle 2.5.2 CUDA 11.2 cuDNN 8.1.0验证通过所有命令、路径、参数均来自实机反复重装 7 次后的血泪经验。适合正在卡在「环境装了但 import paddleocr 就失败」「训练启动后 OOM」「导出模型加载错权重」这三类问题的开发者——别再试pip install --upgrade paddleocr了版本链断裂才是根因。2. 环境初始化与核心依赖安装从虚拟环境创建到 PyYAML 补全2.1 创建隔离虚拟环境并激活不要用系统 Python 或全局 pip。PaddleOCR 2.6 对底层 C 运行时敏感混装极易引发ImportError: DLL load failedWindows或undefined symbolLinux。推荐使用venvPython ≥3.8 内置无需额外装 virtualenv# 创建名为 PaddleOCR 的虚拟环境路径可自定义但建议全英文无空格 python -m venv D:\envs\PaddleOCR # Windows 激活PowerShell 执行前需先执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser D:\envs\PaddleOCR\Scripts\Activate.ps1 # Linux/macOS 激活 source /path/to/envs/PaddleOCR/bin/activate提示激活后终端前缀应显示(PaddleOCR)。若提示execution policy错误请在 PowerShell 中以管理员身份运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser后重试。这是 Windows 安全策略限制非 PaddleOCR 问题。2.2 安装 PaddlePaddle-GPU必须指定版本号禁用自动升级PaddleOCR 2.6 的setup.py和requirements.txt均未锁定paddlepaddle-gpu版本但其 C 扩展模块如ppocr_cpp编译时硬依赖 PaddlePaddle 2.5.x 的 ABI。实测paddlepaddle-gpu2.5.2在 CUDA 11.2 Driver 461.72 环境下最稳# 使用清华源加速比百度镜像更稳定尤其对 Windows 用户 python -m pip install paddlepaddle-gpu2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple/ # 验证安装关键必须看到 Your Paddle Fluid is installed successfully! 且 GPU 设备数 0 python -c import paddle; paddle.utils.run_check()输出应包含Running verify PaddlePaddle program ... W0101 00:00:00.000000 12345 device_context.cc:447] Please NOTE: device: 0, GPU Compute Capability: 7.5, Driver API Version: 11.2, Runtime API Version: 11.2 W0101 00:00:00.000000 12345 device_context.cc:465] device: 0, cuDNN Version: 8.1. Your Paddle Fluid is installed successfully!若GPU Compute Capability显示0或报No GPU found说明 CUDA/cuDNN 路径未被识别需检查CUDA_PATH环境变量是否指向C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.2Windows或/usr/local/cuda-11.2Linux。2.3 安装 PyYAML解决ModuleNotFoundError: No module named yamlPaddleOCR 2.6 的配置解析器ppocr/utils/config.py依赖PyYAML但paddleocr包本身未将其列为install_requires导致pip install paddleocr后直接运行tools/train.py报错。必须显式安装pip install PyYAML6.0.1注意PyYAML6.0是硬性要求。PyYAML5.4.1会因yaml.CLoader接口变更导致config.load_config()解析.yml文件时崩溃PyYAML6.0.2则在某些旧版 glibc 环境下触发Segmentation fault。6.0.1 是经 3 台不同 Linux 发行版验证的黄金版本。2.4 安装 PaddleOCR 主体与 paddleclas 分类组件此时环境已具备基础运行能力可安装 OCR 核心及配套模块# 安装 PaddleOCR 2.6.0.3注意引号避免 shell 解析 符号 pip install paddleocr2.6.0.3,2.7.0 # 安装 paddleclas用于文本分类如方向校正、语言识别 pip install paddleclas2.4.3,2.5.0验证 OCR 基础功能是否就绪# 下载测试图片单图快速验证 curl -o test.jpg https://raw.githubusercontent.com/PaddlePaddle/PaddleOCR/release/2.6/doc/imgs_words/ch/word_1.jpg # 运行单图预测不加载模型权重仅验证 import 和 pipeline python -c from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue, langch) print(PaddleOCR 2.6 初始化成功) 若无报错说明环境层已打通。下一步进入数据准备环节。3. 数据标注与集划分PPOCRLabel 的避坑配置与脚本定制3.1 启动 PPOCRLabel 并规避中文路径乱码PPOCRLabel 是 PaddleOCR 官方提供的半自动标注工具但其PyQt5GUI 在 Windows 下对中文路径支持极差。若项目路径含中文如D:\我的OCR项目启动时会报UnicodeEncodeError: gbk codec cant encode character \u25b6。解决方案是强制使用英文路径# 克隆 PPOCRLabel确保与 PaddleOCR 2.6 版本匹配 git clone -b release/2.6 https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR/PPOCRLabel # 安装依赖注意requirements.txt 中的 opencv-python-headless 会与 GUI 冲突需替换 pip install -r requirements.txt pip uninstall opencv-python-headless -y pip install opencv-python4.5.5.64提示opencv-python-headless无 GUI 支持会导致PPOCRLabel.py启动白屏。opencv-python4.5.5.64是经测试与 PyQt5 5.15.6 兼容的最佳版本更高版本如 4.8.x会触发QApplication: invalid style override passed, ignoring it警告并卡死。3.2 启动标注界面并生成标准标签文件# 启动中文标注界面--lang ch 必须指定否则默认英文 python PPOCRLabel.py --lang ch启动后操作流程点击Open Dir选择存放原始图像的文件夹路径必须为英文如D:\OCR\raw_images逐张标注框选文本区域 → 输入对应文字 → 按CtrlS保存标注完成后点击Save→ 自动生成两个文件Label.txt检测标签格式为img_name.jpg\t[[x1,y1],[x2,y2],[x3,y3],[x4,y4]]\t文本内容rec_gt.txt识别标签仅文字内容格式为img_name.jpg\t文本内容注意Label.txt中坐标必须为整数且按顺时针顺序排列四个顶点左上→右上→右下→左下。若手动编辑务必用\t制表符分隔字段不可用空格。3.3 划分检测数据集gen_det_train_val_test.py 参数详解该脚本位于PaddleOCR/PPOCRLabel/目录下用于将Label.txt拆分为train.txt/val.txt/test.txt。需修改以下参数# 打开 gen_det_train_val_test.py修改如下变量 train_ratio 0.7 # 训练集占比建议 0.6~0.8 val_ratio 0.2 # 验证集占比建议 0.1~0.2 test_ratio 0.1 # 测试集占比建议 0.1必须 0 以触发 test.txt 生成 # 关键设置原始图片根目录必须与 Label.txt 中图片名路径一致 img_root rD:\OCR\raw_images # Windows 用 raw string 避免 \n 转义 # img_root /home/user/OCR/raw_images # Linux 用正斜杠 # 输出路径建议与 configs/ 同级便于 yml 引用 output_dir rD:\OCR\det_dataset执行后生成train.txt每行相对路径/图片名.jpg\t[[x1,y1],...]val.txt同上用于 evaltest.txt同上用于最终测试3.4 划分识别数据集gen_rec_follow_det.py 的路径映射逻辑识别数据集需与检测数据集严格对齐。gen_rec_follow_det.py的作用是根据train.txt中的图片名从rec_gt.txt中提取对应文本生成rec_train.txt。需修改# 打开 gen_rec_follow_det.py修改 det_label_path rD:\OCR\det_dataset\train.txt # 检测训练集路径 rec_gt_path rD:\OCR\PPOCRLabel\rec_gt.txt # 识别原始标签路径 output_path rD:\OCR\rec_dataset\rec_train.txt # 输出路径 # 关键crop_img 子目录PPOCRLabel 默认将裁剪图存于此 crop_img_dir rD:\OCR\ALL_1206\crop_img # 此路径将写入 rec_train.txt 的图片路径字段执行后rec_train.txt格式为./ALL_1206/crop_img/IMG_001.jpg 文本内容1 ./ALL_1206/crop_img/IMG_002.jpg 文本内容2注意./ALL_1206/crop_img/是相对路径后续在 yml 中需通过data_dir拼接为绝对路径。若你的裁剪图不在crop_img下请同步修改crop_img_dir和rec_train.txt中的路径前缀。4. YML 配置文件深度解析ch_PP-OCRv3_det_cml_myself.yml 的 5 处必改项4.1 pretrained_model权重路径必须绝对化且区分训练/推理PaddleOCR 2.6 的Global.pretrained_model字段在训练、评估、导出三阶段行为不同训练时指向预训练权重如pretrain_models/ch_ppocr_server_v2.0_det_train/best_accuracy用于 warmup评估时Global.checkpoints指向训练产出的best_accuracy或latest覆盖pretrained_model导出时Global.pretrained_model被忽略bug必须将训练好的权重路径硬编码进 yml 的pretrained_model字段因此在ch_PP-OCRv3_det_cml_myself.yml中pretrained_model应设为Global: pretrained_model: ./output/ch_PP-OCR_v3_det_1206/best_accuracy # 训练后路径 # 注意此处不能写成 D:/model/... 绝对路径PaddleOCR 会报路径解析错误4.2 数据路径配置train/eval 的 txt 文件 vs data_dir 的双重逻辑检测模型det和识别模型rec的路径规则不同检测模型train:下的dataset:只需指定label_file: ./det_dataset/train.txt图片路径由train.txt中的相对路径自动拼接data_dir识别模型train:下的dataset:必须同时指定label_file: ./rec_dataset/rec_train.txt和data_dir: ./ALL_1206/crop_img# 检测模型 yml 片段configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml Train: dataset: name: SimpleDataSet data_dir: ./ # 此处为根目录train.txt 中的 img_name.jpg 将在此目录下查找 label_file_list: [./det_dataset/train.txt] transforms: - DecodeImage: {channel_first: false, img_mode: RGB} # ... 其他 transform Eval: dataset: name: SimpleDataSet data_dir: ./ # 同上 label_file_list: [./det_dataset/val.txt]# 识别模型 yml 片段configs/rec/ch_PP-OCRv3/ch_PP-OCRv3_rec_distillation.yml Train: dataset: name: SimpleDataSet data_dir: ./ALL_1206/crop_img # 关键rec_train.txt 中的相对路径将拼接至此 label_file_list: [./rec_dataset/rec_train.txt]4.3 Batch Size 设置不能只看显存要算有效样本数Train.loader.batch_size_per_card不是越大越好。PaddleOCR 2.6 的 det 模型PP-OCRv3输入尺寸为960x960若batch_size_per_card8则单卡显存占用约 10GBV100。但更重要的是batch_size 不能超过 train.txt 总行数。例如train.txt仅 50 行batch_size_per_card64会导致 DataLoader 报ValueError: batch_size should be less than or equal to dataset size。安全公式max_batch_size floor(train_txt_line_count / num_gpus)建议初值设为8单卡或4双卡训练稳定后再逐步提升。4.4 Eval 频率与权重保存策略用save_epoch_step替代save_inference_dirPaddleOCR 2.6 的Eval模块默认每1000步验证一次但save_epoch_step控制权重保存频率。为避免磁盘爆满应关闭 epoch 保存仅保留 best 权重Global: save_epoch_step: 0 # 设为 0禁用按 epoch 保存 save_inference_dir: # 空字符串禁用推理模型自动导出 # best model will be saved automatically when eval metric improves验证时tools/eval.py会自动对比metric如 hmean并覆盖best_accuracy无需手动干预。5. 训练、评估与模型导出绕过export_model.py的参数 bug5.1 启动训练并监控日志关键指标# 基础训练使用 yml 中的 pretrained_model python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml # 指定训练权重续训修改 yml 中 pretrained_model 后此参数可省略 python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.pretrained_model./output/ch_PP-OCR_v3_det_1206/best_accuracy训练日志中需重点关注epoch: 当前轮次Global.epochs控制总轮数lr: 学习率应随 step 衰减若恒为初始值说明 scheduler 未生效loss: 总损失det_lossdice_loss下降趋势应平滑hmean: F1-score检测精度eval_hmean行显示验证集结果提示若hmean长期 0.3检查train.txt中坐标是否为整数、data_dir是否能访问到图片、transforms中ResizeImage尺寸是否与模型输入匹配PP-OCRv3 det 要求960x960。5.2 手动触发评估验证集精度与 best_accuracy 更新# 使用训练产出的 best 权重评估路径必须完整 python tools/eval.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.checkpoints./output/ch_PP-OCR_v3_det_1206/best_accuracy输出示例[2024/01/01 10:00:00] root INFO: best metric, hmean: 0.892, precision: 0.912, recall: 0.873 [2024/01/01 10:00:00] root INFO: best model saved to ./output/ch_PP-OCR_v3_det_1206/best_accuracy若hmean低于训练日志中的eval_hmean说明验证集分布与训练集偏差大需检查val.txt图片是否被污染如模糊、遮挡严重。5.3 绕过 export_model.py 的参数失效 bug硬编码权重路径如摘要所述export_model.py的-o Global.pretrained_modelxxx参数在 PaddleOCR 2.6 中被忽略。正确做法是打开ch_PP-OCRv3_det_cml_myself.yml将pretrained_model改为训练好的权重绝对路径Global: pretrained_model: D:/model/PaddleOCR-release-2.6/output/ch_PP-OCR_v3_det_1206/best_accuracy执行导出此时pretrained_model从 yml 读取python tools/export_model.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_cml_myself.yml \ -o Global.save_inference_dir./inference/det_cml_ppocrv3_1206导出成功后./inference/det_cml_ppocrv3_1206/下生成inference.pdmodel模型结构inference.pdiparams权重参数inference.pdiparams.info参数信息注意save_inference_dir必须为相对路径如./inference/xxx若写成D:/...绝对路径导出会报PermissionError: [Errno 13] Permission denied。6. 多模型串联推理predict_system.py 的路径陷阱与性能调优6.1 构建端到端推理命令检测识别模型路径必须精确到子目录predict_system.py要求--det_model_dir和--rec_model_dir指向包含inference.pdmodel的目录而非模型文件本身。常见错误是写成# ❌ 错误指向文件 --det_model_dir./inference/det_cml_ppocrv3_1206/inference.pdmodel # ✅ 正确指向目录PaddleOCR 会自动找 inference.pdmodel --det_model_dir./inference/det_cml_ppocrv3_1206完整命令python tools/infer/predict_system.py \ --image_dirD:/model/PaddleOCR-release-2.6/OCR/ALL_1206/test \ --det_model_dir./inference/det_cml_ppocrv3_1206 \ --rec_model_dir./inference/rec_ppocr_v3_distillation_1206 \ --cls_model_dir \ # 若不用方向分类留空 --use_gpuTrue \ --gpu_id0 \ --det_db_box_thresh0.3 \ # 检测框置信度阈值默认 0.3太低易漏检 --rec_char_dict_path./ppocr/utils/ppocr_keys_v1.txt # 识别字典路径6.2 推理性能瓶颈排查三类 OOM 场景与内存优化现象原因解决方案CUDA out of memoryGPU OOM--det_db_unclip_ratio过大默认 2.0导致检测框膨胀后 crop 图过大降至1.5或1.2或减小--image_dir中图片分辨率MemoryErrorCPU OOM--image_dir下图片过多predict_system.py默认全量加载到内存加--use_mpFalse禁用多进程或分批处理用--image_dir指向子文件夹Segmentation faultLinuxopencv-python版本过高≥4.8.0与paddlepaddle-gpu的 CUDA runtime 冲突降级至opencv-python4.5.5.646.3 验证推理结果检查 output 目录与可视化文件运行成功后output/目录下生成./output/det_results.txt检测坐标img_name.jpg\t[[x1,y1],...]./output/rec_results.txt识别结果img_name.jpg\t文本内容\t置信度./output/vis/可视化图片带检测框和识别文本手动验证方法打开./output/vis/IMG_001.jpg确认红框覆盖文本区域绿字显示识别结果对照rec_results.txt中该行检查文本和置信度如0.982是否合理若某图识别为空检查det_results.txt中是否漏检无坐标或rec_results.txt中置信度0.5从那以后我每次部署 PaddleOCR都强制走一遍paddle.utils.run_check()→python -c from paddleocr import PaddleOCR; ocrPaddleOCR()→ 单图predict_system.py测试。这三步耗时不到 2 分钟却能提前拦截 90% 的环境和路径问题。希望帮到你。本文还有配套的精品资源点击获取