wehub-resource-sync
e904b667c6
Build/Publish Develop Docs / deploy (push) Failing after 1s
PaddleOCR Code Style Check / check-code-style (push) Failing after 1s
PaddleOCR PR Tests GPU / detect-changes (push) Failing after 1s
PaddleOCR PR Tests / detect-changes (push) Failing after 1s
PaddleOCR PR Tests GPU / test-pr-gpu (push) Has been cancelled
PaddleOCR PR Tests / test-pr (push) Has been cancelled
PaddleOCR PR Tests GPU / test-pr-gpu-impl (push) Has been cancelled
PaddleOCR PR Tests / test-pr-python (3.13) (push) Has been cancelled
PaddleOCR PR Tests / test-pr-python (3.8) (push) Has been cancelled
PaddleOCR PR Tests / test-pr-python (3.9) (push) Has been cancelled
481 lines
12 KiB
Markdown
481 lines
12 KiB
Markdown
---
|
||
comments: true
|
||
---
|
||
|
||
# 文档转 Markdown 使用教程
|
||
|
||
## 1. 功能介绍
|
||
|
||
文档转 Markdown（doc2md）是 PaddleOCR 内置的轻量级 Office 文档结构化转换功能，**无需 OCR 推理**，直接解析文档结构并输出规范的 Markdown 文本。适用于需要将 Word、Excel、PowerPoint 文件快速转为可读文本的场景，如知识库构建、文档检索、内容提取等。
|
||
|
||
**支持格式**：`.docx`（Word）/ `.xlsx`（Excel）/ `.pptx`（PowerPoint）
|
||
|
||
**核心能力一览：**
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>功能</th>
|
||
<th>Word (.docx)</th>
|
||
<th>Excel (.xlsx)</th>
|
||
<th>PowerPoint (.pptx)</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>标题层级</td>
|
||
<td>✅ 内置样式 + 字号启发式 + 中文编号</td>
|
||
<td>— </td>
|
||
<td>— </td>
|
||
</tr>
|
||
<tr>
|
||
<td>文本格式化（粗体/斜体/下划线/删除线）</td>
|
||
<td>✅</td>
|
||
<td>✅</td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td>上标 / 下标</td>
|
||
<td>✅</td>
|
||
<td>✅</td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td>超链接</td>
|
||
<td>✅</td>
|
||
<td>✅</td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td>列表（有序 / 无序 / 嵌套）</td>
|
||
<td>✅</td>
|
||
<td>— </td>
|
||
<td>— </td>
|
||
</tr>
|
||
<tr>
|
||
<td>表格（含合并单元格）</td>
|
||
<td>✅ HTML table</td>
|
||
<td>✅ HTML table</td>
|
||
<td>✅ HTML table</td>
|
||
</tr>
|
||
<tr>
|
||
<td>图片</td>
|
||
<td>✅ 按比例宽度</td>
|
||
<td>✅ 浮动图片</td>
|
||
<td>✅ 按比例宽度</td>
|
||
</tr>
|
||
<tr>
|
||
<td>数学公式（OMML → LaTeX）</td>
|
||
<td>✅ 行内 / 显示公式</td>
|
||
<td>✅ drawing 层公式</td>
|
||
<td>✅</td>
|
||
</tr>
|
||
<tr>
|
||
<td>代码块</td>
|
||
<td>✅ 等宽字体自动识别</td>
|
||
<td>— </td>
|
||
<td>— </td>
|
||
</tr>
|
||
<tr>
|
||
<td>文本框</td>
|
||
<td>✅</td>
|
||
<td>— </td>
|
||
<td>— </td>
|
||
</tr>
|
||
<tr>
|
||
<td>图表（Chart）</td>
|
||
<td>✅ → HTML table</td>
|
||
<td>— </td>
|
||
<td>✅ 14 种图表类型</td>
|
||
</tr>
|
||
<tr>
|
||
<td>页眉 / 页脚</td>
|
||
<td>✅ 多节 + 奇偶页</td>
|
||
<td>— </td>
|
||
<td>— </td>
|
||
</tr>
|
||
<tr>
|
||
<td>多 sheet / 多幻灯片</td>
|
||
<td>— </td>
|
||
<td>✅</td>
|
||
<td>✅ <code>---</code> 分隔</td>
|
||
</tr>
|
||
<tr>
|
||
<td>演讲者备注</td>
|
||
<td>— </td>
|
||
<td>— </td>
|
||
<td>✅</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
## 2. 快速开始
|
||
|
||
在使用 doc2md 功能前，请确保已按照[安装教程](./installation.md)完成 PaddleOCR 基础安装，然后安装 doc2md 可选依赖：
|
||
|
||
```bash
|
||
pip install "paddleocr[doc2md]"
|
||
```
|
||
|
||
**依赖说明：**
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>包名</th>
|
||
<th>版本约束</th>
|
||
<th>用途</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>python-docx</code></td>
|
||
<td><code>>=0.8.11</code></td>
|
||
<td>Word (.docx) 文档解析</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>python-pptx</code></td>
|
||
<td><code>>=0.6.21</code></td>
|
||
<td>PowerPoint (.pptx) 文档解析</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>openpyxl</code></td>
|
||
<td><code>>=3.0.0</code></td>
|
||
<td>Excel (.xlsx) 文档解析</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>pylatexenc</code></td>
|
||
<td><code>>=2.10,<3</code></td>
|
||
<td>数学公式 Unicode → LaTeX 符号映射</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
### 2.1 命令行方式
|
||
|
||
```bash
|
||
# 转换 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
|
||
```
|
||
|
||
<details><summary><b>命令行支持更多参数设置，点击展开以查看命令行参数的详细说明</b></summary>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数</th>
|
||
<th>参数说明</th>
|
||
<th>参数类型</th>
|
||
<th>默认值</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>-i</code>, <code>--input</code></td>
|
||
<td><b>含义：</b>输入文件路径，必填（使用 <code>--formats</code> 时可省略）。<br/>
|
||
<b>说明：</b>支持 <code>.docx</code>、<code>.xlsx</code>、<code>.pptx</code> 格式。</td>
|
||
<td><code>str</code></td>
|
||
<td>必填</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>-o</code>, <code>--output</code></td>
|
||
<td><b>含义：</b>输出 Markdown 文件路径。<br/>
|
||
<b>说明：</b>如果不设置，转换结果将打印到标准输出（stdout）。设置后，Markdown 写入指定文件，图片保存到同目录下的 <code>images/</code> 文件夹。</td>
|
||
<td><code>str</code></td>
|
||
<td><code>None</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>-q</code>, <code>--quiet</code></td>
|
||
<td><b>含义：</b>静默模式。<br/>
|
||
<b>说明：</b>启用后不打印耗时、保存路径等提示信息。</td>
|
||
<td>flag</td>
|
||
<td><code>False</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>--formats</code></td>
|
||
<td><b>含义：</b>列出当前支持的文件格式后退出。<br/>
|
||
<b>说明：</b>启用后不需要 <code>--input</code>，仅输出支持的扩展名列表。</td>
|
||
<td>flag</td>
|
||
<td><code>False</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>--no-drawings</code></td>
|
||
<td><b>含义：</b>跳过文本框和 drawing 层内容提取。<br/>
|
||
<b>说明：</b>适用于 <code>.docx</code> 和 <code>.xlsx</code>，启用后将跳过文本框（docx）和 drawing 层数学公式（xlsx）的提取。</td>
|
||
<td>flag</td>
|
||
<td><code>False</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>--no-headers-footers</code></td>
|
||
<td><b>含义：</b>跳过页眉页脚内容提取。<br/>
|
||
<b>说明：</b>仅适用于 <code>.docx</code>，启用后不提取文档的页眉和页脚内容。</td>
|
||
<td>flag</td>
|
||
<td><code>False</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>--sheet-name</code></td>
|
||
<td><b>含义：</b>仅转换指定名称的 sheet。<br/>
|
||
<b>说明：</b>仅适用于 <code>.xlsx</code>，不设置则转换所有 sheet。</td>
|
||
<td><code>str</code></td>
|
||
<td><code>None</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>--max-rows</code></td>
|
||
<td><b>含义：</b>每个 sheet 的最大转换行数。<br/>
|
||
<b>说明：</b>仅适用于 <code>.xlsx</code>，用于限制大表格的输出行数。</td>
|
||
<td><code>int</code></td>
|
||
<td><code>None</code></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</details>
|
||
<br />
|
||
|
||
### 2.2 Python API
|
||
|
||
**基础用法：**
|
||
|
||
```python
|
||
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` 字段说明：**
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>字段</th>
|
||
<th>类型</th>
|
||
<th>说明</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>markdown</code></td>
|
||
<td><code>str</code></td>
|
||
<td>转换后的 Markdown 文本</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>images</code></td>
|
||
<td><code>dict[str, bytes]</code></td>
|
||
<td>提取的图片字典，key 为相对路径（如 <code>images/image1.png</code>），value 为图片字节</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>title</code></td>
|
||
<td><code>Optional[str]</code></td>
|
||
<td>文档标题，可能为 <code>None</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>metadata</code></td>
|
||
<td><code>dict</code></td>
|
||
<td>文档元信息，如格式类型、sheet 数量等</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
**指定输出路径（自动保存文件和图片）：**
|
||
|
||
```python
|
||
from paddleocr._doc2md import convert
|
||
|
||
# 指定 output 后，Markdown 写入文件，图片保存到同目录 images/ 下
|
||
result = convert("report.docx", output="output/report.md")
|
||
```
|
||
|
||
**各格式可用的 kwargs 参数：**
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>参数</th>
|
||
<th>类型</th>
|
||
<th>默认值</th>
|
||
<th>适用格式</th>
|
||
<th>说明</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>extract_drawings</code></td>
|
||
<td><code>bool</code></td>
|
||
<td><code>True</code></td>
|
||
<td>docx, xlsx</td>
|
||
<td>是否提取文本框（docx）/ drawing 层数学公式（xlsx）</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>extract_headers_footers</code></td>
|
||
<td><code>bool</code></td>
|
||
<td><code>True</code></td>
|
||
<td>docx</td>
|
||
<td>是否提取页眉页脚</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>sheet_name</code></td>
|
||
<td><code>Optional[str]</code></td>
|
||
<td><code>None</code></td>
|
||
<td>xlsx</td>
|
||
<td>仅转换指定名称的 sheet，<code>None</code> 表示转换全部</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>max_rows</code></td>
|
||
<td><code>Optional[int]</code></td>
|
||
<td><code>None</code></td>
|
||
<td>xlsx</td>
|
||
<td>每个 sheet 的最大转换行数</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
**按格式传入 kwargs 示例：**
|
||
|
||
```python
|
||
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 采用延迟导入，缺少对应格式的解析库时会抛出此错误。请根据提示安装对应依赖：
|
||
```bash
|
||
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 的行数：
|
||
```bash
|
||
paddleocr doc2md -i data.xlsx -o output.md --max-rows 100
|
||
```
|
||
|
||
---
|
||
|
||
**Q：只想转换 Excel 中的某一个 sheet？**
|
||
|
||
使用 `--sheet-name` 指定 sheet 名称：
|
||
```bash
|
||
paddleocr doc2md -i data.xlsx -o output.md --sheet-name "Sheet1"
|
||
```
|
||
|
||
---
|
||
|
||
**Q：Word 文档中的页眉页脚内容不需要，如何跳过？**
|
||
|
||
使用 `--no-headers-footers` 参数：
|
||
```bash
|
||
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 功能则针对图片或扫描件进行文字识别，适用于没有原始文档的场景。
|