当文档解析同时进入 CLI、Open API、Python SDK、TypeScript SDK、Go SDK、MCP Server、LangChain 和 LlamaIndex，真正危险的不是“有没有解析能力”，而是不同入口输出口径不一致。今天值得关注的是：MCP 与 Agent 工作流正在把工具调用、结构化结果、缓存和权限变成工程常态，MinerU 这类文档解析层也需要从“单次解析工具”升级为“多入口一致的上下文生产系统”。

热点背景

过去一年，RAG 和 Agent 工程的关注点正在从“模型能不能读文件”转向“系统能不能稳定生产可追溯上下文”。MCP 把工具、资源、结构化返回、用户确认和 Host 权限边界放到更明确的位置；LangChain、LlamaIndex 等框架也持续把 loader、parser、retriever 和 evaluation 串到生产链路里。

这对 PDF 解析、OCR、表格提取、公式识别和版面分析提出了一个更细的问题：同一份文档，如果今天用 CLI 解析，明天用 Open API 批处理，后天让 Agent 通过 MCP Server 调用，再进入 LangChain 或 LlamaIndex，输出结构、参数、错误码、文件资产、页码和验收状态是否还能对齐？

对企业知识库和 Sciverse 这类科研数据基础设施来说，这不是工程洁癖。科研论文、实验报告、表格、公式、图表和补充材料一旦进入 AI-ready 数据层，就会被 Agent 多次检索、引用、重组和复核。如果入口之间缺少契约，后续 RAG 的召回、引用、复现和审计都会变得不可控。

核心观点

Agent 时代，文档解析不应该只交付“某一次调用的结果”，而应该交付一份跨入口一致的解析契约。

这份契约至少包含三层含义。

第一，输入契约一致。文件来源、URL、页码范围、OCR 开关、语言、公式识别、表格提取、输出格式、回调、隐私边界和版本都要被记录。无论从 CLI、Python SDK、Open API、MCP Server 还是 RAG 框架调用，都应能解释“这次解析到底用了什么参数”。

第二，输出契约一致。Markdown、结构化 JSON、表格、公式、图片/图表资产、PDF to Word、HTML、LaTeX、元素提取结果和页面定位信息，不应只是散落在不同目录里的文件，而应能被统一索引、验收和回放。

第三，验收契约一致。RAG 入库不能只看“解析成功”。每个样本都应记录 OCR、版面、表格、公式、元素、metadata、错误码、人工抽样结论和版本漂移结果。Agent 可以调用解析工具，但不能绕过验收状态直接把内容写进知识库。

技术展开

MinerU 的价值在于，它不是只把 PDF 当成纯文本文件处理，而是面向复杂文档结构提供一组可组合能力：OCR、版面分析、表格提取、公式识别、Markdown 输出、结构化 JSON、多格式导出、元素提取、批量处理，以及围绕 CLI、Open API、Python SDK、TypeScript SDK、Go SDK、MCP Server、LangChain、LlamaIndex 的生态入口。

在多入口解析契约里，可以把 MinerU 放在“文档上下文生产层”。

CLI 适合本地预检、开发调试、失败样本复现和私有文档初步解析。它的优势是可脚本化、便于把样本集和参数固化到仓库。

Open API 适合服务端批处理、异步任务、回调、队列和跨团队系统集成。它需要额外关注额度、文件大小、页数上限、超时、重试和数据边界。

Python SDK 适合把解析任务接入数据管线、评测脚本、批量回放和内部平台。TypeScript SDK 与 Go SDK 则更适合前端工作台、Node 服务、Go 后端和平台工程场景。

MCP Server 适合把 MinerU 暴露给 Agent，让 Agent 在权限受控的情况下调用解析、读取输出、查看资源或触发复核。但 MCP 接入不应被理解成“让 Agent 任意读文件”，而应被设计成有 allowlist、用户确认、日志、输出目录和验收状态的工具层。

LangChain 与 LlamaIndex 适合把 MinerU 的解析结果进入 RAG、检索、索引和问答链路。这里的关键不是 loader 一行代码能不能跑通，而是 Markdown、JSON、表格、公式、图片资产和 metadata 是否能以稳定结构进入 chunk、embedding、retriever 和引用系统。

能力边界也要说清楚。本文不声称 MinerU 在所有样本上优于 Docling、Unstructured、LlamaParse、传统 OCR、云文档智能服务或通用大模型直读文档。真正应该上线的是一套可复现实验：用自己的 PDF、Office、扫描件、科研论文、表格和公式样本跑同一批维度，再决定哪个入口、哪种参数、哪类文档进入生产。

对比分析

下面的表格不是跑分结论，而是多入口解析契约下的评测维度。读者应替换自己的样本运行。

方案	典型入口	适合场景	多入口契约待测项	观察方式
MinerU	CLI、Open API、Python SDK、TypeScript SDK、Go SDK、MCP Server、LangChain、LlamaIndex	PDF 解析、OCR、表格、公式、版面、多格式输出、Agent/RAG 入库	不同入口参数是否可对齐；Markdown/JSON/资产是否一致；错误与重试是否可记录	固定样本从不同入口解析，比对输出结构、页码、元素、表格、公式和 metadata
传统 OCR	OCR API、桌面软件、脚本	扫描件文字提取、票据或图片文字识别	是否保留版面、表格、公式、图片和阅读顺序	检查 OCR 文本与原页位置、表格结构和公式可用性
通用大模型直接读文档	Chat、文件上传、视觉模型 API	快速理解、摘要、问答、低频人工分析	是否能稳定导出结构化 JSON、表格、公式、页码证据和可回放参数	要求输出证据定位和结构化结果，记录不可复现或格式漂移案例
云厂商文档智能服务	托管 API、控制台、SDK	企业文档智能、票据、表单、合规流程	API 限制、区域合规、数据保留、字段 schema、成本和重试	核对 live docs、合同、账号后台和真实错误返回
开源 PDF 工具	命令行、Python 包	文本抽取、PDF 拆分、基础表格处理	对扫描件、复杂版面、公式、跨页表格和图片资产支持程度	用复杂科研论文、财报和扫描件做失败样本记录
RAG 框架自带 loader	LangChain、LlamaIndex loader	快速入库、原型验证	是否把文档结构压扁成纯文本；metadata 是否足够	对比 chunk 中的标题层级、页码、表格和公式保真度
Docling	CLI、Python、服务化集成	文档转换、结构化解析、RAG 前处理	输出 schema、表格、OCR、图片、批处理与下游集成	固定样本记录 Markdown/JSON/表格/图片输出差异
Unstructured	API、开源库、连接器	多格式文档分区、企业数据管线	element 类型、partition 策略、metadata、云/本地边界	检查 element 粒度、表格、标题层级、失败重试
LlamaParse	云解析 API、LlamaIndex 集成	LlamaIndex 生态、RAG 入库、结构化解析	解析模式、配额、输出格式、与索引链路一致性	记录解析参数、输出格式、RAG 引用与成本边界

一个务实的结论是：文档解析工具不应只比较“谁能读出来”。在 Agent 和 Sciverse 场景里，更应该比较谁能把 OCR、版面、表格、公式、图片、JSON、Markdown、API 任务和人审记录统一成可复现的工程资产。

可复现实验方案

建议至少准备 40-80 份文档，按真实业务比例抽样，不要只选干净论文。

样本类型	建议数量	重点覆盖
科研论文 PDF	10-20	双栏、公式、引用、图表、跨页表格、补充材料
企业报告 / 财报	8-15	长表格、脚注、目录、页眉页脚、图表说明
扫描件 / 图片	6-12	OCR、倾斜、噪声、多语言、印章、低分辨率
DOCX / PPTX / XLSX	6-12	Office 原生结构、表格、标题、幻灯片、工作簿
历史失败样本	10-20	曾经解析错字、漏表、错公式、乱序或超时的页面

样本应覆盖 PDF、扫描 PDF、图片、DOCX、PPTX、XLSX、长文档、表格密集文档、公式密集文档、图表密集文档、多语言文档和科研材料。涉及 Sciverse 或科研 Agent 时，建议加入论文、实验数据说明、方法章节、图表页、公式页和补充材料。

维度	验收问题	人工验收标准
精准 OCR	扫描页、低清图片、多语言是否识别正确	关键术语、数字、单位、上下标不影响业务理解
版面还原	阅读顺序、标题层级、双栏、脚注是否稳定	Markdown 与原文逻辑顺序一致，页眉页脚不干扰正文
表格提取	表头、行列、合并单元格、跨页表是否保留	表格能被程序读取，关键数值、单位和表头可核对
公式识别	行内公式、块级公式、编号、上下标是否可用	LaTeX 或结构化公式可人工复核，公式上下文不丢失
元素提取	图片、图表、表格、公式是否作为元素保存	元素类型、页码、位置、文件路径和引用关系可追溯
结构化 JSON	schema、metadata、页码、错误状态是否稳定	可被脚本差异比对，可进入验收表或 manifest
Markdown 输出	是否适合人工阅读和 RAG chunk	标题、段落、列表、表格、公式不被过度压扁
MCP/Agent 接入	Agent 是否按权限调用工具并返回结构化结果	工具输入可见、输出可审计、失败可重试
RAG 入库	chunk、metadata、引用、召回是否可解释	回答能回到页码、元素或原文证据

每个失败案例都要记录入口、版本、参数、样本哈希、页码、元素类型、期望结果、观察结果、严重程度、是否阻塞上线、复核人和处理结论。不要只写“解析不好”。

case_id	文档	入口	页码	元素	待测项	期望	观察结果	状态	处理
C001	paper-01.pdf	CLI	3	公式	上下标与编号	公式可转 LaTeX，编号保留	待读者运行	todo	替换样本后填写
C002	report-02.pdf	Open API	12	表格	合并单元格	表头、单位、行列正确	待读者运行	todo	人工抽样
C003	scan-03.pdf	Python SDK	1	OCR	低清扫描	关键字段不漏识别	待读者运行	todo	记录原页截图
C004	deck-04.pptx	MCP Server	5	图表	Agent 工具调用	输出带资源路径和验收状态	待读者运行	todo	检查日志
C005	workbook-05.xlsx	LangChain / LlamaIndex	2	metadata	入库一致性	chunk 保留来源和页/表信息	待读者运行	todo	检查 retriever

把上表中的 paper-01.pdf、report-02.pdf、scan-03.pdf、deck-04.pptx 和 workbook-05.xlsx 替换成自己的文件。每次只改变一个变量：解析入口、解析参数、版本或样本集。否则出了差异，很难判断是工具变化、参数变化还是样本变化。

代码示例

以下示例用于说明多入口解析契约的记录方式，具体参数、URL、鉴权、输出字段、限制和错误码请以上线当天的官方文档、账户后台和实际返回为准。

mineru -p ./samples/paper-01.pdf \
  -o ./runs/cli/paper-01 \
  -m auto

建议同时保存一份 parse-run.json：

{
  "case_id": "C001",
  "entry": "cli",
  "source": "./samples/paper-01.pdf",
  "output_dir": "./runs/cli/paper-01",
  "mode": "auto",
  "checks": ["ocr", "layout", "table", "formula", "markdown", "json"],
  "review_status": "needs_review"
}

curl --request POST "https://mineru.net/api/v4/extract/task" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${MINERU_API_TOKEN}" \
  --data '{
    "url": "https://example.com/sample.pdf",
    "is_ocr": true,
    "enable_formula": true,
    "enable_table": true
  }'

生产系统里不要只保存最终 Markdown。建议保存 task_id、文件 URL、文件哈希、页码范围、参数、输出格式、状态、错误码、重试次数和人工验收结论。

from pathlib import Path
import json
from datetime import datetime, timezone

run = {
    "case_id": "C003",
    "entry": "python-sdk",
    "source": "./samples/scan-03.pdf",
    "output_dir": "./runs/python/scan-03",
    "options": {
        "ocr": True,
        "table": True,
        "formula": True
    },
    "review_status": "needs_review",
    "created_at": datetime.now(timezone.utc).isoformat()
}

Path(run["output_dir"]).mkdir(parents=True, exist_ok=True)
Path(run["output_dir"], "parse-contract.json").write_text(
    json.dumps(run, ensure_ascii=False, indent=2),
    encoding="utf-8"
)

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["mineru-open-mcp"],
      "env": {
        "MINERU_API_TOKEN": "your_key_here",
        "OUTPUT_DIR": "./runs/mcp"
      }
    }
  }
}

建议把 MCP 工具分成两类：parse_document 触发解析，需要权限控制或人工确认；read_reviewed_output 只读取已经通过验收的 Markdown、JSON、表格、公式和图片资产。这样 Agent 可以使用 MinerU，但不能把未验收内容直接写进知识库。

metadata = {
    "parser": "MinerU",
    "entry": "llamaindex-reader",
    "source_file": "paper-01.pdf",
    "review_status": "accepted",
    "checks": ["ocr", "layout", "table", "formula"],
}

复现步骤

1. 准备样本：选择 PDF、扫描件、图片、DOCX、PPTX、XLSX、科研论文、企业报告、历史失败样本和高风险业务文档。
2. 选择方案：至少选择 MinerU 与一个对照方案，例如 Docling、Unstructured、LlamaParse、传统 OCR、云文档智能服务或 RAG loader。
3. 固定入口：先用 CLI 跑小样本，再用 Open API、Python SDK、MCP Server、LangChain 或 LlamaIndex 跑同一批样本。
4. 执行解析：记录版本、参数、文件哈希、页码范围、输出目录、任务 ID、错误码和重试次数。
5. 查看输出：同时检查 Markdown、JSON、表格、公式、图片/图表资产、PDF to Word、HTML、LaTeX 和 metadata。
6. 人工抽样：重点看扫描页、双栏页、表格页、公式页、图表页、跨页结构、多语言页和关键字段页。
7. 记录问题：按 OCR、版面、表格、公式、元素、metadata、权限、API、SDK、MCP、RAG 入库分类。
8. 决定是否上线：只有 accepted 内容进入默认知识库；needs_review 进入人审队列；rejected 进入失败样本集。
9. 回放复测：升级 MinerU、SDK、MCP Server、LangChain、LlamaIndex、解析参数或 chunk 策略后，用同一批样本重跑并比较差异。

可复现实验声明

本文未包含官方实测跑分，评测部分为可复现实验方案和示例记录表，读者需替换自己的样本运行。

来源链接

• https://mineru.net/llms.txt
• https://mineru.net/apiManage/docs
• https://mineru.net/apiManage/limit
• https://github.com/opendatalab/MinerU
• https://github.com/opendatalab/MinerU/releases/tag/mineru-3.4.4-released
• https://github.com/opendatalab/MinerU-Ecosystem
• https://github.com/opendatalab/MinerU-Ecosystem/tree/main/cli
• https://github.com/opendatalab/MinerU-Ecosystem/tree/main/sdk/python
• https://github.com/opendatalab/MinerU-Ecosystem/tree/main/sdk/go
• https://github.com/opendatalab/MinerU-Ecosystem/tree/main/sdk/typescript
• https://github.com/opendatalab/MinerU-Ecosystem/tree/main/mcp
• https://github.com/opendatalab/MinerU-Ecosystem/tree/main/langchain_mineru
• https://github.com/opendatalab/MinerU-Ecosystem/tree/main/llama-index-readers-mineru
• https://modelcontextprotocol.io/specification/2026-07-28
• https://modelcontextprotocol.io/specification/2026-07-28/server/tools
• https://modelcontextprotocol.io/specification/2026-07-28/server/resources
• https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation
• https://openai.github.io/openai-agents-python/mcp/
• https://python.langchain.com/docs/concepts/document_loaders/
• https://docs.llamaindex.ai/en/stable/module_guides/loading/
• https://docling-project.github.io/docling/
• https://github.com/docling-project/docling
• https://docs.unstructured.io/
• https://github.com/Unstructured-IO/unstructured
• https://developers.llamaindex.ai/llamaparse/
• https://sciverse.opendatalab.com/
• https://huggingface.co/datasets/opendatalab/Sci-Base