文档解析控制面：RAG 和 Agent 入库不能只靠一个 loader

文档解析控制面：RAG 和 Agent 入库不能只靠一个 loader

Agent、Context Engineering 和 MCP 正在把文档解析推向生产治理问题：同一份 PDF、Office 或科研文档，经 CLI、Open API、Python SDK、LangChain、LlamaIndex、MCP Server 进入知识库时，必须有一致的参数、输出、验收和失败记录。MinerU 的 OCR、版面分析、表格提取、公式识别、Markdown/JSON 输出与多入口生态，适合成为这层“解析控制面”。

热点背景

近期 Agent 工程的讨论有一个共同方向：模型不只是拿上下文回答问题，而是通过工具、状态、子 Agent 和外部资源持续完成任务。LangChain 在 Context Engineering 相关文章中把上下文管理拆成写入、选择、压缩、隔离等策略；MCP 官方规范则把 tools、resources、prompts、授权、隐私和安全边界放在协议核心。换到文档解析场景，这意味着 PDF 解析不再只是离线预处理，而会成为 Agent、RAG、知识库、Workflow 和科研数据管线中的可调用能力。

问题也随之变化。过去团队常问“这个 loader 能不能读 PDF”；现在更应该问：同一份文档用 CLI、Open API、Python SDK、LangChain、LlamaIndex 或 MCP Server 解析时，是否使用同一套页码范围、OCR 开关、公式开关、表格开关、模型模式、输出格式和验收标准？如果解析版本变了，知识库里的旧 chunk 是否需要重建？如果 Open API 额度、页数上限、callback 签名或 token 过期，Agent 是否会把半成品结果写入知识库？

MinerU 公开资料把产品定位在 LLM、RAG、Agent workflows 的高精度文档解析场景，支持 PDF、DOCX、PPTX、XLSX、图片、网页等输入，输出 Markdown、JSON、LaTeX、HTML 等结构化数据，并提供 CLI、REST API、Python SDK、Go SDK、TypeScript SDK、LangChain、LlamaIndex、MCP Server 等入口。公开路径中未找到可核验的 llms-full、llms-full.txt 或 llms-full.md 资料，本文仅使用可访问的 llms.txt、官网 API 文档、GitHub README 与生态仓库。

对 Sciverse 类科研数据基础设施来说，这个话题尤其关键。科研 PDF、实验报告、专利、PPT、表格和网页资料只有先进入稳定的解析控制面，才能变成 AI-ready scientific data：可检索、可引用、可复核、可被 Agent 调用，而不是一次性的 OCR 文本。

核心观点

1. RAG 入库的第一层控制面，不在向量库，而在解析入口

很多 RAG 项目把治理重点放在 embedding、rerank、权限过滤和回答引用上，但文档进入向量库之前，质量已经被解析层决定了一大半。

如果解析入口没有统一控制，常见问题会很快出现：

• 扫描件有的任务开 OCR，有的任务没开；
• 表格在一个入口输出 HTML，在另一个入口只剩 Markdown 文本；
• 公式有时是 LaTeX，有时是普通字符；
• LangChain loader 默认只返回 Markdown，但后端 API 其实有 JSON、docx、html、latex 等结果；
• MCP Server 让 Agent 可以随时解析文件，但没有记录页码、权限、token、输出目录和失败原因；
• 解析版本或模型模式切换后，旧知识库 chunk 没有重建，导致检索结果混用不同解析口径。

所以，文档解析控制面要解决的不是“再封装一个 API”，而是把解析参数、输出结构、验收记录、失败重试和版本漂移管起来。

2. Agent 时代，解析结果必须同时面向人、程序和工具

一个面向生产的解析结果至少有三类消费者。

这也是 MinerU 的能力组合适合做控制面的原因。精准 OCR 处理扫描件和图片文字；版面分析保持阅读顺序、标题层级和页眉页脚边界；表格提取保留行列结构；公式识别输出 LaTeX/MathML；元素提取和结构化 JSON 让程序可以追踪段落、表格、公式、图片和页面位置；Markdown 输出适合阅读和入库；批量处理、私有化部署、API、SDK、CLI 与 MCP Server 则把同一套能力接到不同工程入口。

3. 解析控制面的目标不是证明工具永远正确，而是让错误可见

文档解析一定会遇到失败样本：低清扫描、手写批注、复杂跨页表格、密集公式、工程图、特殊语言、图片中的表格、页码缺失、URL 内容变化、API 限流。控制面的价值是让这些失败被记录，而不是被静默写入知识库。

建议每次解析都保留这些元数据：

这些字段对 Sciverse 类科研数据管线很重要：科研 Agent 不只是“读完论文”，还要知道某个结论来自哪一页、哪个表、哪条公式、哪个解析版本，是否经过人工验收。

技术展开

可以把 MinerU 放在“原始文档”和“知识库 / Agent 工具链”之间，作为文档解析控制面：

PDF / DOCX / PPTX / XLSX / 图片 / HTML
-> MinerU CLI / Open API / Python SDK / Go SDK / TypeScript SDK / MCP Server
-> Markdown + JSON + docx + html + latex + 图片/表格/公式资产
-> 解析参数登记 + 元素级验收 + 失败集 + 版本记录
-> LangChain / LlamaIndex / 自研知识库 / Sciverse 数据层
-> Agent 查询、RAG 问答、字段抽取、报告生成

第一层是入口治理。CLI 适合本地样本预检和批量脚本；Open API 适合服务端异步任务；Python SDK 适合数据处理管线；Go SDK 和 TypeScript SDK 适合业务系统集成；LangChain 和 LlamaIndex 适合快速进入 RAG；MCP Server 适合让 Cursor、Claude Desktop、Windsurf 等 Agent 客户端调用解析能力。控制面要做的是让这些入口共享同一套样本、参数和验收表。

第二层是输出治理。不要只保存一份 full.md。对科研论文、企业报告、财报、专利、PPT 和 Excel 来说，Markdown 适合阅读和向量化，JSON 适合保留元素顺序和结构，HTML 表格适合复核行列，LaTeX 公式适合科研检查，docx/html 适合人工审核，图片资产适合多模态索引和证据回看。

第三层是安全治理。MCP 和 Agent 让工具调用更自然，也让数据外发、URL 拉取、token 使用、callback 验签、输出目录和日志留存变得更敏感。内部合同、未公开科研数据、医疗或财务文档进入解析服务前，必须确认 API、私有化部署、许可证、额度、页数上限、文件大小、缓存策略和隐私边界。

第四层是版本治理。MinerU GitHub README 中的 3.x changelog 已经显示，解析后端、OCR、VLM、CLI/API/router、模型下载、并发和部署能力都在持续演进。能力变强是好事，但生产知识库必须记录“当时用的是什么入口、什么模型模式、什么参数、什么版本”，否则重跑样本、解释差异和回滚都会变困难。

对比分析

下面的表格是选型与评测维度，不是实测排名。本文没有在同一批样本、同一环境和同一验收表上运行测试，因此不写具体胜负结论。

客观选型不应该写“谁被吊打”。更可靠的方法是把每个方案放进同一张评测表：样本相同、参数可复现、验收标准一致、失败案例可追踪。只有真实跑完，才适合写具体结论。

可复现实验方案

样本集设计

建议准备 30-50 份文档，覆盖真实业务，而不是只用干净 demo：

评测维度

失败案例记录方式

失败样本不要只写“效果不好”，而要记录成可回归对象：

待读者替换样本运行说明

读者应把示例路径替换为自己的文档集，保持同一批样本在 CLI、Python SDK、Open API、LangChain、LlamaIndex、MCP Server 中分别运行。每个入口都写入同一张验收表，不要把某个入口的成功结果直接推断为所有入口都一致。

代码示例

CLI：先做本地样本预检

# 本地文件或目录解析，适合先跑小样本
mineru -p ./samples -o ./outputs/mineru

# 低资源或纯 CPU 环境，可显式选择 pipeline backend
mineru -p ./samples/paper.pdf -o ./outputs/paper -b pipeline

Python SDK：把解析结果写入控制面记录

from pathlib import Path
from mineru import MinerU

client = MinerU("your-api-token")
source = "./samples/paper.pdf"

result = client.extract(
source,
model="vlm",
ocr=True,
formula=True,
table=True,
pages="1-20",
extra_formats=["docx", "html", "latex"],
timeout=600,
)

out_dir = Path("./outputs/paper")
result.save_all(out_dir)

control_record = {
"doc_id": "paper_001",
"source_uri": source,
"entrypoint": "python-sdk",
"task_id": result.task_id,
"state": result.state,
"model": "vlm",
"pages": "1-20",
"outputs": ["markdown", "json", "docx", "html", "latex"],
"review_status": "pending",
}

print(control_record)

Open API：记录任务提交与 callback 验签字段

curl -X POST "https://mineru.net/api/v4/extract/task" \\
-H "Authorization: Bearer $MINERU_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"url": "https://example.com/paper.pdf",
"model_version": "vlm",
"page_ranges": "1-20",
"extra_formats": ["docx", "html", "latex"],
"callback": "https://your-service.example/mineru/callback",
"seed": "your_callback_signing_seed"
}'

LangChain：把 loader 结果和解析元数据一起入库

from langchain_mineru import MinerULoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

loader = MinerULoader(
source="./samples/paper.pdf",
mode="precision",
token="your-api-token",
language="en",
pages="1-20",
split_pages=True,
ocr=True,
formula=True,
table=True,
)

docs = loader.load()
for doc in docs:
doc.metadata["parser"] = "mineru"
doc.metadata["review_status"] = "pending"

chunks = RecursiveCharacterTextSplitter(
chunk_size=1200,
chunk_overlap=200,
).split_documents(docs)

复现步骤

上线与验证注意事项

API 限制必须当天核对。MinerU llms.txt、官网 API 文档、Python SDK README 与 LlamaIndex Reader README 对不同模式的页数上限存在不同口径：例如 flash 模式常见口径是 10MB / 20 页，precision 或标准解析在不同资料中出现 200MB / 200 页或 200MB / 600 页的描述。生产上线应以 live docs、账户后台、实际 API 返回和官方 GitHub 当前文档为准，不要把旧文章里的数字写死进系统。

数据安全要先于便利性。MCP Server 公开说明会把你提供的文件或 URL 发送到 MinerU API；如果处理内部文档、未公开论文、医疗、财务、合同或客户数据，需要确认是否使用官方 API、私有化部署或本地部署，明确 token 管理、URL 白名单、日志留存、缓存策略和输出目录权限。

隐私边界要写进工具描述。Agent 能调用解析器，不代表它可以解析任何文件。建议在 MCP 工具、Workflow、Skill 或后端服务中限制来源路径、文件大小、页数、租户、用户授权和回调地址。

抽样验收不能省。每次模型模式、MinerU 版本、OCR 语言、API 参数、RAG loader 或切块策略变化，都应重跑核心样本集。重点验收表格、公式、图注、跨页段落、页眉页脚和多语言 OCR。

失败重试要可解释。超时、限流、URL 读取失败、页数超限、文件拆分失败、callback 验签失败，都应该进入失败表，而不是自动重试到不可追踪。

人工复核要分级。关键字段、财务数字、科研实验结果、公式推导、合同条款属于高风险内容，必须在入库前标注 review_status。未复核内容可以进入候选库，但不应直接进入默认回答链路。

版本漂移要有重建策略。解析器、模型、OCR、API、SDK、LangChain/LlamaIndex 集成都可能升级。建议给每个 chunk 记录解析版本和参数，必要时按 source_hash + parser_version + options 判断是否重建。

许可证、额度和页数上限要在上线前确认。MinerU 当前 GitHub 许可证为基于 Apache 2.0 的 MinerU Open Source License，并带有附加商业门槛和在线服务标识义务；生态 SDK 仓库则使用 Apache-2.0。实际商业使用、第三方在线服务和高并发部署前，应让法务或合规同事核对官方许可证、额度、价格、页数、文件大小和服务条款。

来源链接

• https://mineru.net/llms.txt
• https://mineru.net/apiManage/docs
• https://github.com/opendatalab/MinerU
• https://raw.githubusercontent.com/opendatalab/MinerU/master/README.md
• https://github.com/opendatalab/MinerU/blob/master/LICENSE.md
• https://github.com/opendatalab/MinerU-Ecosystem
• https://github.com/opendatalab/MinerU-Ecosystem/tree/main/sdk/python
• 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://opendatalab.github.io/MinerU/
• https://arxiv.org/abs/2409.18839
• https://arxiv.org/abs/2604.04771
• https://modelcontextprotocol.io/specification/2025-06-18
• https://blog.langchain.com/context-engineering-for-agents/
• https://python.langchain.com/docs/concepts/document_loaders/
• https://developers.llamaindex.ai/python/framework/module_guides/loading/
• https://docling-project.github.io/docling/
• https://docs.unstructured.io/
• https://docs.llamaindex.ai/en/stable/llama_cloud/llama_parse/
• https://docs.aws.amazon.com/textract/latest/dg/API_AnalyzeDocument.html