做 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 版本的 PyTorchMinerU 会复用已有的 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 mineruxxxx或者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_DIRD:/models/mineru-models这样 MinerU 在启动时会优先从MINERU_MODEL_DIR加载模型不再走网络下载。如果你不想用环境变量也可以直接把模型放到默认目录下然后手动创建对应的目录结构效果一样。还有一个小技巧如果你已经下载过模型但不知道具体文件结构可以在运行 MinerU 时加--debug参数不同版本参数名可能略有差异以mineru --help为准它会打印出每个模型文件的加载路径。根据打印结果去整理目录比自己猜目录省心得多。3.3 验证安装跑通最小示例模型准备好之后别急着处理大 PDF。先跑一个最小示例确认整个链路是通的。我用的是官网入门文档里那个示例 PDFmineru -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并输出Markdown4.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_outputTrue, textTrue, encodingutf-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_workersMAX_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(fFAIL {name}: {msg}, filesys.stderr) else: print(fDONE {name})注意 PowerShell 的默认编码对中文字符支持可能有问题如果日志打印乱码可以在脚本开头加上sys.stdout.reconfigure(encodingutf-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_file20): 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_pagepno, to_pagepno) out.save(f{src}_part_{start//page_per_file1}.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 解析这一步从“不可控”变成了“可控”。本地部署之后剩下的切分、清洗、元数据构建都是可以反复迭代的工程问题这就比什么都强了。