做 RAG 的人早晚会遇到一个灵魂拷问：辛苦搭好的向量库，为什么检索出来的内容总是答非所问？我自己的经验里，一半以上问题出在文档解析这一步。PDF 解析质量不行，后面向量化、检索做得再花哨也是白搭。所以这次我决定把 MinerU 4.0 在 Windows 上老老实实本地部署一遍，用它做 RAG 文档预处理，把 PDF 离线解析成结构化 Markdown。这篇东西就是完整记录，从环境准备、安装踩坑、命令行和 Python API 调用，到怎么把它接进 RAG 流水线，全部按实际过程写，直接能抄作业。

MinerU 是一款开源文档解析工具，能把 PDF 识别成带结构信息的 Markdown，重点解决扫描件、复杂排版、表格和公式这些传统文本提取工具搞不定的场景。本地部署意味着整个解析过程不依赖公网服务，文档不用出内网，对做私有知识库、企业文档库的朋友来说，这一步是刚需。这篇文章适合谁看？已经在做 RAG 但被 PDF 预处理折磨过的人，打算把 MinerU 接进自己知识库流程的开发者，以及想在 Windows 上跑通 GPU/CPU 解析环境的新手。我会尽量把原理和操作都讲透，让你看完不是只会跑命令，而是知道为什么这么做。

1. 为什么 RAG 的老毛病出在文档解析

做 RAG 检索增强生成，常规流程就是：文档加载、文本清洗、切片、向量化、召回、再扔给大模型生成答案。大部分人把精力花在切分策略和向量库调优上，但很少会回头怀疑一开始的文档解析质量。实际上这一步埋的雷最多。

1.1 RAG 链路里最容易被低估的解析环节

拿一本扫描版技术书或者一份双栏排版的行业报告举例。如果用 PyMuPDF 这类库直接提取文字，扫描件很多时候根本没有文本层，提取出来是空的；双栏排版提取出来则是左栏一段、右栏一段乱七八糟穿插；表格会变成一堆无意义的数字串；页眉页脚还会混进正文语料。

这些问题到了向量化阶段会放大。切片按长度硬切，把两张表格内容、正文段落和页脚页码切进同一个 chunk，检索时返回的上下文就是一堆垃圾。大模型拿到这种上下文，回答自然天马行空。我见过太多人折腾 prompt 折腾半天，最后发现是解析环节把文档搞坏了。所以我说，RAG 的瓶颈往往不在检索算法，也不在向量库选型，而在最前面那道 PDF 解析工序。

1.2 MinerU 不是普通的 PDF 转文本工具

MinerU 和那些一键转 Word 的在线工具完全不是一回事。它内部是一条完整的文档解析管线，核心做了四件事：第一，版面分析，识别出标题、正文、图表、页眉页脚、页码这些区域，并给出阅读顺序；第二，OCR 识别，不依赖 PDF 自带文本层，直接对图像做文字检测和识别，扫描件也能处理；第三，公式识别，把数学公式转成 LaTeX 格式，而不是拍成一堆乱码；第四，表格还原，把表格结构化输出成 Markdown 表格，而不是把单元格内容挤成一行文字。

4.0 版本给我最明显的感受是整体解析速度更快，版面分析模型对复杂排版的容错能力也更强。底层模型虽然会随着版本迭代有变化，但核心思路没变——先理解版面结构，再做内容提取。这个"先结构后内容"的逻辑就是它和普通文本抽取的本质差别。

1.3 为什么选择本地离线部署

我选本地部署的原因很简单：要解析的 PDF 里有大量内部资料，不允许上传到任何公网服务。离线部署意味着模型权重、推理过程全部跑在本地机器上，数据不出内网，合规性上更让人放心。另一个原因是批量效率，在线接口通常有并发限制和大小上限，本地部署没有这些束缚，解析几十份几百份 PDF 都行。

当然本地部署也有代价，主要是环境维护和硬件要求。这篇文章我假设你用的是 Windows 10 或 11，后面所有命令都是基于 Windows 环境写的。

2. 部署前必须想清楚的几件事

很多人拿到一个开源工具就急着 pip install，装完跑不起来才回头排查环境。MinerU 不是那种零依赖的小工具，部署前先搞清楚三件事：用什么方式装、用什么硬件跑、模型文件放哪里。这三点想明白，后面会顺畅很多。

2.1 三种部署方式的取舍

Windows 上跑 MinerU 主要有三条路：直接 pip 安装到原生 Windows、装 WSL 在 Linux 子系统里跑、用 Docker 容器跑。我的建议是，没有特殊需求就选原生 pip，最直接，也和本文步骤对得上。

WSL 的好处是 Linux 生态干净，但文件路径转发和 GPU 透传偶尔有毛病；Docker 的好处是环境隔离彻底，但 Windows 上 Docker Desktop 本来就吃内存，再把模型文件塞进容器，管理起来也麻烦。我实际对比下来的结论：如果你只是想在 Windows 上把 PDF 转成 Markdown，原生安装就够了。如果你是团队协作要统一环境，那才考虑 Docker 镜像。

2.2 GPU 和 CPU 的影响有多大

MinerU 的解析包含神经网络推理，所以显卡很关键。有 NVIDIA 显卡并且装好了 CUDA，解析速度会快很多，体验流畅。没有 N 卡也没关系，CPU 模式能跑，只是速度慢，一份几十页的扫描 PDF 可能要等几分钟，而 GPU 可能十几秒就完事。

怎么判断自己能不能用 GPU？打开 PowerShell 跑一句nvidia-smi。如果正常输出显卡信息，说明驱动已经就绪。输出nvidia-smi不是内部或外部命令，就得先去装驱动。有了显卡驱动还不够，还得确认 PyTorch 能调用 CUDA。这个后面安装完再验证。

如果机器配置比较老，只有 CPU，也不要急着放弃。MinerU 本身支持 CPU 推理，模型文件会选中性化一些的配置，解析小文件完全可以用。只是批量处理大批 PDF 时，CPU 模式的耗时可能让你怀疑人生。

2.3 模型文件与磁盘空间

MinerU 是模型驱动型工具，首次运行时需要下载若干模型文件，包括 OCR 识别模型、版面分析模型、公式识别模型和表格模型。文件加起来少说几 GB，多则十几 GB，磁盘空间要提前留够。

模型下载地址通常可以通过环境变量指定，例如使用 ModelScope 魔搭这类模型仓库，按官方文档配置好对应变量就能走国内可访问的下载源。如果你有离线环境需求，可以在一台联网机器上把模型下载完，按缓存目录结构拷到离线机器上，这样部署纯粹离线，完全不依赖外网。Windows 上模型缓存目录一般在用户主目录下的.cache文件夹中，具体路径看日志输出。

3. MinerU 4.0 安装实操

环境思路理清后，安装本身其实不难，但有几个细节不处理会卡住。我按实际操作顺序写，遇到的报错也放在后面一起说。

3.1 用虚拟环境隔离，避免把系统 Python 搞乱

我强烈建议先用虚拟环境隔离。MinerU 依赖的包版本比较倔，和公司里其他 Python 项目混在一起容易冲突。具体来说，用 conda 或者 Python 自带的 venv 都行。

conda create -n mineru python=3.10 -y conda activate mineru

如果你不想装 conda，用 venv 也可以：

python -m venv mineru-env .\mineru-env\Scripts\activate

激活后命令行前面会出现(mineru-env)这样的前缀，说明当前环境的 Python 已经隔离了。这个步骤很关键，后面装再多的包也不会影响系统里其他项目。

3.2 pip 安装与版本验证

激活环境后直接装 MinerU：

pip install mineru

如果下载速度不理想，可以临时指定 pip 镜像源：

pip install mineru -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后验证一下：

mineru --version

能输出版本号就说明装上了。我在 Windows 上遇到过一个问题：装完命令报不是内部或外部命令，原因通常是虚拟环境的 Scripts 目录没进 PATH，或者终端没重启。重新激活环境、重开终端一般能解决。

3.3 模型下载与首次运行

第一次运行 MinerU 时，它会自动下载模型，这个阶段特别考验网络。我的建议是，在跑正式文件之前，先拿一个小 PDF 试一次，故意让它在模型下载环节跑起来，这个时候你要盯住日志，看模型下载是否成功。

如果你有网络条件限制，可以提前用环境变量把模型仓库切到 ModelScope。在 PowerShell 里设置：

$env:MODELSCOPE_CACHE = "D:\models" $env:MODELSCOPE_DOMAIN = "modelscope.cn"

然后再跑解析命令。模型会下载到指定目录，后面再用就不需要重复下载了。如果想完全离线，把整个缓存目录拷到目标机器的同样位置就能复用。

3.4 Windows 上常见安装报错

我实际踩过的坑不多，但确实有几个典型问题值得提前说。

第一个是 Microsoft C++ Build Tools 缺失。部分依赖包在 Windows 上需要编译原生代码，报错信息一般是error: Microsoft Visual C++ 14.0 is required。解决办法就是去装 Visual Studio Build Tools，安装时勾选“使用 C++ 的桌面开发”工作负载。

第二个是杀毒软件拦截进程。Windows Defender 有时会把 python 进程在解析时的行为误判成异常，导致解析中断。遇到类似情况，先把工作目录加入 Defender 排除项，或者临时关掉实时防护测试。

第三个是路径带中文或空格导致解析失败。MinerU 对中文路径的处理在旧版本上确实有坑，4.0 好了很多，但还是建议输入输出目录用纯英文路径，省心。

4. 核心实操：把 PDF 变成结构化 Markdown

工具装好、模型跑通之后，真正的工作才开始。MinerU 提供了命令行和 Python API 两套用法，日常临时解析用命令行，批量预处理用 Python 脚本。

4.1 命令行把 PDF 转成 Markdown

先看最基本的命令：

mineru -p input.pdf -o ./output --lang zh

-p指定输入的 PDF 文件，-o指定输出目录，--lang指定文档语言，zh表示中文。如果不指定语言，MinerU 会自动检测，但中文文档建议直接显式指定，识别准确率更高，还能省掉自动检测的时间。

执行完成后，输出目录下会生成一个和 PDF 同名的文件夹，里面有*.md文件、images子目录，以及 JSON 格式的中间结果。Markdown 文件就是我们要的结果，它保留了标题层级、段落划分、表格结构，公式是 LaTeX 格式，图片则单独抽出来放在 images 目录，Markdown 里用相对路径引用。

4.2 关键参数怎么选

MinerU 命令行参数不少，但真正影响成败的就那么几个。

--workers控制并行进程数。CPU 核多的机器可以调大一点，比如--workers 4，解析会快不少。但如果机器本身内存不大，并行进程开多了容易内存暴涨，建议保守一点，先 2 个试试。

--device可以指定设备类型，CPU 模式就是--device cpu。如果你的机器有 NVIDIA GPU，不指定它也会自动优先用 GPU，但我建议显式指定，避免模型加载时来回试探。

--formula和--table分别控制公式和表格识别开关。默认都是开启的，如果确认文档里没有公式或表格，把这些开关关掉能明显提速。反过来，遇到数学论文或者财务报表，这些开关必须开着。

关于 OCR 模式，MinerU 会自动判断 PDF 是否需要 OCR。文本型 PDF 会直接走文本提取通道，速度很快；扫描型 PDF 没有文本层，就自动走 OCR 识别。这种自适应逻辑省事，但如果你明知道文档是扫描件，想强制 OCR，可以看看命令行参数里有没有--force-ocr之类的选项，按需打开。

4.3 Python 批量调用与参数控制

命令行处理单个 PDF 很方便，但 RAG 文档预处理往往要一次性处理一个目录下几十上百个 PDF。这时候用 Python 封装最合适。

MinerU 提供 Python API，可以直接在代码里调用解析逻辑。不过我从实用角度建议一种更稳的方式：用subprocess调命令行，这样版本升级后只要命令格式没大变，脚本基本不用改。

import subprocess import pathlib import logging LOGGER = logging.getLogger(__name__) def parse_pdf(pdf_path, output_root): pdf_path = pathlib.Path(pdf_path) output_root = pathlib.Path(output_root) output_root.mkdir(parents=True, exist_ok=True) result = subprocess.run( [ "mineru", "-p", str(pdf_path), "-o", str(output_root), "--lang", "zh", "--workers", "2", ], capture_output=True, text=True, encoding="utf-8", ) if result.returncode != 0: LOGGER.error(f"解析失败: {pdf_path} | {result.stderr}") return False md_file = output_root / f"{pdf_path.stem}.md" if not md_file.exists(): LOGGER.warning(f"没找到 md 文件: {pdf_path}") return False LOGGER.info(f"解析完成: {pdf_path} -> {md_file}") return True def batch_parse(pdf_dir, output_root): pdf_dir = pathlib.Path(pdf_dir) for pdf_path in pdf_dir.glob("*.pdf"): parse_pdf(pdf_path, output_root / pdf_path.stem) if __name__ == "__main__": logging.basicConfig(level=logging.INFO) batch_parse(r"./docs", r"./parsed")

这段脚本有几个细节值得说。第一，encoding="utf-8"很重要，Windows 控制台默认编码是 GBK，不指定的话中文报错信息会乱码。第二，解析完要检查 md 文件是否存在，防止进程静默失败。第三，每个 PDF 对应一个独立输出目录，这样后续 RAG 加载器可以直接按目录扫描。

如果你想用 MinerU 的 Python API 而不是 subprocess，可以按官方文档导入对应的解析入口类，传入参数几乎和命令行一一对应，返回结果可以直接拿到内存里处理，省掉文件读写环节。但批量预处理场景下，subprocess 的方式有天然优势：进程隔离，单个 PDF 崩了不会拖垮整个脚本，还可以方便地用外部工具监控进度。

4.4 输出结构解读与质量检查

解析完成的输出目录里，除了 Markdown 文件还有 JSON 中间产物，很多人不看这些文件，其实它们对检查解析质量很有用。JSON 文件记录了每一页识别出来的版面结构，包括文本块、图片区域、表格区域的位置和内容，如果后续要做自定义后处理，这些结构信息比 Markdown 更细致。

质量检查这一环不能省。我见过太多人跑完命令看都没看就直接把结果丢进向量库，结果错的一塌糊涂。快速检查方法就是随机抽几页，对照原 PDF 检查：标题层级对不对、表格还原对不对、公式是不是 LaTeX、页眉页脚是否被正确剔除。

如果发现版面顺序错乱，优先检查语言参数是否指定正确；如果表格还原质量差，考虑该文档是否排版过于复杂；如果是图片型扫描件但没走 OCR，看看是否有强制 OCR 选项。质量检查这件事，花 5 分钟能省下后面几天调检索效果的功夫。

5. 把 MinerU 接进 RAG 文档预处理链路

工具单独能跑只是第一步。真正让 MinerU 发挥价值，是把它嵌进 RAG 文档预处理流水线里，让解析结果直接成为向量库的输入。这里我分享一套我实际在用的落地姿势。

5.1 预处理流水线的落地姿势

一个成熟的 RAG 文档预处理流水线，至少要包含四个阶段：输入监测、格式解析、内容清洗、切片入库。MinerU 处在“格式解析”环节，但前后需要其他逻辑衔接。

我的方案是维护两个目录：inbox放新接收的 PDF，parsed放解析好的 Markdown。预处理脚本扫描inbox，发现新文件就调 MinerU 解析，成功后把 PDF 移到processed目录，防止重复处理，同时把 Markdown 路径写入一个待处理队列，供后续切片入库任务消费。

这种“目录驱动”的模式虽然简单，但配合任务调度器可以做成自动运行的流水线。新 PDF 一进inbox，几分钟后向量库里就有它的索引了。Windows 下用计划任务定时跑脚本就够，不需要上复杂的编排系统。

5.2 切分加载与向量化建议

MinerU 输出的是 Markdown，好处是结构信息都在，切分时可以按标题切。市面上常见的文档加载器和切分器大多支持 Markdown 格式，他们能识别#标题层级，按层级切分要比按固定字符长度切科学得多。

接入 LangChain 这类框架时的通用思路是：用 Markdown 加载器读取parsed目录下的文件，然后按标题层级切分，最后向量化存入向量库。如果用的是 Ollama 跑本地大模型，配合一个简易 RAG 知识库流程也是可以的，关键是文档预处理这一步能直接复用 MinerU 的输出。

关于chunk_size和overlap的选择，我的经验是：解析质量高的情况下，可以放心用较大的 chunk，比如 800 到 1200 字符，overlap 控制在 100 到 200。因为 Markdown 结构完整，一个大 chunk 内部通常是语义连贯的内容；解析质量差的情况下，再小切分也救不回来。这也是为什么我反复强调前一步质量检查重要。

5.3 小专题：知识库能不能存图片

热搜里有个问题我觉得挺有意思：“RAG 知识库能存储图片吗？”这个得分情况。传统文本向量库存的是文本的向量表示，PDF 里的图片本身是不能直接被文本向量库索引的。MinerU 解析 PDF 时会把图片抽到images目录，Markdown 里只保留图片路径引用。如果 RAG 链路用的是通用向量模型，图片内容根本无法参与检索，那图片路径对检索结果没有影响，但 Markdown 里保留了结构信息，至少图片不会变成乱码字符污染上下文。

如果你想真正让图片内容参与检索，得走多模态路线：先用多模态模型把图片生成描述文本，再把描述文本向量化。MinerU 抽出图片后，你可以自己加一个步骤，对每张图片调用多模态模型生成 caption，再把 caption 拼进文档。这套方案成本高一些，但确实可行。

5.4 解析前后效果对比

我拿自己手头一份几十页的中文年报 PDF 做过对比。用传统文本提取工具直接抽文本，出来的内容里表格全乱，两栏文字穿插，检索“营收同比”这种关键词，召回的内容牛头不对马嘴。同样的文件走 MinerU 解析后，表格还原成规整的 Markdown 表格，版面顺序恢复正确，公式也转成了 LaTeX，向量检索的命中率提升非常明显。

这不是玄学，而是因为向量化阶段吃的是语义完整的文本块，解析质量直接决定语义 chunk 的质量。所以如果你觉得 RAG 效果一直上不去，与其反复调 prompt，不如回头看看文档解析这一步有没有做好。

6. 常见问题与排查技巧实录

最后这一部分，我把实操中遇到的典型问题和排查思路整理成表格，方便你按图索骥。这些坑很多都不在官方文档里，属于实战经验。

6.1 显存不足与 CPU 太慢怎么权衡

没有 GPU 的机器跑 MinerU，确实需要耐心。一份几页的文本型 PDF 可能几秒就完，但扫描型 PDF 会慢很多。我的建议是：如果只是零散解析几个文件，CPU 模式完全能忍；如果你打算在 Windows 上批量处理大量历史 PDF，建议弄一张二手 NVIDIA 显卡，或者租一台带 GPU 的 Windows 云主机跑预处理，处理完再下载结果，这样性价比最高。

显存不足的问题常见于老显卡。调小--workers是最直接的解决办法。另外可以尝试关闭公式或表格识别，模型占用会显著下降。

6.2 表格公式识别不准

表格识别不准的情况多出现在非常复杂的嵌套表格、跨页表格上。MinerU 对规整表格的还原能力很强，但遇到复杂表格，输出多少会有点歪。我的处理方式是：如果是重要的表格，解析后人工对照修正一下；如果不重要，接受它的不完美，毕竟比直接提取的乱码强太多。公式识别不准时，检查 PDF 原图的分辨率是不是太低，低分辨率扫描件里的小字号公式确实难识别。

6.3 模型下载失败与离线缓存

模型下载失败是最烦人的问题之一，因为中途失败会导致缓存目录里留下不完整文件，下次运行仍然报错。最稳妥的流程是：先跑一次小文件，确认所有模型都下载成功；再开始批量任务，这样不会跑到一半才发现模型有问题。

离线机器的部署方法也不复杂。在一台联网 Windows 机器上跑一次解析，让模型全部下载到缓存目录，然后把整个缓存目录拷贝到离线机器相同位置。只要版本一致，解析时会自动找到模型，真正做到完全离线运行。

6.4 Windows 特有的几个坑

Windows 和 Linux 的差异在 MinerU 使用中有几个体感明显的地方。一是终端编码，PowerShell 和 CMD 默认编码不同，Python 脚本输出日志最好显式指定 UTF-8，否则中文乱码影响排查问题。二是文件占用，PDF 被 Excel 或其他程序打开时，MinerU 解析可能报权限错误，批量处理前先确认文件没有被占用。三是路径分隔符，代码里拼接路径时建议用pathlib，不要手写反斜杠，否则换个目录结构就出问题。

我还建议把 MinerU 封装成定时任务。Windows 任务计划程序创建一个每日任务，运行预处理脚本。配合邮件或日志通知，每天自动处理新增 PDF，RAG 索引保持最新。这个方案我已经跑了一段时间，稳定省心。整条链路里最值得投入精力的，还是文档解析这一步的调优，别本末倒置去折腾那些花里胡哨的检索技巧。