文档解析控制面：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 输出的要求
人工审核	可读、可批注、可对照原文	Markdown、docx、html、图片资产、页码范围
RAG / 知识库	可切块、可检索、可过滤	Markdown、结构化 JSON、元素类型、来源元数据
Agent / MCP	可调用、可选择、可审计	工具参数、任务 ID、状态、输出目录、失败原因

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

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

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

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

字段	示例	用途
doc_id	paper_2026_001	关联原始文件
source_uri	samples/paper.pdf	回到来源
source_hash	sha256:...	判断文件是否变化
entrypoint	cli/api/python-sdk/mcp/langchain	追踪解析入口
model_version	pipeline/vlm/MinerU-HTML	追踪解析模式
page_ranges	1-20	控制解析范围
options	ocr=true, table=true, formula=true	复现实验
outputs	md,json,docx,html,latex	确认产物
review_status	pending/accepted/rejected	控制是否入库
failure_type	table_split/formula_error/timeout	建立失败集

这些字段对 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、模型下载、并发和部署能力都在持续演进。能力变强是好事，但生产知识库必须记录“当时用的是什么入口、什么模型模式、什么参数、什么版本”，否则重跑样本、解释差异和回滚都会变困难。

对比分析

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

方案方向	典型代表	适合场景	评测维度 / 待测项	观察方式
传统 OCR	Tesseract、PaddleOCR、通用 OCR API	图片文字、扫描件、票据、简单版面	字符识别、语言、噪声、旋转、低清扫描	抽样比对原文字符、数字、单位和表头
通用大模型直接读文档	多模态聊天模型、文件上传能力	临时阅读、小样本分析、人工辅助	是否保留页码、表格结构、公式、可复现参数	要求输出证据位置，记录多次运行稳定性
云厂商文档智能	Amazon Textract、Azure AI Document Intelligence、Google Document AI	企业表单、票据、云上工作流	表单、表格、版面、权限、区域合规、价格	按业务样本测字段召回、审计和成本
开源 PDF 工具	PyMuPDF、pdfplumber、pypdf	文本型 PDF、轻量抽取、自研管线	文本顺序、表格、图片、扫描件 OCR	对多栏、跨页表格、公式页做失败记录
RAG 框架 loader	LangChain loader、LlamaIndex reader	快速接入 RAG、原型验证	元数据、页级切分、输出格式、错误处理	检查 Document metadata 与元素结构是否足够
专业解析工具	Docling、Unstructured、LlamaParse	文档转换、RAG 入库、结构化输出	Markdown/JSON、表格、图片、OCR、部署方式	用统一样本和验收表记录输出差异
MinerU 控制面	CLI、Open API、SDK、MCP Server、LangChain、LlamaIndex	多入口工程化入库、Agent 工具调用、科研数据管线	OCR、版面、表格、公式、JSON、Markdown、多格式输出、参数一致性	同一批样本跨入口重跑，比较产物和验收记录

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

可复现实验方案

样本集设计

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

样本类别	文档类型	建议数量	重点观察
科研论文	PDF、arXiv PDF、扫描论文	8-10	双栏阅读顺序、公式、图表、参考文献边界
企业报告	PDF、DOCX、PPTX	8-10	标题层级、页眉页脚、图文混排、批注
表格文档	XLSX、PDF 表格、跨页表格	5-8	合并单元格、跨页、单位、表头
图片/扫描件	PNG、JPG、扫描 PDF	5-8	OCR、旋转、低清、混合语言
网页/HTML	产品文档、API 页面	3-5	HTML 结构、链接、代码块、表格
高风险样本	合同、医疗、财务、专利	3-5	隐私、字段准确性、人工复核

评测维度

维度	验收问题	人工验收标准
OCR	文字、数字、单位是否正确	关键字段零容忍；普通段落记录错误率
版面分析	阅读顺序是否符合人类阅读	多栏、标题、脚注、页眉页脚不污染正文
表格提取	行列、合并单元格、跨页是否保留	表头、单位、数值和行列关系可复核
公式识别	公式是否转为可读 LaTeX/MathML	上下标、编号、变量符号可人工核对
元素提取	图片、图表、图注是否可引用	资产路径、页码、元素类型可追踪
多格式输出	Markdown、JSON、docx/html/latex 是否满足流程	阅读、人审、入库和程序处理都能使用
Agent 接入	MCP 工具参数和返回是否清楚	有任务 ID、页码、输出目录、失败原因
版本漂移	重跑后差异是否可解释	记录入口、版本、参数、模型模式

失败案例记录方式

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

doc_id	页码	入口	参数	失败类型	期望结果	实际结果	严重级别	处理动作
paper_001	7	python-sdk	ocr=true, table=true	formula_error	公式转 LaTeX，编号保留	上标丢失	P1	加入回归集，人工复核
report_003	12-13	api	model_version=vlm	table_split	跨页表合并	被拆成两张表	P1	阻断入库，记录样本
slide_002	4	mcp	pages=4	layout_order	左图右文顺序正确	图注提前	P2	标记需复核

待读者替换样本运行说明

读者应把示例路径替换为自己的文档集，保持同一批样本在 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)

复现步骤

1. 准备样本：选择 30-50 份真实文档，覆盖 PDF、DOCX、PPTX、XLSX、图片、扫描件和 HTML。
2. 选择方案：至少比较 MinerU CLI、Python SDK、Open API、一个 RAG loader，以及一个替代解析方案。
3. 固定参数：统一页码范围、OCR、公式、表格、语言、模型模式、输出格式和超时时间。
4. 执行解析：每次运行都保存原文件哈希、入口、任务 ID、输出目录和错误码。
5. 查看输出：同时检查 Markdown、JSON、docx/html/latex、图片资产和表格/公式结果。
6. 人工抽样：对关键页、关键表、关键公式、关键字段做人工复核，不只看首页效果。
7. 记录问题：把失败案例写入回归表，标注页码、失败类型、严重级别和处理动作。
8. 决定是否上线：只有 P0/P1 失败可控、API 限制明确、隐私边界确认、版本漂移可追踪后，再进入知识库或 Agent 工作流。

上线与验证注意事项

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