PaddlePaddle/PaddleOCR · 上手攻略

• 仓库：PaddlePaddle/PaddleOCR
• 链接：https://github.com/PaddlePaddle/PaddleOCR
• 分类：multimodal（文档 OCR / 文档解析）
• 作者：Jay
• 更新：2026-07-07

是什么

PaddleOCR 是百度飞桨（PaddlePaddle）团队开源的多功能 OCR 与文档解析工具包，GitHub Stars 超 8.4 万，被 Dify、RAGFlow、Cherry Studio 等主流项目深度集成。它不只是一套光学字符识别引擎，更是一个覆盖"图片→结构化数据"完整流程的文档 AI 基础设施。

当前稳定版本为 PaddleOCR 3.6.0（2026-05-28），包含三大核心模块：

解决什么问题

1. 图片/PDF → 结构化文本：将扫描件、照片、截图转化为可编辑文本或 JSON
2. 多语言文档处理：支持 100+ 语言，单一模型覆盖中英日韩等主流语言
3. 复杂文档解析：表格、公式、印章、古文、稀有字符
4. 与 LLM 无缝对接：输出 Markdown / JSON，直接喂给 RAG 或 Agent 流水线

快速安装

环境要求

• Python ≥ 3.8（建议 3.10+）
• PaddlePaddle ≥ 3.1.0
• CUDA 11.2+（GPU 推理，推荐）/ 仅 CPU 亦可

安装步骤

# 1. 安装 PaddlePaddle（GPU 版，以 CUDA 11.8 为例）
pip install paddlepaddle-gpu==3.1.1 -i https://mirror.baidu.com/pypi/simple

# 2. 安装 PaddleOCR（核心包）
pip install "paddleocr>=3.6.0"

# 3. 分离依赖（可选，仅基础文字识别不需要全文安装）
# 基础识别：无需额外安装
# 文档解析功能：额外安装
pip install paddleocr[layout] paddleocr[table] paddleocr[formula]

⚠️ 注意：百度镜像源 (mirror.baidu.com) 在部分网络环境下可用，如遇超时可换回官方 PyPI：pip install paddlepaddle-gpu==3.1.1 -i https://pypi.org/simple

核心用法

1. PP-OCRv6：通用文字识别（最常用）

from paddleocr import PaddleOCR

# 初始化（首次运行自动下载模型，约 150MB）
ocr = PaddleOCR(
    use_angle_cls=True,   # 自动旋转纠正
    lang='ch',            # 'ch'/'en'/'japan'/'korean'，或 'multi_lang'（50语言）
    use_gpu=True,         # GPU 加速，设为 False 则用 CPU
    show_log=False,       # 关闭日志
)

# 识别单张图片
result = ocr.ocr("path/to/image.jpg", cls=True)

# 遍历结果
for line in result[0]:
    box, (text, confidence) = line
    print(f"文字: {text}, 置信度: {confidence:.2f}")
    # 输出示例：文字: 百度, 置信度: 0.98

命令行快速调用（无需写代码）：

# 图片文件
paddleocr --image_dir ./demo.jpg --lang ch

# 文件夹批量处理
paddleocr --image_dir ./images/ --lang ch --batch_size 10

# 输出为 JSON
paddleocr --image_dir ./demo.jpg --lang ch --use_json=True

2. PaddleOCR-VL：文档理解（2026 版旗舰）

# 文档整页解析，返回 Markdown
from paddleocr import PaddleOCR

ocr_vl = PaddleOCR(
    use_ocr_vl=True,          # 启用 PaddleOCR-VL 模式
    use_gpu=True,
    lang='ch',
)

# 图片路径或 URL
result = ocr_vl.ocr("path/to/document.jpg", cls=True)

# 返回结构化结果（文字块、表格位置、公式等）
for line in result[0]:
    print(line)

⚠️ 注意：PaddleOCR-VL 需要更大的显存（建议 ≥ 4GB GPU 显存），tiny 模型可降至 ~2GB。版本 3.6.0 中模型已上传 HuggingFace，可从 PaddlePaddle/PaddleOCR-VL-1.6 直接加载。

3. PP-StructureV3：复杂文档结构化

from paddleocr import PaddleOCR
from ppstructure import analyze_documents

# 分析文档（版面 + 表格 + 公式）
results = analyze_documents(
    "path/to/paper.pdf",
    ocr=True,
    layout=True,
    table=True,
    formula=True,
)

# results 包含：
# - html：原始版面结构
# - markdown：融合文字+表格+公式的 Markdown
# - json：完整坐标与属性

4. Python API 进阶：批量 + 输出控制

from paddleocr import PaddleOCR
from tqdm import tqdm

ocr = PaddleOCR(use_angle_cls=True, lang='ch', use_gpu=True, show_log=False)

import os
image_dir = "./docs/"
outputs = []

for img_name in tqdm(os.listdir(image_dir)):
    if img_name.endswith(('.jpg', '.png', '.pdf')):
        result = ocr.ocr(os.path.join(image_dir, img_name))
        outputs.append({
            "file": img_name,
            "texts": [line[1][0] for line in result[0]] if result[0] else [],
        })

# 导出 JSON
import json
with open("ocr_results.json", "w", encoding="utf-8") as f:
    json.dump(outputs, f, ensure_ascii=False, indent=2)

典型适用场景

坑与注意

1. 首次运行慢：首次调用 PaddleOCR() 会自动下载模型文件（100-300MB），需确保网络畅通或提前手动下载。

2. CUDA 版本不匹配：paddlepaddle-gpu 对 CUDA 版本敏感。如果报 CUDA error，确认 nvcc --version 与安装的 paddlepaddle-gpu 版本对应（推荐 paddlepaddle-gpu==3.1.1 + CUDA 11.8）。

3. CPU 推理速度：完整 PP-OCRv6 在 CPU 上单图约 0.5-2s，GPU 可降至 0.1s 以内。批量处理优先用 GPU。

4. 表格识别精度：PP-StructureV3 的表格识别对无线框表格效果较差，建议配合后处理校验。

5. PaddleOCR-VL 显存：1.6B 参数版（VL-1.6）需较大显存；服务器部署建议用 medium 或 small 档位。

6. 模型下载源：默认从百度源下载模型，HuggingFace 镜像为 https://hf-mirror.com，可在 huggingface.co/PaddlePaddle 手动下载。

7. Docker 部署：官方提供 PaddleOCR Docker 镜像，避免环境依赖问题： bash docker pull paddlepaddle/paddleocr:latest docker run -it --rm -v $(pwd):/workspace paddlepaddle/paddleocr python your_script.py

与同类对比

一句话总结：如果你需要的是"把各种图片/PDF 变成 LLM 能用的结构化数据"，PaddleOCR 是开源最优解；如果只是简单截图文字提取，EasyOCR 更轻量。

一句话推荐结论

PaddleOCR 是当前开源生态中功能最完整、精度最高的文档 OCR + 解析方案，尤其适合 RAG/Agent 流水线中"非结构化文档 → LLM 可读数据"这一核心环节，推荐所有做文档 AI 的开发者优先掌握。