AI工作流 - PDF/Word和Markdown的转换方案：pandoc markitdown，mineru

AI工作流

Word和Markdown互转常规方案：pandoc和MarkItDown

Markdown转Word

使用AI工具对代码快速梳理出包含流程图和公式的markdown文档，markdown包含mermaid和LaTeX，直接用typora导出word格式不成功，需要借助drawio和pandoc命令行。

pandoc转化为latex公式

使用命令行，将Markdown转换为Word，latex公式以MathML格式嵌入Word

1
pandoc input.md -o output.docx --mathml

注意直接用typora里面调用pandoc是转不了公式的，必须用pandoc命令行–mathml

参考 科研神器Pandoc：秒将包含LaTeX公式的Markdown转换为Word

mermaid流程图转化为drawio

将markdown的mermaid流程图代码插入drawio：调整图像->插入->高级->mermaid

然后手动调整流程图曲线，最后另存为png图片，插入word。

注意有的mermaid代码插入drawio报错，可能是流程图的文字字符不符合语法，修改对应行的文字描述

参考 Drawio使用——mermaid语法

Word转Markdown

可用选项

在线工具

  1. Word2MD.net：支持将 Word (.docx) 文档在线转换为干净、结构化的 Markdown，保留标题、列表、表格、链接和图片。支持批量文件处理和 ZIP 下载，所有操作在浏览器本地完成，确保隐私安全
  2. Doc2Markdown：可将 Word、PDF、PowerPoint、Excel 等文档转换为优化的 Markdown，提供实时编辑和预览功能，自动处理表格和图片，适合技术写作者和学生

Python 工具

  • MarkItDown（微软开源）：支持 Word、PDF、PPT、Excel 等多种格式转换为 Markdown，具备 OCR 文字识别、语音转文字和元数据提取功能，适合文档分析和内容索引场景。通过 pip 安装后可在 Python 中调用进行批量转换

本地工具与插件

  1. Pandoc：强大的文档转换工具，支持 Word 转 Markdown。使用命令行 pandoc input.docx -o output.md 即可生成 Markdown 文件
  2. VS Code 插件：安装 “Word to Markdown” 或 “Markdown Paste” 插件，可直接在 VS Code 中打开 Word 文件并转换为 Markdown，支持粘贴内容自动格式化

实测

pandoc处理纯文本word性能最好，MarkItDown配合图片插件是效果最好的，可以提取word中图片输出到markdown相对路径

1
2
git clone git@github.com:microsoft/markitdown.git
pip install markitdown[all]
  • 图片插件安装：

https://pypi.org/project/markitdown-docx-image-plugin/

1
2
pip install markitdown-docx-image-plugin
markitdown --list-plugins

使用：

1
markitdown --use-plugins "D:\path\doc.docx" -o "D:\path\.md"

图片会被提取到markitdown所在路径，需拷贝到.md相同路径

markitdown缺陷：总有部分图片解析不出来

PDF/Word转Markdown最佳方案: mineru

mineru环境搭建

官方说明 https://github.com/opendatalab/MinerU

MinerU — High-accuracy document parsing engine for LLM · RAG · Agent workflowsConverts PDF · DOCX · PPTX · XLSX · Images · Web pages into structured Markdown / JSON

python虚拟环境中安装

1
2
3
4
5
6
7
8
9
10
11
# 在当前目录创建新的 venv
uv venv
# 激活 venv（重要！）
.venv\Scripts\activate
# 验证当前 Python
where python
# 应该只显示一个：C:\ai-projects\minerU\.venv\Scripts\python.exe
# 安装 mineru（这次会装到 venv 里）
uv pip install -U "mineru[all]"
# 运行
mineru -p xxx.pdf -o . -b pipeline

python系统全局环境中安装（新手推荐）

1
2
3
4
# 直接在系统 Python 安装
pip install -U "mineru[all]"
# 运行
mineru -p xxx.pdf -o . -b pipeline

如何卸载

方法一：卸载 mineru 专有包

1
2
3
只卸载 mineru 明确引入的包，保留通用包（如 numpy、torch、transformers 等可能被其他项目使用的包）：

pip uninstall mineru mineru-vl-utils magika pdftext pypdfium2 pypptx-with-oxml langdetect mammoth pylatexenc reportlab fast-langdetect modelscope lmdeploy mmengine-lite

方法二：pip-autoremove 插件（最推荐）

这是一个专门解决此类问题的 pip 插件——卸载一个包时同时清理它的依赖（如果依赖没有被其他包使用的话）。

1
2
3
4
5
6
7
8
# 安装 pip-autoremove*
pip install pip-autoremove

*# 卸载 mineru 及其不再需要的依赖*
pip autoremove mineru -y

*# 或者完整卸载 [all] 相关包*
pip autoremove "mineru[all]" -y

方法三：使用 uv 工具（最现代）

如果你用 uv 作为包管理器：

1
2
3
4
5
# uv 可以追踪依赖关系*
uv pip install mineru[all]

*# 卸载并自动清理不需要的依赖*
uv pip uninstall mineru

uv 比 pip 更智能，会自动处理依赖清理。

pdf转化示例

转化pdf到markdown：

  • 输入：pdf包含图片和表格
  • 输出：markdown图片和表格均正常，图片使用相对路径./images存储。
  • 使用MFR predict，OCR，速度较慢
1
mineru -p OA_RCP_specification_v_0.4.7_rev1.pdf -o . -b pipeline

image-20260826181429713

word转化示例

  • 输入：docx包含图片和公式
  • 输出：markdown的图片均正常，公式转化为图片有格式错乱
  • 速度很快
1
mineru -p 基于Tenvenin模型的CKF算法估计SOC.docx -o . -b pipeline

image-20260826182655818

将word转化为pdf后，再转化为markdown：

  • 图片正常，公式正常

image-20260826183242940

mineru问题记录

转化大pdf文件（几百页）有内存报错

错误 1：numpy 内存分配失败

1
numpy._core._exceptions._ArrayMemoryError: Unable to allocate 7.38 MiB for an array with shape (960, 672, 3) and data type float32

错误 2：PyTorch CPU 分配器失败

1
RuntimeError: [enforce fail at alloc_cpu.cpp:121] data. DefaultCPUAllocator: not enough memory: you tried to allocate 3686400 bytes.

错误 3：OpenBLAS 内存分配失败

1
OpenBLAS error: Memory allocation still failed after 10 retries, giving up.

错误 4：Pickle 序列化内存溢出

1
MemoryError

原因：Windows 页面文件 (Page File) 不足

根本原因不是物理内存不够，而是 Windows 页面文件已满。

执行 python -c "import psutil;

print(psutil.swap_memory())" 可看到类似输出：

1
2
3
4
5
Total RAM: 15.7 GB
Available RAM: 8.7 GB
Total Page File: 4.0 GB
Used Page File: 4.0 GB (100%)
Free Page File: 0.0 GB
  1. PyTorch 加载 layout/OCR 模型时申请大块虚拟地址空间（即使在 CPU 上运行也会预留）
  2. 物理内存不足时，Windows 把冷数据换出到页面文件
  3. 页面文件只有 4GB 且已 100% 满，无法继续扩展虚拟内存
  4. 任何内存分配（包括几 MB 的小数组）都直接失败

解决：扩大 Windows 页面文件

  1. 按 Win + R，输入 sysdm.cpl，回车
  2. 「高级」选项卡 → 「性能」区域的「设置」
  3. 切换到「高级」选项卡 → 点击「虚拟内存」区域的「更改」
  4. 取消勾选「自动管理所有驱动器的分页文件大小」
  5. 选择 C 盘 → 选择「自定义大小」
    • 初始大小：8192 MB (8 GB)
    • 最大值：16384 MB (16 GB)
  6. 点「设置」→「确定」
  7. 重启电脑（必须重启才生效）

小结

mineru基本可以满足pdf和word等复杂文档转化为AI工作流可用的markdown文档，可极大提高AI模型的信息获取准确性。

与之对比，使用大模型临时产生的python脚本只能提取pdf/word中的纯文本部分或暴力截取图片，信息易丢失。