企业官网建设流程全解析

最近在折腾Windows本地的RAG知识库时，我发现整套流程里最容易被低估、也最影响结果质量的环节，是文档预处理，尤其是PDF解析。很多项目团队第一版检索效果差，问题通常不在embedding模型或向量库，而是PDF里根本没有解析出干净的文本结构：扫描件文字提不出来，双栏论文读出来是乱序碎片，表格和公式直接丢成一行。这个瓶颈不解决，后面接什么RAG框架都是白搭。

我目前主力方案是MinerU 4.0。它在Windows本地可以离线跑，专门把PDF转成带版面语义的Markdown和JSON，支持扫描版OCR、公式识别、表格结构还原和阅读顺序整理，正好卡在RAG文档预处理这一步。这篇文章不聊高大上的架构，就完整记录我在这台Windows机器上部署MinerU 4.0、准备离线模型、接入RAG预处理流水线的全过程，包括踩过的坑和最后稳定的配置参数。

1. 为什么文档预处理会成为RAG质量的分水岭

1.1 传统PDF解析在RAG场景里的硬伤

早先我搭知识库用的是Python那边最常见的pdfplumber和PyPDF2，配合pypdfium2做兜底。这三件套对付"电子版导出、单栏、纯文字"的PDF还行，一旦换成真实世界里的文档就露怯：

• 扫描版PDF：这类文档根本没有文本层，pdfplumber提取出来全是空字符串，必须外挂OCR工具，而传统OCR只吐纯文本流，页面里的标题层级、栏位关系、表格结构全部丢失。
• 双栏排版：学术论文、杂志、政府公告普遍双栏。按坐标从上到下扫描会把左栏下半截和右栏上半截拼接在一起，语义被切得七零八落。
• 表格和公式：传统工具只能拿到单元格里的散装文字，表格行与列的对应关系靠猜。公式更惨，直接变成一堆无序的符号。

这些问题的本质在于：传统PDF解析是"坐标文本抽取"，不是"版面结构理解"。而RAG的向量化恰恰最依赖语义完整性——一段被拦腰截断的技术方案、一个拆散了的参数对比表，喂给embedding模型之后，检索出来的结果必然带毒。

1.2 MinerU的解析逻辑：把"版面结构"还给你

MinerU与上面这些工具的根本区别是，它把解析当成一条"视觉理解+结构化输出"的流水线来做。官方给的流程大致是这样：输入图像先做预处理（倾斜矫正、去摩尔纹、去阴影），然后走版面检测模型，把页面切分成标题、正文、表格、图片、公式等区域；再针对不同区域做内容识别，扫描件走OCR文字识别，公式区域走专门的公式识别模型转LaTeX，表格区域做表格结构还原；最后依据版面信息重新排列阅读顺序，输出成Markdown和JSON。

这一套下来，PDF解析的输出不再是"一坨文字"，而是有层级、有坐标、有类型标注的结构化数据。我举一个实际案例：一份市面上的行业研究报告，封面后第三页是"近五年市场规模对比表"，传统解析给出的是一串挤在一起的数字；MinerU给的是一个完整的Markdown表格，列名、单位、年份对应关系一目了然。这个问题解决掉之后，RAG的召回结果质量立刻上了一个台阶。

1.3 4.0版本在工程易用性上的改进

如果你以前用过MinerU 1.x或2.x，4.0最直观的感受是三点：

• 模型权重体积更小，推理速度更快。同样的GPU，老版本跑一本300页扫描版报告要15分钟，4.0我这里大约7-8分钟。
• 安装和调用方式收敛了，pip装完直接用，CLI和Python API两套入口都保留，不用再折腾复杂的编译和依赖。
• 离线部署友好度提升。模型文件支持通过环境变量指定本地缓存目录，能提前拉好模型再拷贝到内网机器，从原理上支持纯离线解析。

有一点必须提醒：MinerU 4.0装完包之后不是马上就能跑，还要先把模型权重准备到位。这个环节恰恰是新手最容易卡住的地方，下一章就从Windows环境准备讲起。

2. Windows环境准备：先把依赖这层地基打牢

2.1 硬件要求与系统约束

先说硬件，因为MinerU是深度学习模型推理，不是普通文本处理工具，对资源有底线要求。

• 系统：Windows 10/11，64位。Win10以下我没试过，不建议挑战。
• 显卡：NVIDIA显卡优先，能上CUDA。显存建议8GB起步，实测4GB显存跑中等规模PDF会频繁OOM。
• 没有N卡怎么办？CPU也能跑，后面第6章会给出实测性能数据和降级方案，但体验确实要打折。
• 内存：16GB起步，32GB更稳。MinerU在处理大PDF时峰值内存不低，我这边300页的扫描版报告峰值吃到过9GB左右。
• 硬盘：模型文件加起来几个GB，加上解析过程中产出的临时文件和图片缓存，预留20GB比较稳。

如果机器配置不够，不用急着换电脑，可以先看第6章的显存降级方案，很多场景还有回旋余地。

2.2 Python版本与隔离环境

Windows上装Python，我的建议非常明确：用3.10或3.11，实在不行才上3.12。我在3.13上试过一次，几个C扩展依赖直接编译报错，后来退回3.11才消停。MinerU对Python版本有官方支持范围，装新版本之前先看一眼依赖声明，别当小白鼠。

环境隔离是必须的。别把MinerU直接装进系统Python，后面跟别的项目打架的概率太高。我这边用venv：

# 在项目目录下创建虚拟环境 python -m venv mineru_env # 激活 mineru_env\Scripts\activate # Windows下如果脚本执行策略限制，先放开当前用户 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

还有一个Windows老毛病：路径长度限制。如果你的项目路径很深，比如C:\Users\张三\Documents\projects\rag_doc_pipeline\.venv\...，很容易触发260字符限制导致安装失败。两个解决办法，选一个就行：

• 把项目路径整体缩短，比如直接放C:\mineru_ws\下。
• 打开注册表，找到HKLM\SYSTEM\CurrentControlSet\Control\FileSystem，把LongPathsEnabled设为1，重启后生效。

2.3 安装顺序：先PyTorch后MinerU

这一步的顺序定了后面少掉一半头发。MinerU底层依赖PyTorch，如果直接pip install mineru，pip会顺手拉一个大版本PyTorch，大概率是CPU版，等你发现的时候已经浪费了半小时下载时间。所以我的顺序是：

# 进入虚拟环境后，先装PyTorch # 有NVIDIA显卡且CUDA可用时，装CUDA版（cu121或cu124，取决于驱动版本） pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 # 没有N卡，或者不想折腾CUDA，直接CPU版 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 再装MinerU，full版本包含全部依赖 pip install -U "mineru[full]"

国内网络环境下，PyTorch的官方index-url有时候偏慢，可以加-i https://pypi.tuna.tsinghua.edu.cn/simple指定清华源，PyPI包本身走镜像问题不大。装完跑一句验证：

mineru --version

如果提示mineru不是内部或外部命令，别慌，这是Windows下Python Scripts目录没进PATH的经典问题。找到虚拟环境下的Scripts\mineru.exe，确认这个目录在PATH里，或者直接重启终端再试。

2.4 安装后的自检清单

装完先别急着跑PDF，花两分钟做个自查，能省后面排查的时间：

1. python -c "import torch; print(torch.__version__)"确认torch能导入。
2. python -c "print(torch.cuda.is_available())"确认CUDA是否可用。如果装了CUDA版但输出False，检查NVIDIA驱动版本和PyTorch的CUDA版本是否匹配。
3. mineru --help能正常打印出参数列表，说明CLI入口没问题。
4. 检查是否装好了Visual C++ Redistributable。Windows Server或精简版系统经常缺这个，缺了会在运行时报找不到DLL。

如果某台机器上torch.cuda.is_available()一直是False，大概率是驱动太老配不上新版PyTorch。解决方向是去NVIDIA官网更新驱动，然后重新安装对应CUDA版本的PyTorch，别指望在现有驱动上硬凑。

环境层搞定之后，接下来的重点就是模型文件。MinerU没有模型文件是跑不起来的，而这一块也是离线部署的核心命门。

3. 离线模型的获取与迁移：不联网也能跑的关键

3.1 模型组成与本地缓存目录结构

MinerU 4.0的推理依赖一组视觉模型，各司其职：

• 版面检测模型：负责识别页面里的标题、正文、图片、表格、公式等区域。
• OCR相关模型：负责扫描版PDF的文字识别，以及部分版面元素的辅助识别。
• 公式识别模型：负责把公式区域的图像转成LaTeX表示。
• 表格结构模型：负责表格行列线的还原。
• 排版模型：负责阅读顺序和最终结构输出的排序。

这些模型加起来体积不小，首次运行时会自动下载并缓存到本地。Windows上默认缓存位置通常在用户主目录下，具体路径受环境变量控制。我统一用MINERU_CACHE_DIR来管理，避免默认位置找起来费劲。

理解这一点很重要：MinerU的"离线能力"不是说软件本身不联网，而是把模型文件提前准备到本地之后，推理阶段完全不依赖网络。只要模型文件在，它就是个纯本地工具。

3.2 联网机器上批量拉取模型

准备离线环境的前置条件，是你有一台能上网的机器（可以是Windows，也可以是Linux/WSL），在上面把模型文件拉下来，再整体迁移到目标离线机器。

拉取模型最稳的方式是设置MINERU_MODEL_SOURCE=modelscope。MinerU支持从多个模型源下载，把模型源切到ModelScope之后，国内网络的稳定性和速度都会好很多，这是实际体验而非玄学。操作如下：

# 在联网机器上 set MINERU_MODEL_SOURCE=modelscope set MINERU_CACHE_DIR=C:\mineru_models # 造一个最简单的PDF，或者随便拿一个已有的小PDF触发首次下载 mineru -p test.pdf -o C:\temp\mineru_test

首次运行会在终端里看到模型逐个下载的进度日志。全部跑完之后，去C:\mineru_models目录确认模型文件是否齐整。目录下会分多个子目录，每个子目录对应一类模型。

3.3 拷贝到离线机器的完整步骤

模型拉取完成后，迁移过程就是纯拷贝的活。我实际操作下来最省事的方案是：

1. 在联网机器上把C:\mineru_models整个目录压缩成tar包（Windows下用7-Zip也行，注意保留目录结构）。
2. 通过U盘、内网共享或者其它离线传输手段拷到目标Windows机器。
3. 在目标机器上设置环境变量，指向解压后的目录：

setx MINERU_CACHE_DIR "C:\mineru_models" setx MINERU_MODEL_SOURCE "offline"

这里有个小细节需要注意：setx设置的是用户级环境变量，设置完需要新开一个终端窗口才会生效。而且我建议对MINERU_CACHE_DIR和MINERU_MODEL_SOURCE都设置，其中MINERU_MODEL_SOURCE设成offline或对应的模型源名，能避免程序在某些场景下仍然尝试访问网络。

拷贝完成后，可以在离线机器上先跑dir C:\mineru_models确认模型文件都在，再跳到下一章做验证。

3.4 怎么判断这次启动真的"全程离线"

很多人以为把模型文件放到位了就是离线，其实没有验证过。我的验证方法很简单：

1. 把目标机器的网络断开（拔网线或者断Wi-Fi）。
2. 正常跑一次MinerU解析。
3. 如果顺利出结果，日志里没有报连接超时、也没有卡在下载进度条，说明缓存命中，离线链路打通。

另外，解析启动时留意日志里有没有出现"Downloading"、"Checking update"这类字样。正常命中本地缓存时，日志会显示模型文件已存在或直接跳过下载阶段。如果断网状态下报错提示找不到模型，优先检查MINERU_CACHE_DIR环境变量是否生效，以及解压后的目录层级是否多套了一层文件夹。很多人栽在这里——压缩包的根目录里还有一层同名目录，导致程序找到...\mineru_models\mineru_models\...，反而读不到模型。

模型就绪之后，就可以正式体验解析效果了。下一章把CLI和Python API两条路都走一遍，也顺便看懂输出目录里到底生成了什么东西。

4. 第一次跑通PDF解析：CLI与Python API实操

4.1 命令行一把梭：最快看到输出结果

命令行是最直观的验证方式。拿一份PDF随便试：

mineru -p input.pdf -o output_dir

如果一切正常，output_dir下会生成：

• input.md：最终的结构化Markdown文件。
• input.json：包含版面元素、坐标、阅读顺序等详细结构的JSON文件。
• images\：解析过程中抽离出来的图片（插图、表格截图等）。

-m参数控制解析模式，4.0里常见的取值有三个：

• auto：程序自动判断页面是否为扫描版，混合文档用这个最省心。
• txt：纯文本型PDF，不做OCR，速度最快。
• ocr：强制走OCR，适合扫描版、图片型PDF。

还有--language指定文档语言，中文文档传--language zh可以提升识别效果。实际参数以你本地mineru --help输出为准，不同小版本可能有微调。

我第一次跑的时候拿了份20页的行业报告，OCR模式下耗时约1分20秒。打开生成的Markdown，双栏论文被正确还原成从上到下的自然阅读顺序，表格成了真正的表格，图片也有引用路径，那一刻感觉之前用的解析工具确实差了一个时代。

4.2 Python API：把解析能力嵌入自己的流程

CLI适合验证和单文件处理，RAG流水线里更常用的是Python API。MinerU的Python入口风格比较简洁，大致长这样：

from mineru import MinerU # 初始化解析器 extractor = MinerU( enable_formula=True, # 是否启用公式识别 enable_table=True, # 是否启用表格还原 language="zh", # 文档语言 ) # 执行解析 result = extractor(pdf_path="input.pdf", output_dir="output_dir") # result中通常包含结构化结果，不同版本的字段略有差异 print(result)

API签名在不同小版本之间可能有微调，但是核心参数大差不差。关键心得是：把output_dir指向固定目录，流水线的下一阶段就可以直接去这个目录读Markdown/JSON，不用在函数之间传一堆内存对象，工程上更稳。

另外，MinerU也暴露了更低层的中间结果接口，比如可以拿到版面检测后的区域框（bbox）列表，如果你需要做细粒度的后处理（比如把某个坐标区域的文本单独提取），在API层面反而比解析完再从JSON里翻更直接。

4.3 输出产物里到底有什么

看懂输出产物，是做好RAG预处理的前提。这里拆开讲：

Markdown文件是最常用的输入源。它保留了：

• 标题层级（#、##、###对应原文的标题结构）。
• 表格（真实Markdown表格语法，不是拼接文本）。
• 公式（LaTeX形式，行内和块级都有）。
• 图片引用路径（指向images目录下的文件）。

JSON文件是版面信息的宝藏。每个文本元素都带：

• type：类型，比如title、text、table、figure、formula。
• bbox：在页面上的坐标框，四个数字分别对应当前页的坐标位置。
• page_idx：页码。
• order：阅读顺序序号，按这个可以还原真正的阅读序列。

这些字段对RAG的价值非常大，尤其是type和order，直接决定了你能不能用"标题为边界、段落为单元"的方式做分块。这个后面第5章会展开。

images目录要留意。它不是把所有PDF页面都导出成图片，而是把解析时识别出的独立元素（插图、表格截图、公式截图）单独存出来。如果你的RAG走的是纯向量检索路线，图片一般用不上；但如果要接多模态模型，这些裁剪好的图反而是高质量的输入。

4.4 不同文档类型如何选择解析模式

用了一段时间之后，我总结出一个比较实用的选型表：

一个值得注意的坑：auto模式对"页面里既有文本层又有扫描图"的混合PDF判断不一定准。我遇到过一次报告的前半是电子版、后半是扫描版，auto模式把前面按文本跑了、对扫描页识别效果差。如果文档类型明确，不如直接强制ocr，慢是慢一点，但结果上限更高。

5. 把MinerU接进RAG预处理流水线

5.1 一条完整的PDF→向量库流水线

工具解析能力强，只解决了RAG流水线的第一环。要让文档真正变成可检索的知识，还需要把解析产物清洗、分块、向量化、入库。我现在的流水线大致是：

1. 解析：MinerU把PDF统一转成Markdown+JSON。
2. 清洗：去掉空行、页眉页脚、无关的水印文字，合并被分页拆断的段落。
3. 结构化分块：利用标题层级划定块边界，生成语义完整的chunk。
4. 向量化：用中文embedding模型把chunk转成向量。
5. 入库+检索：写入向量库，上层接RAG查询和问答。

这五步里，第1步和第3步是MinerU带来的核心增量，因为以前从PDF直接转纯文本时，根本找不到"标题在哪、正文从哪开始、表格跟哪个小节相关"这些边界信息。

5.2 基于版面语义的分块思路（而不是按字数硬切）

RAG项目里最流行也最偷懒的分块方式是"固定token数硬切"，比如每500个token切一刀，中间重叠50个。这种做法对小短文没问题，但遇到结构复杂的长文档就是在制造检索灾难：一个标题可能被切到上一块的末尾，而它的正文跑到了下一块的开头；一张表格被拦腰截断成上下两半。

MinerU的JSON给了我们做语义分块的现成依据。我的核心思路是：

1. 从JSON里按照order顺序遍历所有元素。
2. 遇到type为title的元素，作为新块起点。
3. 标题后面的text、table、formula元素归属当前块，直到下一个标题出现。
4. 如果一个标题下内容过长（超过预设上限，比如2000字），再按"段落/句子边界"二次切分，而不是盲目截断。

这样切出来的块天然保持"标题-正文-子标题-正文"的层级关系。检索时既可以按块匹配，也可以把标题路径作为元数据拼进prompt，让增强生成阶段获得更清晰的上下文定位。

5.3 表格和图片内容怎么处理才不拖垮检索

表格是RAG里最尴尬的内容类型。把它转成Markdown原文，向量化之后，检索器拿到的是"列名+单元格数字"的拼接，语义并不好。但完全丢弃表格，又会丢掉报告中最密集的信息。我的处理策略按场景分三档：

• 简单问答场景：保留Markdown表格原文，但它单独成块，不做二次切分。这样"近五年市场规模对比表"这种完整表格能整体命中。
• 需要精确计算的场景：把表格按行转成自然语言描述，比如"2021年市场规模为120亿元，同比增长15%"，检索和生成的准确率都会提高。
• 多模态RAG场景：用MinerU导出的images目录里的表格截图，交给视觉语言模型做图文联合理解。这不是常规路线，但真需要的时候很好用。

图片除了表格截图，基本不参与文本检索。理由很简单：大部分embedding模型是纯文本模型，图片描述错误反而带来噪声。真要检索图片，走多模态向量化，或者给图片预先写一段高质量文本描述再索引，都比硬塞进文本chunk强。

5.4 一个可以直接复制的Pipeline脚本

下面这个脚本是我目前线上用的简化版本，覆盖了从PDF到向量入库前的核心逻辑，你把它改改路径就能跑：

import json import re from pathlib import Path from mineru import MinerU def parse_pdf(pdf_path: Path, output_dir: Path) -> Path: """调用MinerU解析PDF，返回Markdown文件路径""" extractor = MinerU( enable_formula=True, enable_table=True, language="zh", ) extractor(pdf_path=str(pdf_path), output_dir=str(output_dir)) # MinerU输出markdown的路径与pdf同名的规律，这里做一个兜底查找 md_files = list(output_dir.glob("*.md")) if not md_files: raise RuntimeError("MinerU解析完成但未找到Markdown输出") return md_files[0] def clean_markdown(md_text: str) -> str: """基础清洗：去页眉页脚水印、压缩空行""" lines = md_text.splitlines() cleaned = [] for line in lines: # 去掉常见的“第X页”和页眉页码模式，按需调整 if re.match(r"^\s*第?\s*\d+\s*页\s*$", line): continue if line.strip(): cleaned.append(line.rstrip()) text = "\n".join(cleaned) # 压缩连续空行为一个 text = re.sub(r"\n{3,}", "\n\n", text) return text def chunk_by_headings(md_text: str, max_len: int = 1500) -> list[dict]: """按标题层级分块，并追加元数据""" chunks = [] current_title = "" current_parts = [] current_len = 0 def flush(): nonlocal current_title, current_parts, current_len if current_parts: content = "\n".join(current_parts).strip() if content: chunks.append({ "title": current_title, "content": content, "length": len(content), }) current_parts = [] current_len = 0 for raw_line in md_text.splitlines(): # 标题检测：# 或 ## 开头 title_match = re.match(r"^(#{1,6})\s+(.*)", raw_line) if title_match: flush() current_title = title_match.group(2).strip() continue # 太长的块按段落边界二次切分 if current_len + len(raw_line) > max_len and current_parts: flush() # 保留标题上下文，重新开启新块 current_title = current_title current_parts.append(raw_line) current_len += len(raw_line) + 1 flush() return chunks def pipeline(pdf_folder: Path, output_root: Path): for pdf_path in pdf_folder.glob("*.pdf"): # 分配独立的输出目录 out_dir = output_root / pdf_path.stem out_dir.mkdir(parents=True, exist_ok=True) md_file = parse_pdf(pdf_path, out_dir) md_text = md_file.read_text(encoding="utf-8") md_text = clean_markdown(md_text) chunks = chunk_by_headings(md_text) # 这里接向量化入库，比如用bge或text2vec转向量后写入向量库 # 先把chunks落到json里，方便排错 (out_dir / "chunks.json").write_text( json.dumps(chunks, ensure_ascii=False, indent=2), encoding="utf-8", ) print(f"{pdf_path.name}: {len(chunks)} chunks") if __name__ == "__main__": pipeline(Path("./pdfs"), Path("./parsed_output"))

这个脚本我故意把向量化部分留成注释，因为不同项目的embedding和向量库选型不同。但分块逻辑是通用的，chunk里带title字段，入库时可以作为元数据，也可以直接拼进向量化的prefix里提升检索质量。

6. 翻车记录与调优经验

6.1 模型反复下载失败的根因

这个坑我花的时间最多。现象是：每次启动MinerU，日志都显示在下载模型，进度条走到一半就卡死，重试也没用。一开始我以为是网络波动，后来仔细查才发现问题出在缓存目录上——我把MINERU_CACHE_DIR设成了C:\mineru_models，但程序实际使用的模型目录在该环境变量下的子路径里，而我拷贝模型时把目录层级搞错了，程序找不到模型文件，于是只要联网就触发重新下载，一直失败。

解决方式：先在联网机器上完整跑一次解析，确认缓存目录下的实际文件结构，再整体打包迁移。别手动去改里面的目录名，保持程序自己生成的结构最稳。

另外，MINERU_MODEL_SOURCE没设置时，程序会按默认源找模型。默认源访问不稳定时，同样会表现为"下载失败"。把模型源切到modelscope之后，这个症状基本消失。

6.2 中文扫描件的乱码与断行问题

扫描版PDF经MinerU处理后偶尔会出现个别字符错乱、标点被替换、段落中间无辜断行。我遇到比例不高，但RAG场景里一个错别字就可能影响检索命中率。

排查下来主要两个原因：

• 原始扫描件的DPI太低。低于150DPI的扫描件识别质量直接崩，建议扫描时保持300DPI以上。
• 页面内有大段彩色背景或阴影，干扰了OCR的前处理。这时可以让MinerU的预处理阶段更激进一些，或者先对源PDF做一次图像增强再喂进来。

我现在的做法是在流水线里保留一个"清洗层"，用简单的正则表达式修正断行和多余空格；如果发现某份文档乱码率异常高，就不跟它较劲，直接提高扫描DPI重新做源文件。

6.3 显存不足与CPU模式下的性能优化

没有大显存显卡的人不用灰心，MinerU在CPU上确实能跑。我测试过一台i5-12400F、无独显的机器，处理一份80页扫描版PDF，OCR模式大约耗时30分钟左右；纯文本型PDF会快很多，大约10分钟。GPU那边，一块8GB显存的RTX 3060跑同样80页扫描件大约是2分半。

如果显存不足，几条降级经验：

• 缩小单次输入的PDF。把大PDF按页码范围拆成多个小文件，逐个解析，最后合并结果。拆页可以用pypdf，也可以让MinerU配合上游的页范围参数。
• 关闭公式识别和表格增强。这两项会额外加载模型并增加显存占用。
• 设置device="cpu"强制走CPU推理。慢是慢，但不会OOM崩溃。

还有一个容易忽略的点：同时开多个MinerU进程并不会线性加速，反而会因为显存/内存争抢导致性能倒退。我这边实测单进程处理时加一个页级并发，比直接开多进程稳定得多。

6.4 Windows特有的路径、杀软与权限坑

Windows版本的MinerU比Linux版多一些"特色"问题，这里集中记录：

• 中文路径：如果PDF路径或输出路径里包含中文，偶尔会出现找不到文件或输出失败的问题。保守做法是统一用英文路径，尤其在公司共享网盘环境里踩过几次之后我彻底学乖了。
• 杀毒软件：模型文件动辄几个GB，Windows Defender以及第三方杀软全盘扫描时会拖慢解析速度，甚至在模型加载阶段把某些文件误判为风险而拦截。我在服务器环境直接把MinerU的工作目录加入杀软白名单。
• 管理员权限：运行MinerU不需要管理员权限，反倒是在管理员终端里运行某些步骤时会有环境变量错乱的问题。推荐用普通用户终端执行，目录选择当前用户有读写权限的位置。
• 文件锁：解析过程中如果输出目录被资源管理器打开，或者PDF正被其它程序占用，Windows会报文件被占用而失败。确保没有其它程序锁住文件再跑。

这些坑都不是MinerU的bug，属于Windows生态的老传统，提前知道能省很多排查时间。最终跑通之后，我现在的日常操作其实就是：PDF丢进输入目录，跑一遍pipeline脚本，chunks落盘，再交给embedding和向量库。整个过程里MinerU从"唯一的瓶颈"变成了"最稳定的一环"。

最后再分享一个我个人的体会：如果你也是第一次在Windows上部署MinerU，别一上来就追求满配、也别直接批处理几百份PDF。先拿一份扫描版、一份复杂排版的电子版，把CLI跑通、把模型离线链路验证掉、把输出目录翻一遍，再上批量。文档预处理这件事，工具选对只是开始，真正决定RAG天花板的是你多了解你的文档，以及多了解工具吐出来的每一个字段。MinerU算是把PDF里的版面信息"还"给了你，怎么用好这份信息，就是我们自己该打磨的功夫了。