PaddleOCR PP-StructureV3 本地部署指南

将扫描件 PDF / 图片转换为可编辑 Word(DOCX),表格为真表格(非图片),全部本地推理,无需联网调 API。

环境要求

项目	要求	说明
操作系统	Windows 10/11 x64	Linux/macOS 也可,安装命令略有不同
Python	3.8 – 3.12	3.13 太新,不兼容 PaddlePaddle 3.x
GPU(可选)	NVIDIA + CUDA 12.x	PaddlePaddle 3.x 的 Windows GPU 包尚未发布,目前只能用 CPU
磁盘空间	≥ 2GB	模型缓存约 1.1GB,包约 500MB
网络	首次需要联网	模型自动下载,之后离线可用

关于 GPU 的说明

截至 2026 年 9 月,PaddlePaddle 在 Windows 上只有 CPU 版 3.x(paddlepaddle 3.0.0),GPU 版最高仅 2.6.2(不支持 PaddleOCR 3.x)。Linux 上有 3.x GPU 包。Windows 用户暂时走 CPU,轻量配置下约数秒/页,可接受。

等 PaddlePaddle 发布 Windows 3.x GPU 包后,只需将脚本中 device="cpu" 改为 device="gpu" 即可启用 GPU 加速。

安装步骤

1. 确认 Python 环境

python --version
# 需要 3.8–3.12,如果默认 Python 是 3.13,用 conda 创建/使用 3.12 环境

如果已有 Anaconda,可以创建专用环境:

conda create -n paddleocr python=3.12 -y
conda activate paddleocr

或使用已有的 3.12 环境,直接指定 Python 路径即可(后续命令中用完整路径调用)。

2. 安装 PaddlePaddle 3.0.0(CPU 版)

python -m pip install paddlepaddle==3.0.0

Linux GPU 版(如有 NVIDIA GPU + CUDA 11.8):

python -m pip install paddlepaddle-gpu==3.0.0 -f https://www.paddlepaddle.org.cn/whl/linux/gpu/avx/cuda118/dist.html

3. 安装 paddleocr(含文档解析依赖)

python -m pip install "paddleocr[doc-parser]"

doc-parser 依赖组包含 PP-StructureV3 所需的全部模块(版面检测、表格识别、公式识别等)。

4. 安装 python-docx(DOCX 导出必需)

python -m pip install python-docx

注意:PaddleOCR 3.7.0 的 save_to_word 功能依赖 python-docx,但 doc-parser 依赖组未自动拉取,需手动安装。漏装会报 ModuleNotFoundError: No module named 'docx'。

5. 验证安装

python -c "from paddleocr import PPStructureV3; print('OK')"

输出 OK 即安装成功。如果出现 urllib3 ... doesn't match 警告,是已有包版本冲突的无害警告,不影响功能。

转换脚本

以下脚本支持单张图片或 PDF 输入,输出 DOCX / Markdown / JSON 三种格式。

#!/usr/bin/env python3
"""扫描件 PDF/图片 → 可编辑 Word(DOCX)转换脚本

使用 PaddleOCR PP-StructureV3,执行完整 OCR + 表格结构识别,
生成可编辑 Word 表格(非图片插入)。

用法:
    python convert.py &#x3C;input.pdf|input.png> [output_dir]

    input:  扫描件 PDF 或图片(png/jpg)
    output: 输出目录(默认 ./output)

首次运行自动下载模型(约 1.1GB,缓存于 ~/.paddlex/),之后离线可用。
"""

import sys
import os
from pathlib import Path


def main():
    if len(sys.argv) &#x3C; 2:
        print(f"Usage: {sys.argv[0]} &#x3C;input.pdf|input.png> [output_dir]", file=sys.stderr)
        sys.exit(2)

    input_file = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else "./output"

    if not os.path.exists(input_file):
        print(f"Error: input file not found: {input_file}", file=sys.stderr)
        sys.exit(2)

    output_path = Path(output_dir)
    output_path.mkdir(parents=True, exist_ok=True)

    # 抑制 urllib3/chardet 版本不匹配的无害警告
    import warnings
    warnings.filterwarnings("ignore", message=".*urllib3.*doesn't match.*")

    from paddleocr import PPStructureV3

    # ── PP-StructureV3 流水线配置 ──
    # device="cpu":              Windows 上 PaddlePaddle 3.x 无 GPU 包,用 CPU
    # use_doc_orientation_classify: 扫描件方向校正(旋转/倒置)
    # use_doc_unwarping:            扫描件弯曲校正(展平卷边页面)
    # use_table_recognition:        表格结构识别(核心功能,还原行列+合并单元格)
    # use_formula_recognition=False: 跳过公式识别模型(~1.5GB),如无公式可关
    # use_chart_recognition=False:   跳过图表解析模块(~1.4GB),如无图表可关
    pipeline = PPStructureV3(
        device="cpu",
        use_doc_orientation_classify=True,
        use_doc_unwarping=True,
        use_table_recognition=True,
        use_formula_recognition=False,
        use_chart_recognition=False,
    )

    print(f"Processing: {input_file}", file=sys.stderr)
    print(f"Output dir: {output_path}", file=sys.stderr)

    output = pipeline.predict(input=input_file)

    for res in output:
        res.print()
        res.save_to_json(save_path=str(output_path))
        res.save_to_markdown(save_path=str(output_path))
        res.save_to_word(save_path=str(output_path))

    print(f"\nDone! Files saved to: {output_path}", file=sys.stderr)
    for f in sorted(output_path.glob("*")):
        print(f"  {f.name} ({f.stat().st_size} bytes)")


if __name__ == "__main__":
    main()

批量处理

如需遍历文件夹下所有 PDF:

import glob
from paddleocr import PPStructureV3

pipeline = PPStructureV3(
    device="cpu",
    use_doc_orientation_classify=True,
    use_doc_unwarping=True,
    use_table_recognition=True,
    use_formula_recognition=False,
    use_chart_recognition=False,
)

for pdf_path in sorted(glob.glob("./pdfs/*.pdf")):
    print(f"Processing: {pdf_path}")
    output = pipeline.predict(input=pdf_path)
    for res in output:
        res.save_to_word(save_path="./output")

使用方法

# 单文件转换
python convert.py 扫描件.pdf output

# 图片也支持
python convert.py 扫描页.png output

# 输出到指定目录
python convert.py 验收单2025.pdf ./result

输出目录下会生成:

文件名.docx — 可编辑 Word,表格为真表格
文件名.md — Markdown(表格用 HTML <table>)
文件名_res.json — 含坐标的结构化 JSON
imgs/ — 提取的图片

处理流程说明

PP-StructureV3 是一条多模块小模型流水线(非大语言模型),各阶段独立:

输入 PDF/图片
    │
    ├─ ① 方向校正 (PP-LCNet_x1_0_doc_ori)        判断页面是否旋转/倒置
    ├─ ② 弯曲校正 (UVDoc)                         展平卷边/弯曲页面
    ├─ ③ 版面检测 (PP-DocLayout_plus-L)           切分区域:标题/正文/表格/图片…
    ├─ ④ 文字行方向 (PP-LCNet_x1_0_textline_ori)  判断横排/竖排
    ├─ ⑤ OCR 文字识别 (PP-OCRv5_server_det+rec)   检测文字位置 → 识别内容
    │
    ├─ ⑥ 表格识别(仅对"表格"区域执行)
    │     ├─ 表格分类 (PP-LCNet_x1_0_table_cls)        判断有线/无线表格
    │     ├─ 表格结构 (SLANeXt_wired / SLANet_plus)    还原行列+合并单元格
    │     ├─ 单元格检测 (RT-DETR-L_table_cell_det)     精确定位每个单元格
    │     └─ 表格内 OCR                               把文字回填到单元格
    │
    └─ ⑦ 输出组装 → DOCX / Markdown / JSON

全部在本地推理,不联网、不调云 API。模型缓存于 ~/.paddlex/official_models/。

模型清单

首次运行自动下载,缓存路径 C:\Users\<用户名>\.paddlex\official_models\:

模型	用途	大小
PP-LCNet_x1_0_doc_ori	方向校正	7 MB
UVDoc	弯曲校正	30 MB
PP-DocLayout_plus-L	版面检测	126 MB
PP-DocBlockLayout	版面块检测	—
PP-LCNet_x1_0_textline_ori	文字行方向	1 MB
PP-OCRv5_server_det	文字检测	109 MB
PP-OCRv5_server_rec	文字识别	182 MB
PP-LCNet_x1_0_table_cls	表格分类	7 MB
SLANeXt_wired	有线表格结构	349 MB
SLANet_plus	无线表格结构	349 MB
RT-DETR-L_wired_table_cell_det	有线表格单元格	124 MB
RT-DETR-L_wireless_table_cell_det	无线表格单元格	124 MB
合计		~1.1 GB

公式识别(PP-FormulaNet,~1.5GB)和图表解析(PP-Chart2Table,~1.4GB)默认关闭,需要时在脚本中把对应参数设为 True。

常见问题

列错位(文本跳列)

扫描件表格边框模糊或断裂时,SLANeXt 表格结构模型可能把相邻列的归属判反。这是模型固有局限,常见缓解手段:

对扫描件先做二值化/去噪增强边框再输入
调高 layout_threshold(默认 0.5)让边框检测更严格
尝试切换有线/无线表格模型

报错 `No module named 'docx'`

缺少 python-docx,手动安装:

python -m pip install python-docx

报错 `No matching distribution found for paddlepaddle-gpu==3.0.0`

Windows 上 PaddlePaddle 3.x GPU 包尚未发布。改用 CPU 版:

python -m pip install paddlepaddle==3.0.0

`信息: 用提供的模式无法找到文件`

Windows 系统的 where 命令提示,PaddleX 内部检查系统工具时搜不到。无害,不影响任何功能。

ccache 警告

ccache 是 C++ 编译加速工具,仅在使用自定义编译算子时才有用。预编译推理模型不需要,忽略即可。

numpy 版本冲突

PaddlePaddle 3.0 可能与 numpy 2.x 有兼容问题。如遇到,降级 numpy:

python -m pip install "numpy&#x3C;2"

关键参数速查

参数	默认值	说明
`device`	自动	`"cpu"` / `"gpu:0"` / `"gpu:0,1"`
`use_doc_orientation_classify`	`False`	扫描件方向校正,建议开启
`use_doc_unwarping`	`False`	扫描件弯曲校正,建议开启
`use_table_recognition`	`True`	表格识别,核心功能
`use_formula_recognition`	`True`	公式识别,无公式可关(省 1.5GB)
`use_chart_recognition`	`False`	图表转表格,无图表可关
`use_seal_recognition`	`False`	印章文字识别
`lang`	中英文	设 `"en"` 用英文模型,纯英文文档精度更高
`layout_threshold`	`0.5`	版面检测置信度阈值,调高更严格
`text_det_limit_side_len`	`960`	文字检测图像边长限制,降到 1200 可提速

版本信息

组件	版本
PaddlePaddle	3.0.0 (CPU)
paddleocr	3.7.0
paddlex	3.7.2
python-docx	1.2.0
License	Apache 2.0

文档生成时间:2026-09-12

PaddleOCR PP-StructureV3 本地部署指南

PaddleOCR PP-StructureV3 本地部署指南

环境要求

关于 GPU 的说明

安装步骤

1. 确认 Python 环境

2. 安装 PaddlePaddle 3.0.0(CPU 版)

3. 安装 paddleocr(含文档解析依赖)

4. 安装 python-docx(DOCX 导出必需)

5. 验证安装

转换脚本

批量处理

使用方法

处理流程说明

模型清单

常见问题

列错位(文本跳列)

报错 No module named 'docx'

报错 No matching distribution found for paddlepaddle-gpu==3.0.0

信息: 用提供的模式无法找到文件

ccache 警告

numpy 版本冲突

关键参数速查

版本信息

报错 `No module named 'docx'`

报错 `No matching distribution found for paddlepaddle-gpu==3.0.0`

`信息: 用提供的模式无法找到文件`