做 RAG 的都知道，文档进向量库之前那一步预处理，往往比选哪个 embedding 模型更影响最终效果。而 PDF 又是文档库里绕不开的重灾区——扫描件、双栏排版、表格、公式、页眉页脚，随便哪一个都能让传统文本提取工具当场翻车。我试过 PyMuPDF、pdfplumber、paddleocr 串流程，结果不是文字顺序错乱，就是表格被拆得没法看。后来接触到 MinerU 这个开源项目，关键是 4.0 版本在 Windows 上可以直接本地部署，离线跑完整套 PDF 解析流水线，输出结构干净的 Markdown 和 JSON，刚好把 RAG 文档预处理这块最难啃的骨头处理掉了。这篇文章就记录一下我在 Windows 环境下部署 MinerU 4.0、离线解析 PDF，以及把解析结果接入 RAG 预处理流程的完整过程，适合正在搭知识库、又不想把内部文档传到云端 API 的开发者参考。
1. RAG文档预处理里最麻烦的一环：PDF解析
1.1 为什么PDF总是让RAG效果打折
PDF 本身是一种排版格式，不是文本格式。它记录的是每个字符的坐标、字体、字号等渲染信息，而不是像 Word 或 HTML 那样的逻辑结构。所以用PyPDF2、pdfplumber这类工具去抽文本时，最常见的问题就是文字顺序错乱。尤其是双栏排版、报纸式版面、复杂的表格，抽出来的文本经常是栏 1 的第一行接着栏 2 的第一行，语义完全断裂。RAG 模块拿到这种文本，切块再 embed 之后，检索出来的片段往往是牛头不对马嘴。
扫描件就更麻烦了。没有文本层，必须走 OCR。传统方案是先用 OCR 识别整页文字，然后直接拼接成一个大字符串。这样做有两个问题：第一，OCR 本身有误差，尤其是针对中文扫描件的倾斜、低对比度页面，错字率会直接影响向量检索的召回；第二，OCR 之后没有任何版面结构信息，标题、段落、列表、表格全混在一起，后续哪怕想按章节切块也无从下手。
实际上，RAG 的切块策略极大依赖文档本身的结构。如果预处理阶段能保留“标题层级”“表格边界”“公式块”这些信息，后续就能按章节切块、按表格单独处理、把公式转成文本描述，检索效果会稳定很多。这也是我最终转向 MinerU 的原因——它把 PDF 解析从“抽文字”提升到了“还原版面结构”的层面。
1.2 MinerU 4.0 到底解决了哪些问题
MinerU 是一个开源文档解析工具，4.0 版本的核心思路是用深度学习模型做版面分析和阅读顺序恢复。它把 PDF 的每一页作为图像输入，通过目标检测识别出文本块、插图、表格、公式、页眉页脚等元素，然后按照人眼的阅读路径重新排列这些元素，最终输出带格式的 Markdown 文件，以及包含版面元素的 JSON 文件。
我实际使用下来，它有几个明显优势。第一，双栏识别稳。我之前用 pdfplumber 抽双栏 PDF，抽出来的顺序完全是乱的，MinerU 解析出来的 Markdown 能按左栏到右栏的逻辑顺序输出。第二，表格能转成 Markdown 表格而不是一堆堆串起来的文本。RAG 检索表格内容时，结构化表格比纯文本好使太多。第三，扫描 PDF 也能处理，内置的 OCR 模型会先识别文字再走版面分析流程，等于把“OCR + 版面还原”合并成一条流水线。
当然，它也有自己的门槛：模型文件较大，需要一定的磁盘空间；首次运行时如果网络不行，模型下载会卡住；CPU 模式下解析速度不算快。这些坑后面我会逐个说。
1.3 有网络和离线环境下的选型差异
很多人做 PDF 解析的第一反应是调用云端的 OCR API 或者 SaaS 解析接口，好处是部署成本低、速度快，坏处也很明显——内部文档、合规要求、数据隐私，这三条一压下来，云端方案基本就被否掉了。MinerU 这类本地部署工具的价值就在于所有计算都在本机完成，PDF 文件不用离开你的电脑。
但“本地部署”不等于“完全离线可用”。MinerU 运行时需要加载深度学习模型，这些模型默认从网上下载。所以离线环境下的正确姿势是：提前准备好模型文件，把模型目录放到 MinerU 能读取的位置，然后断网解析。这也是我这篇文章标题里“离线 PDF 解析”的比较准确的表述——用着用着就再也不需要网络连接了。
如果你在的网络有防火墙限制，模型下载可能会一直卡在“获取中”。这时候不要死等，直接把模型文件拷进本地目录，再通过环境变量指定模型路径，比什么重试都靠谱。具体怎么操作，我在第 3 节详细写。
2. Windows部署前需要想清楚的三件事
2.1 操作用户权限与终端选择
在 Windows 上部署 MinerU，第一件容易踩坑的事是终端权限。安装 Python 包、写系统环境变量这些操作确实需要管理员权限，但真正运行 MinerU 解析 PDF 时，我建议你用普通权限的终端，不要整个终端都开成管理员模式。原因很简单：管理员模式下，Python 进程的文件路径解析、临时目录映射有时候会和普通用户模式不一样，遇到权限报错时反而是非管理员终端更稳定。
终端本身，我推荐用 Windows Terminal + PowerShell。不要用老旧的 cmd，路径中的中文和空格问题在 cmd 里特别容易炸。另外注意：在 PowerShell 里粘贴命令时，如果路径中包含空格，必须用引号包起来，例如mineru -p "D:\我的资料\月度报告.pdf" -o output/，否则会被 PowerShell 拆成多个参数。
还有一个细节：Windows 的路径分隔符是\，但 Python 和很多命令行工具都兼容/。为了避免转义问题，我建议在命令里统一用正斜杠D:/my_docs/report.pdf，这样可以少踩很多坑。
2.2 Python版本和虚拟环境隔离
MinerU 的依赖涉及深度学习框架、图像处理库、PDF 解析库，版本敏感度很高。我强烈建议不要直接装在系统全局 Python 里，尤其是你已经装了其他项目依赖的情况下。用venv或者conda单独建一个环境，最省心。
Python 版本方面，MinerU 4.0 官方要求 Python 3.9 及以上，我用的是 Python 3.10。如果版本低于 3.9，部分依赖包会找不到对应的 wheel，装到一半报错。建议直接装新版 Python，不要在这个问题上抠。创建虚拟环境的命令很简单：
python -m venv mineru-env mineru-env\Scripts\activate激活之后，命令行前缀会变成(mineru-env)，这时候再装 MinerU，就不会污染其他项目。
2.3 GPU还是CPU：先看你的文档量
如果你只是偶尔解析几份 PDF，文档量不过上百页，CPU 模式完全够用。MinerU 在 CPU 模式下解析一份 10 页左右的论文 PDF，大概需要一两分钟，取决于文档复杂度。如果你要批量处理几百上千份 PDF，那就得考虑 GPU 加速了。
GPU 部署意味着你需要先装好 CUDA 版本的 PyTorch，然后再装 MinerU。这里有个先后顺序问题：如果在装 MinerU 之前已经安装了 CPU 版本的 PyTorch，MinerU 会复用已有的 PyTorch 版本，不会自动帮你切换成 GPU 版。所以想用 GPU 的同学，请先确认torch.cuda.is_available()返回 True，再装 MinerU。
显存方面，我用一块 8GB 显存的 GPU 解析过扫描版 PDF，显存占用大概在 4GB 到 6GB 之间。如果你是老卡显存只有 4GB，建议留一部分页面在 CPU 上跑，或者把线程数调小一点。另外，笔记本用户要特别注意散热，GPU 满载跑二十分钟以后，性能会因温度墙明显下降。所以我后来索性在批量任务里把-j线程数限制为 1 或者 2，换取更稳定的运行时长。
3. MinerU 4.0的安装与离线模型配置实录
3.1 pip安装与依赖包冲突处理
激活虚拟环境之后，安装 MinerU 本身并不复杂：
pip install -U mineru但如果你在安装过程中看到ERROR: Cannot install mineru==xxxx或者torch相关的冲突提示，大概率是 Python 版本或者已有依赖包版本不兼容。我的处理方式是先升级 pip 和 setuptools，再单独安装冲突包：
pip install --upgrade pip setuptools wheel pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu pip install mineru注意，我这里安装的是 CPU 版 PyTorch，因为我的批量解析机器没有独显。如果你要 GPU 加速，上面的--index-url要换成对应的 CUDA 版本，比如：
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118装完之后，用pip show mineru检查安装的版本和依赖列表，确认核心依赖都装全了。如果网络环境不好，pip 下载经常超时，可以临时切换到国内镜像源，比如阿里云或清华，但要注意别把 PyTorch 的官方源也一并替换，否则容易下错 CPU 版。
3.2 离线模型目录的获取与放置
MinerU 首次运行时会尝试下载模型文件，这些模型包括页面检测、文字识别、公式识别等几个模块，加起来有几个 GB。如果你是在公司内网、隔离网或者普通家用宽带受限的环境，模型下载这关会很难受。
我的办法是“借一台有网络的机器把模型缓存跑出来”。具体步骤：
- 在一台能正常访问外网的电脑上，安装好 MinerU 4.0。
- 随便找一个小 PDF，运行一次解析命令，让它自动下载模型。
- 等模型下载完成，找到本地的模型缓存目录。
模型缓存的默认位置一般在用户目录下，可能是.cache/mineru或者~/.cache/huggingface/hub这类目录。你可以在运行日志里搜一下包含download、model的路径信息，一般可以看到完整的模型路径。把整个模型目录拷贝到离线机器上，然后设置环境变量：
set MINERU_MODEL_DIR=D:/models/mineru-models这样 MinerU 在启动时会优先从MINERU_MODEL_DIR加载模型，不再走网络下载。如果你不想用环境变量，也可以直接把模型放到默认目录下，然后手动创建对应的目录结构，效果一样。
还有一个小技巧：如果你已经下载过模型，但不知道具体文件结构，可以在运行 MinerU 时加--debug参数（不同版本参数名可能略有差异，以mineru --help为准），它会打印出每个模型文件的加载路径。根据打印结果去整理目录，比自己猜目录省心得多。
3.3 验证安装：跑通最小示例
模型准备好之后，别急着处理大 PDF。先跑一个最小示例，确认整个链路是通的。我用的是官网入门文档里那个示例 PDF：
mineru -p sample.pdf -o output/ -l zh如果你的版本参数不同，最少看一眼mineru --help，里面会列出支持的命令行选项。常见参数大致包括：
-p或--input：输入 PDF 路径-o或--output：输出目录-l：文档语言-j：线程数--formula或-f：是否启用公式识别--table：是否启用表格识别--no-ocr：跳过 OCR（针对纯文本 PDF）
命令跑完后，在输出目录下会看到类似这样的结构：
output/ ├── markdown/ │ └── sample.md └── content_list.json如果两个文件都在，说明 MinerU 已经可以正常工作了。此时再把网络断掉，重新跑一次，确认离线模式也能出结果，然后再上量。
4. 用MinerU批量解析PDF并输出Markdown
4.1 命令行基本用法和常用参数
单文件解析是最简单的用法，但实际项目中，我们面对的往往是一个文件夹下的几十上百份 PDF。MinerU 本身不直接提供递归批处理功能，所以我都是用脚本批量调用命令行。在此之前，先把常用参数理解清楚，避免批量跑的时候因为参数配错而浪费几个小时。
我常用的组合是这样的：
mineru -p "D:/docs/all_pdfs/report_0325.pdf" -o "D:/docs/mineru_output/" -l zh -j 2参数说明：
-j 2：线程数设成 2。CPU 模式下线程数开太多反而会互相抢占资源，导致某些阶段频繁切换，2 到 4 是最稳的。-l zh：告诉模型文档是中文为主的。如果你的文档是英文，可以改成en。-o输出目录如果不存在，MinerU 会自动创建。
有些版本还支持--pdf_extract_method之类的参数，用来指定提取文本的方法，比如纯 PyMuPDF 还是走完整的版面分析模型。这个参数一旦改错，模型可能直接退化成普通文本抽取，输出结果质量差一截。所以安装完之后，我建议先跑一次默认参数，再看输出质量，不要一开始就迷信各种高级调参。
4.2 批量处理文件夹内所有PDF的脚本实践
由于命令行一次只跑一个输入文件，批量处理我写了段 Python 脚本，用subprocess循环调用 MinerU，并且做了一个并发限制，避免同时跑太多进程把内存打爆。
import subprocess import sys from pathlib import Path from concurrent.futures import ThreadPoolExecutor, as_completed INPUT_DIR = Path("D:/docs/all_pdfs") OUTPUT_DIR = Path("D:/docs/mineru_output") MODEL_DIR = Path("D:/models/mineru-models") MAX_WORKERS = 2 def parse_pdf(pdf_path: Path, out_dir: Path): cmd = [ "mineru", "-p", str(pdf_path), "-o", str(out_dir), "-l", "zh", "-j", "2", ] if MODEL_DIR.exists(): cmd.extend(["-m", str(MODEL_DIR)]) result = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8") if result.returncode != 0: return pdf_path.name, result.stderr[-500:] return pdf_path.name, "ok" pdf_files = list(INPUT_DIR.glob("*.pdf")) with ThreadPoolExecutor(max_workers=MAX_WORKERS) as executor: futures = {executor.submit(parse_pdf, p, OUTPUT_DIR): p for p in pdf_files} for fut in as_completed(futures): name, msg = fut.result() if msg != "ok": print(f"FAIL {name}: {msg}", file=sys.stderr) else: print(f"DONE {name}")注意 PowerShell 的默认编码对中文字符支持可能有问题，如果日志打印乱码，可以在脚本开头加上：
sys.stdout.reconfigure(encoding='utf-8')用并行任务的话，输出目录建议每个 PDF 单独建子目录，避免多个进程同时写同一个文件造成冲突。MinerU 的-o参数是指定输出根目录，每个 PDF 会生成一个以 PDF 文件名命名的子目录，所以只要每次调用时传入同一个根目录，问题不大。但为了保险，我习惯在调用前确认OUTPUT_DIR存在。
4.3 解析结果里藏着哪些信息和“脏数据”
很多人以为 MinierU 输出的 Markdown 是干净可直接入库的，但实际跑完几百份 PDF 之后你会发现问题不少。Markdown 里除了正文，还会有图片引用、表格、公式 LaTeX 代码，以及一些被识别错误产生的杂散片段。
以我处理的这批文档为例，输出里经常出现几个问题：
- 图片路径：MinerU 会把页面中的插图导出为图片，并在 Markdown 里插入相对路径。比如
，如果你把 Markdown 直接切成片段进入 RAG，这些相对路径会成为没意义的字符串，必须过滤或替换。 - 按页生成的分隔线：有些版本会在每页末尾插入
<!-- 第 1 页结束 -->之类的注释，不属于原始阅读内容，处理时需要去掉。 - 表格宽度不统一：Markdown 表格在列数不一致时，切块容易把表格拦腰截断。我的做法是表格单独处理，不参与常规文本分块。
- 公式的 LaTeX 代码：如果你不开公式识别，公式区域可能输出一堆不明字符；如果开启，会变成
$$ ... $$，这种片段直接向量化效果很差，最好转成文字描述，或者单独走一个公式 embedding 通道。
所以我把解析输出分成三路：正常文本块、表格块、公式块。各路分别清洗、分别切分，再统一进入 RAG 的文档索引体系，这样检索精度比混在一起高很多。
5. 把解析结果接到RAG预处理流程里
5.1 Markdown分块：按结构切，而不是按字符长度硬切
RAG 最常见的切分方式是用固定窗口，比如每 500 字切一刀，加 100 字重叠。这种方式对纯文本凑合，但对带结构的 Markdown 文档来说，很容易把标题和下面的内容拆散，导致检索时上下文缺失。
我拿到 MinerU 生成的.md之后，会先按标题层级切分。基本思路是：遇到#、##、###标题就开启一个新块，标题路径自动作为后续块的前缀。这里给出一个简化版的分块函数：
import re def split_markdown_by_headings(md_text: str): lines = md_text.splitlines() chunks = [] current_path = [] current_lines = [] heading_re = re.compile(r'^(#{1,6})\s+(.*?)\s*$') def flush(): if not current_lines: return text = "\n".join(current_lines).strip() if text: chunks.append({ "path": " > ".join(current_path), "text": text, }) for line in lines: m = heading_re.match(line) if m: flush() level = len(m.group(1)) title = m.group(2).strip() current_path = current_path[:level - 1] + [title] current_lines = [line] else: current_lines.append(line) flush() return chunks这套切分逻辑比固定窗口更适合 RAG，因为每个块都带着完整的标题路径，检索到小节内容时，用户能立刻知道这段内容处于文档的哪个位置。如果你的文档没有标题结构，再退回字符切分。
5.2 清洗与过滤：表格、公式、页眉页脚的处理
MinerU 输出的 Markdown 虽然是结构化文本，但直接进向量库之前还需要清洗。我从实践中总结了一套固定流程：
- 去除图片引用：正则
!\[[^\]]*\]\([^)]*\)替换为空字符串。 - 去除注释和分隔线：类似
<!-- ... -->的内容直接删掉。 - 压缩多余空行：连续两个以上换行只保留一个。
- 页眉页脚：如果文档有固定的页眉页脚，在文本中会出现大量重复片段，比如公司名称、页码。可以先统计高频重复行，长度小于 50 字且出现次数超过页面数一半的行直接移除。
- 表格处理：Markdown 表格保留列头，但把分割线
---|---|删除。如果表格特别宽，可以转换成自然语言描述，比如“列名：值”，这样 embedding 模型更容易理解。
公式的处理我建议看场景。如果是技术论文，公式代表核心信息，不要粗暴删除，但可以统一转成[公式: LaTeX 内容]的文本形式，让向量模型至少能捕捉一部分语义；如果是普通商业文档，公式出现频率低，直接保留$$块也可以。
清洗完之后，建议肉眼抽查几个样本。MinerU 的版面模型不是万能的，某些双栏排版或彩色背景复杂的页面还是可能识别错乱。我的抽查比例是千分之一，也就是每处理 1000 页抽 1 页看看，确认清洗规则没有误伤正文。
5.3 给分块补元数据，让向量检索更顺手
光有文本块还不够，RAG 检索时如果能在命中结果里展示来源、页码、标题路径，用户会更容易信服。这些信息属于分块的元数据，我是在生成分块时一并写入的。
从 MinerU 的content_list.json里，可以拿到每个版面元素的类型、坐标、所在页面。结合 Markdown 切分结果，我建立了一条对应关系：Markdown 里某段文字，对应 content_list 里的某个 text 块，然后反查它的页码。具体实现稍微有点繁琐，因为标题文本和正文文本并不总是一一对应，我的简化做法是：根据页面分隔标记倒推，在 Markdown 里插入的每页结束注释处记录当前页码，之后生成的块统一继承这个页码。
最终写入向量库的 chunk 结构大致如下：
{ "file_id": "report_0325", "page": 12, "heading_path": "第一章 > 背景介绍", "chunk_text": "MinerU 的版面分析模型基于深度学习……", "chunk_type": "text" }这些字段可以直接映射为向量数据库的元数据字段。检索时，除了返回相关片段，还自动带上来源文档和页码，前端展示时就能做引用链接，RAG 的可信度和可追溯性一下子提上来了。
6. 部署和运行过程中的常见故障与排查
6.1 模型下载卡在“获取中”的解决思路
“mineru 一直获取中”是我在离线环境下遇到最多的一个问题。探索几次后发现，这个现象几乎都是网络问题引发的：要么 DNS 解析不了模型仓库，要么下载超时。解决思路就是绕开自动下载，手动把模型放到本地。
具体操作步骤：
- 找一台有网络的机器，安装 MinerU，跑通一次，让它把所有模型下载完成。
- 到模型缓存目录（通常是
~/.cache/mineru或~/.cache/huggingface/hub），把模型相关文件夹全部复制到一个干净的目录，比如D:/models/mineru-models。 - 在离线机器上设置环境变量
MINERU_MODEL_DIR指向该目录，然后重新运行。 - 如果仍然提示下载，打开
--debug日志，看它实际尝试读取的模型路径是绝对路径还是相对路径。如果是绝对路径，说明源码里写死了路径，这种情况下直接把模型放到那个绝对路径即可。
实测下来，步骤 3 能解决 90% 的问题。剩下 10% 是因为版本更新后模型文件列表变了，旧模型目录缺少新文件。这时只需要从有网络的机器上补拷贝新增文件，一般就能通过。
6.2 内存占用过高和解析中断的处理
MinerU 处理复杂的扫描件 PDF 时，内存占用会爬升得很快。我遇到过一次 200 页的扫描 PDF，跑到 60 页左右进程直接 OOM 崩掉。后来我改用两个办法解决了问题。
第一，限制线程数。把-j 参数调成 1或 2，会显著减少内存峰值，代价是解析时间拉长。我在批量脚本里已经把MAX_WORKERS控制在 2，单进程内线程数再限制为 1，内存占用从原本的 8GB 左右降到 3GB 左右。
第二，将大 PDF 拆页处理。用 PyMuPDF 把文件拆成每 20 页一个子 PDF，然后让 MinerU 分别解析。这样做有两个额外好处：每个子文件独立失败重试，不会因为一个坏页导致整个文档全部重跑；多个子文件还可以并行塞给多台机器处理。
import fitz # PyMuPDF def split_pdf(src: str, page_per_file=20): doc = fitz.open(src) total = doc.page_count for start in range(0, total, page_per_file): out = fitz.open() end = min(start + page_per_file, total) for pno in range(start, end): out.insert_pdf(doc, from_page=pno, to_page=pno) out.save(f"{src}_part_{start//page_per_file+1}.pdf") out.close()如果你连 PyMuPDF 都不想装，MinerU 某些版本本身也支持--page参数指定页码范围，可以查一下帮助确认。
6.3 Windows下路径和权限引发的小毛病
Windows 特有的小毛病是真的频繁。第一个是路径太长。MinerU 输出目录默认会带上输入文件的完整路径，如果原始文件路径本身很长，最终可能超过 Windows 路径长度限制。解决办法是开启 Windows 长路径支持，或者干脆把输入文件复制到一个短路径下处理，比如C:/tmp/。
第二个是输出目录被某个进程占用。如果你的杀毒软件或者 OneDrive 正在同步输出目录，MinerU 写入文件时可能会报PermissionError或Access is denied。遇到这种情况，把输出目录排除出同步盘，或者干脆放到本地非同步目录。
第三个是中文文件名编码问题。MinerU 的日志和输出文件在中文路径下偶尔会出现乱码，但内容本身一般没问题。为了保证可追溯性，我建议在批处理脚本里把路径统一转换成unicodedata.normalize('NFKC', ...)格式，能减少一些莫名奇妙的编码错误。
最后一个提醒：Windows 的防火墙可能拦截 MinerU 内部的某些进程间通信，如果解析时提示端口占用或连接失败，考虑给 Python 进程加防火墙放行规则。注意这里不需要开任何代理，只是本机通信的白名单问题。
7. 最后说一点我自己的使用体会
把 MinerU 4.0 部署到 Windows 这一路，我印象最深的不是模型效果，而是“模型管理”这件事。很多人以为本地部署就是pip install然后公网跑，实际上离线环境、批量处理、路径问题才是真正花时间的地方。我建议第一次上手一定要先跑通最小闭环，再逐步加参数、加并行、加自定义清洗，不要一上来就指望完美结果。
一个小技巧分享：批量解析之前，先把所有 PDF 用脚本统一检查一遍，看是不是有加密、损坏或缺页的情况。MinerU 遇到加密 PDF 会直接失败，但你可以在传入前用 PyMuPDF 这种底层库先行过滤，免得批量跑了一半才发现中间夹着一个坏文件。
另外，如果要长期维护一个知识库，我建议把 MinerU 的解析输出作为中间产物存储下来，不要每次重新解析。Markdown 和 JSON 文件压缩后很轻，但能让你在调整分块策略时免去重复跑几个小时的烦恼。我第一次就是没留中间产物，后来改切分策略，整套 PDF 又重跑了一天，非常肉疼。
说到底，RAG 的文档预处理是脏活累活，没有什么工具能一键解决所有问题。但 MinerU 4.0 至少把 PDF 解析这一步从“不可控”变成了“可控”。本地部署之后，剩下的切分、清洗、元数据构建都是可以反复迭代的工程问题，这就比什么都强了。
