MCP 2026-07-28 规范把工具调用、授权、进度、取消和错误处理进一步推到 Agent 工程前台。对文档解析来说，这意味着 PDF、Office、扫描件和科研资料不能再被当成“随手一读”的输入，而要先经过额度、权限、样本、版本和人工验收。MinerU 的 CLI、Open API、Python SDK、Go SDK、TypeScript SDK、MCP Server、LangChain 与 LlamaIndex 入口，适合搭建这层解析预算门禁。
热点背景
最近 Agent 工程的一个明显变化是：工具调用正在从“能连上”走向“能治理”。MCP 官方 2026-07-28 规范将 tools、resources、prompts、elicitation、progress、cancellation、error reporting、安全与用户同意放在协议核心；OpenAI Agents SDK 的 MCP 文档也强调 tool filtering、工具列表缓存、失败重连和 tracing。换到文档解析场景，问题不再只是“这个 PDF 能不能转 Markdown”，而是：Agent 是否有权解析这份文件或 URL？解析会消耗多少 API 额度、页数预算和任务时间？解析结果是否包含表格、公式、图片、页码、结构化 JSON 和 Markdown？失败、重试、版本漂移和人工复核是否会被记录？
MinerU 官方llms.txt将 MinerU 定义为面向 LLM、RAG 和 Agent 工作流的智能文档解析平台，支持 PDF、Word、PPT、图片、HTML 等输入，输出 Markdown、JSON、LaTeX、HTML 等结构化数据，并覆盖 CLI、Open API、Python SDK、Go SDK、TypeScript SDK、MCP Server、LangChain、LlamaIndex 等生态入口。公开检索未找到可核验的llms-full、llms-full.txt或llms-full.md资料，本文不引用不存在的完整资料。
这与 Sciverse 类科研数据基础设施也自然相关。科研 Agent 需要的不只是“读一篇论文”，而是把论文 PDF、实验报告、专利、图表、公式和表格变成可检索、可引用、可复核、可调用的 AI-ready 数据。解析预算门禁的价值，就是在数据进入知识库前把风险挡住。
核心观点
1. Agent 时代，解析请求本身就是生产动作
当 Agent 可以通过 MCP Server 或 SDK 调用文档解析时，一次解析可能意味着文件上传、URL 抓取、API 额度消耗、临时文件生成、日志记录和知识库写入。它不再是离线脚本，而是生产系统中的工具调用。解析预算门禁要先判断“能不能解析、用哪个入口解析、解析到什么粒度、解析后能否入库”。
2. RAG 效果的上限，取决于入库前的结构预算
很多 RAG 失败不是检索模型的问题，而是入库前把表格、公式、图注、页码、标题层级和阅读顺序弄丢了。预算门禁不是只限制费用，也限制“结构最低标准”：没有页码、没有元素类型、表格无法验收、公式无法复核、Markdown 和 JSON 不一致时，不应直接进入默认知识库。
3. MCP 让文档解析变成工具，也让审批变成必要能力
MCP 的方向让 tools 和 resources 更容易被 Agent 调用。文档解析很适合做成 MCP 工具，但工具越自然，越要有 allowlist、页码范围、输出目录、token 权限、人工确认和失败回放。MinerU MCP Server 暴露parse_documents等工具，适合放进这层门禁，而不是绕过门禁。
4. Sciverse 类科研数据层需要稳定的解析账本
科研数据处理链路强调证据、引用、原文片段和资源可追溯。PDF 解析如果只交付一段纯文本，后续科研 Agent 很难判断某个结论来自哪页、哪张表、哪个公式、哪个版本。解析预算门禁要记录文档哈希、入口、页码、解析参数、版本、输出资产、验收人和失败原因。
技术展开
MinerU 在这个主题下的价值，不是把所有解析请求都“自动放行”，而是提供足够多的工程入口和结构化产物，让团队能按风险分层处理。
第一层是入口分层。CLI 适合本地预检、失败样本回放和批处理脚本；Open API 适合服务端异步任务；Python SDK 适合数据管线；Go SDK 和 TypeScript SDK 适合业务系统集成；LangChain 和 LlamaIndex 适合 RAG 入库；MCP Server 适合 Agent 工具调用。预算门禁要让这些入口共享同一套样本、参数、额度核对和验收表。
第二层是结构分层。精准 OCR 处理扫描件和图片文字；版面分析保留阅读顺序、标题层级和页眉页脚边界；表格提取保留行列结构；公式识别输出 LaTeX 或 MathML；元素提取把段落、表格、公式、图片和图表作为资产；结构化 JSON 适合程序验收，Markdown 适合人工阅读和 RAG 入库。
第三层是预算分层。公开资料、低风险网页和小样本可以走快速预览；长文档、科研 PDF、合同、财务、医疗、专利和内部资料要优先考虑精确解析、本地部署、私有化部署或人工审批。MinerU 官方资料中，Flash/Quick Parse 和 Precision Extract 的认证、页数、文件大小、输出格式存在不同口径；上线前必须以 live docs、API 页面、账户后台和实际返回为准。
第四层是失败分层。解析失败不应该只留下“failed”。至少要记录quota_exceeded、rate_limit、timeout、permission_denied、file_too_large、page_limit、ocr_low_confidence、table_structure_error、formula_latex_error、layout_order_error、version_drift等类型。这样下次升级 MinerU、SDK、MCP Server、LangChain、LlamaIndex 或切块策略时，才能复现问题。
能力边界也要说清楚：通用大模型直接读文档在小文件、临时问答上很方便，但不天然交付可审计元素账本；传统 OCR 能提取文字，但难以覆盖公式、表格、复杂版面和多格式输出；RAG 框架 loader 适合快速接入，但生产入库仍需要页级、元素级和失败级验收；云厂商文档智能服务适合已有云栈，但数据边界、费用、区域和格式能力要单独评估。
对比分析
以下不是实测结论，而是上线前建议使用的评测维度和观察方式。
| 方案 | 适合场景 | 应重点观察 | 预算门禁检查项 |
|---|---|---|---|
| 传统 OCR | 扫描件文字提取、低结构要求归档 | 多语言、低清、倾斜、表格内文字 | 是否保留页码、表格结构、公式和阅读顺序 |
| 通用大模型直接读文档 | 小样本问答、一次性阅读 | 上下文长度、引用稳定性、成本、幻觉 | 是否能输出可复核 JSON、元素定位和失败原因 |
| 云厂商文档智能服务 | 已有云栈、票据/合同/表单 | 数据区域、价格、额度、格式支持 | 是否满足隐私、合规、页数和文件大小限制 |
| 开源 PDF 工具 | 文本 PDF、轻量抽取 | 图片型 PDF、复杂版面、表格、公式 | 是否需要额外 OCR/版面/表格模型 |
| RAG 框架 loader | 快速 Demo、轻量知识库 | metadata、chunk 边界、页码、错误处理 | 是否能阻止未验收 chunk 入库 |
| Docling | 多格式转换、结构化文档管线 | PDF/Office/图片转换、表格、布局、导出 | 是否满足私有化、资产目录和评测回放需求 |
| Unstructured | 元素化解析、企业数据预处理 | partition、元素类型、表格/OCR策略 | 是否能统一样本、版本和错误台账 |
| LlamaParse | LlamaIndex 生态、托管解析 | Markdown/JSON、解析模式、费用和隐私 | 是否符合数据边界、额度和区域要求 |
| MinerU | PDF/Office/图片到 Markdown/JSON，多入口 RAG/Agent | OCR、版面、表格、公式、元素资产、MCP/SDK | 是否记录入口、参数、版本、额度、人工验收和失败回放 |
可复现实验方案
样本集设计
建议准备一批真实样本，按风险和结构复杂度分层：
| 样本组 | 文档类型 | 建议关注点 |
|---|---|---|
| A | 科研论文 PDF | 摘要、章节、公式、图表、引用、补充材料 |
| B | 扫描 PDF / 图片 | OCR、多语言、倾斜、低清、页眉页脚 |
| C | 企业报告 / 合同 | 多栏、页码、表格、脚注、敏感字段 |
| D | DOCX / PPTX / XLSX | 原生 Office 结构、表格、图表、幻灯片层级 |
| E | 专利 / 标准 / 技术手册 | 长文档、编号、跨页表、公式、图片 |
| F | Sciverse 相关科研资料 | 论文全文证据、表格资源、图注、段落定位 |
评测维度
| 维度 | 观察方式 | 人工验收标准 |
|---|---|---|
| OCR 准确性 | 抽样核对关键段落、编号、单位 | 不影响检索、引用和关键字段判断 |
| 版面还原 | 对照原文阅读顺序、标题层级、多栏顺序 | Markdown 阅读顺序与人类阅读基本一致 |
| 表格提取 | 检查表头、合并单元格、跨页表、单位 | 表格可被程序读取，关键行列不错位 |
| 公式识别 | 对照原文公式、上下标、符号、编号 | LaTeX/MathML 可读，关键公式需人工复核 |
| 元素提取 | 检查段落、表格、公式、图片、图注 | 每类元素有类型、页码和来源定位 |
| JSON/Markdown 一致性 | 比较同一元素在两种输出中的内容 | 不出现关键内容丢失或顺序错乱 |
| API 预算 | 记录文件大小、页数、任务耗时、错误码 | 超限、限流、失败重试必须可解释 |
| Agent 工具安全 | 检查 MCP allowlist、审批、输出目录 | Agent 不能任意解析任意路径或 URL |
失败案例记录方式
失败样本不要只截图到群里，建议写入固定表：
| doc_id | file_hash | 页码 | 入口 | 参数 | 失败类型 | 观察结果 | 期望结果 | 严重级别 | 处理结论 |
|---|---|---|---|---|---|---|---|---|---|
| paper_001 | sha256:… | 7 | CLI | model=vlm,pages=1-10 | formula_latex_error | 公式下标疑似错误 | 对照原文公式 3 | P1 | 人工复核后再入库 |
| report_014 | sha256:… | 12 | Open API | extraFormats=docx,json | table_structure_error | 跨页表头丢失 | 表头应延续到下一页 | P1 | 阻断入库 |
| scan_009 | sha256:… | 1 | MCP Server | parse_documents | ocr_low_confidence | 设备编号 0/O 混淆 | 编号需完全一致 | P2 | 进入复核队列 |
| slides_003 | sha256:… | 5 | LlamaIndex | split_pages=True | layout_order_error | 图注与图错配 | 图注应跟随图片 | P2 | 调整切块策略 |
| patent_006 | sha256:… | 40 | Python SDK | pages=1-50 | version_drift | 新旧输出顺序不同 | 升级后差异可解释 | P1 | 加入回归集 |
读者应替换为自己的样本运行。不要把本文表格里的示例当作实测结果。
代码示例
CLI：先做小样本预算预检
# Flash/Quick Parse 适合低风险预览；生产限制以 live docs 为准mineru-open-api flash-extract ./samples/paper.pdf>./runs/paper.flash.md# Precision Extract 适合需要表格、公式、资源包和多格式输出的样本mineru-open-api auth mineru-open-api extract ./samples/paper.pdf\--pages1-20\-fdocx,latex,html\-o./runs/paper_precision/建议同时记录命令、时间、文件哈希、页码范围、输出目录、MinerU CLI/SDK 版本和人工验收状态。
Python SDK：把解析结果写入预算台账
fromdatetimeimportdatetime,timezonefromhashlibimportsha256frompathlibimportPathfrommineruimportMinerU source=Path("./samples/paper.pdf")file_hash=sha256(source.read_bytes()).hexdigest()client=MinerU("YOUR_MINERU_API_TOKEN")result=client.extract(str(source),model="vlm",pages="1-20",extra_formats=["docx","html","latex"],)record={"doc_id":"paper_001","file_hash":file_hash,"entrypoint":"python_sdk","model":"vlm","pages":"1-20","markdown_chars":len(result.markdownor""),"image_count":len(getattr(result,"images",[])or[]),"status":"needs_human_review","checked_at":datetime.now(timezone.utc).isoformat(),}print(record)字段名请按当前 SDK 实际返回调整。生产代码应显式处理限流、超时、额度不足、文件超限和重试幂等。
MCP Server：只暴露可审批的解析工具
{"mcpServers":{"mineru":{"command":"uvx","args":["mineru-open-mcp"],"env":{"MINERU_API_TOKEN":"YOUR_MINERU_API_TOKEN","OUTPUT_DIR":"/project/mineru-reviewed-output"}}}}在 Agent 客户端侧，建议只允许parse_documents和get_ocr_languages，并要求用户确认本地文件、远程 URL、页码范围和输出目录。涉及内部文档、未公开科研数据、合同、医疗、财务或客户资料时，不要让 Agent 自动外发。
LangChain / LlamaIndex：把验收状态作为 metadata
fromlangchain_mineruimportMinerULoader loader=MinerULoader(source="./samples/paper.pdf",mode="precision",token="YOUR_MINERU_API_TOKEN",split_pages=True,pages="1-20",)docs=loader.load()fordocindocs:doc.metadata["parser"]="mineru"doc.metadata["review_status"]="needs_human_review"doc.metadata["ingest_allowed"]=False只有当抽样验收通过后，才把ingest_allowed改为True并进入默认知识库。
复现步骤
- 准备样本：收集 PDF、扫描件、图片、DOCX、PPTX、XLSX、科研论文、专利和技术报告，记录来源授权。
- 选择方案：至少比较 MinerU 的一个入口和 2-3 个替代方案，例如传统 OCR、RAG loader、Docling、Unstructured 或 LlamaParse。
- 执行解析：先用 CLI 小样本预检，再用 Open API、Python SDK、MCP Server、LangChain 或 LlamaIndex 扩展到批量样本。
- 查看输出：同时检查 Markdown、JSON、表格、公式、图片资产、docx/html/latex 等可用产物。
- 人工抽样：按页码、元素类型和风险等级抽样，不只看首页和摘要。
- 记录问题：把失败类型、入口、参数、版本、页码、文件哈希和人工结论写入同一张表。
- 决定是否上线：只有通过 OCR、表格、公式、版面、JSON/Markdown 一致性和安全检查的样本，才能进入默认 RAG 或 Agent 工具链。
- 升级后重跑：MinerU、SDK、MCP Server、API、RAG 框架、切块策略或样本类型变化后，重跑固定失败集。
上线与验证注意事项
API 限制要当天核对。MinerUllms.txt与 Ecosystem README 对 Precision Extract 的页数上限存在不同口径：llms.txt写到 200MB / 600 页，Ecosystem README 表格写到 200MB / 200 页。生产上线应采用保守口径，并以 live docs、API 页面、账户后台和实际返回为准；Flash/Quick Parse 的文件大小、页数、输出格式、认证方式也要按当天页面核对。
数据安全和隐私边界要前置。MinerU MCP README 明确说明 MCP Server 会连接 MinerU 官方 API 解析你提供的文件或 URL。公开论文和公开网页可以更容易进入托管 API 验证；内部合同、财务、医疗、客户资料、未公开科研数据和受版权约束材料，应优先考虑本地、私有化或明确授权后的受控上传。
抽样验收不能只看“解析成功”。至少抽查 OCR、版面还原、表格提取、公式识别、多语言支持、元素提取、结构化 JSON、Markdown 输出和图片资产。关键字段、关键表格、关键公式和入库 chunk 要有人审记录。
失败重试要保证幂等。Open API、SDK、MCP Server、callback 和批处理都可能出现限流、超时、额度不足、文件超限或临时失败。建议使用doc_id + file_hash + parser_version + pages + options作为幂等键，避免重复写入知识库。
版本漂移要能解释。MinerU 主仓库 README 显示 3.x 版本在 OCR、VLM、Hybrid、API/CLI/router、长文档、Office 原生解析和模型层持续演进。能力升级是好事，但知识库上线必须记录当时使用的版本、入口、模型模式、参数、样本哈希和验收结论。
许可证、额度和页数上限要单独核对。MinerUllms.txt写到 AGPL-3.0，主仓库 README 的 License Information 写到基于 Apache 2.0 且带附加条件的 MinerU Open Source License，Ecosystem 仓库为 Apache-2.0。涉及商业使用、在线服务、私有化部署或再分发时，应以官方 GitHub 当前 LICENSE、live docs 和合同条款为准。
可复现实验声明
本文未包含官方实测跑分，评测部分为可复现实验方案和示例记录表，读者需替换自己的样本运行。
来源链接
- 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/blob/master/LICENSE.md
- https://github.com/opendatalab/MinerU-Ecosystem
- https://github.com/opendatalab/MinerU-Ecosystem/tree/main/mcp
- 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/langchain_mineru
- https://github.com/opendatalab/MinerU-Ecosystem/tree/main/llama-index-readers-mineru
- https://modelcontextprotocol.io/specification/2026-07-28
- https://openai.github.io/openai-agents-python/mcp/
- https://github.com/docling-project/docling
- https://docs.unstructured.io/open-source/introduction/overview
- https://docs.cloud.llamaindex.ai/llamaparse/getting_started
- https://sciverse.opendatalab.com/
- https://pypi.org/project/sciverse/0.4.2/