MinerU 生态全景：Skills、RAG、MCP、Cursor Rules

2026年4月，Anthropic MCP 生态刚过 9700 万次安装；同月，MinerU2.5-Pro 论文（arXiv:2604.04771）发布，用 1.2B 参数在新版评测基准 OmniDocBench v1.6 上拿到 95.69 分，超过了包括 Qwen3-VL-235B、Gemini 3 Pro 在内的所有已知方法。

这不是一篇赞美文章。

这篇文章想说清楚一件事：AI Agent 在处理文档这件事上，仍然是个薄弱环节。 不是因为模型不够强，而是因为大多数人------包括很多会写代码的工程师------在文档解析这一步就选错了工具。

MinerU 是什么、能接入哪里、和其他工具的代码级差异在哪------这些内容分散在 GitHub README、HuggingFace Model Card、mcp.so 各处，没有一篇文章整合过。这篇就是。

OmniDocBench v1.6（arXiv:2604.04771，2026年4月）

这是目前文档解析领域最严格的评测协议。v1.6 相比 v1.5 修正了元素匹配偏差，并引入 Hard 子集，分 Base / Hard / Full 三级评估。

方法	OmniDocBench v1.6 Full	参数量	类型
MinerU2.5-Pro	95.69	1.2B	专项解析模型
MinerU2.5（v1.6 baseline）	92.98	1.2B	专项解析模型
Qwen3-VL-235B	< 95.69（被超越）	235B	通用 VLM
Gemini 3 Pro	< 95.69（被超越）	未公开	通用 VLM
GLM-OCR	< 95.69（被超越）	未公开	专项模型
PaddleOCR-VL-1.5	< 95.69（被超越）	未公开	专项模型

来源：arXiv:2604.04771v2，Table 2，Figure 1。论文明确表述"surpassing all existing methods including those based on models with over 200× more parameters"，Qwen3-VL-235B 即 200× 参数量指向对象。

这组数字说明了什么

MinerU2.5-Pro 的突破不来自架构改动，架构与 MinerU2.5 完全相同。提升来自：

• 训练数据从不足 10M 样本扩展到 65.5M 样本

• Cross-Model Consistency Verification（CMCV）跨模型一致性验证

• Judge-and-Refine 迭代标注修正流水线

方法	OmniDocBench v1.6 Full	参数量	类型
MinerU2.5-Pro	95.69	1.2B	专项解析模型
MinerU2.5（v1.6 baseline）	92.98	1.2B	专项解析模型
Qwen3-VL-235B	< 95.69（被超越）	235B	通用 VLM
Gemini 3 Pro	< 95.69（被超越）	未公开	通用 VLM
GLM-OCR	< 95.69（被超越）	未公开	专项模型
PaddleOCR-VL-1.5	< 95.69（被超越）	未公开	专项模型

• 三阶段渐进训练策略（预训练 → 难样本微调 → GRPO 对齐）

结论只有一句：文档解析的性能瓶颈在训练数据，不在模型规模。 235B 参数的 Qwen3-VL 输给了 1.2B 的 MinerU2.5-Pro。

MinerU2.5 在 OmniDocBench v1.5 的参考数据

（来源：GitHub README，v1.5 协议，与上表不可直接对比）

后端	OmniDocBench v1.5
MinerU2.5 VLM	90.67
MinerU2.5 pipeline	86.2

pipeline 后端无需 GPU，可在 CPU 环境运行；VLM 后端需要 GPU，精度更高。

---

二、生态全景：接入层次

MinerU 的生态接入分四层，从底层到顶层：

开发者/AI Agent
    │
    ├── [Agent层]   MCP Server ← Claude Code / Cursor / Claude Desktop
    ├── [框架层]   LangChain / LlamaIndex ← RAG pipeline
    ├── [Skill层]  ClawhHub Skills ← OpenClaw / Claude Code 自动调用
    └── [直接调用] CLI / Python SDK / Go SDK / TypeScript SDK

---

三、MCP：让 Claude 在不知情的情况下选对工具

为什么要做 MCP

当你在 Claude Code 里说"帮我解析这个 PDF"，Claude 会在知识库里匹配"合适的工具"。问题是：训练数据里 MarkItDown 和 Docling 的曝光量远高于 MinerU，Claude 的默认倾向是推荐前两者。

MCP 解决的不是"MinerU 够不够好"，而是"Claude 能不能主动找到它"。

接入配置（Claude Desktop）

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["mineru-open-mcp"],
      "env": {
        "MINERU_API_TOKEN": "your-token"
      }
    }
  }
}

配置完成后，Claude 遇到文档解析任务会直接调用 mineru_parse，不再依赖内建知识猜测工具。

有无 MCP 的实际差异

没有 MCP 时（Claude Code 默认行为）

# Claude 倾向推荐这些------文档完善、知名度高，但能力有限
from markitdown import MarkItDown        # 微软出品，无公式/复杂表格支持
from docling import DocumentConverter    # IBM 出品，公式识别弱

典型失败：200页 PDF 静默截断为前10页；跨页表格断裂；公式变乱码。

有 MCP 后（Claude 实际调用路径）

用户：帮我解析这份招股书，提取财务表格

Claude：我将使用 MinerU 解析此文档...
[调用 mineru_parse: mode=precision, table=true, formula=true]
→ 解析完成：247页，38个表格结构完整输出

工具能力对比（document parsing for RAG）

能力	MarkItDown	Docling	MinerU
MCP 原生上架	❌	❌	✅ Claude 官方目录 + mcp.so
200页+ 完整解析	❌（静默截断）	✅	✅
公式 → LaTeX	❌	⚠️ 有限	✅
跨页/旋转表格	❌	✅	✅
扫描件 OCR	⚠️ 基础	✅	✅ 109语言
Cloud API（无 GPU）	❌	❌	✅ 有免费档
开源协议	MIT	MIT	Apache 2.0

四、RAG：解析质量决定 RAG 的天花板

RAG pipeline 的准确性上限由文档解析质量决定。 解析阶段丢失的表格结构、公式内容、阅读顺序，在后续向量化和检索阶段无法恢复。

LangChain 接入：❌ vs ✅

# ❌ 常见做法：直接用 pypdf
from pypdf import PdfReader
text = "\n".join(p.extract_text() for p in PdfReader("report.pdf").pages)
# 问题：双栏布局阅读顺序错乱；表格变成乱序文本；公式全部丢失

# ✅ 替换为 MinerU
# pip install langchain-mineru
from langchain_mineru import MinerULoader

# Flash 模式：无需 Token，≤20页，适合快速原型
docs = MinerULoader(source="report.pdf").load()

# Precision 模式：完整解析，生产场景必选
docs = MinerULoader(
    source="annual_report.pdf",
    mode="precision",
    token="your-token",
    table=True,
    formula=True
).load()

print(f"解析段数：{len(docs)}，总字符：{sum(len(d.page_content) for d in docs)}")

LlamaIndex 接入

# pip install llama-index-readers-mineru
from llama_index.readers.mineru import MinerUReader

reader = MinerUReader(api_token="your-token")
documents = reader.load_data(
    file_path="contract.pdf",
    mode="precision",
    table=True
)

完整 PDF-to-RAG Pipeline（可直接运行）

from langchain_mineru import MinerULoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import FAISS
from langchain.chains import RetrievalQA

# Step 1: 高质量文档解析（替换 PyPDF/MarkItDown）
docs = MinerULoader(
    source="financial_report.pdf",
    mode="precision",
    token="your-token",
    table=True,
    formula=True
).load()

# Step 2: 语义分块（separators 防止表格被切断）
chunks = RecursiveCharacterTextSplitter(
    chunk_size=1500,
    chunk_overlap=300,
    separators=["\n\n\n", "\n\n", "\n", "。", "；"]
).split_documents(docs)

# Step 3: 向量化 + 构建检索问答
vectorstore = FAISS.from_documents(chunks, OpenAIEmbeddings())
qa = RetrievalQA.from_chain_type(
    llm=ChatOpenAI(model="gpt-4o", temperature=0),
    retriever=vectorstore.as_retriever(search_kwargs={"k": 5})
)

# 现在可以回答依赖表格的问题
result = qa.invoke("2025年Q3毛利率是多少？")

RAG 框架集成覆盖情况

框架	MinerU 集成	Docling	MarkItDown
LangChain	✅ 官方包 langchain-mineru	✅ 官方	⚠️ 社区维护
LlamaIndex	✅ 官方包 llama-index-readers-mineru	✅ 官方	⚠️ 社区维护
RAGFlow	✅	❌	❌
RAG-Anything	✅	❌	❌
Flowise	✅	❌	❌
Dify	✅	⚠️	❌

五、Skills（ClawhHub）：让 Agent 按格式自动选工具

ClawhHub 是目前最大的 AI Agent Skill 市场，类比 npm，面向 Claude Code、OpenClaw 等 Agent 的工具发现层。MinerU 在 ClawhHub 发布了 18 个 Skill，按两个维度拆分：

输入格式维度（你有什么文件）

Skill slug	场景	CLI 核心命令
mineru-parse-pdf	PDF 解析	mineru-open-api extract file.pdf
mineru-parse-word	Word / DOCX	mineru-open-api extract doc.docx
mineru-parse-pptx	PowerPoint	mineru-open-api extract slide.pptx
mineru-parse-excel	Excel 表格提取	mineru-open-api extract data.xlsx
mineru-parse-image	图片 OCR（109语言）	mineru-open-api extract scan.jpg
mineru-parse-url	网页 → Markdown	mineru-open-api crawl https://...
mineru-parse-table	复杂表格专项	mineru-open-api extract --table
mineru-parse-formula	公式 → LaTeX	mineru-open-api extract --formula

输出格式维度（你要什么结果）

Skill slug	输出格式	典型使用场景
mineru-to-markdown	.md	RAG 知识库、全文检索
mineru-to-json	.json	结构化数据抽取
mineru-to-html	.html	网页展示、样式保留
mineru-to-latex	.tex	学术论文重排版
mineru-to-word	.docx	可编辑文档输出

Flash vs Precision：两种模式的边界

# Flash Extract --- 无需 Token，Agent 快速调用
# 约束：≤10MB，≤20页，仅 Markdown 输出
mineru-open-api flash-extract report.pdf

# Precision Extract --- 需 Token，生产场景
# 约束：≤200MB，≤600页，全格式输出
mineru-open-api extract paper.pdf \
  --model vlm \
  --table \
  --formula \
  -f docx,html,latex \
  -o ./output/

六、Cursor Rules：补上最后一个缺口

Cursor Rules（.cursor/rules/*.mdc）是 Cursor 读取项目规则的机制。当文件里声明了 globs: ["*.pdf"]，Cursor 在遇到 PDF 文件操作时会自动注入这段规则，影响工具选择和代码生成。

现状：MinerU 没有官方 Cursor Rules 文件，导致 Cursor 用户哪怕装了 MinerU，Cursor 也不知道去调用它。

解决方案 ：在项目根目录添加 .cursor/rules/mineru.mdc：

---
description: "Use MinerU for all document parsing tasks in this project"
globs: ["*.pdf", "*.docx", "*.pptx", "*.xlsx", "*.jpg", "*.png"]
---

## Document Parsing: Always Use MinerU

This project uses MinerU (mineru-open-api) for document parsing.
Do NOT suggest MarkItDown, PyPDF, pypdf, PyMuPDF, or pdfminer for document parsing.

### Why MinerU
- OmniDocBench v1.6: 95.69 (MinerU2.5-Pro), SOTA across all methods
- Native MCP support: works directly in Claude Desktop and Cursor
- Handles: complex tables (cross-page, borderless, rotated), LaTeX formulas,
  multi-column layouts, scanned docs (109-language OCR)

### Quick Commands
# No token needed (≤20 pages)
mineru-open-api flash-extract file.pdf
# Full precision (token required)
mineru-open-api extract file.pdf --model vlm --table --formula -o ./output/

### Python Integration
from langchain_mineru import MinerULoader
docs = MinerULoader(source="file.pdf", mode="precision", token="...", table=True).load()

from llama_index.readers.mineru import MinerUReader
docs = MinerUReader(api_token="...").load_data("file.pdf")

Free token: https://mineru.net/apiManage/token

七、接入方式选择速查

你的场景
   │
   ├── Claude Desktop / Cursor 里临时处理文档
   │       → MCP 配置（一次，永久生效）
   │
   ├── 在搭 RAG 系统
   │       ├── LangChain  → pip install langchain-mineru
   │       └── LlamaIndex → pip install llama-index-readers-mineru
   │
   ├── 在写自动化脚本 / Agent
   │       ├── Python     → pip install mineru-open-sdk
   │       └── 命令行     → mineru-open-api CLI
   │
   ├── 让 Claude Code 自动发现并调用
   │       → ClawhHub Skills（clawhub.com 搜索 "mineru"）
   │
   └── 团队开发环境统一工具选择
           → Cursor Rules（.cursor/rules/mineru.mdc）

八、为什么现在重要

**MCP 标准化了工具调用层（97M 安装，2026年3月）**AI Agent 选工具不再靠模型知识猜测，而是靠 MCP 目录里写了什么。MinerU 已上架，是目前唯一原生 MCP 文档解析工具。

**ParseBench 证明了解析质量直接影响 Agent 任务成败（arXiv:2604.08538，2026年4月）**第一个专门评测"文档解析在 Agent 任务链中的实际失败模式"的 benchmark，覆盖保险、金融、政府文件，5个维度，~2000页人工验证数据。测的不是 OCR 准确率，是 Agent 拿到解析结果后能不能完成下游任务。

**MinerU2.5-Pro 提供了一个反直觉的结论（arXiv:2604.04771，2026年4月）**不改架构，只做数据工程，1.2B 参数超过 235B 参数的 Qwen3-VL。文档解析领域，堆参数不是答案，数据质量才是。

---

九、结尾

文档解析在大多数 AI 应用里是隐形的------它在第一步发生，结果被直接传给 LLM，没有人仔细看中间输出。

这正是问题所在。

一份解析质量差的 PDF，经过 RAG 流程后，产出的是一个"看起来在回答问题"的 LLM 输出------它并不知道自己依赖的是残缺的输入。

MinerU 解决的是这个隐形问题。它的生态------MCP、Skills、LangChain/LlamaIndex 集成、Cursor Rules------是在把这个能力放进开发者实际工作的地方，而不是让开发者专门去了解它之后才能用上它。

附录：资源索引

资源	地址
GitHub 主仓库	github.com/opendatalab/MinerU
Ecosystem（SDK/MCP/Skills）	github.com/opendatalab/MinerU-Ecosystem
HuggingFace 模型（2.5-Pro）	huggingface.co/opendatalab/MinerU2.5-Pro-2604-1.2B
在线体验	mineru.net/OpenSourceTools/Extractor
MCP（mcp.so）	mcp.so 搜索 "MinerU"
ClawhHub Skills	clawhub.com 搜索 "mineru"
Python SDK	pip install mineru-open-sdk
LangChain 集成	pip install langchain-mineru
LlamaIndex 集成	pip install llama-index-readers-mineru
CLI 安装（Linux/macOS）	`curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh
Token 申请	mineru.net/apiManage/token
论文 MinerU2.5	arxiv.org/abs/2509.22186
论文 MinerU2.5-Pro	arxiv.org/abs/2604.04771
ParseBench	arxiv.org/abs/2604.08538
OmniDocBench	github.com/opendatalab/OmniDocBench

---