| name | mineru-office-to-markdown |
| description | 使用开源 MinerU 在本地将 PDF、DOCX、PPTX、XLSX 及常见图片转为 Markdown（及配套资源）， 便于知识库、RAG、Baklib 录入前处理。在用户提到 MinerU、办公文档转 Markdown、 PDF 转 MD、PPT/Word 抽取正文、本地批量解析、pipeline 后端时使用。 |
MinerU：办公文档 → Markdown（本地）
MinerU 可将 PDF、DOCX、PPTX、XLSX、图片 等转为 Markdown / JSON 等结构化结果，表格多为 HTML 表格嵌入 MD，复杂版式还原能力较强。本技能说明在你本机的安装方式、推荐 CLI 参数，以及目录批量时的必备注意事项。
官方文档：Usage · CLI 参数 · 常见问题
本技能不做什么
- 不在此仓库内执行 MinerU：解析依赖本机 Python 环境与较大模型下载，须由使用者在自己的工作区终端运行命令。
- 不替代 MinerU 官方对许可证、商用范围与模型来源的说明；生产或对外分发前请阅读仓库 LICENSE。
- 不保证 对
.doc（老版 Word）直接支持：MinerU 以 DOCX 等现代格式为主；老文档请先另存为 DOCX 或 PDF 再转换。
前置条件
- Python：3.10–3.13（Windows 上若依赖限制，请以官方文档为准，常见为 3.10–3.12）。
- 磁盘与内存：全量安装与模型缓存通常需要数十 GB 磁盘与足够内存；大 PDF 首次运行会下载模型，耗时较长。
- 网络：首次使用需能从模型源拉取权重（见官方「模型源配置」）。
安装（推荐）
在独立虚拟环境中安装，避免污染系统 Python：
pip install --upgrade pip
pip install uv
uv venv .venv
source .venv/bin/activate
uv pip install -U "mineru[all]"
源码安装与精简依赖见官方 Quick Start 与 Extension Modules。
单文件转换
将 <输入文件> 换为你的 PDF / DOCX / PPTX / XLSX / 图片路径，<输出目录> 为已存在或可由工具创建的父目录：
mineru -p "<输入文件>" -o "<输出目录>" -b pipeline -l ch
说明：
-b pipeline：兼容面广，可在纯 CPU 环境运行（具体以本机实测为准）；需要更高精度时可查阅官方后端对比表改用 hybrid-* / vlm-*（硬件要求更高）。-l ch：中文 OCR/版面语言提示；多语言文档请查阅 CLI 的 -l 可选值。
仅处理 PDF 部分页（0-based）示例：
mineru -p "<输入.pdf>" -o "<输出目录>" -b pipeline -l ch -s 0 -e 9
更多参数（公式/表格开关、环境变量等）见官方 CLI 工具说明。
目录批量（重要）
当前 CLI 对「输入目录」的扫描通常只处理该目录下的直接文件，不会递归子文件夹。若根目录下只有子目录、没有散落文件，会报 No supported documents found。
推荐做法（二选一）：
- 分批：对每个仅含素材文件的子文件夹分别执行一次
mineru -p "<子目录>" -o "<输出根>" ...。
- 扁平化：将支持的文件复制到单层临时目录（注意重名可加前缀），再对该临时目录执行一次
mineru。
支持的扩展名以官方为准，一般包括：pdf、docx、pptx、xlsx、常见图片格式等。CSV 等表格文件通常不在同一套「版式解析」路径内，需改用表格工具或专用导入流程。
输出结果怎么找
成功后在输出目录下会按文档名生成子文件夹；常见情况：
- 版式解析结果可能在
auto/ 下生成 *.md 与 images/ 等。
- Office 原生解析结果可能在
office/ 下生成 *.md（以你本机 MinerU 版本实际目录为准）。
若日志中出现与 *_origin.pdf 可视化相关的 Skipping visualization，多为可选中间件缺失，不一定表示正文 Markdown 未生成，请以对应 *.md 是否存在为准。
与 Baklib 工作流衔接
转换得到的 Markdown 与图片可在本地校对后，再使用本仓库 baklib-data-import 将文件批量迁入 Baklib DAM（或按你们镜像规范放入 baklib-intake-assistant 约定目录）。路径、元数据与脱敏规则以各技能说明为准。
故障排查提示
- 首次大文档失败、第二次成功：多为首次仍在下载模型；可先对少量页试跑，再全量。
- 超时或内存：查阅官方 FAQ；可尝试调整官方文档中的窗口/并发相关环境变量（如
MINERU_PROCESSING_WINDOW_SIZE 等）。
- 命令帮助：
mineru --help。
