wehub-resource-sync
e904b667c6
12 KiB
comments
| comments |
|---|
| true |
文档转 Markdown 使用教程
1. 功能介绍
文档转 Markdown（doc2md）是 PaddleOCR 内置的轻量级 Office 文档结构化转换功能，无需 OCR 推理，直接解析文档结构并输出规范的 Markdown 文本。适用于需要将 Word、Excel、PowerPoint 文件快速转为可读文本的场景，如知识库构建、文档检索、内容提取等。
支持格式：.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]"
依赖说明：
| 包名 | 版本约束 | 用途 |
|---|---|---|
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 符号映射 |
2.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
命令行支持更多参数设置，点击展开以查看命令行参数的详细说明
| 参数 | 参数说明 | 参数类型 | 默认值 |
|---|---|---|---|
-i, --input |
含义：输入文件路径，必填（使用 --formats 时可省略）。说明：支持 .docx、.xlsx、.pptx 格式。 |
str |
必填 |
-o, --output |
含义：输出 Markdown 文件路径。 说明：如果不设置，转换结果将打印到标准输出（stdout）。设置后，Markdown 写入指定文件，图片保存到同目录下的 images/ 文件夹。 |
str |
None |
-q, --quiet |
含义：静默模式。 说明：启用后不打印耗时、保存路径等提示信息。 |
flag | False |
--formats |
含义：列出当前支持的文件格式后退出。 说明：启用后不需要 --input，仅输出支持的扩展名列表。 |
flag | False |
--no-drawings |
含义：跳过文本框和 drawing 层内容提取。 说明：适用于 .docx 和 .xlsx，启用后将跳过文本框（docx）和 drawing 层数学公式（xlsx）的提取。 |
flag | False |
--no-headers-footers |
含义：跳过页眉页脚内容提取。 说明：仅适用于 .docx，启用后不提取文档的页眉和页脚内容。 |
flag | False |
--sheet-name |
含义：仅转换指定名称的 sheet。 说明：仅适用于 .xlsx，不设置则转换所有 sheet。 |
str |
None |
--max-rows |
含义：每个 sheet 的最大转换行数。 说明：仅适用于 .xlsx，用于限制大表格的输出行数。 |
int |
None |
2.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)
ConvertResult 字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
markdown |
str |
转换后的 Markdown 文本 |
images |
dict[str, bytes] |
提取的图片字典，key 为相对路径（如 images/image1.png），value 为图片字节 |
title |
Optional[str] |
文档标题，可能为 None |
metadata |
dict |
文档元信息，如格式类型、sheet 数量等 |
指定输出路径（自动保存文件和图片）：
from paddleocr._doc2md import convert
# 指定 output 后，Markdown 写入文件，图片保存到同目录 images/ 下
result = convert("report.docx", output="output/report.md")
各格式可用的 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)
3. 各格式支持特性
3.1 Word (.docx)
标题识别支持三种方式：
- 内置 Heading 样式：Word 内置的 Heading 1–6 样式直接映射为
#–###### - 字号启发式：字号大于正文 1.5 倍且段落较短时，自动识别为标题
- 中文编号："一、"格式识别为 H2，"（一）"格式识别为 H3
文本格式化：粗体（**）、斜体（*）、下划线（<u>）、删除线（~~）、上标（<sup>）、下标（<sub>）
列表：有序列表、无序列表、嵌套列表，自动识别缩进层级
表格：输出为 HTML <table> 格式，支持 rowspan/colspan 合并单元格
图片：按文档内容区宽度百分比计算，输出 <img width="75%"> 形式
数学公式：OMML 格式公式转为 LaTeX，行内公式为 $...$，显示公式为 $$...$$
代码块：自动检测等宽字体（Courier New、Consolas 等 9 种字体），输出为 fenced code block（```）
其他：文本框内容（wps:txbx）、图表（Chart → HTML table）、超链接（两种格式）、页眉页脚（多节 + 奇偶页）
3.2 Excel (.xlsx)
多 sheet：每个 sheet 输出一个以 ## sheet名称 开头的章节
数据边界裁剪：自动去除尾部空行和空列，只输出有效数据区域
合并单元格：使用 rowspan/colspan 还原单元格合并结构
字体格式化：粗体、斜体、下划线、删除线、上标、下标
超链接：支持单元格级超链接
浮动图片：支持 OneCellAnchor 和 TwoCellAnchor 两种锚定方式的浮动图片
数学公式：通过解析 drawing 层 XML 提取 OMML 格式公式并转为 LaTeX
3.3 PowerPoint (.pptx)
多幻灯片：每张幻灯片内容以 --- 分隔
文本格式化：粗体、斜体、下划线、删除线、上标、下标
图片：按幻灯片宽度百分比计算，输出带宽度的 <img> 标签
表格：HTML <table> 格式，支持合并单元格，支持带背景图片的表格
图表：支持 14 种图表类型，转换为 HTML table 输出
分组形状（GroupShape）：递归处理嵌套的形状组合
数学公式：从 mc:AlternateContent 中提取 OMML 格式公式并转为 LaTeX
演讲者备注：附加在每张幻灯片内容末尾
4. 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 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/ 文件夹下。Markdown 文件中的图片引用路径也会相应更新为相对路径。
Q：doc2md 与 PaddleOCR 的 OCR 功能有什么区别？
doc2md 直接解析 Office 文档的 XML 结构，不使用任何 OCR 模型，速度快、零 GPU 依赖。适用于有原始 Office 文件的场景。PaddleOCR 的 OCR 功能则针对图片或扫描件进行文字识别，适用于没有原始文档的场景。