5步上手MinerU把PDF和Office文档转成LLM可用的Markdown指南【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU你在为 RAG 知识库、Agent 工作流准备语料时手里的资料往往不是干净文本而是带多栏版式、公式、表格的 PDF、DOCX、PPTX。MinerU 就是干这件事的文档解析工具输入这些文件输出按阅读顺序排好、公式转成 LaTeX、表格转成 HTML 的 Markdown 和 JSON直接喂给大模型。这篇指南带你从安装到第一次跑通再拆解最常用的三个能力和关键配置。跑通第一次最短路径是 5 步按顺序执行即可安装 Python 3.10–3.13 环境安装核心依赖uv pip install mineru[core]core 模块包含解析所需的全部核心依赖体积适中想一次装齐所有加速模块可以改用mineru[all]。国内网络建议先切模型源避免模型下载卡住export MINERU_MODEL_SOURCEmodelscope模型默认托管在 Hugging Face这一行让首次自动下载改走 ModelScope 镜像。用仓库自带的示例 PDF 跑一次解析mineru -p demo/pdfs/demo1.pdf -o ./output执行后 CLI 会自动拉起一个本地临时的 mineru-api 服务来完成解析首次运行会自动下载模型耐心等待即可。打开./output目录你会得到demo1.md主文件以及_middle.json、_content_list.json和可视化质检文件等辅助产物。重点看demo1.md是否通顺、demo1_layout.pdf里的阅读顺序编号是否合理这就是第一份正反馈。MinerU 从 PDF 到 Markdown 的整体链路如下预处理、模型层、管线层最终都落到统一中间态再输出上图展示了 MinerU 的分层设计预处理做乱码检测和扫描版识别管线层做表格合并、公式替换最后统一输出 Markdown 和 content list。核心能力拆解1. 多格式输入与版面还原它能解决的核心问题是顺序错乱多栏、跨页、页眉页脚混在一起的文档解析出来还是一段乱码顺序的文本。MinerU 会自动剥离页眉、页脚、页码输出符合人类阅读顺序的内容且 PDF、图片、DOCX、PPTX、XLSX 都是原生支持。开启方式就是上面那条mineru -p 输入 -o 输出输入可以是单个文件或整个目录。最小示例mineru -p ./my_docs -o ./output一个注意点解析结果好不好最快的验证方式是打开输出目录里的{文件名}_layout.pdf每页会显示每个内容块的阅读顺序编号和类型色块上图展示的是 layout 质检效果数字标记阅读顺序不同底色区分标题、正文、公式块顺序不对一眼就能看出来。2. 公式转LaTeX与表格转HTML学术论文和研报里最让传统解析工具头疼的就是公式和表格。MinerU 的公式解析和表格解析默认都是开启的公式会输出 LaTeX、表格会输出 HTML不需要额外配置。想临时关掉某个能力用 CLI 参数或环境变量都行mineru -p demo/pdfs/demo2.pdf -o ./output -f false -t false-f false关闭公式解析、-t false关闭表格解析对应的环境变量是MINERU_FORMULA_ENABLE和MINERU_TABLE_ENABLE环境变量优先级高于命令行参数在所有子命令里都生效。一个注意点pipeline 后端有一个实验性的中文公式优化开关MINERU_FORMULA_CH_SUPPORT中文论文场景可以打开试试完整说明见 环境变量说明。3. 三种解析后端怎么选这是上手后第一个要做的重要决策。MinerU 提供三种后端用-b参数切换后端特点适合场景pipeline纯 CPU 可跑无幻觉显存要求最低老机器、批量跑普通文档hybrid-engine默认精度高Volta 及以后架构 GPU、8G 显存起有 NVIDIA 显卡的主力选择vlm-http-client轻量客户端本地无需 torch连远程 OpenAI 兼容服务边缘设备、算力集中在服务器最小示例纯 CPU 环境强制走 pipelinemineru -p input.pdf -o ./output -b pipelinehybrid 后端支持--effort medium|high两档解析强度默认 medium 在精度基本不变的前提下速度更快但 medium 档不支持图片/图表分析需要时切 high。注意 vllm 和 lmdeploy 两个加速模块不要同时安装会引入依赖冲突装哪个都可以效果接近。配置与进阶下面是日常最可能用到的几项配置完整清单在 命令行工具文档配置项用途示例值MINERU_MODEL_SOURCE模型下载源切换modelscope/localMINERU_FORMULA_ENABLE公式解析总开关falseMINERU_TABLE_ENABLE表格识别总开关trueMINERU_PROCESSING_WINDOW_SIZE处理窗口大小影响长文档内存与吞吐64MINERU_API_MAX_CONCURRENT_REQUESTSAPI 服务最大并发请求数3-s/-e参数只解析指定页码范围从 0 起-s 0 -e 9怎么选有 NVIDIA 显卡就用默认 hybrid-engine不用改任何配置机器只有 CPU 就加-b pipeline算力和客户端分离的部署就在服务器上用mineru-api起服务、客户端走vlm-http-client远程调用多 GPU 场景再叠加mineru-router做统一入口和负载均衡。想深入调参时vllm/lmdeploy 的官方参数也可以直接透传给 mineru 各子命令。避坑清单现象首次运行长时间无输出。原因正在自动下载模型大模型文件走网络比较慢。解决先export MINERU_MODEL_SOURCEmodelscope切镜像源或用mineru-models-download命令提前下载模型第二次运行直接命中本地缓存。现象vllm 模块安装失败或报 CUDA 相关错误。原因vllm 新版本默认要求兼容 CUDA 13.0 的显卡驱动。解决确认驱动版本支持所装 vllm 对应的 CUDA 运行时或按 Docker 部署文档 用预构建镜像规避环境问题。现象Windows 安装后解析速度慢得像纯 CPU。原因装到的是不带 CUDA 的 torch。解决去 PyTorch 官网选择与你 CUDA 版本匹配的安装命令重装 torch 和 torchvisionRTX 50 系显卡则按 FAQ 安装对应 cu128 的 lmdeploy wheel。现象Linux 上解析结果缺一部分文字。原因部分发行版缺 CJK 字体PDF 渲染成图片时把中文字渲染丢了。解决sudo apt install fonts-noto-core fonts-noto-cjk后刷新字体缓存或直接用自带字体的 Docker 镜像。现象macOS 上想走 Docker 部署报错。原因Docker 方案只支持 Linux 和 WSL2。解决macOS 用户直接 pip/uv 安装即可MPS 加速开箱可用不需要 Docker。解析结果不满意时先别急着提 issue输出目录里的layout.pdf和span.pdf是官方给的质检入口能帮你定位是版面切错还是 OCR 漏字。完整输出文件说明见 output_files常见问题见 FAQ。下一步建议拿一份你自己的真实文档跑一遍打开 layout 文件确认阅读顺序再根据文档类型论文偏公式、报表偏表格决定后端和开关组合跑顺之后可以把content_list.json接进你的 RAG 管线开始真正的批量处理。【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 5步上手MinerU：把PDF和Office文档转成LLM可用的Markdown指南
5步上手MinerU把PDF和Office文档转成LLM可用的Markdown指南【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU你在为 RAG 知识库、Agent 工作流准备语料时手里的资料往往不是干净文本而是带多栏版式、公式、表格的 PDF、DOCX、PPTX。MinerU 就是干这件事的文档解析工具输入这些文件输出按阅读顺序排好、公式转成 LaTeX、表格转成 HTML 的 Markdown 和 JSON直接喂给大模型。这篇指南带你从安装到第一次跑通再拆解最常用的三个能力和关键配置。跑通第一次最短路径是 5 步按顺序执行即可安装 Python 3.10–3.13 环境安装核心依赖uv pip install mineru[core]core 模块包含解析所需的全部核心依赖体积适中想一次装齐所有加速模块可以改用mineru[all]。国内网络建议先切模型源避免模型下载卡住export MINERU_MODEL_SOURCEmodelscope模型默认托管在 Hugging Face这一行让首次自动下载改走 ModelScope 镜像。用仓库自带的示例 PDF 跑一次解析mineru -p demo/pdfs/demo1.pdf -o ./output执行后 CLI 会自动拉起一个本地临时的 mineru-api 服务来完成解析首次运行会自动下载模型耐心等待即可。打开./output目录你会得到demo1.md主文件以及_middle.json、_content_list.json和可视化质检文件等辅助产物。重点看demo1.md是否通顺、demo1_layout.pdf里的阅读顺序编号是否合理这就是第一份正反馈。MinerU 从 PDF 到 Markdown 的整体链路如下预处理、模型层、管线层最终都落到统一中间态再输出上图展示了 MinerU 的分层设计预处理做乱码检测和扫描版识别管线层做表格合并、公式替换最后统一输出 Markdown 和 content list。核心能力拆解1. 多格式输入与版面还原它能解决的核心问题是顺序错乱多栏、跨页、页眉页脚混在一起的文档解析出来还是一段乱码顺序的文本。MinerU 会自动剥离页眉、页脚、页码输出符合人类阅读顺序的内容且 PDF、图片、DOCX、PPTX、XLSX 都是原生支持。开启方式就是上面那条mineru -p 输入 -o 输出输入可以是单个文件或整个目录。最小示例mineru -p ./my_docs -o ./output一个注意点解析结果好不好最快的验证方式是打开输出目录里的{文件名}_layout.pdf每页会显示每个内容块的阅读顺序编号和类型色块上图展示的是 layout 质检效果数字标记阅读顺序不同底色区分标题、正文、公式块顺序不对一眼就能看出来。2. 公式转LaTeX与表格转HTML学术论文和研报里最让传统解析工具头疼的就是公式和表格。MinerU 的公式解析和表格解析默认都是开启的公式会输出 LaTeX、表格会输出 HTML不需要额外配置。想临时关掉某个能力用 CLI 参数或环境变量都行mineru -p demo/pdfs/demo2.pdf -o ./output -f false -t false-f false关闭公式解析、-t false关闭表格解析对应的环境变量是MINERU_FORMULA_ENABLE和MINERU_TABLE_ENABLE环境变量优先级高于命令行参数在所有子命令里都生效。一个注意点pipeline 后端有一个实验性的中文公式优化开关MINERU_FORMULA_CH_SUPPORT中文论文场景可以打开试试完整说明见 环境变量说明。3. 三种解析后端怎么选这是上手后第一个要做的重要决策。MinerU 提供三种后端用-b参数切换后端特点适合场景pipeline纯 CPU 可跑无幻觉显存要求最低老机器、批量跑普通文档hybrid-engine默认精度高Volta 及以后架构 GPU、8G 显存起有 NVIDIA 显卡的主力选择vlm-http-client轻量客户端本地无需 torch连远程 OpenAI 兼容服务边缘设备、算力集中在服务器最小示例纯 CPU 环境强制走 pipelinemineru -p input.pdf -o ./output -b pipelinehybrid 后端支持--effort medium|high两档解析强度默认 medium 在精度基本不变的前提下速度更快但 medium 档不支持图片/图表分析需要时切 high。注意 vllm 和 lmdeploy 两个加速模块不要同时安装会引入依赖冲突装哪个都可以效果接近。配置与进阶下面是日常最可能用到的几项配置完整清单在 命令行工具文档配置项用途示例值MINERU_MODEL_SOURCE模型下载源切换modelscope/localMINERU_FORMULA_ENABLE公式解析总开关falseMINERU_TABLE_ENABLE表格识别总开关trueMINERU_PROCESSING_WINDOW_SIZE处理窗口大小影响长文档内存与吞吐64MINERU_API_MAX_CONCURRENT_REQUESTSAPI 服务最大并发请求数3-s/-e参数只解析指定页码范围从 0 起-s 0 -e 9怎么选有 NVIDIA 显卡就用默认 hybrid-engine不用改任何配置机器只有 CPU 就加-b pipeline算力和客户端分离的部署就在服务器上用mineru-api起服务、客户端走vlm-http-client远程调用多 GPU 场景再叠加mineru-router做统一入口和负载均衡。想深入调参时vllm/lmdeploy 的官方参数也可以直接透传给 mineru 各子命令。避坑清单现象首次运行长时间无输出。原因正在自动下载模型大模型文件走网络比较慢。解决先export MINERU_MODEL_SOURCEmodelscope切镜像源或用mineru-models-download命令提前下载模型第二次运行直接命中本地缓存。现象vllm 模块安装失败或报 CUDA 相关错误。原因vllm 新版本默认要求兼容 CUDA 13.0 的显卡驱动。解决确认驱动版本支持所装 vllm 对应的 CUDA 运行时或按 Docker 部署文档 用预构建镜像规避环境问题。现象Windows 安装后解析速度慢得像纯 CPU。原因装到的是不带 CUDA 的 torch。解决去 PyTorch 官网选择与你 CUDA 版本匹配的安装命令重装 torch 和 torchvisionRTX 50 系显卡则按 FAQ 安装对应 cu128 的 lmdeploy wheel。现象Linux 上解析结果缺一部分文字。原因部分发行版缺 CJK 字体PDF 渲染成图片时把中文字渲染丢了。解决sudo apt install fonts-noto-core fonts-noto-cjk后刷新字体缓存或直接用自带字体的 Docker 镜像。现象macOS 上想走 Docker 部署报错。原因Docker 方案只支持 Linux 和 WSL2。解决macOS 用户直接 pip/uv 安装即可MPS 加速开箱可用不需要 Docker。解析结果不满意时先别急着提 issue输出目录里的layout.pdf和span.pdf是官方给的质检入口能帮你定位是版面切错还是 OCR 漏字。完整输出文件说明见 output_files常见问题见 FAQ。下一步建议拿一份你自己的真实文档跑一遍打开 layout 文件确认阅读顺序再根据文档类型论文偏公式、报表偏表格决定后端和开关组合跑顺之后可以把content_list.json接进你的 RAG 管线开始真正的批量处理。【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考