1. 为什么要在 Windows 上折腾 MinerU 4.0 本地部署

先说结论：如果你手头有一堆 PDF 需要喂给 RAG 系统，又不想把文件传到别人的服务器上，MinerU 4.0 在 Windows 本地跑起来是目前性价比很高的方案。我自己从 MinerU 2.x 一路用到 4.0，中间踩过的坑足够写一本小册子，这篇就把 Windows 环境下从零部署到跑通 RAG 文档预处理的完整链路讲清楚。

MinerU 是上海人工智能实验室开源的一个 PDF 解析工具，核心能力是把 PDF 里的文字、表格、公式、图片按结构化方式提取出来，输出 Markdown 或 JSON。这件事听起来简单，但真正做过 RAG 的人都知道，PDF 解析是整个 RAG 链路里最脏最累的活。扫描件、双栏排版、跨页表格、数学公式、页眉页脚干扰，随便一个都能让解析结果变成一堆乱码。MinerU 4.0 相比早期版本，在版面分析模型和公式识别上做了明显升级，尤其是对中文文档的支持比很多国外工具好得多。

那为什么强调"Windows 本地部署"？三个现实原因。第一，数据合规。很多企业的合同、财报、技术文档不允许上传到外部服务，本地跑是硬需求。第二，成本。调用云端 PDF 解析 API 按页收费，文档量一大账单很吓人，本地部署一次配置长期使用。第三，可控性。解析参数、输出格式、后处理逻辑都能自己调，遇到特殊版式可以针对性优化。

适合读这篇的人：正在搭建 RAG 知识库的开发者、需要批量处理 PDF 的技术人员、想在自己 Windows 机器上跑通离线文档解析的爱好者。不需要你有深度学习背景，但基本的命令行操作和 Python 环境管理要会。

我先把整体链路说清楚，避免你后面迷路：安装环境 → 部署 MinerU → 解析单个 PDF 验证 → 批量解析 → 输出结构化数据 → 接入 RAG 向量库。这篇重点在前五步，最后一步会讲清楚对接思路和注意事项。

提示：MinerU 4.0 对显存有要求，纯 CPU 也能跑但速度慢很多。如果你的机器有 NVIDIA 显卡（6GB 显存以上），体验会好很多。没有显卡也能用，后面会讲 CPU 模式的配置方法。

2. Windows 环境准备：Python、CUDA 与依赖的取舍

2.1 Python 版本选择与虚拟环境隔离

MinerU 4.0 官方推荐 Python 3.10 到 3.12。我实测下来 3.10 最稳，3.12 也能跑但个别依赖包编译时会报错。Windows 上装 Python 建议直接用官方安装包，安装时勾选"Add Python to PATH"，这一步忘了后面命令行调用会各种找不到。

虚拟环境必须建，别偷懒直接装在全局环境里。MinerU 依赖的 PyTorch、transformers 版本和很多其他项目冲突，全局装迟早出事。用 conda 或 venv 都行，我个人习惯 conda，因为管理 CUDA 版本方便：

conda create -n mineru python=3.10 conda activate mineru

如果你用 venv：

python -m venv mineru_env mineru_env\Scripts\activate

建好环境后先升级 pip，这一步能避免很多"找不到满足要求的版本"的报错：

python -m pip install --upgrade pip

2.2 CUDA 与 PyTorch 的版本匹配

这是 Windows 部署最容易翻车的地方。MinerU 底层用 PyTorch，PyTorch 要匹配你的 CUDA 驱动版本。先查驱动支持的 CUDA 版本：

nvidia-smi

右上角会显示"CUDA Version: 12.x"之类的信息，这是驱动支持的最高 CUDA 版本。然后去 PyTorch 官网找对应的安装命令。比如 CUDA 12.1：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

这里有个坑要提醒：不要盲目装最新版 PyTorch。MinerU 4.0 对 PyTorch 版本有要求，装太新的版本可能出现算子不兼容。我建议先看 MinerU 官方 requirements 里指定的版本范围，再决定装哪个。如果实在搞不定 CUDA，直接装 CPU 版 PyTorch 也能跑，就是慢：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

判断装没装对，跑这段代码验证：

import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else "CPU mode")

输出True和你的显卡型号就说明 GPU 可用。输出False就是 CPU 模式，后面解析速度会差好几倍。

2.3 那些容易被忽略的系统级依赖

Windows 上跑 MinerU 有几个系统级依赖经常被漏掉，导致运行时报奇怪的错。

第一个是Visual C++ Redistributable。很多 Python 包的底层 C 扩展需要它，缺了会报 "DLL load failed"。去微软官网下载最新的 x64 版本装上，重启命令行。

第二个是模型下载的网络问题。MinerU 首次运行会自动下载版面分析、公式识别等模型，这些模型托管在 HuggingFace 上。如果你的网络访问 HuggingFace 不稳定，会卡在下载环节。解决办法是配置镜像源，在命令行设置环境变量：

set HF_ENDPOINT=https://hf-mirror.com

这个设置只对当前命令行窗口有效，要永久生效得在系统环境变量里加。我建议直接加到系统环境变量，省得每次都要设。

第三个是磁盘空间。MinerU 的模型文件加起来好几个 GB，加上解析过程中的临时文件，建议预留至少 20GB 空间。装在 C 盘的话注意别把系统盘撑爆。

3. MinerU 4.0 安装：pip 安装与源码安装的选择

3.1 pip 直接安装的完整流程

最省事的方式是 pip 安装。MinerU 4.0 已经发布到 PyPI，直接：

pip install mineru

但这里有个现实问题：pip 安装会拉取一堆依赖，包括 opencv、paddleocr 相关的包，在国内网络环境下经常超时。我的做法是先用国内镜像源装基础依赖，再装 MinerU：

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

如果中途某个包编译失败（Windows 上常见于需要 C++ 编译器的包），去下载对应的预编译 wheel 文件手动装。比如python-Levenshtein、pycryptodome这类包，在 Windows 上编译经常出问题。

装完之后验证：

mineru --version

能输出版本号就说明装上了。如果报"不是内部或外部命令"，说明 Scripts 目录没加到 PATH，或者虚拟环境没激活。

3.2 源码安装：什么时候需要，怎么做

pip 安装适合大多数场景，但有两种情况建议源码安装。一是你想改解析逻辑，比如自定义输出格式、调整版面分析阈值；二是 pip 版本和你的环境有依赖冲突，需要手动控制某些包的版本。

源码安装流程：

git clone https://github.com/opendatalab/MinerU.git cd MinerU pip install -e .

-e是可编辑安装，改代码后不用重装。源码安装的坑在于依赖版本可能和你的环境冲突，建议在干净的虚拟环境里做。如果装完发现某个包版本不对，可以单独降级：

pip install "numpy<2.0"

numpy 2.0 和很多老包不兼容，这是 Windows 上特别常见的坑。MinerU 依赖链里如果有包还没适配 numpy 2.0，就会报各种奇怪的错，降级到 1.26 通常能解决。

3.3 模型文件的下载与本地缓存管理

MinerU 首次运行会下载模型，默认缓存在用户目录下的.cache文件夹。Windows 路径大概是C:\Users\你的用户名\.cache\huggingface。这些模型文件建议保留，删了下次还要重新下。

如果你想指定模型缓存位置（比如 C 盘空间不够），设置环境变量：

set HF_HOME=D:\models\huggingface

模型下载完成后，后续解析就不需要联网了，这也是"离线解析"的关键——模型本地化之后，整个解析过程完全离线，PDF 不出本机。

注意：首次运行一定要联网把模型下全。如果下载中断，重新运行会自动续传。但有时候缓存文件损坏会导致反复报错，这时候删掉对应的缓存目录重新下。

4. 跑通第一个 PDF：从命令行到 Python API

4.1 命令行方式快速验证

装好之后先用命令行跑一个 PDF，确认整条链路通了。准备一个测试 PDF，然后：

mineru -p test.pdf -o output_dir

参数说明：-p指定输入 PDF 路径，-o指定输出目录。跑完之后 output_dir 里会有 Markdown 文件和图片文件夹。

第一次跑会触发模型加载，速度慢是正常的。GPU 模式下，一页普通文档大概 1 到 3 秒；CPU 模式下可能要 10 秒以上。如果卡在某个步骤不动，大概率是模型下载没完成或者显存不够。

命令行还支持一些实用参数：

mineru -p test.pdf -o output_dir -m auto -l ch

-m是解析模式，auto会自动判断文档类型；-l指定语言，中文文档用ch，英文用en。语言参数影响 OCR 和版面分析的准确度，别设错。

4.2 Python API 调用与参数详解

实际项目里更多是用 Python 调用，方便集成到 RAG 流程。基本用法：

from mineru import MinerU parser = MinerU() result = parser.parse("test.pdf") print(result.markdown)

但实际用的时候要配置更多参数。比如指定输出目录、控制是否保留图片、设置解析精度：

from mineru import MinerU parser = MinerU( output_dir="./output", device="cuda", # 或 "cpu" lang="ch", formula_enable=True, # 是否识别公式 table_enable=True, # 是否识别表格 ) result = parser.parse("test.pdf") # 保存 Markdown with open("./output/test.md", "w", encoding="utf-8") as f: f.write(result.markdown)

device参数很关键，设成cuda走 GPU，设成cpu走 CPU。如果你有显卡但设成了 cpu，速度会白白慢好几倍。反过来，显存不够时设成 cuda 会报 OOM 错误，这时候要么换小模型，要么降 batch size。

4.3 解析结果的结构与字段含义

MinerU 的输出不只是 Markdown，还有结构化的 JSON。理解这个结构对后续 RAG 处理很重要。典型输出包含：

content_list是我最常用的字段，它把文档拆成一个个块，每块带类型标记（文本、标题、表格、图片）。做 RAG 切分时，按这个结构切比按固定字数切效果好得多，因为不会把一个表格从中间切断。

for block in result.content_list: print(block["type"], block["text"][:50])

这样能看到每个块的类型和内容开头，方便你决定怎么切分。

5. 批量解析与 RAG 文档预处理的工程化

5.1 批量处理的目录组织与并发控制

单个 PDF 跑通之后，下一步是批量处理。最朴素的做法是遍历目录：

import os from pathlib import Path from mineru import MinerU parser = MinerU(output_dir="./output", device="cuda", lang="ch") pdf_dir = Path("./pdfs") for pdf_file in pdf_dir.glob("*.pdf"): try: result = parser.parse(str(pdf_file)) out_path = Path("./output") / f"{pdf_file.stem}.md" out_path.write_text(result.markdown, encoding="utf-8") print(f"完成: {pdf_file.name}") except Exception as e: print(f"失败: {pdf_file.name}, 原因: {e}")

但这样是串行的，几百个 PDF 要跑很久。可以加并发，但要注意：GPU 显存有限，并发数不能太高。我的经验是 6GB 显存最多同时跑 2 个，12GB 可以跑 4 个。用concurrent.futures控制：

from concurrent.futures import ThreadPoolExecutor def process_pdf(pdf_file): parser = MinerU(output_dir="./output", device="cuda", lang="ch") result = parser.parse(str(pdf_file)) return pdf_file.stem, result.markdown with ThreadPoolExecutor(max_workers=2) as executor: futures = [executor.submit(process_pdf, f) for f in pdf_dir.glob("*.pdf")] for future in futures: name, md = future.result() Path(f"./output/{name}.md").write_text(md, encoding="utf-8")

注意每个线程里重新创建 parser 实例，共享实例可能有线程安全问题。

5.2 解析失败的常见原因与重试策略

批量处理一定会遇到失败。我统计过自己处理的几千个 PDF，失败率大概 3% 到 5%。常见原因和应对：

重试策略建议做指数退避，第一次失败等 5 秒重试，第二次等 30 秒，第三次就跳过并记录到失败列表。别无限重试，有些 PDF 就是解析不了，记录下来人工处理。

import time def parse_with_retry(parser, pdf_path, max_retries=3): for attempt in range(max_retries): try: return parser.parse(str(pdf_path)) except Exception as e: if attempt == max_retries - 1: raise time.sleep(5 * (2 ** attempt))

5.3 从解析结果到向量库的切分策略

解析出来的 Markdown 不能直接整篇塞进向量库，必须切分。切分策略直接决定 RAG 的检索质量。我的经验是按语义块切，不要按固定字数切。

利用 MinerU 的content_list，可以按块类型分别处理：

def split_for_rag(content_list, max_chars=800): chunks = [] current = "" for block in content_list: text = block.get("text", "") if block["type"] == "table": # 表格单独成块，不切分 if current: chunks.append(current) current = "" chunks.append(text) elif len(current) + len(text) > max_chars: chunks.append(current) current = text else: current += "\n" + text if current: chunks.append(current) return chunks

这样切出来的块，表格是完整的，段落是连贯的。每个块还可以加上元数据（来源文件、页码、块类型），检索时能过滤和溯源。

提示：切分粒度没有标准答案。技术文档建议 500 到 800 字，法律合同建议按条款切，学术论文建议按章节切。多试几组参数，用实际查询验证检索效果。

6. 离线解析的边界与 RAG 对接的注意事项

6.1 哪些 PDF 解析效果好，哪些会翻车

MinerU 不是万能的，用之前要建立合理预期。解析效果好的：电子版 PDF（文字可选）、标准排版的技术文档、单栏或双栏论文、带清晰表格的报表。解析效果差的：低质量扫描件、手写体、复杂艺术排版、跨页合并的大表格、竖排古籍。

扫描件是最大的坑。MinerU 内置 OCR，但 OCR 质量取决于扫描清晰度。我处理过一批 300dpi 的扫描合同，识别率能到 95% 以上；但 150dpi 以下的模糊扫描件，识别率掉到 70% 都不到。这种情况建议先做图像预处理（去噪、二值化、纠偏），再喂给 MinerU。

公式识别也是双刃剑。开启公式识别会显著增加解析时间，而且对印刷体公式效果好，对手写公式基本没戏。如果你的文档里公式不多，可以关掉这个功能提速。

6.2 图片和表格在 RAG 里怎么处理

这是很多人问的问题：RAG 知识库能存储图片吗？答案是能，但要分情况。

纯文本 RAG 只存文字，图片信息会丢失。如果你的文档里图片承载关键信息（比如流程图、架构图），需要做多模态 RAG。MinerU 会把图片单独提取出来存到 images 目录，你可以：

1. 用多模态模型给图片生成文字描述，把描述存进向量库
2. 用 CLIP 之类的模型做图文联合嵌入
3. 图片单独建索引，检索时返回图片路径

表格的处理更微妙。MinerU 输出的表格是 Markdown 或 HTML 格式，直接向量化效果一般，因为表格的语义在结构里。我的做法是把表格转成自然语言描述再向量化：

def table_to_text(table_md): # 简单示例：把 Markdown 表格转成描述 lines = table_md.strip().split("\n") header = lines[0] return f"表格内容：{header}，共 {len(lines)-2} 行数据"

复杂表格建议保留原始结构，检索到之后由大模型来理解。

6.3 本地部署 MinerU 与本地大模型的配合

MinerU 负责文档解析，大模型负责问答，两者配合才构成完整的本地 RAG。典型架构：

PDF → MinerU 解析 → 结构化文本 → 切分 → 向量化 → 向量库 ↓ 用户提问 → 向量化 → 检索 → 上下文 + 问题 → 本地大模型 → 回答

向量化模型和生成模型都可以本地跑。向量化推荐 bge-m3 或 m3e，中文效果好，模型小，CPU 也能跑。生成模型看你的硬件，7B 到 14B 的模型在消费级显卡上能跑，再大就需要专业卡了。

这里有个性能权衡：MinerU 解析和大模型推理都吃显存，如果同时跑，显存会不够。建议错峰，先批量解析完文档，再启动大模型做问答。或者解析用 CPU，推理用 GPU。

6.4 我踩过的几个典型坑与规避方法

最后分享几个实际踩过的坑，都是文档里不会写的。

坑一：路径里有中文或空格。MinerU 某些版本对中文路径支持不好，会报编码错误。解决办法是把 PDF 和输出目录都放在纯英文路径下，比如D:\rag\pdfs。

坑二：显存泄漏。长时间批量处理，显存会慢慢涨上去最后 OOM。解决办法是每处理 N 个文件重启一次 parser 实例，或者定期调用torch.cuda.empty_cache()。

坑三：输出文件覆盖。如果两个 PDF 同名，输出会互相覆盖。批量处理时用文件哈希或完整路径做输出文件名，别只用 stem。

坑四：模型版本不一致。团队协作时，不同人装的 MinerU 版本不同，解析结果会有差异。建议在项目里锁定版本，用 requirements.txt 固定。

坑五：忽略日志。MinerU 运行时的日志里有大量有用信息，比如哪一页解析失败、用了哪个模型。批量处理时把日志重定向到文件，出问题好排查。

mineru -p test.pdf -o output_dir > parse.log 2>&1

这套流程我在自己的 RAG 项目里跑了几个月，处理了上万份 PDF，整体稳定。核心体会是：解析质量决定 RAG 上限，与其在检索环节调参，不如在文档预处理阶段多花功夫。MinerU 4.0 在 Windows 本地部署虽然配置麻烦点，但跑通之后就是一套完全可控、数据不出本机的文档处理流水线，对于有数据合规要求的场景，这个投入是值得的。