一、写在前面为什么是 PaddleOCRPaddleOCR 是百度飞桨PaddlePaddle开源的多语言 OCR 与文档智能引擎覆盖文本检测、文字识别、版面分析、表格还原、关键信息抽取、文档结构理解与结构化输出的完整链路支持 110 语种服务覆盖 170 多个国家和地区html5.qq.com。截至 2026 年其在 GitHub 上的 Star 数已突破 8.22 万超越谷歌 Tesseract OCR成为全球最受关注的开源 OCR 项目之一jjckb.cn1。最新一代PP-OCRv6一次性推出 Tiny / Small / Medium 三档模型参数量从 1.5M 到 34.5M在 OCR 专业任务上超越 Qwen3-VL-235B、GPT-5.5、Gemini-3.1-Pro 等千亿级视觉语言模型其中 Tiny 仅 1.5MB单图预测最快 97 毫秒可直接在浏览器端运行html5.qq.com1。PaddleOCR 已被 Dify、RAGFlow、Cherry Studio、MinerU、UmiOCR 等项目广泛集成成为 RAG、Agent 与智能文档工作流的底层组件csdn.net。二、PaddleOCR 核心架构与能力总览PP-OCRv6 三档模型对比模型层级参数量检测 Hmean识别准确率典型部署场景PP-OCRv6_tiny~1.1M (rec)73.5%73.5%浏览器端、边缘设备PP-OCRv6_small~5.2M (rec)81.3%81.3%移动端、本地端PP-OCRv6_medium~34.5M86.2%83.2%服务端、高精度需求PP-OCRv6_medium 相比 PP-OCRv5_server检测 Hmean 提升 4.6%识别准确率提升 5.1%modelscope.cn1。其核心架构创新包括LCNetV4MetaFormer 风格 结构重参数化的统一骨干网络、RepLKFPN含膨胀可重参数化深度卷积的检测颈部、EncoderWithLightSVTR融合局部-全局注意力与加性跳跃连接的识别颈部三、环境搭建与安装3.1 版本依赖关系PaddleOCR 3.x 依赖于 3.0 及以上版本的 PaddlePaddle 框架且引入了重要的接口变动基于 2.x 编写的旧代码很可能无法直接在 3.x 上运行paddleocr.ai1。3.2 安装推理引擎CPU 端安装python -m pip install paddlepaddle3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/GPU 端安装以 Linux CUDA 11.8 为例其他平台参考飞桨官网安装文档python -m pip install paddlepaddle-gpu3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/PaddleOCR 3.x 还支持通过 Transformers 作为推理后端python -m pip install transformers5.8.03.3 安装 paddleocr# 完整功能安装 python -m pip install paddleocr[all] # 或最小化安装 python -m pip install paddleocr3.4 验证安装python -c import paddleocr; print(paddleocr.__version__)建议使用 conda 创建独立虚拟环境以避免依赖冲突conda create -n paddle_ocr python3.9 conda activate paddle_ocr四、快速上手4.1 命令行使用PP-OCRv6 通用 OCR 流水线paddleocr ocr -i ./general_ocr_002.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --use_textline_orientation False \ --engine paddle单独使用文本检测或识别模块paddleocr text_detection -i ./general_ocr_001.png --engine paddle paddleocr text_recognition -i ./general_ocr_rec_001.png --engine paddlePP-StructureV3 文档解析paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \ --use_doc_orientation_classify False \ --use_doc_unwarping False \ --engine paddle4.2 Python 脚本使用通用 OCR 识别基于 3.x 新 APIpredictfrom paddleocr import PaddleOCR ocr PaddleOCR( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, enginepaddle, ) result ocr.predict(./general_ocr_002.png) for res in result: res.print() res.save_to_img(output) res.save_to_json(output)输出示例节选{res: { input_path: /root/.paddlex/predict_input/general_ocr_002.png, dt_polys: array([[[3, 10], ..., [4, 30]], ..., [[99, 456], ..., [99, 479]]], dtypeint16), rec_texts: [www.997700, 登机牌, BOARDING, PASS, 航班FLIGHT, 福州, FUZHOU, ...], rec_scores: array([0.67582953, ..., 0.97418666]), rec_polys: array([[[3, 10], ..., [4, 30]], ...], dtypeint16) }}单模块调用from paddleocr import TextDetection, TextRecognition # 文本检测 det_model TextDetection(enginepaddle) output det_model.predict(general_ocr_001.png) for res in output: res.print() res.save_to_img(save_path./output/) res.save_to_json(save_path./output/res.json) # 文本识别 rec_model TextRecognition(enginepaddle) output rec_model.predict(inputgeneral_ocr_rec_001.png) for res in output: res.print()五、核心功能实战5.1 通用场景文字识别PaddleOCR 在通用场景下能精准识别电子设备屏幕、复杂背景、低分辨率图像中的数字、字母和特殊符号csdn.net。关键参数调优ocr PaddleOCR( use_doc_orientation_classifyFalse, use_doc_unwarpingFalse, use_textline_orientationFalse, text_det_thresh0.3, # 检测阈值 text_det_box_thresh0.6, # 框阈值 text_det_unclip_ratio1.5, # 检测框扩展比例 text_rec_score_thresh0.5, # 识别置信度过滤 enginepaddle, )5.2 多语言识别PP-OCRv6 单模型可覆盖 50 种语言无需为不同语种频繁切换模型modelscope.cn。通过lang参数切换# 中文 ocr PaddleOCR(langch) # 英文 ocr PaddleOCR(langen) # 日文 ocr PaddleOCR(langjapan) # 多语言模式 ocr PaddleOCR(langmulti)5.3 版面分析与表格识别PP-StructureV3PP-StructureV3 驱动的版面结构分析支持表格含嵌套、公式、印章、图表等的定位与还原并提供 Markdown、JSON、DOCX 导出html5.qq.com。from paddleocr import PPStructure table_engine PPStructure(recoveryTrue) result table_engine(document.pdf) for line in result: print(line)输出可进一步导出为 Excel适合财务报表解析、科研论文表格提取复杂合并单元格识别准确率可达 92% 以上gitcode.com。5.4 关键信息抽取KIE对于身份证、发票、合同等结构化场景PaddleOCR 提供两种思路直接使用 SER将关键字段标注为name_key/name_value等类别识别后取对应类别文本即可。联合 SER RE先用 SER 获取所有 key/value再用 RE 方法进行配对建立映射关系paddleocr.ai。数据量方面固定场景 50 张左右标注图片即可达到可接受效果若涉及罕见字、特殊字体建议基于 PP-OCRv3/v4 模型微调并准备至少 5000 张垂类场景的文本识别图像paddleocr.ai。5.5 RAG 场景文档转 Markdown/JSON将扫描件 / PDF 批量转为结构化 Markdown 或 JSON可直接接入企业知识库构建、RAG 检索增强生成与智能问答html5.qq.com1。这是 PaddleOCR 在大模型时代最核心的价值定位——它解决的不是「能不能识别」而是「识别之后能不能直接进入下一个 AI 流程」。六、自定义模型训练与微调6.1 数据准备文本检测数据集格式PPOCRLabel 标注后图片路径\t[{transcription: 文本内容, points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]]}, ...]文本识别数据集格式图片路径\t文本内容数据集划分脚本示例import random train_txt open(train.txt, w, encodingutf-8) val_txt open(val.txt, w, encodingutf-8) with open(Label.txt, r, encodingutf-8) as f: data f.readlines() count len(data) tra int(0.9 * count) li range(count) train random.sample(li, tra) for i in li: if i in train: train_txt.write(data[i]) else: val_txt.write(data[i])6.2 修改配置文件检测模型配置文件位于configs/det/识别模型位于configs/rec/。关键参数csdn.net1Global: use_gpu: True epoch_num: 500 save_model_dir: ./output/db_mv3/ save_epoch_step: 100 eval_batch_step: [0, 2000] pretrained_model: ./pretrain_models/ch_ppocr_mobile_v2.0_det_train/best_accuracy character_dict_path: ppocr/utils/ppocr_keys_v1.txt Architecture: model_type: rec algorithm: SVTR_LCNet Backbone: name: PPLCNetV3 scale: 0.95 Train: dataset: name: SimpleDataSet data_dir: ./train_data/ label_file_list: [./train_data/train_list_1W.txt, ./train_data/train_list_2W.txt, ./train_data/train_list_5W.txt] ratio_list: [1.0, 0.5, 0.2]6.3 启动训练# 检测模型训练 python tools/train.py -c configs/det/ch_PP-OCRv3/ch_PP-OCRv3_det_student.yml \ -o Global.pretrained_model./pretrain_models/ch_PP-OCRv3_det_distill_train/student.pdparams # 识别模型训练 python tools/train.py -c configs/rec/PP-OCRv3/ch_PP-OCRv3_rec_distillation.yml \ -o Global.pretrained_model./pretrain_models/ch_PP-OCRv3_rec_train/best_accuracy.pdparams6.4 模型评估与导出# 评估 python tools/eval.py -c configs/det/ch_PP-OCRv3_det_cml.yml \ -o Global.checkpoints./output/ch_PP-OCRv3_det/latest # 导出推理模型 python tools/export_model.py -c configs/det/ch_PP-OCRv3_det_cml.yml \ -o Global.checkpoints./output/ch_PP-OCRv3_det/best_accuracy \ Global.save_inference_dir./inference/det/6.5 训练建议数据配比训练过程中每个 epoch 的真实垂类数据、合成数据、通用数据比例建议在 1:1:1 左右paddleocr.ai。小样本过拟合使用更强的数据增强 Dropout Early Stoppingcsdn.net。训练不稳定采用分层学习率 Warmup 策略 Gradient Clipcsdn.net。加载预训练模型微调优于从 backbone 重新训练收敛速度更快csdn.net。七、常见问题与解决方案7.1 环境与安装类报错现象原因解决方案CUDA driver version is insufficient for CUDA runtime version显卡驱动版本与 CUDA Toolkit 不匹配nvidia-smi查看驱动版本对应安装匹配的 paddlepaddle-gpu 版本csdn.net1Compiled with WITH_GPU, but no GPU found in runtimeCUDA 版本与 paddle 不匹配或驱动未更新卸载当前 paddle按官网指引安装合适版本CentOS 下需更新 kernel-develcsdn.net1libstdc.so.6: version GLIBCXX_3.4.XX not found系统库依赖冲突使用 Docker 容器化部署或sudo apt-get install libstdc6csdn.netPlease compile with gpu to EnableGpu()同时安装了 CPU 与 GPU 版本或设置使用 GPU 但 paddle 不支持卸载 CPU 版本只保留 paddlepaddle-gpucsdn.netCMake must be installed缺少编译工具pip install cmakecsdn.netImportError: cannot import name _registerMatType from cv2.cv2opencv 版本冲突pip install opencv-python-headless4.1.2.30iotword.comImportError: cannot import name inference from paddle未安装 paddlepaddlepython -m pip install paddlepaddle2.0.1 -i https://mirror.baidu.com/pypi/simpleiotword.comnumpy 版本冲突PaddlePaddle 3.0 对 numpy 版本有要求pip install numpy1.21.6或numpy1.26.4aliyun.com17.2 模型与推理类报错现象原因解决方案模型下载超时 / 失败网络问题或磁盘权限设置国内镜像源export PADDLE_PDX_MODEL_SOURCEBOS或手动下载模型csdn.net内存溢出 / OOM模型过大或 batch size 过高禁用不必要的预处理模块使用 mobile 而非 server 模型降低 batch_size开启enable_memory_optimTruecsdn.net1识别结果乱码语言模型不匹配中文识别需指定langchgitcode.com检测框偏移阈值设置不当调整det_db_thresh建议 0.3-0.5、det_db_unclip_ratiogitcode.com识别文字重复或漏识别后处理参数不当调整det_db_unclip_ratio2.5、det_db_box_thresh0.3csdn.netCUBLAS_STATUS_EXECUTION_FAILEDGPU 程序执行失败驱动版本不匹配或 cuBLAS 异常安装指定版本如 3.2.1的 PaddlePaddle GPU 版csdn.netSegmentation faultCUDA 版本与 paddle 不匹配按官网安装匹配版本如pip3 install paddlepaddle-gpu2.1.0.post112csdn.net7.3 性能优化建议优化手段效果说明use_doc_orientation_classifyFalse内存 -20%速度 15%不需要文档方向分类时关闭csdn.netuse_doc_unwarpingFalse内存 -30%速度 25%不需要文档展平时关闭csdn.netenable_memory_optimTrue内存 -40%开启内存优化csdn.netbatch 推理GPU 利用率 40%单张改为批量推理gitcode.com短边控制 600-800 像素速度提升高清图像先降采样gitcode.com导出推理模型去除训练相关代码tools/export_model.pygitcode.com八、部署方式与生态集成具体包括高性能推理支持 Paddle Inference 与 ONNX Runtime 后端高性能推理支持 CUDA 12paddleocr.aiC 本地部署PP-OCRv5/v6 C 方案已支持 Linux 与 Windows精度与 Python 实现一致paddleocr.ai服务化部署官方开源高稳定性服务化方案支持自定义 Docker 镜像与 SDKpaddleocr.ai跨端部署Android、iOS、浏览器端PaddleOCR.jspaddleocr.ai多硬件支持NVIDIA GPU、昆仑芯 XPU、华为昇腾 NPU、海光 DCU、Intel Arc GPU、Apple Silicon、AMD GPU 等paddleocr.ai生态集成MCP 服务器、Agent Skills与 RAGFlow、MinerU、Dify 等深度集成paddleocr.ai1PaddleOCR-VL 还支持通过 vLLM 进行服务化部署docker run --rm --gpus device0 --network host \ ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest \ paddleocr genai_server --model_name PaddleOCR-VL-1.5-0.9B \ --host 0.0.0.0 --port 8080 --backend vllmcsdn.net九、总结与最佳实践PaddleOCR 的价值已从「把字识别出来」演进为「把原始图片和 PDF 文档尽可能稳定地转换成结构化、可检索、可进入大模型流程的数据」csdn.net。基于本文的实战梳理落地时建议遵循以下路径环境隔离始终用 conda/venv 创建独立环境避免依赖冲突。版本对齐PaddleOCR 3.x 必须搭配 PaddlePaddle 3.0CUDA 版本与驱动、paddlepaddle-gpu 严格对应。先推理后训练先用官方预训练模型跑通推理链路确认场景适配后再考虑微调。按需选模型浏览器/边缘端选 tiny移动端选 small服务端选 medium不需要文档预处理模块时果断关闭以换性能。数据为王垂类场景微调时真实数据 合成数据 通用数据按 1:1:1 配比单字符至少出现 200 张以上。结构化输出面向 RAG / Agent 时优先使用 PP-StructureV3 或 PaddleOCR-VL输出 Markdown/JSON 而非纯文本。多端部署训练一次通过 ONNX / C / Lite /.js 多端落地兼顾精度与延迟。随着 PP-OCRv6 与 PaddleOCR-VL 的持续推进PaddleOCR 正从一款强大的 OCR 工具走向真正意义上的文档 AI 基础设施——在 OCR 仍然是文档 AI 入口的前提下它有能力成为下一步智能处理的可靠起点csdn.net。参考资料PaddleOCR 官方文档https://www.paddleocr.ai/PaddleOCR GitHubhttps://github.com/PaddlePaddle/PaddleOCRPP-OCRv6 模型库https://huggingface.co/collections/PaddlePaddle/pp-ocrv6飞桨官网安装文档https://www.paddlepaddle.org.cn/install/quick
