企业官网建设流程全解析

PaddleOCR doc2md 文档转 Markdown 全指南：Office 文档结构化转换原理与实战

【免费下载链接】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

doc2md 是 PaddleOCR 内置的轻量级 Office 文档结构化转换功能，无需 OCR 推理、零 GPU 依赖，直接解析 Word / Excel / PowerPoint 的底层 XML 结构并输出规范 Markdown，适合知识库构建、文档检索、内容提取与 RAG 数据预处理等场景。本文将带你掌握paddleocr doc2md命令行与 Python API 的完整用法、全部参数语义、三种格式的转换能力边界，以及其背后的源码实现原理。

1. 功能定位：与 OCR 互补的「原生文档」转换通道

doc2md 与 PaddleOCR 的 OCR 能力在适用场景上形成互补：

doc2md 只认三种格式：.docx（Word）、.xlsx（Excel）、.pptx（PowerPoint），不支持.doc（旧版 Word）、.csv、.pdf。其源码实现位于 paddleocr/_doc2md/ 目录，整体分为三个层次：

• registry.py：ConverterRegistry注册表，按文件扩展名（.docx/.xlsx/.pptx）或 MIME 类型路由到对应转换器，并通过@default_registry.register装饰器完成注册；
• base.py：定义抽象基类BaseConverter与数据类ConvertResult；
• core.py：对外统一入口convert()，负责按扩展名分派转换器、写入输出文件与图片目录；
• converters/：三种格式的具体转换器（docx.py / xlsx.py / pptx.py），以及 math/ 子模块（OMML 数学公式转 LaTeX）。

核心能力一览：

2. 安装与依赖

doc2md 使用延迟导入策略：只有真正转换某格式时才加载对应解析库，因此基础安装只需要 PaddleOCR 本体（按安装教程完成），再安装可选依赖：

pip install "paddleocr[doc2md]"

该 extras 依赖在 pyproject.toml 中定义为四个包：

也可按需单独安装（见 FAQ 中的报错排查）。此外，OMML 公式解析依赖lxml（math/omml.py 中import lxml.etree），通常随 PaddleOCR 基础依赖一并安装。

3. 快速开始

3.1 命令行方式

# 转换 Word 文档，输出到文件 paddleocr doc2md -i report.docx -o output.md # 转换 Excel 表格，输出到文件 paddleocr doc2md -i data.xlsx -o output.md # 转换 PowerPoint 演示文稿，输出到文件 paddleocr doc2md -i slides.pptx -o output.md # 不指定输出路径，结果打印到终端 paddleocr doc2md -i report.docx # 查看支持的格式列表 paddleocr doc2md --formats

命令行在 paddleocr/_cli.py 中通过_register_doc2md_command注册为paddleocr顶层子命令。CLI 参数与 Python 入口的对应关系在_execute_doc2md中建立：--no-drawings→extract_drawings=False，--no-headers-footers→extract_headers_footers=False，--sheet-name/--max-rows原样透传。

全部命令行参数：

3.2 Python API

from paddleocr._doc2md import convert # 转换文档，返回结果对象 result = convert("report.docx") # 访问 Markdown 文本 print(result.markdown) # 查看提取的图片（字典，key 为相对路径，value 为图片字节） print(list(result.images.keys())) # 查看文档标题 print(result.title) # 查看元信息（格式、sheet 数等） print(result.metadata)

convert()的源码行为（paddleocr/_doc2md/core.py）：

1. 校验输入文件存在，否则抛FileNotFoundError；
2. 通过default_registry.get_converter()按扩展名路由到转换器，未知扩展名抛ValueError（附带支持的格式列表）；
3. 调用转换器convert_file()，转换期间异常统一包装为RuntimeError；
4. 若传入output，自动创建父目录、写入 Markdown（UTF-8），并把result.images中的图片字节写到输出目录的images/下。

ConvertResult字段说明（定义见 paddleocr/_doc2md/base.py）：

指定输出路径（自动保存文件和图片）：

from paddleocr._doc2md import convert # 指定 output 后，Markdown 写入文件，图片保存到同目录 images/ 下 result = convert("report.docx", output="output/report.md")

各格式可用的 kwargs 参数：

按格式传入 kwargs 示例：

from paddleocr._doc2md import convert # Word：不提取文本框和页眉页脚 result = convert("report.docx", extract_drawings=False, extract_headers_footers=False) # Excel：仅转换名为 "Sheet1" 的 sheet，最多 100 行 result = convert("data.xlsx", sheet_name="Sheet1", max_rows=100)

提示：from paddleocr import doc2md_convert也是官方入口之一（见 core.py 中的 docstring 示例），convert()与之一致。

4. 各格式支持特性详解

4.1 Word (.docx)

标题识别支持三种方式（对应源码_detect_heading_level，见 converters/docx.py）：

• 内置 Heading 样式：Word 内置的 Heading 1–6 样式直接映射为#–######；Title映射为 H1，Subtitle映射为 H2；
• 字号启发式：当段落字号大于正文 1.5 倍时（font_size > body_font_size * 1.5），居中段落判为 H1、短段落（≤60 字符）判为 H2。正文基准字号由_get_body_font_size统计全文最常用字号得出（无显式字号时默认 16pt）；
• 中文编号："一、"格式识别为 H2，"（一）"格式识别为 H3（正则见 docx.py）。

文本格式化：粗体（**）、斜体（*）、删除线（~~）、上标（<sup>）、下标（<sub>）、下划线（<u>）。源码通过_effective_bold/_effective_italic/_effective_underline实现"run 级 → 字符样式 → 段落样式"的继承解析，并做相邻同类 run 合并（_merge_runs）。一个工程细节：超链接文本会强制去掉下划线，避免 Word 默认的链接下划线样式污染输出。

列表：有序列表、无序列表、嵌套列表。源码_build_numbering_map解析numbering.xml，把numId + ilvl映射到numFmt（decimal/lowerLetter/lowerRoman 等判为有序），输出时用 4 空格缩进表示层级（docx.py）。

表格：输出为 HTML<table>，_table_to_html通过比较底层tc元素自动计算colspan/rowspan还原合并单元格，并支持"重复标题行（tblHeader）识别"与"首行默认表头"回退策略（docx.py）。

图片：按内容区宽度百分比计算，输出<img width="75%">形式。源码读取wp:inline/wp:anchor的extent中的cx（EMU 单位），除以page_width - left_margin - right_margin得到百分比并钳制在 100% 内（docx.py）。

数学公式：OMML 格式公式转为 LaTeX，行内公式为$...$，显示公式为$$...$$。段落级的m:oMathPara/m:oMath会被拆分为"文本 + 公式"混合片段（_iter_math_paragraph_parts），公式转换核心在 math/omml.py，内置m:scr字体映射（script→\mathscr、fraktur→\mathfrak、double-struck→\mathbb等）。

代码块：_CODE_FONTS内置 9 种等宽字体（Courier New、Courier、Consolas、Monaco、Menlo、Source Code Pro、Fira Code、DejaVu Sans Mono、monospace），段落内所有带文本 run 均为等宽字体时判为代码，连续代码段落缓冲为 fenced code block（```）。

其他：文本框内容（mc:AlternateContent > mc:Choice > wps:txbx > w:txbxContent，仅取mc:Choice避免 VML 回退内容重复）以>引用块输出；图表（Chart）解析 chart part 的 XML，把分类轴、系列名称与数值还原为带caption/thead/tbody的 HTML table；页眉页脚支持多节 + 奇偶页 + 首页不同（odd_and_even_pages_header_footer、different_first_page_header_footer），并自动过滤纯页码文本（如"第 页"、"共 页"、"- 3 -"）；目录（TOC）段落会被提取为 Markdown 链接列表，并借助_Toc书签锚点保证可跳转。

4.2 Excel (.xlsx)

• 多 sheet：每个 sheet 输出一个以## sheet名称开头的章节（sheet_name未设置时遍历wb.sheetnames）；
• 数据边界裁剪：_find_data_bounds自动去除尾部空行和空列，只输出有效数据区域，max_rows在此处截断行号；
• 合并单元格：使用rowspan/colspan还原单元格合并结构；
• 字体格式化：粗体、斜体、下划线、删除线、上标、下标；
• 超链接：支持单元格级超链接；
• 浮动图片：同时支持OneCellAnchor和TwoCellAnchor两种锚定方式（xlsx.py），其中OneCellAnchor可计算显示宽度，TwoCellAnchor则按无宽度输出；
• 数学公式：通过解析 drawing 层mc:AlternateContent内的 XML 提取 OMML 公式并转为 LaTeX（xlsx.py），这也是--no-drawings参数影响 xlsx 公式提取的原因。

4.3 PowerPoint (.pptx)

• 多幻灯片：每张幻灯片内容以---分隔；
• 文本格式化：粗体、斜体、下划线、删除线、上标、下标；
• 图片：按幻灯片宽度百分比计算，输出带宽度的<img>标签；
• 表格：HTML<table>格式，支持合并单元格，支持带背景图片的表格；
• 图表：支持 14 种图表类型，转换为 HTML table 输出；
• 分组形状（GroupShape）：_process_shape递归处理嵌套的形状组合（pptx.py），Picture / GroupShape / Chart / Table / TextFrame 依次处理；
• 数学公式：从mc:AlternateContent中提取 OMML 格式公式并转为 LaTeX（pptx.py）；
• 演讲者备注：附加在每张幻灯片内容末尾。

5. 典型应用场景

• 知识库构建：把企业内部 Word 规范、Excel 报表、PPT 培训材料批量转为 Markdown，灌入向量库前无需 OCR；
• RAG 数据预处理：doc2md 输出的标题层级与 HTML 表格天然适合按 chunk 切分，公式保留为 LaTeX 便于数学类文档检索；
• 文档对比与迁移：将 Office 内容统一为 Markdown 后，可使用统一工具链做 diff、发布到静态站点（如 MkDocs）；
• 批量流水线：在 Python 脚本中遍历目录调用convert()，配合output参数自动落盘 Markdown 与图片。

6. FAQ

Q：转换时提示RuntimeError: python-docx is required？

doc2md 采用延迟导入，缺少对应格式的解析库时会抛出此错误（如 docx.py 中from docx import Document失败即抛RuntimeError）。请根据提示安装对应依赖：

pip install python-docx # Word (.docx) pip install python-pptx # PowerPoint (.pptx) pip install openpyxl # Excel (.xlsx) pip install pylatexenc # 数学公式支持

或直接安装全部依赖：pip install "paddleocr[doc2md]"。

Q：格式不支持，提示ValueError？

运行paddleocr doc2md --formats查看当前支持的扩展名。doc2md 仅支持.docx、.xlsx、.pptx，不支持.doc（旧版 Word）、.csv、.pdf等格式。扩展名匹配失败时，get_converter还会尝试按 MIME 类型匹配（registry.py），仍失败则抛出附带支持列表的ValueError。

Q：Excel 转换后表格行数很多，输出太长？

使用--max-rows限制每个 sheet 的行数：

paddleocr doc2md -i data.xlsx -o output.md --max-rows 100

Q：只想转换 Excel 中的某一个 sheet？

使用--sheet-name指定 sheet 名称：

paddleocr doc2md -i data.xlsx -o output.md --sheet-name "Sheet1"

Q：Word 文档中的页眉页脚内容不需要，如何跳过？

使用--no-headers-footers参数：

paddleocr doc2md -i report.docx -o output.md --no-headers-footers

Q：图片输出到哪里？

使用-o指定输出文件时，图片自动保存在输出文件同目录的images/文件夹下（由 core.py 中的images_dir = output_path.parent / "images"逻辑落盘）。Markdown 文件中的图片引用路径也会相应更新为相对路径（如images/image1.png）。若不传-o，图片仅保留在返回结果的images字典中，不会写入磁盘。

Q：doc2md 与 PaddleOCR 的 OCR 功能有什么区别？

doc2md 直接解析 Office 文档的 XML 结构，不使用任何 OCR 模型，速度快、零 GPU 依赖，适用于有原始 Office 文件的场景。PaddleOCR 的 OCR 功能则针对图片或扫描件进行文字识别，适用于没有原始文档的场景。两者可组合使用：原始 Office 文件走 doc2md，扫描版/图片走 OCR，形成完整的文档数字化链路。

7. 相关源码导读

如果你想深入 doc2md 的实现细节，可按以下路径继续阅读：

• 对外 API 与输出落盘：paddleocr/_doc2md/core.py、paddleocr/_doc2md/base.py
• 格式路由与注册机制：paddleocr/_doc2md/registry.py
• Word 转换器（标题/列表/表格/公式/文本框/页眉页脚/图表）：paddleocr/_doc2md/converters/docx.py
• Excel 转换器（多 sheet/合并单元格/浮动图片/边界裁剪）：paddleocr/_doc2md/converters/xlsx.py
• PowerPoint 转换器（分组形状/图表/备注/公式）：paddleocr/_doc2md/converters/pptx.py
• OMML → LaTeX 公式转换：paddleocr/_doc2md/math/omml.py、paddleocr/_doc2md/math/latex_dict.py
• CLI 参数定义与映射：paddleocr/_cli.py
• 依赖声明：pyproject.toml

【免费下载链接】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