PaddleOCR 从入门到实战：PP-OCRv6 超轻量 OCR 全流程指南（环境搭建、推理识别、自定义训练与避坑）

一、写在前面：为什么是 PaddleOCR

PaddleOCR 是百度飞桨（PaddlePaddle）开源的多语言 OCR 与文档智能引擎，覆盖文本检测、文字识别、版面分析、表格还原、关键信息抽取、文档结构理解与结构化输出的完整链路，支持 110+ 语种，服务覆盖 170 多个国家和地区html5.qq.com。截至 2026 年，其在 GitHub 上的 Star 数已突破 8.22 万，超越谷歌 Tesseract OCR，成为全球最受关注的开源 OCR 项目之一jjckb.cn+1。

最新一代 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.com+1。

PaddleOCR 已被 Dify、RAGFlow、Cherry Studio、MinerU、UmiOCR 等项目广泛集成，成为 RAG、Agent 与智能文档工作流的底层组件csdn.net。

二、PaddleOCR 核心架构与能力总览

PP-OCRv6 三档模型对比

PP-OCRv6_medium 相比 PP-OCRv5_server，检测 Hmean 提升 +4.6%，识别准确率提升 +5.1%modelscope.cn+1。

其核心架构创新包括：LCNetV4（MetaFormer 风格 + 结构重参数化的统一骨干网络）、RepLKFPN（含膨胀可重参数化深度卷积的检测颈部）、EncoderWithLightSVTR（融合局部-全局注意力与加性跳跃连接的识别颈部）

三、环境搭建与安装

3.1 版本依赖关系

PaddleOCR 3.x 依赖于 3.0 及以上版本的 PaddlePaddle 框架，且引入了重要的接口变动，基于 2.x 编写的旧代码很可能无法直接在 3.x 上运行paddleocr.ai+1。

3.2 安装推理引擎

CPU 端安装：

python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

GPU 端安装（以 Linux + CUDA 11.8 为例，其他平台参考飞桨官网安装文档）：

python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

PaddleOCR 3.x 还支持通过 Transformers 作为推理后端：

python -m pip install "transformers>=5.8.0"

3.3 安装 paddleocr

# 完整功能安装
python -m pip install "paddleocr[all]"
# 或最小化安装
python -m pip install paddleocr

3.4 验证安装

python -c "import paddleocr; print(paddleocr.__version__)"

建议使用 conda 创建独立虚拟环境以避免依赖冲突：

conda create -n paddle_ocr python=3.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 paddle

PP-StructureV3 文档解析：

paddleocr pp_structurev3 -i ./pp_structure_v3_demo.png \
    --use_doc_orientation_classify False \
    --use_doc_unwarping False \
    --engine paddle

4.2 Python 脚本使用

通用 OCR 识别（基于 3.x 新 API predict）：

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    engine="paddle",
)
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]]], dtype=int16),
    'rec_texts': ['www.997700', '登机牌', 'BOARDING', 'PASS', '航班FLIGHT', '福州', 'FUZHOU', ...],
    'rec_scores': array([0.67582953, ..., 0.97418666]),
    'rec_polys': array([[[3, 10], ..., [4, 30]], ...], dtype=int16)
}}

单模块调用：

from paddleocr import TextDetection, TextRecognition

# 文本检测
det_model = TextDetection(engine="paddle")
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(engine="paddle")
output = rec_model.predict(input="general_ocr_rec_001.png")
for res in output:
    res.print()

五、核心功能实战

5.1 通用场景文字识别

PaddleOCR 在通用场景下能精准识别电子设备屏幕、复杂背景、低分辨率图像中的数字、字母和特殊符号csdn.net。关键参数调优：

ocr = PaddleOCR(
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    text_det_thresh=0.3,           # 检测阈值
    text_det_box_thresh=0.6,       # 框阈值
    text_det_unclip_ratio=1.5,     # 检测框扩展比例
    text_rec_score_thresh=0.5,     # 识别置信度过滤
    engine="paddle",
)

5.2 多语言识别

PP-OCRv6 单模型可覆盖 50 种语言，无需为不同语种频繁切换模型modelscope.cn。通过 lang 参数切换：

# 中文
ocr = PaddleOCR(lang="ch")
# 英文
ocr = PaddleOCR(lang="en")
# 日文
ocr = PaddleOCR(lang="japan")
# 多语言模式
ocr = PaddleOCR(lang="multi")

5.3 版面分析与表格识别（PP-StructureV3）

PP-StructureV3 驱动的版面结构分析支持表格（含嵌套）、公式、印章、图表等的定位与还原，并提供 Markdown、JSON、DOCX 导出html5.qq.com。

from paddleocr import PPStructure

table_engine = PPStructure(recovery=True)
result = table_engine("document.pdf")

for line in result:
    print(line)

输出可进一步导出为 Excel，适合财务报表解析、科研论文表格提取，复杂合并单元格识别准确率可达 92% 以上gitcode.com。

5.4 关键信息抽取（KIE）

对于身份证、发票、合同等结构化场景，PaddleOCR 提供两种思路：

1. 直接使用 SER：将关键字段标注为 name_key / name_value 等类别，识别后取对应类别文本即可。
2. 联合 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.com+1。这是 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", encoding="utf-8")
val_txt = open("val.txt", "w", encoding="utf-8")
with open("Label.txt", "r", encoding="utf-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.net+1：

Global:
  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.pdparams

6.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 环境与安装类

7.2 模型与推理类

7.3 性能优化建议

八、部署方式与生态集成

具体包括：

• 高性能推理：支持 Paddle Inference 与 ONNX Runtime 后端，高性能推理支持 CUDA 12paddleocr.ai
• C++ 本地部署：PP-OCRv5/v6 C++ 方案已支持 Linux 与 Windows，精度与 Python 实现一致paddleocr.ai
• 服务化部署：官方开源高稳定性服务化方案，支持自定义 Docker 镜像与 SDKpaddleocr.ai
• 跨端部署：Android、iOS、浏览器端（PaddleOCR.js）paddleocr.ai
• 多硬件支持：NVIDIA GPU、昆仑芯 XPU、华为昇腾 NPU、海光 DCU、Intel Arc GPU、Apple Silicon、AMD GPU 等paddleocr.ai
• 生态集成：MCP 服务器、Agent Skills，与 RAGFlow、MinerU、Dify 等深度集成paddleocr.ai+1

PaddleOCR-VL 还支持通过 vLLM 进行服务化部署：

docker run --rm --gpus device=0 --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 vllm

csdn.net

九、总结与最佳实践

PaddleOCR 的价值，已从「把字识别出来」演进为「把原始图片和 PDF 文档，尽可能稳定地转换成结构化、可检索、可进入大模型流程的数据」csdn.net。基于本文的实战梳理，落地时建议遵循以下路径：

1. 环境隔离：始终用 conda/venv 创建独立环境，避免依赖冲突。
2. 版本对齐：PaddleOCR 3.x 必须搭配 PaddlePaddle 3.0+；CUDA 版本与驱动、paddlepaddle-gpu 严格对应。
3. 先推理后训练：先用官方预训练模型跑通推理链路，确认场景适配后再考虑微调。
4. 按需选模型：浏览器/边缘端选 tiny，移动端选 small，服务端选 medium；不需要文档预处理模块时果断关闭以换性能。
5. 数据为王：垂类场景微调时，真实数据 + 合成数据 + 通用数据按 1:1:1 配比，单字符至少出现 200 张以上。
6. 结构化输出：面向 RAG / Agent 时优先使用 PP-StructureV3 或 PaddleOCR-VL，输出 Markdown/JSON 而非纯文本。
7. 多端部署：训练一次，通过 ONNX / C++ / Lite /.js 多端落地，兼顾精度与延迟。

随着 PP-OCRv6 与 PaddleOCR-VL 的持续推进，PaddleOCR 正从一款强大的 OCR 工具，走向真正意义上的文档 AI 基础设施——在 OCR 仍然是文档 AI 入口的前提下，它有能力成为下一步智能处理的可靠起点csdn.net。

参考资料

• PaddleOCR 官方文档：https://www.paddleocr.ai/
• PaddleOCR GitHub：https://github.com/PaddlePaddle/PaddleOCR
• PP-OCRv6 模型库：https://huggingface.co/collections/PaddlePaddle/pp-ocrv6
• 飞桨官网安装文档：https://www.paddlepaddle.org.cn/install/quick