PaddleOCR doc2md：无需 OCR 即可将 Word、Excel 与 PowerPoint 一键转换为 Markdown
【免费下载链接】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 推理链路，直接解析 OOXML 文档结构并输出规范的 Markdown 文本。本文以官方教程 docs/version3.x/doc2md.en.md 为核心骨架，结合仓库源码深入讲解其架构、命令行与 Python API 用法、各格式支持细节及常见问题排查，帮助你在知识库构建、文档检索与内容提取场景中直接落地使用。
1. 功能定位：不跑模型的结构化转换器
doc2md 的核心设计理念是"无需 OCR 推理"。与 OCR 对图片/扫描件做像素级文字识别不同，doc2md 直接读取 Office 文件的 XML 内部结构（.docx/.xlsx/.pptx本质上是 ZIP 打包的 OOXML 文档），将段落、表格、图片、公式等结构化元素映射为 Markdown 语法。因此它速度极快、零 GPU 依赖，适合拥有原始 Office 文件的场景。
从源码看，整个功能收敛在 paddleocr/_doc2md 包内，对外暴露两个核心入口（见 paddleocr/init.py）：
doc2md_convert(source, **kwargs)：转换文档并返回结果对象；doc2md_supported_formats()：列出当前支持的扩展名。
支持格式：.docx（Word）、.xlsx（Excel）、.pptx（PowerPoint）。
三种格式的核心能力对比如下：
| 功能 | Word (.docx) | Excel (.xlsx) | PowerPoint (.pptx) |
|---|---|---|---|
| 标题层级 | ✅ 内置样式 + 字号启发式 + 中文编号 | — | — |
| 文本格式化（粗体/斜体/下划线/删除线） | ✅ | ✅ | ✅ |
| 上标 / 下标 | ✅ | ✅ | ✅ |
| 超链接 | ✅ | ✅ | ✅ |
| 列表（有序 / 无序 / 嵌套） | ✅ | — | — |
| 表格（含合并单元格） | ✅ HTML table | ✅ HTML table | ✅ HTML table |
| 图片 | ✅ 按比例宽度 | ✅ 浮动图片 | ✅ 按比例宽度 |
| 数学公式（OMML → LaTeX） | ✅ 行内 / 显示公式 | ✅ drawing 层公式 | ✅ |
| 代码块 | ✅ 等宽字体自动识别 | — | — |
| 文本框 | ✅ | — | — |
| 图表（Chart） | ✅ → HTML table | — | ✅ 14 种图表类型 |
| 页眉 / 页脚 | ✅ 多节 + 奇偶页 | — | — |
| 多 sheet / 多幻灯片 | — | ✅ | ✅---分隔 |
| 演讲者备注 | — | — | ✅ |
2. 安装与依赖
使用 doc2md 前，请先按照安装教程完成 PaddleOCR 基础安装，然后安装 doc2md 可选依赖：
pip install "paddleocr[doc2md]"该 extra 依赖在 pyproject.toml 中定义，四类解析库缺一不可：
| 包名 | 版本约束 | 用途 |
|---|---|---|
python-docx | >=0.8.11 | Word (.docx) 文档解析 |
python-pptx | >=0.6.21 | PowerPoint (.pptx) 文档解析 |
openpyxl | >=3.0.0 | Excel (.xlsx) 文档解析 |
pylatexenc | >=2.10,<3 | 数学公式 Unicode → LaTeX 符号映射 |
值得注意的实现细节是doc2md 采用延迟导入（lazy import）策略：三个转换器模块（docx.py、xlsx.py、pptx.py）在真正转换时才引入对应解析库。若缺失依赖，会抛出如RuntimeError: DOCX conversion requires python-docx: pip install paddleocr[doc2md]之类的明确错误（参见 docx.py 与 xlsx.py），这也是 FAQ 中"转换时报 python-docx is required"的根因。
3. 命令行快速上手
doc2md 以paddleocr doc2md子命令形式集成在 CLI 中，注册逻辑见 paddleocr/_cli.py。基础用法：
# 转换 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 # 不指定输出路径，结果打印到终端（stdout） paddleocr doc2md -i report.docx # 查看支持的格式列表后退出 paddleocr doc2md --formats完整命令行参数如下：
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
-i,--input | 输入文件路径，必填（使用--formats时可省略）；支持.docx、.xlsx、.pptx | str | 必填 |
-o,--output | 输出 Markdown 文件路径；不设置则打印到 stdout；设置后图片自动保存到同目录images/子目录 | str | None |
-q,--quiet | 静默模式，不打印耗时、保存路径等提示 | flag | False |
--formats | 打印支持的文件格式列表并退出，此时无需--input | flag | False |
--no-drawings | 跳过文本框（docx）与 drawing 层数学公式（xlsx）的提取，仅适用于 docx / xlsx | flag | False |
--no-headers-footers | 跳过页眉页脚提取，仅适用于 docx | flag | False |
--sheet-name | 仅转换指定名称的 sheet，不设置则转换全部；仅适用于 xlsx | str | None |
--max-rows | 每个 sheet 的最大转换行数，用于限制大表格输出；仅适用于 xlsx | int | None |
这些 flag 在 CLI 内部被一一映射为 Python API 的 kwargs（见 paddleocr/_cli.py）：--no-drawings对应extract_drawings=False，--no-headers-footers对应extract_headers_footers=False，--sheet-name与--max-rows直接透传。转换完成且未开启--quiet时，CLI 会打印耗时（毫秒）与输出/图片保存路径。
4. Python API 详解
Python API 的顶层入口是paddleocr._doc2md.convert，其底层实现见 paddleocr/_doc2md/core.py：先校验文件存在性，再通过注册表按扩展名/MIME 类型选出转换器实例，执行convert_file后，若指定output则自动写入 Markdown 文件并落盘images/图片。
基础用法：
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)ConvertResult字段说明（数据结构定义见 paddleocr/_doc2md/base.py）：
| 字段 | 类型 | 说明 |
|---|---|---|
markdown | str | 转换后的 Markdown 文本 |
images | dict[str, bytes] | 提取的图片字典，key 为相对路径（如images/image1.png），value 为图片原始字节 |
title | Optional[str] | 文档标题，可能为None |
metadata | dict | 文档元信息，如格式类型、sheet 数量等 |
指定输出路径（自动保存 Markdown 与图片）：
from paddleocr._doc2md import convert # 指定 output 后，Markdown 写入文件，图片保存到同目录 images/ 下 result = convert("report.docx", output="output/report.md")图片落盘逻辑由convert统一处理：result.images中的每个相对路径都被拼接到输出文件所在目录，逐一以二进制写入（见 core.py），因此 Markdown 中的图片引用天然是相对路径。
各格式可用的 kwargs 参数：
| 参数 | 类型 | 默认值 | 适用格式 | 说明 |
|---|---|---|---|---|
extract_drawings | bool | True | docx, xlsx | 是否提取文本框（docx）/ drawing 层数学公式（xlsx） |
extract_headers_footers | bool | True | docx | 是否提取页眉页脚 |
sheet_name | Optional[str] | None | xlsx | 仅转换指定名称的 sheet，None表示全部 |
max_rows | Optional[int] | None | xlsx | 每个 sheet 的最大转换行数 |
按格式传入 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)5. 各格式支持特性深度解析
5.1 Word (.docx)
标题识别采用三种互补策略：
- 内置 Heading 样式：Word 内置 Heading 1–6 样式直接映射为
#–######； - 字号启发式：字号大于正文 1.5 倍且段落较短时，自动提升为标题；
- 中文编号：
一、格式识别为 H2，（一）格式识别为 H3。对应正则见 docx.py：_RE_H2 = re.compile(r"^[一二三四五六七八九十百千]+[、．.]")、_RE_H3 = re.compile(r"^（[一二三四五六七八九十百千]+）")。
文本格式化：粗体（**）、斜体（*）、下划线（<u>）、删除线（~~）、上标（<sup>）、下标（<sub>）。样式解析时遵循"run 级 > 字符样式 > 段落样式"的优先级链（见 docx.py 中的_effective_bold/_effective_italic/_effective_underline辅助函数），确保继承样式不被漏掉。
列表：有序、无序、嵌套列表，缩进层级自动识别。
表格：输出为 HTML<table>格式，合并单元格用rowspan/colspan还原。
图片：按文档内容区宽度计算百分比，输出<img width="75%">形式。
数学公式：OMML 格式公式转为 LaTeX，行内公式用$...$，显示公式用$$...$$。
代码块：自动检测等宽字体（Courier New、Consolas 等 9 种），输出为 fenced code block（```）。
其他：文本框内容（wps:txbx，对应 Word 2010 wordprocessingShape 命名空间，见 docx.py）、图表（Chart → HTML table）、超链接（支持普通链接与HYPERLINK域代码两种格式，域代码正则_RE_FIELD_HYPERLINK见 docx.py）、页眉页脚（多节 + 奇偶页）。页眉页脚中仅含页码的文本（如- 3 -、Page of）会被_RE_PAGE_ONLY正则过滤，避免污染正文（见 docx.py）。
5.2 Excel (.xlsx)
多 sheet：每个 sheet 输出一个以## sheet名称开头的章节。
数据边界裁剪：通过_find_data_bounds自动定位非空单元格区域，去除尾部空行/空列，只输出有效数据范围（实现见 xlsx.py 起）。
合并单元格：使用rowspan/colspan还原合并结构。
字体格式化：粗体、斜体、下划线、删除线、上标、下标。
超链接：支持单元格级超链接。
浮动图片：同时支持OneCellAnchor与TwoCellAnchor两种锚定方式——OneCellAnchor可从ext.cx直接读取图片显示宽度（EMU 单位），TwoCellAnchor则回退为默认处理（见 xlsx.py）。列宽换算按"1 字符 ≈ 7px、1px = 9525 EMU"计算（见 xlsx.py）。
数学公式：解析 sheet 关联的 drawing 层 XML，在mc:AlternateContent/mc:Choice下遍历a:p段落提取 OMML 公式并转为 LaTeX（见 xlsx.py）。
5.3 PowerPoint (.pptx)
多幻灯片：每张幻灯片内容以---分隔。
文本格式化：粗体、斜体、下划线、删除线、上标、下标，删除线通过 DrawingML 命名空间下的a:strike元素检测（见 pptx.py）。
图片：按幻灯片宽度计算百分比，输出带宽度的<img>标签。
表格：HTML<table>格式，支持合并单元格与带背景图片的表格。
图表：支持 14 种图表类型（面积图、折线图、饼图、气泡图、柱状图、条形图、圆环图、雷达图、散点图等，类型枚举映射见 pptx.py 的_CHART_TYPE_NAMES），全部转换为 HTML table 输出。
分组形状（GroupShape）：递归处理嵌套的形状组合。
数学公式：从mc:AlternateContent中提取 OMML 公式并转为 LaTeX。
演讲者备注：附加在每张幻灯片内容末尾。
6. 架构原理：注册表驱动的转换器
doc2md 的内部架构遵循"注册表 + 策略模式"，代码结构清晰、易于扩展：
- base.py：定义
ConvertResult数据类与BaseConverter抽象基类，后者声明supported_extensions/supported_mimetypes类属性与抽象的convert_file方法； - registry.py：
ConverterRegistry维护"扩展名 → 转换器类"和"MIME 类型 → 转换器类"两张映射表。register支持作为装饰器使用，get_converter先按扩展名匹配、再按 MIME 兜底，均未命中时抛出带支持列表的ValueError——这正是 FAQ 中"格式不支持报 ValueError"的来源（见 registry.py）； - converters/：docx、xlsx、pptx 三个转换器分别实现对应格式的 XML 解析与 Markdown 渲染；
- math/：OMML 公式解析与 Unicode → LaTeX 符号映射（依赖
pylatexenc），供三种格式复用。
convert()入口通过from . import converters触发全部内置转换器的注册（见 core.py），随后交由default_registry.get_converter(file_path)分发（见 core.py）。用户如需新增自定义格式，可自行继承BaseConverter并注册到注册表，无需改动核心流程。
7. FAQ：常见问题与排查
Q：转换时提示RuntimeError: python-docx is required？
doc2md 采用延迟导入，缺少对应格式解析库时会抛出此错误。按需安装依赖：
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等格式。
Q：Excel 转换后表格行数很多，输出太长？
使用--max-rows限制每个 sheet 的行数：
paddleocr doc2md -i data.xlsx -o output.md --max-rows 100Q：只想转换 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-footersQ：图片输出到哪里？
使用-o指定输出文件时，图片自动保存在输出文件同目录的images/文件夹下，Markdown 中的图片引用路径同步更新为相对路径。
Q：doc2md 与 PaddleOCR 的 OCR 功能有什么区别？
doc2md 直接解析 Office 文档的 XML 结构，不使用任何 OCR 模型，速度快、零 GPU 依赖，适用于拥有原始 Office 文件的场景；PaddleOCR 的 OCR 功能则针对图片或扫描件进行文字识别，适用于没有原始文档的场景。两者互为补充：前者负责"结构化文档 → 文本"，后者负责"图像 → 文本"。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
