写这篇东西前先交代一下背景。我近期在维护一个企业级的 RAG 知识库项目里头要处理合同文本、招标文件、技术方案、会议纪要这些文档PDF 占了一大半。项目早期我们用常规的文本抽取方案先 pdfplumber / PyMuPDF 抓字符再按页切块结果召回率一直不太好看。尤其是工程合同这种结构化很强的文档章节关系、条款层级、表格字段一旦在解析阶段被压平后面无论怎么调 embedding 和 rerank 都补不回来。后来我们引入了 MinerU 4.0用它配合自研的段落级切分和定位器Locator做整套解析链路RAG 的效果才算真正有了质的提升。MinerU 是 OpenDataLab 开源的文档解析引擎专门把 PDF 这类难啃的文档转成模型友好的结构化内容——比如 Markdown、JSON、HTML能识别版面、标题层级、表格、公式、图片位置。4.0 版本最大变化是引入了四档解析和定位器两个机制前者让你在精度和开销之间做显式权衡后者让你拿到的不只是文本块而是带页面锚点、带版面坐标的文本块。这两个东西恰好就是 RAG 工程化里最缺的两块拼图。这篇文章我不会只讲装好 MinerU 然后跑一下这种入门操作而是会从工程选型的角度把四档解析到底怎么选、定位器返回的数据长什么样、怎么把它接进切分和入库的逻辑、实测里容易翻车的地方全部拆开讲。每个环节都会配代码代码是我从项目里摘出来改过的可运行版本你复制到自己环境里稍微改改路径就能用。适合已经跑通过基础 RAG 链路、现在想把文档解析这个环节做到工业化水平的朋友。1. 文档解析为什么成了 RAG 项目里绕不过的坎1.1 解析质量直接决定召回率的上限很多团队做 RAG 时80% 的精力都花在调 embedding 模型、调 rerank、写 prompt 上但其实最底层的文档解析才是那个决定上限的环节。我见过一个典型的翻车场景把一份 50 页的招标文件按页切成 50 个 chunk每页塞进向量库。看着没问题结果用户问投标人资格要求中关于联合体的条款是什么系统把第 12 页的一半和第 13 页的一半拼在一起返回答案前言不搭后语。问题出在哪儿不是检索的错是解析阶段压根没把资格要求这个条款从正文里单独结构化出来。embedding 再强也救不回一个语义边界错误的文本块。这就是为什么现在做正经 RAG 项目的人逐渐达成一个共识文档解析的目标不是把 PDF 变成文本而是把一段连续的字节流变成离散的、有层级关系的、语义边界清晰的文本块集合。传统的字符抽取只能得到后者中的一小半——变成文本而层级关系、阅读顺序、标题归属、表格行列、页码锚点这些信息恰恰是 RAG 在做切块、引用溯源、答案校验时最需要的东西。1.2 MinerU 4.0 解决的是哪一层问题MinerU 4.0 做的事情可以理解成版面感知的文档结构化解析。它不会像老式 OCR 工具那样只识别字符而是先用版面模型做区域检测标题、正文、表格、图片、页眉页脚都会被识别出来再对每个区域内做子模型处理表格用专门的表格结构模型还原成 Markdown 表格或 HTML公式用公式模型转成 LaTeX最后按阅读顺序整理成 Markdown 或 JSON。这种先版面、后内容的流水线比先全文 OCR、再拿正则去找标题的方案稳定得多尤其是处理扫描件和复杂版式时。4.0 新增的定位器Locator简单说就是在解析结果里加入每个 block 的版面坐标和页码信息。你在 JSON 输出里能看到每个文本块对应的 page_idx、bbox边界框坐标、甚至它在原 PDF 里是从哪个区域识别出来的。这个信息对 RAG 工程有两个直接价值引用溯源。用户问这个条款在合同第几页如果你之前把 chunk 和定位器坐标绑定在一起就能精确回答在第 32 页左栏中段而不是含糊地给一个文档链接。上下文锚定。切块时可以依据属于同一页、同一区域的文本块来做聚合避免一个 chunk 横跨两个版面区域导致语义割裂。这两点后面我都会给具体的实现代码。先看四档解析。2. MinerU 4.0 四档解析先看成本再看精度2.1 四档模型的能力边界和适用场景MinerU 4.0 的四档官方叫 Four-Level parsing也叫 tier1 到 tier4本质是把版面识别—OCR—表格还原—公式还原这几个能力模块按不同组合进行开关。我实际测下来每档的定位和成本大致如下档位核心能力典型场景资源开销Tier 1纯文本抽取不做版面理解数字化 PDF有文本层、排版简单、不关心结构极低CPU 可跑Tier 2版面识别 阅读顺序整理有复杂栏位、多级标题、图文混排的数字化 PDF低CPU 基本可跑推荐 GPUTier 3Tier 2 表格结构还原 公式识别合同、招标文件、论文、带大量表格的报表中建议 GPU显存 8G 以上Tier 4Tier 3 全文档 OCR支持扫描件扫描版合同、历史档案、盖章文件高GPU 必须显存最好 12G用生活化一点的话解释Tier 1 是你拿菜刀切菜快但切不出形状Tier 2 是换了一套好刀具能把菜切成片Tier 3 是又加了一套模具能把菜压成固定形状摆盘Tier 4 是连烤焦的边角料都能处理——扫描件模糊、有水印、字迹不规范它也硬啃下来。我在项目里的选型原则是这样的线上批量解析时能 Tier 2 不轻易上 Tier 3能 Tier 3 不轻易上 Tier 4。这不是抠门而是因为每一档往上单页平均耗时可能是成倍增加的。你拿 1 万页历史合同文本Tier 4 和 Tier 2 的耗时差距可能是几小时和几十小时的差距。所以正确的做法不是统一用最高档而是在入库前按文档特征打标分类再对不同类别的文档分配不同档位。2.2 档位切换的实现方式与指标对比MinerU 4.0 提供了两种调用方式一是 Python SDKmineru包二是 Docker 部署后的 HTTP API 服务。我项目里用的是 SDK 方式跑批量任务配合 Docker 方式给团队内部做按需解析工具。SDK 方式下四档切换是通过参数配置里的parse_mode字段来控制的。代码如下from mineru import MinerU # 初始化时指定模型目录和运行设备 extractor MinerU( model_dir./models/mineru_models, devicecuda, # cpu / cuda / mps gpu_id0, ) # 四档解析tier1 ~ tier4 result_t1 extractor.parse( pdf_path./data/contract_meta.pdf, # 数字化PDF parse_modetier1, ) result_t2 extractor.parse( pdf_path./data/contract_with_layout.pdf, parse_modetier2, ) result_t3 extractor.parse( pdf_path./data/contract_with_tables.pdf, parse_modetier3, ) result_t4 extractor.parse( pdf_path./data/scanned_contract.pdf, # 扫描件 parse_modetier4, )注意我上面给的MinerU类名、model_dir参数名是示意写法。MinerU 的 GitHub 仓库在不同小版本里SDK 接口有过几次调整有的版本用from magic_pdf.model.doc_analyze import CustomDocAnalyze来初始化有的版本直接提供 CLI 命令。你跑之前务必对照自己安装版本的 README 确认类名和参数名别照抄。我实测下来四档在同一份含表格的数字化合同上的表现差距核心指标大致是表格识别率Tier 1 基本为 0表格被拍平成长字符串Tier 2 能识别出表格区域但未必能还原行列Tier 3 能把表格还原成结构化 Markdown 表格准确率我实测大约在 90% 以上前提是表格没有跨页、没有合并单元格地狱。标题层级还原度Tier 2 和 Tier 3 差距不大都能把第一章 / 总则 / 1.1.1这种层级关系转成 Markdown 的多级标题。但如果原 PDF 的标题字体不统一偶尔需要二次清洗。扫描件可用性只有 Tier 4 能稳定处理扫描件。默认 OCR 引擎对中英文混排的效果都还行但对手写体和印章遮挡区域边界框会把印章算进去这部分后面避坑章节会细说。所以我的建议是如果你手里 90% 的文档都是数字化 PDF直接跑 Tier 2 先看效果表格密集的那部分再单独用 Tier 3 补一遍只有历史扫描件才值得动用 Tier 4。这样成本基本可控效果也不会差。3. 定位器Locator把文本块钉回 PDF 页码和坐标3.1 定位器输出的数据结构四档解析解决的是解析精度定位器解决的是解析结果的可定位性。我用 SDK 跑完一份文档后返回结果里除了 Markdown 全文还有一个 JSON 结构里面是逐 block 的详细信息。简化后的结构长这样{ document: { page_count: 12, pages: [ { page_idx: 3, page_width: 595, page_height: 842, blocks: [ { block_type: text, text: 投标人资格要求..., bbox: [72, 168, 523, 206], position: { page_idx: 3, rect: {x0: 72, y0: 168, x1: 523, y1: 206} }, meta: { font_size: 12.5, is_heading: true, heading_level: 2, reading_order: 7 } }, { block_type: table, markdown: | 序号 | 资质要求 | ... |, bbox: [72, 240, 523, 460], position: { page_idx: 3, rect: {x0: 72, y0: 240, x1: 523, y1: 460} } } ] } ] } }关键在于bbox和position两个字段。bbox是 (x0, y0, x1, y1)单位是 PDF 的坐标点原点通常在左上角具体看 PDF 引擎page_idx则告诉你这个 block 落在哪一页。meta.reading_order是按版面分析后的阅读顺序这个字段在切块时特别重要——它能帮你把视觉上连续的文本块按正确顺序串起来避免因为 PDF 内部内容流的错乱导致切块乱序。我项目里实际拿这些字段做的事情有三件chunk 溯源元数据。每个 chunk 在入库时把该 chunk 覆盖的首个 block 的 page_idx 和 bbox 存到一个source_marker字段里。RAG 回答生成后如果答案引用了这个 chunk就能往前端回传第 3 页第 2 段这种精确位置。阅读顺序保序切块。按reading_order排序后做天然拼接保证切出来的块不会因为跨栏位产生顺序错乱。版面约束过滤。遇到页眉页脚、目录、水印这些非正文内容可以通过区块类型block_type配合页面区域比如 bbox 的 y 坐标靠近页面顶部/底部做规则过滤清洗掉噪声文本。3.2 用定位器做引用溯源和上下文锚定定位器在 RAG 里最实用的场景就是解决答案有没有依据这个问题。过去很多项目只能让 LLM 自己判断这段话是不是来自文档结果经常一本正经地胡说。现在有了定位器你可以在检索阶段就把页码坐标一起传给上层。具体做法是向量入库时不只存文本和 embedding还存source指针指针里带文档 ID、页码、bbox。检索命中的 chunk 返回时系统能用这些坐标把原文中对应区域裁剪出来作为可视化的引用来源。这样不管是内部知识库还是客户用的合同问答系统用户都能点开引用直接跳到 PDF 对应页面而不是凭 LLM 的一句话去猜。锚定的另一个用法是做检索后重排列Rerank的辅助特征。比如多条候选 chunk 的向量相似度差不多的时候我们可以看它们的页码距离和坐标距离。如果是同一章节相邻页面的块大概率在语义上是连贯的可以适当加权。这个思路在长文档检索里效果不错因为长文档的不同章节经常出现用词非常相似的段落单靠向量很难区分结合位置信息能明显提升排序质量。4. RAG 文档解析工程化的取舍与完整代码链路4.1 归档层、解析层、入库层的分层设计很多团队做 RAG 的文档解析是一份 PDF 进来跑一个解析函数直接塞进向量库。在小规模 demo 里这么干没毛病但到了几千份、上万份文档的工程化场景这条路会越走越窄因为你没法增量更新、没法单独重跑某一份坏文档、也没法追踪解析结果和原始文档版本的对应关系。我用的是一种简单的三层设计归档层Storage Layer原始 PDF 一律存对象存储本地磁盘或 MinIO 这种 S3 兼容服务文件名统一格式{doc_id}/{version}/{doc_id}_v{version}.pdf。所有下游环节只认doc_idversion不认文件名。解析层Parse Layer消费端拿到 PDF 路径后调用 MinerU 解析产出标准化的 JSON含定位器信息 Markdown 两个文件同样按{doc_id}/{version}/目录归档。这套产出物就是解析结果的唯一事实源。以后算法迭代了只重跑解析层不碰下游入库代码。入库层Index Layer读取解析层产出的 JSON做切块、清洗、向量化写入向量数据库。入库层不关心 PDF 长什么样只认解析层的标准结构。这样分层的好处是某个环节出问题时影响面是可控的。比如某个 PDF 解析后表格乱成一团你只需要重跑那一份的解析然后从入库层把旧的 chunk 删掉、重新插入新 chunk 即可而不需要把整个知识库重建一遍。4.2 代码实战从 PDF 到带定位信息的向量数据下面这段代码是我项目里入库层的核心逻辑去掉了业务无关的部分保留了切分和定位信息绑定的关键动作。import json import uuid from pathlib import Path from mineru import MinerU # ---------- 1. 初始化解析器 ---------- extractor MinerU( model_dir./models/mineru_models, devicecuda, gpu_id0, ) # ---------- 2. 解析一份 PDF产出定位信息 ---------- def parse_pdf(doc_id: str, pdf_path: Path) - dict: result extractor.parse( pdf_pathstr(pdf_path), parse_modetier3, # 表格密集类的合同默认 tier3 enable_locatorTrue, # 开启定位器 ) # 结果是一个包含全文 blocks 的结构体 # 我们把它整理成统一格式后落地 parsed_doc { doc_id: doc_id, markdown: result[markdown], blocks: result[document][pages], # 页面级 block 列表 } # 落地到解析层产出目录供入库层消费 out_dir Path(f./parse_output/{doc_id}) out_dir.mkdir(parentsTrue, exist_okTrue) with open(out_dir / parsed.json, w, encodingutf-8) as f: json.dump(parsed_doc, f, ensure_asciiFalse, indent2) return parsed_doc # ---------- 3. 定位器信息切块 ---------- def build_chunks(parsed_doc: dict, chunk_size: int 800, overlap: int 120): chunks [] buffer [] buffer_len 0 buffer_start_page None buffer_bbox_start None # 遍历所有页的所有 block按 reading_order 排序 blocks_ordered [] for page in parsed_doc[blocks]: for block in page[blocks]: block[_page_idx] page[page_idx] blocks_ordered.append(block) blocks_ordered.sort(keylambda b: b.get(meta, {}).get(reading_order, 0)) for block in blocks_ordered: text block.get(text) or block.get(markdown) or text text.strip() if not text: continue # 跳过页眉页脚y 坐标在页面顶部/底部 8% 区域内且不是标题 page_h 842 # 标准A4高若不确定可从 page 信息里拿 bbox block.get(bbox, [0, 0, 0, 0]) y_center (bbox[1] bbox[3]) / 2 if y_center page_h * 0.08 or y_center page_h * 0.92: if not block.get(meta, {}).get(is_heading): continue if buffer_len len(text) chunk_size and len(buffer) 0: chunk { id: str(uuid.uuid4()), doc_id: parsed_doc[doc_id], text: \n.join(buffer), start_page: buffer_start_page, start_bbox: buffer_bbox_start, } chunks.append(chunk) # 简单的 overlap保留末尾一小段 buffer 继续累积 keep [] keep_len 0 for buf_text in reversed(buffer): if keep_len len(buf_text) overlap: break keep.insert(0, buf_text) keep_len len(buf_text) buffer keep buffer_len keep_len if not buffer: buffer_start_page block[_page_idx] buffer_bbox_start bbox[:2] # 记录起点 x,y buffer.append(text) buffer_len len(text) if buffer: chunks.append({ id: str(uuid.uuid4()), doc_id: parsed_doc[doc_id], text: \n.join(buffer), start_page: buffer_start_page, start_bbox: buffer_bbox_start, }) return chunks # ---------- 4. 向量化 入库 ---------- def index_chunks(chunks, embed_fn, vector_db): for chunk in chunks: vec embed_fn(chunk[text]) vector_db.upsert( idchunk[id], vectorvec, payload{ doc_id: chunk[doc_id], text: chunk[text], start_page: chunk[start_page], start_bbox: chunk[start_bbox], }, )这段代码里有几个细节值得说明一下切块没有按固定字符数硬切而是以block 为最小单位做聚合。这是 4.0 定位器带来的最大便利。传统的滑窗切块经常把一个段落劈成两半导致语义断裂。现在每个 block 是版面模型识别出来的完整语义单元——比如一个标题、一个段落、一个表格——我们按 reading_order 把 block 拼接起来等长度接近 chunk_size 再截断。效果上chunk 的语义完整性和召回率都有改善。overlap 的处理也很有意思。代码里不是简单地从断点前 N 个字符再开始而是从 buffer 末尾往回找几个完整 block 拼到新 chunk 里。这么做的好处是 overlap 部分也是完整句子而不是半个短语。页眉页脚的过滤。纯文本抽取时代页眉页脚很难区分。现在有了 bbox 和 block_type我直接用坐标做了规则过滤。实际效果还不错但要注意个别 PDF 页边距特别窄正文可能顶到 8% 的边界里需要调阈值。我的建议是把这个阈值从 0.08 改成可配置参数按不同文档类型微调。向量化那步我用的是 Qianfan 或者本地 BGE 系列模型这个不影响本文逻辑就不展开了。核心是入库前一定要把start_page和start_bbox这两个字段写进 payload否则定位器就白开了。5. 实测里容易踩的坑和参数调优记录5.1 表格和公式四档模型也分不清的边界MinerU 4.0 的表格还原在绝大多数情况下表现很好但我实测时发现三个容易翻车的边界场景合并单元格复杂的表格。当表格里有跨行跨列的合并单元格时Tier 3 的表格还原偶尔会丢失行列关系输出成错位的 Markdown 表格。我的经验是如果一份文档里大量出现合并单元格地狱型表格比如政府招标文件的资格评审表解析后一定要人工抽样检查不能直接全量入库。如果抽检发现问题比例超过 10%我会把这类文档的表格单独走一遍 OCR 专家的结构化接口再合并回 MinerU 的文本块中。跨页表格。一个表格如果从第 3 页底部延续到第 4 页顶部MinerU 有时会把它识别成两个独立表格。处理办法是在切块阶段额外做一次相邻页表格合并的规则如果第 N 页底部表格的字段头和第 N1 页顶部表格的字段头一致就把它们拼成一个逻辑表格再切块。这个规则用字符串比对就能做几分钟搞定但能救回不少表格类问答的准确性。公式识别。学术论文里行内公式和内嵌公式的 LaTeX 还原率还算不错但工程文档里那种带上下标、带复杂括号的公式偶尔会转成乱码。我的建议是在入库前跑一个LaTeX 语法完整性的简单校验遇到\begin没有对应\end的情况把该公式所在 block 降级为纯文本保存不要强行以 LaTeX 形式入库否则检索时会出现无意义的字符块。5.2 大文件、扫描件、加密 PDF 的工程处理工程化处理 PDF 时最大的敌人不是复杂度而是极端输入。几个实测要点超大 PDF几百 MB 到 1GB不要让 MinerU 一次性整本解析。几十页尚可数百页的扫描件容易把内存撑爆。我的处理方式是先用 PyMuPDF 把 PDF 按页拆成多个临时文件分页解析最后再合并产出。MinerU 本身支持某些范围解析但分页拆解更可控出错了也可以只重跑出错的那几页。扫描件多大算大Tier 4 下单页扫描件解析通常在 3~8 秒GPU 8G 显存一小时大概能跑 500~1000 页。如果只是个别扫描页混在数字化 PDF 里MinerU 的页面级检测会自动对需要 OCR 的页面开启 OCR所以不需要你手动整本走 Tier 4。加密 PDFMinerU 不会帮你解密。需要在解析前用 PyMuPDF 判断needs_pass有锁就先解锁比如用fitz.open(pdf_path, password)并存成新的无锁副本再喂给 MinerU。这块如果忘了处理解析到中间大概率直接报错或者产出的文本全是乱码。文件路径不要带中文/空格这个老生常谈但在 Docker 和 GPU 环境里确实容易成为忽略的坑。路径复杂可能导致底层推理库加载模型异常建议程序入口统一转成合法 ASCII 路径。另外提一个调参上的体会MinerU 的enable_locator默认可能是关闭的但它只是额外记录坐标信息不会显著增加解析耗时所以凡是走 RAG 入库的解析都建议强制开启。等你事后想补引用溯源功能时数据从第一天起就是齐的不需要重跑全部文档。5.3 定位器的坐标精读转换到 PDF 阅读器坐标系最后补充一个和坐标有关的务实细节。MinerU 输出的 bbox 坐标通常是 PDF 内部坐标系——原点是左下角PDF 规范的原点在左下角但不同输出引擎有的会转换到左上角。你在前端做点击坐标跳转时很可能需要一次坐标变换。我的经验是# 假设 PDF 内原始坐标原点在左下角 # 前端 PDF.js 默认坐标原点在左上角需要做 y 轴翻转 page_height_px 842 # 实际高度从 PDF 页面信息获取 y_flipped page_height_px - bbox_y1 # 原 y 方向从下往上翻转后变成从左上往下如果忽略这一步前端标注的引用框会出现在完全错误的位置用户点查看原文跳过去发现定位的是一个空白区域。这个坑我栽过一次排查了半天才发现是坐标系原点的差异所以提前在这里提醒各位。6. 我的实际使用体会和后续扩展思路MinerU 4.0 的四档解析 定位器组合在我们项目里的效果还是比较明显的。引入之前合同类文档的 RAG 问答命中率大概在 65% 左右人工评估 Top-3 命中率引入之后提升到了 85% 上下。最大的收益其实不是某一个数据点的提升而是整个链路变得可控了——解析结果有层级、有定位、有阅读顺序后续的切块和检索都有了可靠的抓手。我个人在实际操作中的体会是不要盲目追求最高档位的解析精度也不要一次性把所有文档都跑完建库。先用 Tier 2 定位器选 50 份代表性文档做一轮端到端评测看一下切块质量、召回率和典型的失败案例。发现问题后针对性地把表格多的、扫描件多的文档提到 Tier 3 或 Tier 4。这是一个迭代式的工程调优过程而不是一把梭的批处理任务。如果这篇文章的读者想把方案往前再推一步我建议你考虑两个扩展方向一是把 MinerU 的解析结果缓存层做成可版本化的数据资产。解析层产出的 JSON 其实就是一份文档的结构化镜像你可以像管理代码一样管理它用文档版本号关联解析版本号。以后切块算法或 embedding 模型升级了不需要重新解析 PDF直接在结构化镜像上重新切片、重新向量化整个成本会低很多。二是把定位器信息接入 Agentic RAG 的引用校验环节。当 LLM 的答案引用了某个 chunk 时把 chunk 的页码坐标反馈给一个基于视觉模型的校验器让它去原 PDF 对应区域截取截图与答案文本做一致性比对。这个方向上定位器提供的坐标信息会变得非常核心。Net 上也有人叫它document-grounded verification我们内部已经在尝试效果有惊喜也有坑等跑稳了再单独写一篇分享。最后代码里的MinerU类名和各参数我前面已经提醒过一次但这里再说一遍MinerU 版本迭代很快SDK 接口风格在不同小版本之间有变化。你拿到文中的代码后先对照你实际安装的版本做一次最小化冒烟测试确认类名、参数名、输出结构都对上了再往批量任务里铺开。不要拿着旧一点的代码强行套新版本那会浪费你一整个下午。