企业官网建设流程全解析

1. 为什么我把RAG的预处理环节单独拿出来说

1.1 RAG系统里最容易拖后腿的其实是“读文档”这一步

接触RAG项目久了你就会发现，真正决定检索质量上限的，往往不是选了多强的 embeddings 模型，也不是向量库调的有多溜，而是最上游那个看起来毫无技术含量的环节——把 PDF 里的内容原样、有序地读出来。

很多团队搭知识库，用的是 PyMuPDF 或者 pdfplumber 这类轻量工具直接抽文本。抽完发现文本乱成一团：双栏论文的读取顺序是乱的，第一栏读到一半突然跳到第二栏，再跳回来；表格里的数字和表头脱节；图表说明和正文混在一起。把这种文本丢进分块器，切出来的块要么语义不完整，要么夹杂着没用的页眉页脚。向量化之后检索召回的片段看着相关，真正喂给大模型时，生成的答案缺乏连贯性，引用数字也是错的。这就是我常说的“垃圾进，垃圾出”的工程版。

我见过不少团队花大力气调 prompt、调检索策略，最后发现瓶颈根本不在那，而在文档解析环节就已经把信息搞乱了。RAG 链路里，文档预处理是从原始文件到可检索知识块之间的“翻译”环节，翻译错了后面全错。

1.2 本地化部署的决策点：离线、隐私、可控

以前做 PDF 解析，很多人第一反应是调云端 API。但我在实际项目里越来越倾向于本地部署，原因很直接：

• 离线可用：有些文档处理任务发生在内网环境，服务器不能通外网，或者网络不稳定。本地部署意味着把解析能力做成了一个固定输出的流水线，随时随地可以跑。
• 隐私安全：企业内部的合同、技术手册、财务报表，真不适合往第三方接口传。尤其这两年数据安全的红线越来越明确，本地化是合规上最稳妥的选择。
• 成本可控：按页计费的 API 在批量处理几十万页文档时，费用相当可观。本地部署主要是一次性的硬件投入，用已有的工作电脑就能跑起来，后期没有增量费用。

所以当 MinerU 4.0 发布后，我第一时间就在 Windows 工作站上部署了一套，专门用来做 RAG 文档预处理。这篇文章就是把整个部署过程、踩坑记录、以及如何把解析结果接到本地 RAG 链路里的经验完整梳理一遍。适合谁看？打算在 Windows 上做离线 PDF 解析、搭建本地知识库的工程师，以及那些已经受够了“PDF 文本抽出来是乱码”的 RAG 实践者。

2. MinerU 4.0 在文档解析上到底强在哪

2.1 核心能力拆解：版面还原、表格重建、公式转换

MinerU 本质上是一个“PDF 到 Markdown/JSON”的结构化解析工具。它的处理管线大致包含几个模块：版面分析、文本行检测与识别、OCR（针对扫描件）、表格结构还原、公式识别与转换。最终输出的 Markdown 不只是纯文本，还保留了标题层级、表格结构、图片引用位置，甚至公式的 LaTeX 表示。

4.0 版本让我印象最深的变化有几个。一是整个推理流程做了重构，资源占用比之前的版本更理性，不会像老版本那样把所有模型都加载进来，而是按需加载，这对 Windows 上显存不大的机器很友好。二是表格解析的效果有明显提升，尤其是带合并单元格、跨行跨列的复杂表格，之前经常还原错位，4.0 的还原准确率高了不少。三是安装和使用方式简化了，一条pip install "mineru[cli]"就能把命令行工具装好，不再需要手动凑一堆依赖。

2.2 它能处理什么，不能处理什么

在决定用它之前，先明确边界。MinerU 能处理的 PDF 大致分三类：

• 数字版 PDF：文档本身带文本层，排版清晰，这类解析速度最快，用txt模式就行。
• 扫描版 PDF：整页都是图片，必须走 OCR。MinerU 内置了 OCR 能力，支持中英文识别，但速度会慢不少。
• 混合型 PDF：一部分是文字层，一部分是扫描图片。用auto模式让它自动判断，这也是我日常用得最多的模式。

边界也很明显。手写批注、极度复杂的艺术排版、老式古籍扫描件，这类文档解析效果会打折扣。遇到这种情况，我一般会提前做预处理，把图像增强后再喂进去，或者干脆单独走人工方案，不要让 MinerU 硬扛。

3. Windows 本地部署全流程

3.1 环境准备：Python、Conda、CUDA 的取舍

先说结论：Windows 上部署 MinerU，最稳的环境组合是Python 3.10 + MiniConda。不要直接拿系统里乱七八糟的全局 Python 环境去装，MinerU 的依赖链里包含 PyTorch、多个视觉模型推理库，版本冲突的概率极高。

安装 MiniConda 之后，创建一个独立环境：

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

关于 GPU 的取舍。MinerU 支持 CPU 推理，但扫描版 PDF 走 OCR 时 CPU 会非常吃力。我的建议是：手头有 NVIDIA 显卡就上 CUDA 版本，显存 6GB 以下建议用轻量模型模式；只有核显或者完全没有独显，也不是不能用，只是批处理速度需要接受。

确认显卡信息：

nvidia-smi

能看到 CUDA 版本信息就可以继续。如果提示找不到命令，多半是显卡驱动太老，先更新驱动。PyTorch 的 CUDA 版本会和驱动对应，但 MinerU 安装时通常会带上合适的 PyTorch 版本，一般不用手动折腾。

3.2 安装 MinerU 与模型下载的准备

环境激活后，直接装：

pip install -U "mineru[cli]"

如果网络环境一般，可以换国内 PyPI 镜像：

pip install -U "mineru[cli]" -i https://pypi.tuna.tsinghua.edu.cn/simple

安装本身不难，真正麻烦的是模型下载。MinerU 首次运行时会从 ModelScope 下载模型权重，模型包体积不小，网络不稳就很容易卡住。我注意到很多人碰到的“mineru 一直获取中”就是这一阶段的问题。

为了避免卡死，我建议在第一次正式运行前，先手动把模型下载好。MinerU 会从 ModelScope 拉取模型，你可以直接用 ModelScope 的 Python SDK 或者 Git 方式把模型仓库下载到本地缓存目录。我当时的做法是：

pip install modelscope

然后用一段 Python 脚本拉取模型：

from modelscope import snapshot_download snapshot_download('opendatalab/PDF-Extract-Kit-1.0')

模型会下载到用户目录下的.cache/modelscope/hub目录。下载完成后，MinerU 首次运行时如果检测到本地已有模型，就会跳过下载，直接加载。如果目标机器完全离线，可以把其他机器上下载好的缓存目录整个拷贝过去，放到相同路径下，就实现了彻底的离线部署。

3.3 首次运行与 CLI 参数说明

装完先跑单个文件试试：

mineru -p ./sample.pdf -o ./output

首次运行会加载模型，需要一点时间。成功之后，output目录下会出现对应的 Markdown 文件，以及一个images子目录存放抽取出来的图片。

MinerU 的 CLI 参数里，我使用频率最高的是这么几个：

不要一上来就对几百个文件跑批。先用一个代表性样本验证输出质量，再决定要不要扩大规模，这是我在所有文档处理项目里保持的习惯。

4. 实战：批量解析 PDF 并产出 Markdown 知识库原料

4.1 单文件解析：检查输出目录结构

先拿一份混合型 PDF 做示范，里面有文字层、也有扫描图片，用auto模式：

mineru -p ./docs/产品手册.pdf -o ./parsed -t auto -d cuda

跑完后parsed目录下会生成：

产品手册/ 产品手册.md images/ img_0.png img_1.png tables/ table_0.md

这里有个细节：MinerU 会把表格单独抽取成table_x.md，同时在主 Markdown 中保留表格的引用位置。这种设计对 RAG 预处理非常有用，因为表格在源文档里的上下文位置很重要，单纯把所有表格堆在一起会丢失语义关联。

打开产品手册.md检查几个关键点：标题层级是否合理、文字阅读顺序是否符合预期、表格里的数字有没有错位。这一步花五分钟，能避免后面批量跑完再返工。

4.2 多文件批量解析与并发控制

确认单文件没问题后，开始批量：

mineru -p ./docs/ -o ./parsed_all -t auto -d cuda

传入目录会递归处理所有 PDF。这里提醒一下并发控制。MinerU 支持多进程，但 Windows 下开太多进程很容易吃满内存。我当时的电脑是 32GB 内存加 12GB 显存，实测开 2 个并发进程最稳，速度没有比开 4 个慢多少，但内存占用少了一大截。稳妥的做法是手动限制线程数：

mineru -p ./docs/ -o ./parsed_all -t auto -d cuda --workers 2

如果显存不够，可以把设备切到 CPU，再减少并发：

mineru -p ./docs/ -o ./parsed_all -t auto -d cpu --workers 1

纯 CPU 跑一份带大量扫描页的 PDF 会慢到怀疑人生，但这种场景下“能跑”比“跑得快”重要，毕竟只是预处理阶段，可以晚上挂机批量跑。

4.3 输出质量抽检：不要迷信工具

批量跑完别急着删原始 PDF，务必抽检。我的抽检清单是：

• 随机打开 5-10 个 Markdown 文件，看正文是否有大段乱序文本。
• 重点检查带表格的页面，确认表格数据的行列对应关系。
• 如果源文档是双栏论文，确认正文是按“先左栏后右栏”的逻辑排下来的。
• 扫描版 PDF 抽查 OCR 识别的文字，看中文常用字有没有明显错识别。

有一次我批量跑了 300 份技术文档，抽检时发现某几份早期扫描版的文件，OCR 把“0”识别成了“O”，导致产品型号全错了。这种东西靠算法本身很难百分之百避免，所以预处理流程里一定要留人工抽检环节。特别在意质量的文档，我会把 MinerU 解析完的 Markdown 再和一个纯文本抽取的结果做交叉比对，用不同工具互相印证。

5. 把 MinerU 解析结果接进 RAG 链路

5.1 为什么先转 Markdown 再切分，而不是直接切纯文本

很多 RAG 教程从 PDF 里抽出文本后，直接按固定字符数切块。这种做法的缺陷在复杂文档上暴露得很彻底：一个标题下本来有五个段落，被固定窗口一切，某个块里只剩半个段落；表格被拆成两半，数字和表头不在同一个 chunk 里；代码块被截断。检索时找不到完整信息，大模型只能靠猜。

MinerU 输出的 Markdown 保留了文档的语义结构，切分时可以按这些结构走。Markdown 里的标题层级天然就是文档的章节骨架；表格是一个完整的块；代码块有明确的边界。基于这些结构切分，得到的 chunk 在语义上完整得多。

我用的是 LangChain 的MarkdownHeaderTextSplitter，按#、##这样的标题层级把文档切成章节，再对过长的章节按长度二次切分。效果比直接RecursiveCharacterTextSplitter好太多，尤其是在技术手册、论文这类结构明显的文档上。

5.2 分块策略：大小、重叠与元数据

分块参数没有通解，但可以给一个我在中文技术文档上反复调出来的起点：

• 目标块大小：500 到 800 个 token。块太小，语义不完整；块太大，检索精度下降。
• 重叠：80 到 120 个 token。保证上下文连贯。
• 元数据：每个 chunk 记录源文件名、页码信息、章节标题。这样后续问答时，大模型可以回答“这个结论来自哪份文档的哪一节”。

MinerU 的 Markdown 输出里如果保留了原始页码的话，尽量把页码信息带进元数据。实际测试中，带页码的检索结果在人工复核时明显更容易定位问题。

5.3 本地向量化与 Ollama 接入示例

我本地的 RAG 链路是：MinerU 解析出 Markdown → 切块 → 本地 embedding 模型向量化 → 存入 Chroma → 检索时走 Ollama 上的本地大模型。

embedding 模型选的是bge-m3，中文效果不错，Ollama 可以直接拉取：

ollama pull bge-m3 ollama pull qwen2.5:7b-instruct

向量化与入库的简单示例：

from langchain_community.document_loaders import DirectoryLoader from langchain_text_splitters import MarkdownHeaderTextSplitter from langchain_community.embeddings import OllamaEmbeddings from langchain_community.vectorstores import Chroma loader = DirectoryLoader("./parsed_all", glob="**/*.md") docs = loader.load() splitter = MarkdownHeaderTextSplitter( headers_to_split_on=[("#", "章节"), ("##", "二级标题")], chunk_size=600, chunk_overlap=100 ) chunks = [] for doc in docs: chunks.extend(splitter.split_text(doc.page_content)) embeddings = OllamaEmbeddings(model="bge-m3", base_url="http://localhost:11434") vectorstore = Chroma.from_documents(chunks, embeddings, persist_directory="./chroma_db")

跑完之后，知识库的“原料”就绪了。我实际体验下来，用 MinerU 预处理过的文档做检索，和之前用 PyMuPDF 直接抽文本的结果对比，最明显的变化是涉及表格数据的问答准确率高了很多。以前检索结果经常给出断裂的表格片段，大模型只能猜数字；现在表格作为一个完整 chunk 被召回，回答里引用的数据基本都能对上原文。

6. Windows 部署里我踩过的几个坑

6.1 模型下载卡住：“mineru 一直获取中”的解法

第一次部署时我也碰到了这个问题。命令敲下去，日志停在“正在获取模型”就不动了，等半小时还是这样。原因通常是网络连接 ModelScope 不稳定，或者缓存目录里有损坏的半成品文件。

排查思路是：先看缓存目录是否在增长文件，如果文件大小不变，说明连接挂了。把缓存目录里不完整的模型目录删掉，重新用modelscope的 SDK 手动下载，下载完成后放在正确路径，再重新跑 MinerU。手动下载的好处是能看到下载进度，确认到底有没有在动。

完全离线环境的话，参照前面说的，把一台已经下载好模型的机器上的.cache/modelscope/hub整个拷贝到离线机相同路径。注意一定要保持目录结构一致，MinerU 会按固定路径查找模型。

6.2 依赖冲突与 DLL 加载失败

Windows 上装 PyTorch 系工具，最容易碰到的就是某个动态库加载失败。我在部署时遇到过libiomp5md.dll加载错误，典型的 OpenMP 运行时冲突，通常是因为环境里还有其他包带了不同版本的 OpenMP。

处理办法比较直接：先把环境里相关的包统一重装一遍：

pip uninstall -y mineru pip install --force-reinstall "mineru[cli]"

如果还不行，新建一个干净的 conda 环境，只装必备依赖，不要去复用平时开发用的环境。这点真的省了很多事。

6.3 显存不足时的降级策略

我一开始直接拿 6GB 显存的显卡跑cuda模式，处理扫描版 PDF 时中途报显存不足。后来改用轻量模式加 CPU 分流才稳定下来：

mineru -p ./docs/ -o ./parsed -t auto -d cpu -m fast

这也是 4.0 的另一个实用点：支持按需加载模型，配合-m参数选轻量模型，资源紧张时能平滑降级。如果你的机器显存只有 4GB 到 6GB，建议别想太多，直接用 CPU 模式跑，速度慢点但是稳。批量场景下宁可让它慢，也不要中途崩掉。

6.4 Windows 杀毒软件干扰

Windows Defender 的实时防护会在文件密集读写时拖慢速度，更极端的情况是直接把模型文件当可疑文件拦掉。这听起来像段子，但我确实遇到过模型加载后行为异常的情况。后来把模型缓存目录和输出目录都加入了 Defender 的排除列表，问题才消停。如果你在公网环境部署，杀毒软件策略比较激进，建议也做这个操作。

7. 和其他 PDF 解析方案的取舍

7.1 工具对比参考

不少朋友问过我：“MinerU 重不重？是不是有点杀鸡用牛刀？”老实说，要看场景。我列一个常用工具的感觉参考：

如果你的 PDF 都是数字版、排版规整、没有表格交叉，也不需要输出结构化 Markdown，PyMuPDF 完全够用，速度快一个量级。如果你的文档有大量扫描页、复杂表格、双栏排版，MinerU 的解析质量能带来明显的下游收益。

7.2 什么时候我反而不建议用 MinerU

一种场景是：需要极速处理几万份简单 PDF，且目标是抽取少量关键字或摘要信息。这种批量场景下 MinerU 的完整解析链路显得过重，跑完还要清理大量中间输出，反而拖慢整个流水线。

另一种场景是：文档本身质量极差，比如模糊的老式扫描件、手写注释满篇飞。MinerU 不是专业 OCR 增强软件，遇到这种文档，先用图像处理手段做增强，或者直接走人工录入，都比强行依赖自动化解析更靠谱。

选型的关键是搞清楚你的“下一步要什么”。要全文问答和语义检索，结构化解析值得投入；只要从固定格式报告里抽几个字段，轻量方案更合适。

8. 本地离线解析后续还能怎么扩展

MinerU 在 Windows 本地部署这件事，我做了之后最大的感受是：整条 RAG 数据链路终于可以完全离线运转了。从 PDF 解析、文本切分、向量化到问答推理，全部跑在本地机器上，不依赖任何外部接口。对处理内部文档的场景来说，这是很大的便利。

一个小技巧分享给坚持看到这里的人：批处理时不要一次性把几千个 PDF 全丢进去，先在目录里放 20 到 50 个文件跑一批，确认输出稳定后再逐步加量。另外，解析完的 Markdown 目录一定要定期备份，后续如果调整分块策略或者换 embedding 模型，不需要重新解析 PDF，直接基于已生成的 Markdown 重新切块就行，能省下大量重复算力。

我踩过几次坑之后，现在固定的流程是：新文档进库时先跑 MinerU 解析，经过一轮抽检后进入 Markdown 原料库，再由触发任务自动分块入库。这个流程跑顺了，RAG 的预处理环节就不再是瓶颈了。