PaddleOCR

PaddleOCR 快速入门

把 PDF 和图片变成 AI 能用的结构化数据——飞桨（PaddlePaddle）出品、Apache-2.0 开源、GitHub 90k+ Stars 的老牌 OCR 工具链。

这是什么?适合谁?

PaddleOCR 是百度飞桨体系下的开源 OCR（光学字符识别）工具链，定位是”Turn any PDF or image document into structured data for your AI”——把文档数字化这条流水线从图片输入一直管到结构化输出。它不只是”识别文字”：文本检测、文本识别、表格识别（PP-Structure）、版面分析、公式识别（PP-FormulaNet）、印章识别、关键信息抽取（PP-ChatOCR）都在一个工具链里，覆盖了文档 AI 的绝大多数场景。

技术上有两条路线可选：轻量推理模型（几 MB 到几十 MB，CPU 可跑，适合嵌入和批量离线处理）和 PaddleOCR 3.x 推出的 PP-OCRv5 / PP-StructureV3 服务化部署（GPU 加速、精度更高）。官方提供 pip 安装、Docker 镜像、RESTful 服务（PaddleX 部署）三种交付形态。

适合谁：需要把扫描件/PDF/图片批量转成可检索文本的运维与数据团队、做 RAG（检索增强生成）需要高质量文档解析的开发者、要在国内环境本地部署（数据不出内网）的企业、做票据/证照/表单录入自动化的业务方。不适合：只需要偶尔截个图转文字的轻用户（手机自带 OCR 或在线工具更省事），以及没有 Python 环境管理能力的纯小白。

准备工作

• 设备要求：CPU 即可运行轻量模型（推荐 8GB+ 内存）；GPU（CUDA）可大幅加速但非必需；服务化部署建议 16GB+ 内存
• 账号要求：无需任何账号或 API Key，完全本地运行
• 付费要求：免费开源（Apache-2.0 协议，可商用）；只有用百度飞桨 AI Studio 星河社区托管算力时才涉及平台额度
• 前置知识：Python 基础（pip 装包、跑脚本）、命令行操作；做版面/表格抽取需要了解 HTML/JSON 输出结构
• 安装：pip install paddleocr（Python 3.8+）。注意 PaddleOCR 依赖飞桨框架，纯 CPU 环境装 pip install paddlepaddle，GPU 环境按官网指引装对应 CUDA 版本；Windows 下建议先装 Visual C++ 运行库再装飞桨

3 步快速上手

第 1 步：安装并跑通第一张图

pip install paddlepaddle   # CPU 版
pip install paddleocr
paddleocr ocr -i https://paddle-model.bj.bcebos.com/PP-OCRv3/inference/PP-OCRv3/ch.jpg --lang ch

首次运行会自动下载 PP-OCRv5 轻量模型（约十几 MB）。输出会在终端打印识别文本，并在当前目录生成可视化图片（框出每行文字）。

第 2 步：批量处理 PDF 与表格

from paddleocr import PaddleOCR
ocr = PaddleOCR(use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False)
result = ocr.predict("invoice.pdf")
for res in result:
    res.print()
    res.save_to_img("output")
    res.save_to_json("output")

Python API 与 CLI 等价。对 PDF 输入，predict 会逐页识别并输出坐标 + 文本；PP-StructureV3 路线还可以直接输出 Markdown/HTML 结构（含表格骨架）。

第 3 步：进阶到版面/表格/公式

paddleocr 3.x 把版面恢复整合进 predict 管线：把 use_doc_orientation_classify 等开关打开，或直接用 PP-StructureV3 产线（PaddleOCR 的 ocr = PaddleOCR(...) 高阶参数 / PaddleX 产线 API），即可获得”阅读顺序 + 表格结构 + 公式 LaTeX”的整页结构化输出，适合直接喂给 LLM 做 RAG 切片。

预期产出：一个从图片/PDF 到带坐标文本、再到结构化 Markdown 的本地文档解析流水线，全程无 API 调用、数据不出本机。

常见踩坑

• 现象：pip install paddleocr 后首次运行报 No module named 'paddle'" 或 DLL 加载失败。 原因：PaddleOCR 依赖的飞桨框架（paddlepaddle）没装或版本不匹配；Windows 上常见于缺 VC++ 运行库。 解决：先 pip install paddlepaddle 再装 paddleocr；Windows 到微软官网装 Visual C++ Redistributable。版本对应关系以 官方文档 为准。

• 现象：识别中文正常，英文/数字混排时准确率下降。 原因：--lang 参数默认按中文优化；PP-OCRv5 已支持多语言混排但需要正确指定。 解决：中文场景保持 --lang ch（PP-OCRv5 的 ch 模型本身支持中英混排数字）；小语种场景查阅官方多语言模型列表选对应语言包。

• 现象：模型下载慢或超时（国内网络访问部分模型源不稳定）。 原因：默认模型权重托管在 BOS（百度云）与部分海外 CDN。 解决：设置 PADDLE_PDX_LOCAL_FONT_FILE_PATH 无关；正确做法是手动从 官方模型库 下载权重后本地加载，或使用 AI Studio 星河社区托管运行（国内网络直达）。

• 现象：GPU 机器上仍然用 CPU 跑，速度没有提升。 原因：装了 CPU 版 paddlepaddle 而不是 paddlepaddle-gpu，或 CUDA/cuDNN 版本不匹配导致静默回退。 解决：python -c "import paddle; paddle.utils.run_check()" 验证安装；GPU 版必须按 官方安装文档 对应 CUDA 版本安装。

• 现象：表格识别输出错位、合并单元格丢失。 原因：老版 PP-Structure 表格模型对复杂表格（合并表头、跨页表）能力有限。 解决：升级到 PaddleOCR 3.x 并启用 PP-StructureV3 产线（SLANePlus 表格结构模型），对合并单元格与无线表的还原显著更好；跨页表格建议先按页输出再人工合并。

• 现象：Windows 下长路径/中文路径导致读图失败。 原因：Windows 260 字符路径限制与部分依赖库的编码处理。 解决：把工作目录换成短英文路径，文件名避免特殊字符。

FAQ

Q1: PaddleOCR 和云 OCR API（如百度智能云 OCR、腾讯云 OCR）怎么选？

A: 云 API 按调用量计费、免运维但数据要出网；PaddleOCR 免费本地部署、数据不出内网，适合大吞吐量（长期成本远低于按次付费）与合规敏感场景。个人轻量使用选云 API 更省事，企业批量处理选 PaddleOCR。参考：百度智能云 OCR 定价（按调用量阶梯计价）。

Q2: 识别精度能达到商用要求吗？

A: 印刷体场景（发票、证件、扫描文档）PP-OCRv5 在公开基准上处于开源第一梯队（官方报告多语言场景较前代错误率显著下降）；手写体、艺术字、严重模糊仍是行业共性难点，建议先抽样实测再上量。权威数据见 PaddleOCR GitHub README 的基准表。

Q3: 可以商用吗？需要开源我的代码吗？

A: Apache-2.0 协议允许商用且不要求衍生作品开源，只要求保留版权声明与协议文本。比 AGPL 类协议（如部分竞品）对企业友好得多。

Q4: 最小部署体积多大？

A: 轻量移动端模型仅几 MB，配合 PaddleLite 可跑在手机/边缘设备；服务器端 PP-OCRv5 服务器版模型更大但精度更高。按需在模型库选择 mobile/server 版本。

Q5: 怎么接进 RAG / LLM 流水线？

A: 常见组合是 PaddleOCR（解析）→ PP-StructureV3（输出带阅读顺序的 Markdown）→ LangChain/LlamaIndex 切片入库。官方也提供 PP-ChatOCRv4（OCR + LLM 抽取关键信息）的产线方案，省去自己拼组件。

小技巧

• 加 --use_textline_orientation=True 自动纠正旋转文本行，扫描件歪斜时收益明显
• save_to_json 输出的坐标可直接用于后续版面还原或高亮定位，别只看图
• 批量处理用 ocr.predict 传目录而不是逐文件循环，内部有批处理优化
• CPU 环境把并发 worker 数压到物理核数的一半，避免内存打爆
• 旧代码从 2.x 迁移到 3.x 时 API 有变更，官方提供迁移指南

进阶学习建议

• 想做发票/证照结构化：直接研究 PP-StructureV3 产线（表格 + 版面 + 阅读顺序），配合 save_to_markdown 输出，比纯 OCR + 正则稳得多
• 想做关键信息抽取（如合同字段）：看 PP-ChatOCRv4 官方示例，把 OCR 结果喂给本地 LLM 抽字段
• 想压榨性能：读 PaddleSlim 的模型量化文档，把 mobile 模型 INT8 量化后推理速度可再提升
• 想二次开发训练自己的检测/识别模型：官方 train 目录与 文档 提供完整数据标注格式、训练脚本与合成数据工具（Style-Text）

免责声明

本文基于官方文档和公开资料整理，AI 辅助生成，MagicNetWorld 尚未完成独立实测。

参考链接

• PaddleOCR 官网
• GitHub 仓库 PaddlePaddle/PaddleOCR
• 飞桨安装文档
• PP-StructureV3 产线文档