创建日期：2026-09-28 ｜ 最近更新：2026-09-28

本文的实测在本机跑（python 3.13.9 / pdfplumber 0.11.10 / pypdf 6.19.0 / pymupdf 1.28.2 / MinerU 4.0.8，RTX 3090），样本是两篇公开论文 PDF，脚本与真实输出在 source/rag-pdf-lab/。 涉及 MinerU 官方行为的地方，均为逐字原文，抓取日期 2026-09-28，留档在同目录 official-mineru-*.html/.txt，另有全站检索索引 official-mineru-search_index.json（2663 块）用于核对「官方有没有说过 X」；第三方说法的逐条核查另见 verify-integrations.md。 文中凡属我的推断/分析，都会显式标注——尤其「为什么会这样」的机制解释。第三类陈述（第三方文章的说法）单独放在第 5 节核对。

PDF 解析：RAG 链路最前面那道闸门

一句话：PDF 不是「内容格式」，是「打印格式」。 它只记录字画在纸上的坐标，不记录段落、标题、表格结构。从「纸」到「文本流」这一步的损失，发生在切片之前、向量化之前——它不在检索链路的任何一环里，却决定了后面所有环节的上限。

入门篇把链路拆成五个环节，后面六篇拆的都是链路里面的事：第 1 篇拆重排，第 2 篇拆切片，第 3 篇拆相似度这把尺子，第 4 篇量边界，第 5 篇拆坏案例，第 6 篇看架构怎么长起来。这一篇往前退一步，讲那条链路的入口——文档是怎么变成文本的。

第 2 篇已经量过一类 PDF 污染：抽出来的文本里混着 457 个控制符和 261 个康熙部首字符，导致关键词 0 命中、embedding 拿到 [UNK]。那是字符级的污染。

这一篇讲另一类，版面级的丢失。它更隐蔽：抽出来的字全对，一个乱码都没有，但顺序错了、结构没了。而且——先说结论——它甚至不需要你换解析器，改一个默认参数就能救回一大半。

0. 先说一个改一个参数就能救的坑

这组论文 PDF 的字体里根本没有「空格」这个字形。词与词之间的空格是靠位置（两个字之间的横向间隙）表达的。抽取器得靠一个阈值去猜「这里够不够宽、算不算一个空格」。

pdfplumber 的这个默认值是 3——源码里写着 (pdfplumber/utils/text.py:27)：

DEFAULT_X_TOLERANCE = 3
DEFAULT_Y_TOLERANCE = 3

在这类 PDF 上，这个 3 猜不出空格，整段文字粘成一个长 token：

默认 extract_text()：
Recurrentneuralnetworks,longshort-termmemory[13]andgatedrecurrent[7]neuralnetworks
inparticular,havebeenfirmlyestablishedasstateoftheartapproachesinsequencemodelingand

x_tolerance=1：
Recurrent neural networks, long short-term memory [13] and gated recurrent [7] neural networks
in particular, have been firmly established as state of the art approaches in sequence modeling and

后果不是「质量差一点」，是检索通道直接断掉：文档里根本没有 state of the art 这个词组，BM25 搜不到、短语匹配搜不到、精确关键词召回全灭。

实测（8 条多词短语，取自页面正文，先核对过确实存在于原版面；source/rag-pdf-lab/bench_phrase_recall.py）：

抽取方式	Attention 论文 2–6 页	ACL 论文 4–8 页
pdfplumber 默认（x_tolerance=3）	2/8 命中	0/8 命中
pdfplumber x_tolerance=1	8/8	8/8
pypdf 默认	8/8	8/8
MinerU markdown（flash 档）	8/8	8/8

请把归因收窄：这不是「PDF 都这样」，也不是「pdfplumber 不行」——pypdf 用默认参数就 8/8。这是 pdfplumber 默认阈值这一处的问题，换 x_tolerance=1 即恢复（文本量同时从 13523 → 15354 字符，多出来的 1831 个字符就是被丢掉的空格）。

这一条值得放在第 0 位，因为它最便宜：在换解析器、上 OCR、调 embedding 之前，先确认你抽出来的文本里词与词之间到底有没有空格。 一个 grep 就能看出来。

1. 双栏打平：字都在，顺序错了

学术论文、财报、说明书大量使用双栏排版。正确读法是「左栏读完再读右栏」，但抽取器拿到的是一页纸上的坐标，它按 y 坐标从上往下扫，于是左右两栏在同一水平位置的行会被当成「同一行」处理。

在 ACL 那篇论文的第 4 页，pdfplumber 的输出里出现了这样一行——左栏表格的表头和右栏正文被拼成了同一行：

Dataset Train Val Test ing the opposite judgment to the sentence’s own

而这句话原本是个完整的句子：左栏底部写着 the sentence misses an example suggest-，右栏顶部接着 ing the opposite judgment to the sentence's own (18%)。一句话被撕成两半，中间隔了整整一页的文字。

把这一页按 chunk_size=800 切分，整篇文档的第 0 个 chunk（bench_chunk_straddle.py，原样打印）：

Dataset Train Val Test 
▼▼▼ 跨栏接缝 ▼▼▼
ing the opposite judgment to the sentence’s own
(18%) and the sentence has exceptions (17%).
#posts 25,839 8,763 8,558
Attacked #sentences 420,545 133,090 134,375 This analysis is based on polished rebuttals,
#attacked 119,254 40,163 40,354
which mostly emphasize logical aspects, and can-
#posts 3,785 1,235 1,064 not fully capture other factors that motivate attacks.
Successful #sentences 66,628 20,240 17,129

表格的一行和正文的一句，在同一个 chunk 里交替出现。 这个 chunk 送进 embedding 之后，它的向量是「表格数字」和「论证文字」的平均——两边都不像。而它还是全文第一个 chunk。

同一个位置的 MinerU 输出（flash 档，实测）：

Counterexample-related rationales are also common: the sentence misses an example suggest-
ing the opposite judgment to the sentence’s own (18%) and the sentence has exceptions (17%).

suggest- 和 ing 被正确地接了回去。

1.1 怎么量它：拿「分栏裁剪」当标准答案

正确顺序不需要人工标注——双栏页面的正确顺序就是版面的定义。所以：把同一页沿中缝裁成两半分别抽取、左栏接右栏，得到的就是 ground truth。

指标用相邻词对保真率：

保真率 = |朴素顺序的相邻词对 ∩ 正确顺序的相邻词对| / |朴素顺序的相邻词对|

它回答的是：「朴素文本里一对挨着的词，有多大比例在原文里真的挨着」。用词对而不是行对，是因为两种抽法的行切分方式本来就不同，按行比对会把「切行差异」误算成「顺序差异」。

1.2 ⚠️ 第一版指标是错的，说一下怎么发现的

这一节请务必看——因为我差点把一个纯噪声当成结论写出来。

第一版我给每行按「x 中心在中线左边还是右边」打 L/R 标签，然后数「栏切换次数」。在 Attention 那篇论文上跑出来：栏切换 177 次（正确顺序应为 9 次），相邻对保持率 57.5%。看起来是个很有冲击力的结论。

然后我把页面渲染成图看了一眼。 那一页是单栏的：所有正文行都横跨整个版心（x 从 108 到 504），中线 306 正好落在行中间——每一行的 x 中心都在 306 附近抖动，x1 从 504.0 变成 504.2 就足以让标签从 L 翻成 R。那 177 次「栏切换」全是浮点数噪声。

所以现在的脚本加了两道闸：

1. 先检测中缝：把页面的 x 方向切成 200 格统计占用，只有中线附近出现「占用低于正文中位数 35%」的空白带，才认定为双栏——判不出来就跳过，不硬算。单栏页（Attention 那篇的第 2–6 页）全部被判为单栏跳过，这才对。
2. 中缝未必在正中：实测到的中缝在 x=296–308 之间浮动，而页面中线是 297.6。按中线裁会切进右栏。

这条教训通用：凡是「按版面几何切分」的指标，先渲染看一眼。几何启发式在非预期版面上不会报错，只会安静地输出垃圾。

1.3 结果

ACL 论文（2020.emnlp-main.1，23 页里的 12 个双栏正文页，bench_reading_order.py）：

页	相邻词对保真率	页	相邻词对保真率
2	87.2%（635/728）	8	87.8%（669/762）
3	88.8%（741/834）	10	86.5%（603/697）
4	87.6%（601/686）	11	86.4%（559/647）
5	85.8%（654/762）	12	88.0%（601/683）
6	99.7%（764/766）	13	86.1%（390/453）
7	87.7%（611/697）	14	100.0%（20/20）

合计：88.5%（6848/7735）——朴素抽取里的「相邻词对」，有 11.5% 在原文中并不相邻。

（第 9 页判为单栏跳过；第 14 页只有 21 个词，是参考文献尾页，样本太小。）

怎么读这个 11.5%（以下是我的分析，不是文档结论）：

• 它不是均匀噪声。 88.5% 的词对是对的——这符合预期，因为 pdfplumber 的行分组本来就跟着 y 走，正文流大多没问题。但从 1.2 的逐页输出能看到，每一页「第一处伪相邻」都落在结构交界上：表格表头接正文、参考文献条目接正文、图注接正文。损伤集中在恰好最需要精确的地方，而不是随机撒在全文里。
• 逐页方差很大（85.8%–99.7%）。第 6 页几乎无损，可能是因为那页结构简单。别把单页数字当结论，12 页的合计才有意义。
• 样本量要说清楚：12 个双栏页、1 篇论文。换论文、换排版（三栏、图文混排、横排表格）结论未必一样。

2. 公式和表格：字符在，结构没了

顺序问题之外，还有结构问题。

Attention 论文第 4 页的公式 (1)，原版面是 Attention(Q, K, V) = softmax(QKᵀ/√d_k)V——分式、上标、下标、根号。

pdfplumber 抽出来是这样（x_tolerance=1，已经是最佳参数了）：

QKT
Attention(Q, K, V ) = softmax( √ )V (1)
d
k

字符一个不少，二维结构全没了：QKᵀ 的上标塌成 QKT，根号 √d_k 的分式和下标被拆到三行上（√、d、k 各占一行）。任何按行阅读的下游（切片的、embedding 的）看到的都是断的。

表格更直观。同一份 ACL 论文第 4 页的表 1，pdfplumber 抽出：

Dataset Train Val Test ing the opposite judgment to the sentence’s own
(18%) and the sentence has exceptions (17%).
#posts 25,839 8,763 8,558
Attacked #sentences 420,545 133,090 134,375 This analysis is based on polished rebuttals,

MinerU（flash 档，实测同一页）：

| Dataset | Train | Val | Test |
| --- | --- | --- | --- |
| #posts | 25,839 | 8,763 | 8,558 |
| Attacked #sentences | 420,545 | 133,090 | 134,375 |
| #attacked | 119,254 | 40,163 | 40,354 |

行、列、表头关系都还在。 这不是「更干净一点」，这是「表格数据还能不能算」的区别——Attacked 那一行的 #sentences 是 420,545，这个对应关系在 pdfplumber 的输出里已经不存在了。

推断（我的分析）：表格结构丢失对 RAG 的杀伤和文字不一样。文字丢了顺序还能靠语义模糊匹配救，表格丢了行列关系，问「Val 列最大的是哪个」这类问题就永远答不对——因为答案根本不在文本里，需要重新计算。

3. 实测 MinerU 4.0：它拿回了什么，又没拿回什么

网上讲 MinerU 的文章不少，但真正跑一遍、把输出贴出来的不多。这一节全是我本机的真实输出。

环境（2026-09-28）：两条路都走了——本地 CLI（pip install mineru → 4.0.8，python 3.13.9，只用得到 flash 档）与本机部署的 HTTP API（4.0.5，/v1/...，四档都能跑）。§3.2 ① 的公式对照出自 HTTP API。

3.1 拿回来的

• 阅读顺序：双栏页左栏→右栏正确串接，跨栏断词 suggest- + ing 正确接回（§1 已给对照）。
• 表格：重建为 Markdown 表格（§2 已给对照）。
• 标题层级：## 4 Quantifying Sentence Characteristics、## 4.2.1 Content 都识别出来了。
• 上下标：d<sub>k</sub>、脚注 <sup>5</sup> 保留。
• 公式：standard 档还原成可编译的 LaTeX，行内公式也一起还原（§3.2 ①）——但 flash 档拿不到，这是本节最要记住的一条。

3.2 没拿回来的（这几条比拿回来的更重要）

① 公式：flash 档只给一个空的块，LaTeX 要 standard 档才有。

同一页（Attention 第 4 页）、同一个公式，两档的差别是空的和完整的：

档位	那个公式块拿到的 content
flash	"" —— 空的。Markdown 里只有一行 ，告诉你「这里有个公式块」，但不告诉你公式是什么
standard	\text {Attention} (Q, K, V) = \text {softmax} (\frac {Q K ^ {T}}{\sqrt {d _ {k}}}) V\tag{1}

standard 档输出的 Markdown 里是这样（注意行内公式 $d_{k}$ 也一起还原了）：

In practice, we compute the attention function on a set of queries simultaneously, packed
together into a matrix $Q .$ ... We compute the matrix of outputs as:

$$
\text {Attention} (Q, K, V) = \text {softmax} (\frac {Q K ^ {T}}{\sqrt {d _ {k}}}) V\tag{1}
$$

所以「MinerU 保留公式 LaTeX」这个说法是对的——但只对 basic 及以上成立，flash 档拿不到。 转述这类结论时，「哪个档位」是不能省的那半句。

实测耗时（同 1 页）：flash 2.1 s，standard 14.4 s（后者含 VLM 推理）。档位是拿时间换质量，不是免费的。

② 开箱即用的只有 flash 一档。

我试着跑 --tier standard，官方 CLI 直接拒绝：

错误: Local parse-server is disabled. Use --tier flash or --remote.

查配置（mineru config show）：

parse_server.local.mode           disabled     ← 默认值
parse_server.local.managed_tier   standard

把它改成 managed 再试，报的是依赖缺失：

错误: Parse server cannot start for tier 'standard'; missing runtime dependencies:
torch, torchvision, transformers, accelerate, safetensors.
Install the dependencies for the selected backend in the same Python environment:
mineru[torch] for Torch; mineru[full] for vLLM/LMDeploy; ...; mineru for ONNX/llama.cpp.

即：pip install mineru 装的是 ONNX/llama.cpp 后端，只支持 flash；basic / standard / advanced 需要额外装 mineru[torch]（torch 那一套，GB 级），或者走 --remote 用官方在线服务。 官方文档对四档的定位（逐字，usage/tiers/）：

Tier	Purpose	Local execution
flash	Fast previews, indexing, native documents	Native PDF text / document parsing; Flash OCR for scans and images
basic	OCR, formulas, and tables	ONNX or Torch small models; no local VLM required
standard	Complex layouts and high-quality parsing	Small models + VLM
advanced	More demanding quality requirements	Standard models and runtime, with more inference computation

注意 basic 那一行的 Purpose 明写 "OCR, formulas, and tables"——公式要 basic 档及以上才有，flash 档拿不到。这与我的实测一致。

这一条我一开始留了空白：当时本机 mineru[torch] 卡在慢速下载，我只验证了 flash，就如实写了「standard 档没验证，不猜」。后来改用本机已部署的 MinerU HTTP API（4.0.5，http://127.0.0.1:8001）补跑，才拿到 §3.2 ① 那张对照表。 留白然后补上，比当时猜一个「按文档描述应该有」要好。

③ MinerU 也不是万能的。 同一页的表 2（一个 2a/2b 两段式表格）没有被识别成表格，而是拍平成了段落：

R1 S is true but does not support the main claim (19%) R2 S misses cases suggesting opposite judgment (18%) R3 S has exceptions (17%)

同一页的表 1 识别对了，表 2 没对。这一条我特意留着——只贴成功的例子，就是在给工具做广告。

④ 4.0 的 CLI 要先起本地服务。 直接 mineru parse 会报 本地 mineru 服务未运行。请先运行 'mineru server start'。这是 4.0 相对 2.x 的形态变化：从「一条命令跑完」变成「文档库 + 后台服务」。批处理脚本要注意先起服务。

3.3 走 HTTP API 时，两个会直接影响 RAG 的细节

上面走的是本地 CLI。本机另有一套 MinerU HTTP API（4.0.5，/v1/...），补跑时踩到两点，都和 RAG 存储直接相关：

① 单独要 markdown 格式，图片会以 base64 内联进正文——实测占 96.9%。

同一页（Attention 第 4 页，含 1 张图）：

取法	大小
output_formats: ["markdown"]	93,726 字符，其中 90,840 字符是 1 张 base64 图 → 占 96.9%
output_formats: ["zip"]（取里面的 markdown.md）	2,888 字符，图片单独放在 images/

差了 32.5 倍。 正文只有 2888 字符，剩下 9 万字符全是那张图的 base64。如果直接把这份 markdown 塞进切片器，一个 chunk 里绝大部分是图片数据的乱码——这和 §1 的「表格正文缝合怪」是同一类病，只是病因换成了编码。

要 markdown 就用 zip，图片单独落盘；只要正文结构就用 middle_json。

② middle_json 的每个块带归一化 bbox，这是做引用定位的本钱。

{ "type": "equation", "index": 6,
  "bbox": [0.356, 0.585, 0.825, 0.62],
  "content": "\\text {Attention} (Q, K, V) = ..." }

bbox 是 [x0, y0, x1, y1] 的归一化坐标，配合块类型（text / table / equation / paragraph_title / page_footnote / page_number / image …），可以在切片时做两件纯文本做不到的事：

• 按类型过滤：page_number、header、footer、aside_text 这类块直接丢掉——否则每页重复的页眉页码都会变成一个无意义的 chunk；
• 带上出处：把 {page, bbox} 存进向量库 payload，回答时能精确指到原文位置，而不是只说「在某份 PDF 里」。

这也是 §2 那个问题的另一面：表格结构在纯文本里没了，而在 middle_json 里，表格是一个 table 类型的块、有自己的 bbox——结构信息一直都在，取决于你取的是哪一路输出。

4. 一条容易踩的归因线：把「工具默认值」说成「PDF 难」

把第 0 节的数字再摆一次：同一个 PDF，pypdf 默认 8/8，pdfplumber 默认 0/8。

如果只看 pdfplumber 的结果，很容易写成「PDF 抽取质量太差，必须上重型解析器」。但换成另一个库、同一个 PDF、同样不做任何调参，问题就没了。

所以面对「抽取质量差」，正确的排查顺序（我的归纳）：

1. 先看默认参数（本例：x_tolerance）。一行代码，零成本，先排除掉。
2. 再看是不是版面问题（双栏、表格、公式）——这一类换参数救不了，需要版面分析能力。
3. 最后才考虑上模型（OCR / VLM 解析）。

反过来，如果一个第三方教程一上来就让你换重型方案，却没提默认参数这一层，那它可能在替工具做营销，而不是在解决问题。

5. 核实：一份流传较广的 MinerU 教程，哪些说法站不住

写作时参考了一篇阿里云开发者社区的文章（developer.aliyun.com/article/1731846，抓取日期 2026-09-28，原文留档在 source/rag-pdf-lab/thirdparty-aliyun-1731846.txt）。按本仓库的引用规范逐条核对后，有几处需要更正。列出来不是为了挑刺，是因为这些说法正在被大量转载。

5.1 API 对不上：mode="flash" / mode="precision" 在官方 4.0 里不存在

原文给的接口是：

loader = MinerULoader(source="demo.pdf", mode="flash", language="en")
# 以及 mode="precision", token="your-token"

官方 4.0 的 SDK 签名是 tier= + ocr_mode=：

parse("document.pdf", tier="flash", ocr_mode="txt", page_range="1-3")

• 档位只有 flash / basic / standard / advanced（本机 mineru parse --help 实测一致）；
• 没有 precision 这个档位名——在官方全站检索索引（2663 块）里 precision 只作为形容词 "high-precision" 出现 2 次，没有一处是模式名；
• 没有 mode= 参数，也没有 token= 参数（认证走 parse_server.remote.api_key 配置或 MINERU_API_KEY 环境变量）。

5.2 「超过 50 页 OOM」与官方说法方向相反

原文：「MinerU 在处理超过 50 页的 PDF 时……在一份 120 页的财报 PDF 上，实测峰值内存占用达到 4.2 GB」。

官方 changelog（3.0.0，逐字）说的是反的：

Optimized the parsing pipeline with a sliding-window mechanism, significantly reducing peak memory usage in long-document scenarios, so documents with tens of thousands of pages no longer need to be split manually.

官方没有给出任何「页数上限」，也没有任何「内存-页数」基准数字；唯一的硬件基线是（逐字，usage/tiers/）：

Plan for at least 16 GB of system memory for higher-throughput local deployment. ... 8 GB is only a planning starting point, not a guarantee for every workload.

顺带一提：官方默认只解析前 10 页（mineru parse --pages 的默认值是「前 10 页」），这是请求范围的默认，不是内存限制——很容易被误读成「上限 10 页/50 页」。

所以「4.2 GB」这个数字无法核对，官方没有任何出处。我没有复现它，也不否认作者可能真的测到过——但没有出处、也没有可复现脚本的数字，不该作为结论引用。

5.3 「120 DPI 扫描件识别率仅 67%」——官方全站没有 DPI 这件事

官方文档里 DPI 检索为 0 命中，没有任何 OCR 输入分辨率的指引。所以这个数字同样查无出处。

5.4 OmniDocBench 的分数：数字接近，但归属搞错了

原文：「MinerU 2.5 Pro 在 OmniDocBench v1.6 上取得了 95.69 的总体分数（基线 92.98，提升 2.71 分），公式识别 CDM 97.29，表格识别 TEDS 93.42」。

我拉了官方榜单（opendatalab/OmniDocBench README，commit 9b46e6d，2026-09-11）核对的 v1.6_full 表：

方法	Overall↑	FormulaCDM↑	TableTEDS↑
PaddleOCR-VL-1.6（0.9B）	96.34	97.53	94.76
MinerU2.5-Pro（1.2B）	95.75	97.45	93.42
MinerU-2.5（1.2B）	93.04	95.77	87.88
MinerU-Pipeline	86.47	83.07	81.88

三处更正：

1. 数字对不齐：95.69 vs 榜单的 95.75，97.29 vs 97.45（只有 TEDS 93.42 完全一致）。差得不多，更像是引用了榜单的早期版本——榜单是活的，会随模型重评而变。引用榜单必须记 commit，否则数字对不上是必然的。
2. 「行业领先」不成立：同一张表里 PaddleOCR-VL-1.6 的 Overall（96.34）、CDM（97.53）、TEDS（94.76）三项都高于 MinerU2.5-Pro。原文说「在公式识别和表格识别两个维度上均处于行业领先位置」，与当前榜单不符。
3. ⚠️ 最重要的一处：95.75 和 86.47 是两个不同的东西。 MinerU2.5-Pro 是那个 1.2B 的 VLM 模型；MinerU-Pipeline 是流水线，榜单上是 86.47。而 pip install mineru 装出来的默认后端（ONNX/llama.cpp）走的是 flash，离 95.75 那个数字隔着一整个 VLM。把 95.75 当成「装个 mineru 就有的效果」，是这类文章最常见的误导。

按官方自己的口径，Pipeline 后端在 OmniDocBench v1.5 上的分数是 86.2（changelog 3.0.0），与榜单上 Pipeline 的 86.47（v1.6）量级一致。两个数字是不同 benchmark 版本，不能混着引用。

5.5 「两个官方集成」——包是真的，但「官方」要加限定语

原文说 LangChain 的 MinerULoader 和 LlamaIndex 的 MinerUReader 是「两个官方集成」。我一开始以为这是编的，核完发现包确实存在——但「官方」这两个字需要加限定语。

包与类都是真的（PyPI JSON API，逐字）：

包	版本	发布	类
langchain-mineru	0.1.0 → 0.1.3	2026-03-20	MinerULoader（源码 __init__.py 逐字导出）
llama-index-readers-mineru	0.1.1	2026-03-27	MinerUReader（参数表 mode/token/ocr/formula/table 与原文一致）

原文写的 langchain-mineru==0.1.0 这个版本号是真的（确实存在，2026-03-20 发布）。

顺带一个细节：langchain-mineru 的 PyPI 元数据里 author / maintainer / home_page / project_urls / license 全部为空，classifiers 是空数组。单看 PyPI，无法区分它是官方包还是第三方包装器——它的「官方」属性完全靠那个生态仓库承载。仓库内 pyproject.toml 还写着 version = "0.1.2"，而 PyPI 上根本没有 0.1.2（只有 0.1.0 / 0.1.1 / 0.1.3）。引用版本号一律以 PyPI 为准，别信仓库工作区。

但「官方」有三层限定：

1. 它们不在核心 MinerU 项目里，而在另一个仓库 opendatalab/MinerU-Ecosystem（2026-03-18 建仓）。核心仓库 opendatalab/MinerU 的 README 检索 MCP/LangChain 均 0 命中。
2. MinerU 自己给这两个的标签不一样：生态仓库 README 逐字表格里，LangChain 是 ✅ Official，LlamaIndex 是 ✅ Community。原文把两者并列称「两个官方集成」，与 MinerU 自己的口径不符。
3. LangChain 侧不认：LangChain 官方文档的 document loaders 清单页（884 KB）里 mineru 命中 0 次（同页 unstructured 命中 3 次，说明该页确实是 provider 清单）。所以「LangChain 官方集成」从 LangChain 一侧无法证实，能证实的只是「MinerU 官方生态仓库托管并自称官方」。

最能说明问题的是核心项目的路线图（官方文档检索索引逐字，next/roadmap/#p2）：

P2 聚焦生态适配：

• LangChain document loader。
• LlamaIndex reader。

在核心 MinerU 项目的路线图里，这两个适配还挂在 P2「尚未完成」的计划上。 同一页还逐字写明核心「不内建」这些能力：

MinerU 坚守"文档入口"定位。以下能力不内建到核心项目：

不做	交给
文档 chunking 策略	LangChain / LlamaIndex 等生态层
embedding 与向量化	向量库和下游应用

顺带一提：MinerU 官方文档给出的集成清单是另外 11 项——Cherry Studio、Sider、Dify、n8n、Coze、FastGPT、ModelWhale、DingTalk、DataFlow、BISHENG、RagFlow。没有 LangChain，没有 LlamaIndex。 而且这批插件页带一句官方限定语：（保留原集成说明，不代表已支持 4.0 V1 API）。

5.6 MCP Server：有，但不在核心项目里

原文结语说 MinerU 的 MCP Server「可以让 Claude Desktop 等 AI 客户端直接调用」。

我第一轮核对时判它「不存在」，那是错的——我只查了核心 CLI（mineru --help 子命令表里确实没有 mcp）和核心 README（mcp 0 命中），就下了结论。补查之后：

• MCP Server 确实有：mineru-open-mcp（PyPI 1.0.22，作者邮箱 OpenDataLab@pjlab.org.cn），且已登记官方 MCP registry（io.github.opendatalab/mineru-open-mcp，stdio 传输）。
• 但它同样在 MinerU-Ecosystem 仓库里，不在核心项目里。 核心路线图把 MCP 列为 P1 待补齐，逐字：

Agent 使用 MinerU 有两条通道：CLI + Skill（Agent 直接操作本地文件系统时的推荐通道，默认使用）；MCP Server（需要标准工具发现、跨平台协议或远程 Agent 调用时使用，P1 补齐）

所以准确的表述是：MCP Server 存在且是官方的，但它是生态仓库的独立产物，核心项目仍把 MCP 当待办。原文说「可以让 Claude Desktop 直接调用」方向没错，但没说清它不在核心包里、也不是核心 CLI 的一部分。

这一条我特意把「我第一轮核错了」写出来。 教训很具体：「核心仓库里没有」不等于「不存在」——一个项目的官方能力可能散在主仓库、生态仓库、独立 registry 三处。查「有没有 X」时只查主仓库，会把「在别处」误判成「没有」。

5.7 CLI 名 mineru-open-cli：不存在，真名是 mineru-open-api

原文说「CLI 工具 mineru-open-cli，适合在 CI/CD 流水线中做批量文档预处理」。

五个渠道一致查无此名：PyPI JSON 404、PyPI simple 404、npm registry 404、官方文档检索索引（2663 块）open-cli 0 命中。

真实的名字有两个体系：

• 核心项目：mineru（面向交互/Agent 的文档库 CLI）与 mineru-kit（无状态批处理、V1 API Server、模型管理）。官方文档逐字：MinerU exposes two primary command trees.
• Open API CLI：mineru-open-api（npm 0.5.9，仓库目录 MinerU-Ecosystem/cli/mineru-open-api）。

这个错名大概是怎么来的（我的推断）：官方安装脚本里，下载产物的文件名是 mineru-open-api-cli-<os>-<arch>，OSS 桶路径段是 open-api-cli，但最终安装的可执行文件名是 mineru-open-api。把桶路径 open-api-cli 和命令名 mineru-open-api 缝一缝，就得到了 mineru-open-cli。

5.8 那条「评测脚本」链接是个占位符

原文给的复现入口是 https://gist.github.com/example/mineru-rag-bench——example 是 GitHub 的示例占位用户名，这个 gist 不存在。

这是最值得警惕的一条：一篇给了具体百分比（25.0% / 50.0% / 62.5%）、声称「可复现」的文章，复现入口是假的。那些数字背后有没有真实实验，读者无从验证。

不是所有数字都要怀疑，但「给了复现入口」就该点一下。 点不开的，按「无出处」处理。

6. 那这一环该怎么摆

我的归纳（不是任何官方文档的结论），按成本从低到高：

顺序	动作	成本	能解决
1	抽完先看文本：词间有空格吗？有乱码吗？	一次 grep	§0 那类「默认值坑」
2	调抽取器参数（x_tolerance 等）	改一个数	同上，且不引入新依赖
3	判定文档类型：是不是双栏？有没有表格/公式？	抽查几页	决定要不要上版面分析
4	上版面分析（MinerU 等）	装依赖 + 跑模型	阅读顺序、表格结构
5	需要公式 LaTeX / 复杂版面	mineru[torch] 或 --remote	flash 档拿不到的那部分

关键判断：如果 1、2 步就能把命中率从 0/8 拉到 8/8，那你根本不需要 4。 先花十分钟做前两步，再决定要不要花一下午装模型。

另外，切片策略要跟着解析输出走——这一点 第 2 篇 已经铺过：解析成 Markdown 就按 Markdown 结构切（标题、表格、公式都是天然的语义边界），解析成元素级 JSON 就按元素类型和坐标切。用纯文本的切法去切结构化输出，等于把刚拿回来的结构又扔了。

7. 引用边界

• 逐字引用的官方原文：MinerU 四档定义、内存与硬件基线、changelog 的 sliding-window 表述、CLI 报错文本、OmniDocBench v1.6_full 榜单（commit 9b46e6d）。URL、抓取方式、原始文件都在 source/rag-pdf-lab/。
• 本机实测：短语命中表、相邻词对保真率、pdfplumber/pypdf/MinerU 的输出对照、MinerU 4.0.8 的档位行为与 CLI 行为。脚本 bench_phrase_recall.py / bench_reading_order.py / bench_chunk_straddle.py，真实输出 run.log。
• 我的推断（文中已标注）：11.5% 的损伤「集中在结构交界」、表格结构丢失对 RAG 的杀伤机制、§4 的排查顺序、§6 的成本表。这些是分析，不是文档结论。
• 先留白、后补上的：§3.2 ① 的「standard 档公式出不出 LaTeX」原本写的是「没验证，不猜」（当时 mineru[torch] 卡在下载），后来改用本机已部署的 MinerU HTTP API（4.0.5）补跑，拿到了 flash 空块 / standard 完整 LaTeX 的直接对照。补跑的脚本是 mineru_api.py，输出在 api-out/。
• 仍未核实的：basic、advanced 两档没有单独跑（只跑了 flash 与 standard）；4.0.5（HTTP 服务）与 4.0.8（pip）是不同版本，上面的档位对照出自 4.0.5，不保证 4.0.8 逐位一致。
• 样本限制：阅读顺序结论来自 1 篇论文的 12 个双栏页；短语命中来自 2 篇论文各 5 页。样本小，看趋势别看小数点。样本 PDF 是公开论文（arXiv 1706.03762、ACL 2020.emnlp-main.1），脚本可复跑。
• 第三方文章：developer.aliyun.com/article/1731846 的说法按事实核对处理，原文留档，逐条对照见 §5。核对不等于否定整篇——它的「PDF 解析是 RAG 前置瓶颈」这个判断方向是对的，本文也是从那里出发的。
• 「核心项目 vs 生态仓库」的区分（§5.5–5.7）：证据在 source/rag-pdf-lab/verify-integrations.md，逐条附 URL 与取数方式（PyPI JSON、GitHub API、npm registry、官方 MCP registry、LangChain 文档清单、官方文档检索索引）。这份核查里也记了我第一轮核错的地方（把「核心仓库里没有」当成了「不存在」）。
• 一个诚实的提醒：§5 核的是那一篇文章。同类教程里相同的说法（mode="precision"、50 页 OOM、95.69 分、MCP 与 CLI 名）大概率来自同一批二手转述——看到一处，就该顺手核其余几处。