PaddleOCR保姆级教程:把PDF变成AI能读的数据

GitHub Trending 日榜第 4 的 PaddleOCR，表面看是一个 OCR 项目，真正值得关注的地方其实更直接：它想把图片、扫描件、PDF、表格、公式这些“视觉文档”，变成 RAG 和 Agent 可以直接消化的 Markdown、JSON 和坐标数据。

讲真，现在做知识库最怕的不是没有大模型，而是资料进库前已经烂了。PDF 里的表格被拆碎，双栏论文顺序错乱，发票金额识别错一位，后面再接多强的 LLM，都会一本正经地胡说。

PaddleOCR 这次上榜，不是偶然。它已经从“识别图片里的字”升级成了一套文档 AI 基础设施：轻量 OCR、结构化解析、文档 VLM、API SDK、MCP Server、浏览器 SDK 都在仓库里。

先把结论放前面。

如果你只是想识别截图、票据、证件、普通图片里的文字，用 PP-OCRv5。
如果你想把 PDF 或扫描文档转成 Markdown/JSON，用 PP-StructureV3。
如果你处理的是复杂论文、古籍、公式、表格、图表、印章，且有 GPU 或愿意用 API，直接看 PaddleOCR-VL-1.6。
如果你要把 OCR 塞进浏览器端产品，仓库里已经有 PaddleOCR.js。

我的判断是：PaddleOCR 不是最“炫”的文档模型，但它是目前最适合认真落地的一类开源 OCR 工具。

这个项目现在到底有什么

AI智能体学习网站：ai-agent-phd.com

PaddleOCR 的 README 里有一句话很关键：把 PDF 和图像转换成适合 LLM 使用的结构化数据。这个定位很准。

它的 3.x 体系大致分成几层：

• PP-OCRv5：通用文字识别管线，包含方向分类、图像矫正、文本检测、文本识别。
• PP-StructureV3：结构化文档解析，把 PDF 或文档图片变成 Markdown/JSON，还能保留更细的坐标信息。
• PP-ChatOCRv4：面向关键信息抽取，适合问“合同金额是多少”“发票抬头是什么”这类问题。
• PaddleOCR-VL：0.9B 文档视觉语言模型，负责更复杂的文档解析。
• PaddleOCR.js：官方浏览器 OCR SDK，可以在前端跑 PP-OCRv5。
• MCP Server 和 Agent Skills：给支持 MCP/Skills 的 AI 应用直接调用 OCR 和文档解析。

这不是一个单模型仓库，而是一套工具箱。

最近的更新也很密。v3.6.0 在 2026 年 5 月 28 日发布，核心是 PaddleOCR-VL-1.6、官方 API 的 Python/Go/TypeScript SDK，以及多页 TIFF 解析。v3.5.0 则加入了 Transformers 后端、Word/Excel/PowerPoint 转 Markdown、DOCX 导出和 PaddleOCR.js。

我拉了 main 分支的最近提交看了一下，截至 2026 年 6 月 5 日，最新几条还在改 MCP、Serving 返回 Markdown 图片、Skills 调用方式和 PaddleOCR-VL-1.6 文档。换句话说，这不是那种 README 很漂亮但仓库已经半休眠的项目。

论文不是装饰，核心思路很实用

AI智能体学习网站：ai-agent-phd.com

这里必须说清楚：PaddleOCR 不是“没有论文只靠工程包装”的项目。README 里明确列了 PaddleOCR 3.0 Technical Report、PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6 等技术报告；PP-OCRv5 也有单独论文，标题就很直白：一个 500 万参数级别的专用 OCR 系统，挑战十亿参数级 VLM 在 OCR 任务上的表现。

我读下来，最值得记住的是三点。

第一，PP-OCRv5 的底层信念不是“参数越大越好”，而是“数据质量决定上限”。论文把训练数据拆成难度、准确性、多样性几个维度，强调高质量标注、困难样本、场景覆盖，而不是无脑堆模型规模。

这点对工程师很有用。OCR 不是聊天机器人，很多时候你要的是字框、坐标、置信度和稳定输出。一个小而专的两阶段 OCR 管线，在定位精度、延迟、成本和可部署性上，未必输给大 VLM。

第二，PaddleOCR 3.0 Technical Report 的重点，是把 OCR 从“读字”推进到“文档理解入口”。报告里把 3.x 的核心拆成 PP-OCRv5、PP-StructureV3、PP-ChatOCRv4。说白了就是三层需求：先识别文字，再恢复版面结构，再做信息抽取。

这正好对应 RAG 项目的真实链路。你不是把一张扫描 PDF 丢给大模型就完事了，你需要先让它变成可检索、可分块、可追溯的结构化文本。

第三，PaddleOCR-VL-1.6 的路线也很克制。它没有把 0.9B 模型继续堆大，而是从 PaddleOCR-VL-1.5 的薄弱区域入手：哪里不稳定、哪里数据覆盖少、哪里监督信号不可靠，就针对性补数据，再通过继续预训练、监督微调、强化学习做渐进式后训练。

这比“又大了十倍”更有参考价值。

官方数据里，PaddleOCR-VL-1.6 在 OmniDocBench v1.6 达到 96.33%，并且在 Real5-OmniDocBench 这种真实扰动场景上也刷新成绩。它重点补强的是表格、古籍、生僻字、印章、文字 spotting 和图表解析。

保姆级上手：先跑通最小闭环

AI智能体学习网站：ai-agent-phd.com

建议你不要一上来就装全家桶。先用最小环境跑通 PP-OCRv5，再决定要不要上文档解析或 VL。

新建环境：

python-mvenv.venv

Windows 激活：

.\.venv\Scripts\activate

macOS 或 Linux 激活：

source.venv/bin/activate

升级 pip：

python-mpipinstall-Upip

如果你只在 CPU 上试用：

python-mpipinstallpaddlepaddle==3.2.0-ihttps://www.paddlepaddle.org.cn/packages/stable/cpu/
python-mpipinstallpaddleocr

如果你是 Linux + CUDA 11.8：

python-mpipinstallpaddlepaddle-gpu==3.2.0-ihttps://www.paddlepaddle.org.cn/packages/stable/cu118/
python-mpipinstallpaddleocr

注意，PaddleOCR 3.x 依赖 PaddlePaddle 3.0 以上。也别在同一个环境里同时装 CPU 版和 GPU 版 PaddlePaddle，这种坑很常见，报错还不一定说人话。

跑一张图片：

paddleocrocr-i./demo.png\
--use_doc_orientation_classifyFalse\
--use_doc_unwarpingFalse\
--use_textline_orientationFalse\
--enginepaddle

Python 里这样写：

frompaddleocrimport PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    engine="paddle",
)

result = ocr.predict("./demo.png")
for res in result:
    res.print()
    res.save_to_img("output")
    res.save_to_json("output")

跑通这一步，你已经能得到识别文本、框位置、置信度和可视化结果。

PDF转Markdown，用PP-StructureV3

如果你的目标是“把资料喂给 AI”，普通 OCR 还不够。你更需要版面解析：标题、段落、表格、公式、图片、阅读顺序。

这时安装文档解析依赖：

python-mpipinstall"paddleocr[doc-parser]"

命令行跑 PP-StructureV3：

paddleocrpp_structurev3-i./paper.pdf\
--use_doc_orientation_classifyFalse\
--use_doc_unwarpingFalse\
--enginepaddle

Python 里这样写：

frompaddleocrimport PPStructureV3

pipeline = PPStructureV3(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    engine="paddle",
)

output = pipeline.predict(input="./paper.pdf")
for res in output:
    res.print()
    res.save_to_json(save_path="output")
    res.save_to_markdown(save_path="output")

这里我建议保留两份结果：Markdown 给 RAG 切块和预览，JSON 给后续追溯坐标、置信度、表格单元格位置。别只留 Markdown，不然线上出错时你很难定位是 OCR 错、版面错，还是后面的 LLM 错。

复杂文档，直接看PaddleOCR-VL-1.6

如果你要处理的是论文、扫描合同、历史文档、复杂表格、公式和图表，PP-StructureV3 已经很强，但 PaddleOCR-VL-1.6 更像“重武器”。

最短 Python 示例：

frompaddleocrimport PaddleOCRVL

pipeline = PaddleOCRVL(pipeline_version="v1.6")
output = pipeline.predict("document_image.png")

for res in output:
    res.print()
    res.save_to_json(save_path="output")
    res.save_to_markdown(save_path="output")

这里别硬拿普通 CPU 死磕。官方文档和 MCP 文档都倾向于把 PaddleOCR-VL 放在 GPU、推理服务或 API 场景里用。我的建议是：本地开发先用官方网站或 API 验证效果，确定它真的比 PP-StructureV3 更适合你的资料，再部署本地服务。

还有一个现实建议：如果文档是大量标准票据、固定版式合同、业务单据，不一定非要上 VL。很多业务场景里，PP-OCRv5 加规则、模板或轻量信息抽取，成本更低，也更可控。

选型表：别把所有问题都交给一个模型

一句话：能用 PP-OCRv5 解决的，别急着上 VLM；确实遇到复杂版面，再升级到 PP-StructureV3 或 PaddleOCR-VL。

最容易踩的坑

第一个坑是版本。PaddleOCR 3.x 的 API 和 2.x 有明显变化，老教程里 use_angle_cls、det_model_dir 这一类参数，在新版本里可能已经有新的名字。官方代码里还做了兼容映射，但新项目别照着旧文章复制。

第二个坑是模型下载。3.x 曾经把默认下载源从 BOS 切到 HuggingFace，也支持通过环境变量切回 BOS。国内网络环境下，如果下载卡住，先查模型源，不要上来就怀疑代码。

第三个坑是把 OCR 当万能文档理解。OCR 的结果再好，也只是文档入口。做 RAG 时，要按标题、页码、表格和段落去切块；做问答时，要把 JSON 坐标和原图页码留住；做审核时，要把低置信度字段单独拉出来复核。

第四个坑是过早本地部署 VL。PaddleOCR-VL-1.6 很香，但它不是“随便一台办公电脑就能丝滑批处理几千页 PDF”的工具。生产上要么走服务化，要么走官方 API，要么先用 PP-StructureV3 扛主流程。

最终判断

PaddleOCR 值得收藏，也值得进生产候选清单。

它强在三件事：模型体系完整，工程入口足够多，论文路线没有盲目迷信大模型。PP-OCRv5 证明了小模型在专用 OCR 上仍有生命力；PP-StructureV3 把 OCR 拉到结构化文档解析；PaddleOCR-VL-1.6 则补上复杂文档场景的上限。

但它不是无脑替代所有文档 AI 工具。你需要语义推理、跨文档总结、合同风险判断，后面还是要接 LLM。PaddleOCR 最适合做那道“入口关”：把脏 PDF、扫描件、图片，尽量干净地变成 AI 能读、能检索、能追溯的数据。

实操建议很简单：

• 个人试用：paddleocr + PP-OCRv5，先跑图片。
• 做知识库：加 paddleocr[doc-parser]，用 PP-StructureV3 输出 Markdown 和 JSON。
• 做复杂文档解析：评估 PaddleOCR-VL-1.6，优先用 GPU 服务或官方 API。
• 做前端产品：看 PaddleOCR.js。
• 做 Agent 工作流：看 MCP Server 和 Agent Skills。

坦白讲，如果你正在做 RAG、企业知识库、合同解析、票据自动化，PaddleOCR 是那种应该先跑一遍样例、再决定要不要引入主链路的项目。

参考入口：

• GitHub 仓库：https://github.com/PaddlePaddle/PaddleOCR
• 官方文档：https://www.paddleocr.ai/latest/
• 官方体验入口：https://www.paddleocr.com
• PaddleOCR 3.0 Technical Report：https://arxiv.org/abs/2507.05595
• PP-OCRv5 论文：https://arxiv.org/abs/2603.24373
• PaddleOCR-VL-1.6 技术报告：https://arxiv.org/abs/2606.03264
• PaddleOCR-VL-1.6 模型页：https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.6