企业官网建设流程全解析

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

先说结论：如果你手头有一堆 PDF 要喂给 RAG 系统，又不想把文件传到别人的服务器上，MinerU 4.0 在 Windows 本地跑是目前比较省心的方案之一。我自己从 3.x 版本一路用到 4.0，踩过的坑不算少，这篇文章就把整个部署流程、参数调优、以及和 RAG 对接时容易翻车的地方一次性讲清楚。

MinerU 是上海人工智能实验室开源的一个文档解析工具，核心能力是把 PDF 里的文字、表格、公式、图片按结构化方式抽出来，输出 Markdown 或 JSON。它跟普通的 PDF 转文本工具最大的区别在于：它用视觉模型理解版面，能识别双栏排版、跨页表格、数学公式这些传统工具搞不定的东西。对于做 RAG 的人来说，这意味着你的知识库切片质量会高一个档次——毕竟垃圾进垃圾出，PDF 解析这一步做不好，后面向量检索再牛也白搭。

为什么强调 Windows 本地部署？三个原因。第一，数据不出本机，合同、财报、内部文档这类东西传第三方 API 心里总不踏实。第二，离线可用，断网也能跑，适合内网环境。第三，成本可控，不用按页付费，解析几千页文档也就电费的事。当然代价是你要自己搞定环境，这篇文章就是干这个的。

适合谁看：正在搭 RAG 知识库、需要批量处理 PDF 的开发者；想把文档解析流程私有化的团队；以及单纯对文档 AI 感兴趣、想在自己电脑上跑跑看的技术爱好者。下面所有操作我都在这台 Windows 11 + RTX 4060 8GB 的机器上实测过，显存更小的机器我会标注替代方案。

2. 部署前的环境盘点与方案选型

2.1 硬件门槛到底卡在哪

MinerU 4.0 的解析流程分两段：版面分析用视觉模型，OCR 和公式识别用另外的模型。真正吃显存的是视觉模型那一段。官方给的参考是 8GB 显存能跑默认配置，6GB 需要调小 batch size，4GB 以下基本只能走 CPU 模式。

我实测下来，8GB 显存处理单页 A4 文档峰值占用在 5.5GB 左右，留了点余量。如果你要批量并发处理，显存会线性上涨，所以别贪心开太多 worker。CPU 模式也能跑，但速度大概是 GPU 的十分之一，一份 50 页的 PDF 要等好几分钟，只适合应急。

内存方面建议 16GB 起步，32GB 更稳。解析过程中会把 PDF 渲染成图片再送进模型，大文件的内存占用不容小觑。硬盘留 20GB 以上，模型文件加起来差不多 10GB。

2.2 三种部署路线的取舍

在 Windows 上跑 MinerU，主流有三条路：

我推荐第一条路，也就是 pip 直接装。原因很简单：MinerU 更新快，整合包往往落后好几个版本，而且出了问题你根本不知道里面发生了什么。Docker 在 Windows 上要装 WSL2 再配 GPU 直通，折腾程度不比 pip 低，还多一层性能损耗。

注意：网上有些所谓"一键部署包"来源不明，可能夹带私货，涉及本地部署的工具尽量从官方渠道获取，别图省事。

2.3 Python 环境隔离的必要性

MinerU 依赖的包不少，其中 torch、transformers 这些对版本敏感。如果你机器上已经有别的 AI 项目，直接全局安装大概率会把现有环境搞崩。所以第一步永远是建虚拟环境。

我用的是 conda，因为它在 Windows 上管理 CUDA 相关的包比较省心。没有 conda 的话用 venv 也行，但装 torch 的时候要自己指定 CUDA 版本。Python 版本选 3.10 或 3.11，3.12 有些依赖还没跟上，别踩这个坑。

3. 手把手完成 MinerU 4.0 本地安装

3.1 创建并激活虚拟环境

打开 Anaconda Prompt（或者你习惯的终端），执行：

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

建完之后先确认一下 Python 版本：

python --version

应该输出 Python 3.10.x。如果还是系统默认版本，说明 conda 没激活成功，检查一下终端提示符前面有没有(mineru)字样。

3.2 安装 PyTorch 的正确姿势

这一步是整个部署最容易翻车的地方。MinerU 依赖 PyTorch，而 PyTorch 的 CUDA 版本必须和你的显卡驱动匹配。先查驱动支持的 CUDA 版本：

nvidia-smi

右上角会显示CUDA Version: 12.x之类的信息。注意这是驱动支持的最高版本，不是你必须装的版本。装比它低的都兼容。

假设显示 12.4，那你可以装 cu121 或 cu118 的 torch。我建议装 cu121，兼容性和性能都比较好：

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

装完验证一下 GPU 是否可用：

python -c "import torch; print(torch.cuda.is_available())"

输出True才算成功。如果是False，八成是装成了 CPU 版本，卸载重装。

实操心得：这一步千万别用pip install torch不带 index-url，默认会装 CPU 版，然后你跑 MinerU 的时候会发现慢得离谱，还找不到原因。

3.3 安装 MinerU 本体

torch 搞定后，装 MinerU 就简单了：

pip install mineru

如果你需要全部功能（包括公式识别、表格识别），装完整版：

pip install "mineru[all]"

装完之后跑一下版本确认：

mineru --version

能输出版本号就说明装好了。第一次运行任何 MinerU 命令时，它会自动下载模型文件，大概 10GB 左右，放在用户目录的缓存文件夹里。国内下载可能慢，可以配个镜像源加速，具体方法看官方文档的环境变量说明。

3.4 模型下载与缓存路径管理

模型默认下载到C:\Users\你的用户名\.cache\huggingface下面。C 盘空间紧张的话，可以改环境变量把缓存挪到别的盘：

setx HF_HOME "D:\ai_cache\huggingface"

设置完要重开终端才生效。这个操作我强烈建议做，因为模型文件会随着版本更新不断累积，C 盘很容易被撑爆。

4. 解析参数调优与 RAG 预处理实战

4.1 命令行解析的基本用法

MinerU 装好后，最简单的用法是：

mineru -p input.pdf -o output_dir

-p指定输入文件或目录，-o指定输出目录。它会生成 Markdown 文件和一堆图片，图片单独放在images子目录里。

处理整个文件夹：

mineru -p ./pdfs -o ./output

批量处理时它会逐个文件跑，不会并发，所以显存压力可控。

4.2 关键参数逐个拆解

MinerU 的参数不少，但真正影响 RAG 效果的就这么几个：

-m或--method：解析方法，可选auto、txt、ocr。auto会自己判断，有文字层的 PDF 走文本提取，扫描件走 OCR。我一般用auto，省心。

-l或--lang：OCR 语言。中文文档写ch，中英混排也写ch，纯英文写en。写错了识别率会掉。

-d或--device：设备，cuda或cpu。有显卡就写cuda。

--batch-size：批处理大小，显存不够就调小。8GB 显存默认值能跑，6GB 建议设成 1。

--formula和--table：是否启用公式和表格识别。做技术文档 RAG 的话这两个都开，做普通文本知识库可以关掉省时间。

一个我常用的完整命令：

mineru -p ./pdfs -o ./output -m auto -l ch -d cuda --formula --table --batch-size 2

4.3 输出结构怎么对接 RAG

MinerU 的输出目录结构是这样的：

output/ ├── 文档名.md ├── 文档名.json └── images/ ├── xxx.jpg └── ...

Markdown 文件是给你直接用的，JSON 文件保留了更细的结构信息（每个块的类型、坐标、置信度）。做 RAG 的时候，我建议用 JSON 而不是 Markdown，因为你可以根据块类型做差异化处理。

比如表格块，你可以单独抽出来做结构化存储，而不是当成普通文本切片。公式块可以转成 LaTeX 保留。图片块可以走多模态 embedding。这些在 Markdown 里都混在一起了，JSON 里分得清清楚楚。

4.4 图片处理与多模态 RAG 的衔接

热词里有人问"RAG 知识库能存储图片吗"，答案是能，但要看你用什么向量库。纯文本向量库（比如 FAISS 配 text embedding）存不了图片，你得用支持多模态的模型，比如 CLIP 或者专门的图文 embedding。

MinerU 输出的图片是独立文件，Markdown 里用相对路径引用。做 RAG 的时候有两种处理方式：

第一种，图片单独走多模态 embedding，存进支持图片的向量库，检索时文本和图片分别召回再融合。这种方式效果好但工程复杂。

第二种，用视觉模型给每张图片生成一段文字描述，把描述当作文本存进普通向量库。这种方式简单，但会丢失图片的细节信息。

我一般根据场景选：技术文档里的架构图、流程图用第一种，因为图里的信息文字描述不全；装饰性图片直接忽略。

5. 常见故障排查与性能优化

5.1 卡在"一直获取中"怎么办

这是被问得最多的问题。MinerU 第一次运行要下载模型，如果网络不通就会一直卡着。排查步骤：

先看终端有没有下载进度条。如果没有，说明请求根本没发出去，检查网络。如果有进度条但不动，可能是源太慢，换镜像源。

模型下载是分块的，中断了可以重跑，会断点续传。但如果缓存文件损坏了，就得手动删掉重下。缓存目录在HF_HOME指向的位置，找到对应的模型文件夹删掉即可。

5.2 显存不足的降级方案

报CUDA out of memory的时候，按这个顺序降级：

1. 把--batch-size调到 1
2. 关掉--formula或--table（公式识别最吃显存）
3. 换-d cpu走 CPU 模式

CPU 模式虽然慢，但胜在稳定，处理重要文档时我有时会故意用 CPU，避免中途崩掉重来。

5.3 解析质量差的几个原因

有时候解析出来乱七八糟，先别怪工具，检查这几点：

PDF 本身是不是扫描件且分辨率很低？低于 150 DPI 的扫描件 OCR 效果会明显下降。

语言设置对不对？中文文档设成en会把汉字识别成乱码。

版面是不是特别复杂？多栏、图文混排、手写批注这些对任何工具都是挑战，MinerU 已经算处理得好的了，但极端情况仍需人工校对。

5.4 批量处理的稳定性技巧

处理几百个 PDF 的时候，最怕跑到一半崩了。我的做法是写个简单的批处理脚本，记录已完成的文件，崩了重跑时跳过已处理的：

import os import subprocess pdf_dir = "./pdfs" out_dir = "./output" done_file = "./done.txt" done = set() if os.path.exists(done_file): with open(done_file, "r", encoding="utf-8") as f: done = set(line.strip() for line in f) for name in os.listdir(pdf_dir): if not name.lower().endswith(".pdf") or name in done: continue pdf_path = os.path.join(pdf_dir, name) subprocess.run(["mineru", "-p", pdf_path, "-o", out_dir, "-m", "auto", "-l", "ch", "-d", "cuda"]) with open(done_file, "a", encoding="utf-8") as f: f.write(name + "\n")

这个脚本很土但很实用，跑一晚上也不怕。

5.5 常见问题速查表

6. 和 RAG 系统对接的进阶思路

6.1 切片策略要跟着解析结果走

很多人 PDF 解析完就直接按固定字数切片，这是浪费了 MinerU 的结构化输出。既然 JSON 里已经标好了每个块的类型和层级，切片时就应该利用这些信息。

我的做法是：标题块作为切片的边界，正文块按语义合并，表格块单独成片，公式块附在上下文里。这样切出来的片语义完整，检索命中率高。

6.2 元数据别浪费

MinerU 的 JSON 里有页码、块坐标、置信度这些信息。存进向量库的时候一起存进去，检索时可以按页码过滤，或者把低置信度的块标记出来人工复核。这些元数据在排查检索问题时特别有用。

6.3 本地部署大模型的组合拳

MinerU 负责解析，向量库负责存储，本地大模型负责生成，这是一套完整的离线 RAG 链路。Windows 上跑本地大模型可以用 Ollama，装完拉个模型就能用，和 MinerU 配合起来就是全本地的文档问答系统。

显存分配要注意：MinerU 解析时占显存，大模型推理时也占显存，两者别同时跑。我的做法是解析阶段和问答阶段分开，解析完把模型卸载了再启动大模型。

6.4 增量更新的处理

知识库不是一次建完就完事，新文档要能增量加进去。MinerU 本身不管理这个，你得自己在应用层做。我的方案是用文件哈希做去重，新文件解析后只把新增的块加进向量库，删掉的文档对应的块也要清理。这块逻辑不难但容易漏，建议一开始就设计好。

7. 一些踩坑之后的个人体会

部署 MinerU 这件事，说难不难，说简单也不简单。真正花时间的不是安装本身，而是环境对齐和参数调优。我见过太多人卡在 torch 版本上，或者被模型下载卡住就放弃了。

几个我觉得最值得记住的点：虚拟环境一定要建，torch 一定要装 CUDA 版，模型缓存一定要挪出 C 盘，批量处理一定要能断点续跑。这四条做到了，基本就不会有太大问题。

解析质量这块，别指望工具能 100% 完美，尤其是扫描件和复杂版面。我的习惯是先拿几份典型文档试跑，看看效果再决定要不要调整参数，而不是一上来就批量处理几千页。试跑的成本很低，返工的成本很高。

最后说个容易被忽略的细节：MinerU 输出的 Markdown 里，图片是相对路径引用的。如果你要把 Markdown 导入别的系统，记得把 images 目录一起带上，或者把图片转成 base64 内嵌。我一开始就因为这个丢过一批图，后来学乖了，输出后先检查一遍图片引用是否完整。

这套流程我现在跑得挺顺，一份 100 页的技术文档大概两三分钟解析完，输出质量足够支撑一个像样的 RAG 知识库。如果你也在 Windows 上折腾本地文档解析，希望这些经验能帮你少走点弯路。