企业官网建设流程全解析

PaddleOCR 版面恢复（Layout Recovery）实战指南：PDF/图片一键转 Word 的两种技术路线

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR

版面恢复（Layout Recovery）是 PaddleOCR 的 PP-Structure 体系中面向文档再编辑场景的核心能力：它将输入的图片、PDF 内容像原文档那样保持段落与顺序不变地输出到 Word（docx）文档中，打通"扫描件/PDF → 可编辑文档"的最后一环。本篇指南以 ppstructure/recovery/README_ch.md 为骨架，结合仓库内 predict_system.py、recovery_to_doc.py 等源码实现，完整讲解两种版面恢复方法的原理、安装、模型下载与命令行实操，读完你即可对标准 PDF 与图片格式 PDF/扫描图分别选择最合适的恢复方案并落地运行。

1. 版面恢复是什么：两种方法对比

版面恢复的目标是"像原文档那样排列着、段落不变、顺序不变"地将输入内容输出到 Word 文档中。PaddleOCR 提供了 2 种版面恢复方法，可根据输入 PDF 的格式进行选择：

• 标准 PDF 解析（输入须为标准 PDF）：基于 Python 的 pdf 转 word 库 pdf2docx 进行优化。该方法通过 PyMuPDF 获取页面元素，然后利用规则解析章节、段落、表格等布局及样式，最后通过 python-docx 将解析的内容元素重建到 Word 文档中。
• 图片格式 PDF 解析（输入可为标准 PDF 或图片格式 PDF）：结合版面分析、表格识别技术，从而更好地恢复图片、表格、标题等内容，支持中、英文 PDF 文档和文档图片格式的输入文件。

两种方法的输入格式与适用场景对比如下：

从源码层面看，两种方法在 predict_system.py 中分别走两条分支：标准 PDF 解析直接调用pdf2docx.converter.Converter转换并保存为{img_name}_api.docx；图片格式 PDF 解析则走完整的版面分析 → OCR/表格识别 → 重建 docx 的管线。

2. 安装与环境准备

2.1 安装 PaddlePaddle

python3 -m pip install --upgrade pip # 您的机器安装的是 CUDA9 或 CUDA10，请运行以下命令安装 python3 -m pip install "paddlepaddle-gpu" -i https://mirror.baidu.com/pypi/simple # 您的机器是 CPU，请运行以下命令安装 python3 -m pip install "paddlepaddle" -i https://mirror.baidu.com/pypi/simple

更多需求，请参照 PaddlePaddle 官方安装文档中的说明进行操作（不同 CUDA 版本与操作系统对应不同安装命令）。

2.2 安装 PaddleOCR 与 recovery 依赖

（1）下载源码

git clone https://github.com/PaddlePaddle/PaddleOCR

（2）安装 recovery 的 requirements

版面恢复最终导出为 docx 文件，因此需要安装 Python 处理 Word 文档的 python-docx API；同时处理 pdf 格式的输入文件，需要安装 PyMuPDF API（要求 Python >= 3.7）。通过如下命令安装全部库：

python3 -m pip install -r ppstructure/recovery/requirements.txt

查看 ppstructure/recovery/requirements.txt 可知其依赖包括：

• python-docx：生成 docx 文档的核心库；
• beautifulsoup4：用于解析表格识别结果中的 HTML 结构（见下文 HtmlToDocx 实现）；
• fonttools>=4.43.0：字体解析处理，用于还原文档字体信息；
• fire>=0.3.0：命令行解析辅助。

使用 pdf2docx 库解析的方式恢复文档，还需要安装 PaddleOCR 优化后的 pdf2docx：

wget https://paddleocr.bj.bcebos.com/whl/pdf2docx-0.0.0-py3-none-any.whl pip3 install pdf2docx-0.0.0-py3-none-any.whl

3. 方法一：使用标准 PDF 解析进行版面恢复

use_pdf2docx_api表示使用 PDF 解析的方式进行版面恢复。该方式通过 whl 包即可快速使用：

# 安装 paddleocr，推荐使用 2.6 版本 pip3 install "paddleocr>=2.6" paddleocr --image_dir=ppstructure/docs/recovery/UnrealText.pdf --type=structure --recovery=true --use_pdf2docx_api=true

也支持通过命令行脚本的方式：

python3 predict_system.py \ --image_dir=ppstructure/docs/recovery/UnrealText.pdf \ --recovery=True \ --use_pdf2docx_api=True \ --output=../output/

从 predict_system.py 的实现可以看到，当--recovery与--use_pdf2docx_api同时为 True 且输入为 PDF（flag_pdf为真）时，程序直接实例化pdf2docx.converter.Converter，将整个 PDF 转换后保存为{img_name}_api.docx，不再经过版面分析/OCR 流程。这也是其"每一页内容恢复后仍在同一页"这一优势的来源——它直接读取 PDF 的矢量元素而非重新识别。需要注意的是：该方法要求输入为标准（文本型）PDF，扫描件等图片型 PDF 不适用，且对复杂表格和部分图片的恢复效果有限。

4. 方法二：使用图片格式 PDF 解析进行版面恢复

4.1 工作原理

该方法先通过版面分析对图片/pdf 形式的文档进行区域划分，定位其中的关键区域（如文字、表格、图片等），记录每个区域的位置、类别、区域像素值信息；随后对不同的区域分别处理：

• 文字区域：直接进行 OCR 检测和识别，在版面信息基础上增加 OCR 检测框坐标和文本内容信息；
• 表格区域：进行表格识别，记录表格 html 和文字信息；
• 图片区域：直接保存图片。

最终通过版面信息、OCR 检测和识别结果、表格信息、保存的图片，对测试图片完成版面恢复。该调用链在 predict_system.py 中体现为：StructureSystem输出结构化结果后，依次调用sorted_layout_boxes（区域排序）、convert_info_docx（生成 docx），若开启--recovery_to_markdown还会调用convert_info_markdown（生成 markdown）。

同样提供 whl 包形式的快速使用方式：

# 安装 paddleocr，推荐使用 2.6 版本 pip3 install "paddleocr>=2.6" # 中文测试图 paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure --recovery=true # 英文测试图 paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure --recovery=true --lang='en' # pdf 测试文件 paddleocr --image_dir=ppstructure/docs/recovery/UnrealText.pdf --type=structure --recovery=true --lang='en'

4.2 下载模型

如果输入为英文文档类型，下载 OCR 检测和识别、版面分析、表格识别的英文模型：

cd PaddleOCR/ppstructure # 下载模型 mkdir inference && cd inference # 下载英文超轻量 PP-OCRv3 检测模型并解压 wget https://paddleocr.bj.bcebos.com/PP-OCRv3/english/en_PP-OCRv3_det_infer.tar && tar xf en_PP-OCRv3_det_infer.tar # 下载英文超轻量 PP-OCRv3 识别模型并解压 wget https://paddleocr.bj.bcebos.com/PP-OCRv3/english/en_PP-OCRv3_rec_infer.tar && tar xf en_PP-OCRv3_rec_infer.tar # 下载英文表格识别模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/en_ppstructure_mobile_v2.0_SLANet_infer.tar tar xf en_ppstructure_mobile_v2.0_SLANet_infer.tar # 下载英文版面分析模型 wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_infer.tar tar xf picodet_lcnet_x1_0_fgd_layout_infer.tar cd ..

如果输入为中文文档类型，在仓库 README 的 PP-OCR 系列模型列表中下载中文超轻量文本检测和识别模型，在 PP-Structure 模型列表中下载对应的表格识别模型与版面分析模型（中文版面分析模型对应 CDLA 数据集，需配合下文layout_cdla_dict.txt字典使用）。

4.3 执行版面恢复

使用下载的模型恢复给定文档的版面，以英文模型为例：

python3 predict_system.py \ --image_dir=./docs/table/1.png \ --det_model_dir=inference/en_PP-OCRv3_det_infer \ --rec_model_dir=inference/en_PP-OCRv3_rec_infer \ --rec_char_dict_path=../ppocr/utils/en_dict.txt \ --table_model_dir=inference/en_ppstructure_mobile_v2.0_SLANet_infer \ --table_char_dict_path=../ppocr/utils/dict/table_structure_dict.txt \ --layout_model_dir=inference/picodet_lcnet_x1_0_fgd_layout_infer \ --layout_dict_path=../ppocr/utils/dict/layout_dict/layout_publaynet_dict.txt \ --vis_font_path=../doc/fonts/simfang.ttf \ --recovery=True \ --output=../output/

运行完成后，恢复版面的 docx 文档会保存到output字段指定的目录下。各字段含义如下：

上述参数均在 ppstructure/utility.py 中定义，其中--recovery、--recovery_to_markdown、--use_pdf2docx_api三个开关默认值均为False。特别注意：--recovery_to_markdown为 True 时，除 docx 外还会额外输出{img_name}_ocr.md文件（由convert_info_markdown生成），便于与 LLM 或 Markdown 工作流衔接。

5. 源码级原理剖析：版面恢复的底层实现

5.1 docx 生成：convert_info_docx

ppstructure/recovery/recovery_to_doc.py 中的convert_info_docx负责把结构化结果重建为 Word 文档，核心逻辑包括：

• 文档基础样式：正文默认字体 Times New Roman、中文字体宋体、字号 6.5pt；普通段落文字字号 10pt，首行缩进 0.25 英寸；
• 按区域类型分派渲染：figure区域居中插入图片（单栏宽 5 英寸、双栏宽 2 英寸）；title区域调用doc.add_heading生成标题；table区域使用HtmlToDocx解析表格 HTML 并套用TableGrid样式；equation区域当前跳过（注释中留白）；其余区域按段落逐行写入文本；
• 单双栏版面还原：根据区域layout标记（single/double）动态插入WD_SECTION.CONTINUOUS连续节，并通过设置w:cols的w:num在 1 栏与 2 栏之间切换，从而还原论文常见的双栏排版。

5.2 区域排序与单双栏判断：sorted_layout_boxes

版面恢复要求"顺序不变"地输出，因此区域必须按阅读顺序排列。recovery_to_doc.py 中的sorted_layout_boxes(res, w)实现了一套基于规则的双栏排序算法：

• 单个区域直接标记为single；
• 区域按(bbox 上边距, bbox 左边距)排序后，通过w/4、3*w/4、w/2等宽度阈值判断每个区域属于左栏、右栏还是跨页通栏：bbox 左边缘小于w/4且右边缘小于3*w/4判定为左栏（double），左边缘大于w/4且右边缘大于w/2判定为右栏（double），其余情况判定为通栏（single）；
• 最终输出顺序为"左栏区域 → 右栏区域 → 跨栏区域"，并在每页末尾合并左右栏结果，保证双栏论文的阅读顺序正确。

5.3 Markdown 导出与段落合并：recovery_to_markdown

ppstructure/recovery/recovery_to_markdown.py 中的convert_info_markdown将版面恢复结果输出为 Markdown：figure区域以居中的<img>标签呈现、title区域转换为#标题、table区域直接输出表格 HTML、equation区域输出为$$...$$公式、页眉页脚（header/footer）跳过、正文区域做特殊字符（*`~$）转义后写入。

值得关注的是其中两套基于排版规则的段落合并函数（源码注释亦说明恢复目前基于规则实现）：

• check_merge_method（recovery_to_markdown.py）：通过比较文本 bbox 左边缘与首行文本左边缘的横向距离（x1_distance是否大于首行高度）决定采用哪种合并策略；
• convert_text_space_head（recovery_to_markdown.py）：以"段首是否缩进两个字符"为分段标志——相邻行 x 坐标差小于行高则视为同一段落连续拼接，否则插入\n\n分段；
• convert_text_space_tail（recovery_to_markdown.py）：以"行尾是否排满"为分段标志，通过行宽与整行宽度的比较判断换段。

5.4 表格 HTML 转 docx：HtmlToDocx

ppstructure/recovery/table_process.py 中的HtmlToDocx类（参考开源 html2docx 实现）负责把表格识别输出的 HTML 转换为 docx 原生表格：

• 通过 BeautifulSoup 解析table > tr、thead/tbody/tfoot > tr提取行，统计colspan计算总列数；
• 逐单元格处理colspan/rowspan合并（docx_cell.merge(cell_to_merge)），th表头自动加粗；
• 每个单元格用独立的HtmlToDocx子解析器递归渲染内部 HTML，支持b/strong/em/i/u/s/sup/sub等行内样式映射（font_styles），并保证"单元格必须以段落结尾"以避免生成损坏的 docx 文件。

整体来看，图片格式 PDF 解析的版面恢复效果强依赖版面分析、OCR 与表格识别三个上游模型的精度，这正是文档中"版面恢复效果依赖于版面分析效果"这一结论的源码层面注脚。

6. 更多学习资源

围绕版面恢复所依赖的各个子任务的训练、评估与推理教程，可继续阅读仓库内对应文档：

• 关于 OCR 检测模型的训练评估与推理，请参考：doc目录下的文本检测教程；
• 关于 OCR 识别模型的训练评估与推理，请参考：文本识别教程；
• 关于版面分析模型的训练评估与推理，请参考：版面分析教程；
• 关于表格识别模型的训练评估与推理，请参考：表格识别教程；
• 版面恢复的 Markdown 导出与段落合并等实现细节，可深入阅读 ppstructure/recovery 目录下的 recovery_to_doc.py、recovery_to_markdown.py 与 table_process.py。

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR