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

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/PaddleOCRdoc2md 是 PaddleOCR 内置的轻量级 Office 文档结构化转换功能无需 OCR 推理、零 GPU 依赖直接解析 Word / Excel / PowerPoint 的底层 XML 结构并输出规范 Markdown适合知识库构建、文档检索、内容提取与 RAG 数据预处理等场景。本文将带你掌握paddleocr doc2md命令行与 Python API 的完整用法、全部参数语义、三种格式的转换能力边界以及其背后的源码实现原理。1. 功能定位与 OCR 互补的「原生文档」转换通道doc2md 与 PaddleOCR 的 OCR 能力在适用场景上形成互补能力doc2mdOCRPP-OCR 系列模型输入有原始 Office 文件.docx/.xlsx/.pptx图片、扫描件、PDF 截图原理直接解析 Office XML 结构深度学习模型推理速度与资源快零 GPU 依赖依赖模型推理结构化输出标题/表格/公式/图片等原生结构文本框位置与文字doc2md 只认三种格式.docxWord、.xlsxExcel、.pptxPowerPoint不支持.doc旧版 Word、.csv、.pdf。其源码实现位于 paddleocr/_doc2md/ 目录整体分为三个层次registry.pyConverterRegistry注册表按文件扩展名.docx/.xlsx/.pptx或 MIME 类型路由到对应转换器并通过default_registry.register装饰器完成注册base.py定义抽象基类BaseConverter与数据类ConvertResultcore.py对外统一入口convert()负责按扩展名分派转换器、写入输出文件与图片目录converters/三种格式的具体转换器docx.py / xlsx.py / pptx.py以及 math/ 子模块OMML 数学公式转 LaTeX。核心能力一览功能Word (.docx)Excel (.xlsx)PowerPoint (.pptx)标题层级✅ 内置样式 字号启发式 中文编号——文本格式化粗体/斜体/下划线/删除线✅✅✅上标 / 下标✅✅✅超链接✅✅✅列表有序 / 无序 / 嵌套✅——表格含合并单元格✅ HTML table✅ HTML table✅ HTML table图片✅ 按比例宽度✅ 浮动图片✅ 按比例宽度数学公式OMML → LaTeX✅ 行内 / 显示公式✅ drawing 层公式✅代码块✅ 等宽字体自动识别——文本框✅——图表Chart✅ → HTML table—✅ 14 种图表类型页眉 / 页脚✅ 多节 奇偶页——多 sheet / 多幻灯片—✅✅---分隔演讲者备注——✅2. 安装与依赖doc2md 使用延迟导入策略只有真正转换某格式时才加载对应解析库因此基础安装只需要 PaddleOCR 本体按安装教程完成再安装可选依赖pip install paddleocr[doc2md]该 extras 依赖在 pyproject.toml 中定义为四个包包名版本约束用途python-docx0.8.11Word (.docx) 文档解析python-pptx0.6.21PowerPoint (.pptx) 文档解析openpyxl3.0.0Excel (.xlsx) 文档解析pylatexenc2.10,3数学公式 Unicode → LaTeX 符号映射也可按需单独安装见 FAQ 中的报错排查。此外OMML 公式解析依赖lxmlmath/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_drawingsFalse--no-headers-footers→extract_headers_footersFalse--sheet-name/--max-rows原样透传。全部命令行参数参数参数说明类型默认值-i,--input含义输入文件路径必填使用--formats时可省略。说明支持.docx、.xlsx、.pptx格式。str必填-o,--output含义输出 Markdown 文件路径。说明不设置则结果打印到 stdout设置后 Markdown 写入指定文件图片保存到同目录images/文件夹。strNone-q,--quiet含义静默模式。说明不打印耗时、保存路径等提示信息。flagFalse--formats含义列出当前支持的文件格式后退出。说明无需--input。flagFalse--no-drawings含义跳过文本框和 drawing 层内容提取。说明适用于.docx跳过文本框wps:txbx和.xlsx跳过 drawing 层数学公式。flagFalse--no-headers-footers含义跳过页眉页脚内容提取。说明仅适用于.docx。flagFalse--sheet-name含义仅转换指定名称的 sheet。说明仅适用于.xlsx不设置则转换所有 sheet。strNone--max-rows含义每个 sheet 的最大转换行数。说明仅适用于.xlsx用于限制大表格输出。intNone3.2 Python APIfrom 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校验输入文件存在否则抛FileNotFoundError通过default_registry.get_converter()按扩展名路由到转换器未知扩展名抛ValueError附带支持的格式列表调用转换器convert_file()转换期间异常统一包装为RuntimeError若传入output自动创建父目录、写入 MarkdownUTF-8并把result.images中的图片字节写到输出目录的images/下。ConvertResult字段说明定义见 paddleocr/_doc2md/base.py字段类型说明markdownstr转换后的 Markdown 文本imagesdict[str, bytes]提取的图片字典key 为相对路径如images/image1.pngvalue 为图片字节titleOptional[str]文档标题可能为Nonemetadatadict文档元信息如格式类型、sheet 数量等指定输出路径自动保存文件和图片from paddleocr._doc2md import convert # 指定 output 后Markdown 写入文件图片保存到同目录 images/ 下 result convert(report.docx, outputoutput/report.md)各格式可用的 kwargs 参数参数类型默认值适用格式说明extract_drawingsboolTruedocx, xlsx是否提取文本框docx/ drawing 层数学公式xlsxextract_headers_footersboolTruedocx是否提取页眉页脚sheet_nameOptional[str]Nonexlsx仅转换指定名称的 sheetNone表示转换全部max_rowsOptional[int]Nonexlsx每个 sheet 的最大转换行数按格式传入 kwargs 示例from paddleocr._doc2md import convert # Word不提取文本框和页眉页脚 result convert(report.docx, extract_drawingsFalse, extract_headers_footersFalse) # Excel仅转换名为 Sheet1 的 sheet最多 100 行 result convert(data.xlsx, sheet_nameSheet1, max_rows100)提示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映射为 H1Subtitle映射为 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映射到numFmtdecimal/lowerLetter/lowerRoman 等判为有序输出时用 4 空格缩进表示层级docx.py。表格输出为 HTMLtable_table_to_html通过比较底层tc元素自动计算colspan/rowspan还原合并单元格并支持重复标题行tblHeader识别与首行默认表头回退策略docx.py。图片按内容区宽度百分比计算输出img width75%形式。源码读取wp:inline/wp:anchor的extent中的cxEMU 单位除以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 公式并转为 LaTeXxlsx.py这也是--no-drawings参数影响 xlsx 公式提取的原因。4.3 PowerPoint (.pptx)多幻灯片每张幻灯片内容以---分隔文本格式化粗体、斜体、下划线、删除线、上标、下标图片按幻灯片宽度百分比计算输出带宽度的img标签表格HTMLtable格式支持合并单元格支持带背景图片的表格图表支持 14 种图表类型转换为 HTML table 输出分组形状GroupShape_process_shape递归处理嵌套的形状组合pptx.pyPicture / GroupShape / Chart / Table / TextFrame 依次处理数学公式从mc:AlternateContent中提取 OMML 格式公式并转为 LaTeXpptx.py演讲者备注附加在每张幻灯片内容末尾。5. 典型应用场景知识库构建把企业内部 Word 规范、Excel 报表、PPT 培训材料批量转为 Markdown灌入向量库前无需 OCRRAG 数据预处理doc2md 输出的标题层级与 HTML 表格天然适合按 chunk 切分公式保留为 LaTeX 便于数学类文档检索文档对比与迁移将 Office 内容统一为 Markdown 后可使用统一工具链做 diff、发布到静态站点如 MkDocs批量流水线在 Python 脚本中遍历目录调用convert()配合output参数自动落盘 Markdown 与图片。6. FAQQ转换时提示RuntimeError: python-docx is requireddoc2md 采用延迟导入缺少对应格式的解析库时会抛出此错误如 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。QExcel 转换后表格行数很多输出太长使用--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 Sheet1QWord 文档中的页眉页脚内容不需要如何跳过使用--no-headers-footers参数paddleocr doc2md -i report.docx -o output.md --no-headers-footersQ图片输出到哪里使用-o指定输出文件时图片自动保存在输出文件同目录的images/文件夹下由 core.py 中的images_dir output_path.parent / images逻辑落盘。Markdown 文件中的图片引用路径也会相应更新为相对路径如images/image1.png。若不传-o图片仅保留在返回结果的images字典中不会写入磁盘。Qdoc2md 与 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.pyWord 转换器标题/列表/表格/公式/文本框/页眉页脚/图表paddleocr/_doc2md/converters/docx.pyExcel 转换器多 sheet/合并单元格/浮动图片/边界裁剪paddleocr/_doc2md/converters/xlsx.pyPowerPoint 转换器分组形状/图表/备注/公式paddleocr/_doc2md/converters/pptx.pyOMML → LaTeX 公式转换paddleocr/_doc2md/math/omml.py、paddleocr/_doc2md/math/latex_dict.pyCLI 参数定义与映射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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考