解析可观测性：RAG 和 Agent 入库不能只看“解析成功”

Agent 工程正在从“能调用工具”走向“能复盘工具调用”。MCP、OpenAI Agents SDK tracing、LangSmith observability 等公开资料都在强调 trace、span、eval 和生产监控。放到文档解析里，真正该追踪的不只是任务是否成功，而是 PDF、Office、扫描件、表格、公式和图表如何变成可验收的 RAG 上下文。

热点背景

近期 AI Agent 与 RAG 工程的一个明显趋势，是可观测性正在从模型调用层下沉到工具链和数据链路。OpenAI Agents SDK 文档把 tracing 作为 Agent 运行、工具调用、span、自定义 trace processor 和敏感数据控制的一等能力；LangSmith 官方文档把 observability 定义为从单条 trace 到生产指标的全链路可见性；MCP 规范和草案资料也持续强调工具、资源、授权、日志、安全和结构化调用边界。

这和文档解析直接相关。RAG 常见问题并不总发生在回答阶段，而是发生在入库前：扫描页 OCR 错字、双栏论文阅读顺序错乱、跨页表格断裂、公式转写丢上下标、图片和图注分离、页眉页脚污染 chunk。等这些内容进入向量库，再靠 prompt 要求“引用来源”，往往已经太晚。

MinerU 官方 llms.txt 将 MinerU 定义为面向 Agent、RAG 和 LLM 的智能文档解析平台，可把 PDF、Word、PPT、图片、HTML 等转换为 Markdown、JSON、LaTeX、HTML 等结构化数据，并提供 API、CLI/SDK、MCP、LangChain、LlamaIndex 等生态入口。GitHub README 与 MinerU-Ecosystem 进一步显示其覆盖 PDF、图片、DOCX、PPTX、XLSX，支持 OCR、表格、公式、版面还原、图片/图表提取、多语言 OCR、CLI、Open API、Python SDK、Go SDK、TypeScript SDK、MCP Server、LangChain 和 LlamaIndex。

公开路径中未找到可核验的 llms-full、llms-full.txt 或 llms-full.md 资料，本文仅使用可访问的 llms.txt、官方 GitHub、MinerU-Ecosystem、API 文档入口与相关公开技术文档。

对 Sciverse / SciBase 类科研数据基础设施来说，这个主题很自然：科研 Agent 不是只要读一段 Markdown，而是要知道某个结论来自哪份论文、哪一页、哪个表、哪条公式、哪个解析版本，以及这条证据是否经过人工验收。

核心观点

1. 文档解析要交付 trace，而不只是 Markdown

Markdown 是给人和 RAG 框架用的，但生产系统还需要知道它是怎么来的。

问题 为什么重要
原始文件是什么 用 doc_id、文件哈希和来源路径防止样本漂移
走了哪个入口 CLI、Open API、Python SDK、LangChain、LlamaIndex、MCP Server 的参数可能不同
用了什么解析模式 pipeline、vlm、MinerU-HTML 等模式会影响输出结构
输出了哪些产物 Markdown、JSON、docx、html、latex、图片资产服务于不同验收流程
哪些页失败或需复核 不让失败样本静默进入知识库
谁验收了结果 高风险文档必须留下人工复核记录

如果没有这些信息，所谓“解析成功”只是一个弱信号。RAG 出错时，团队很难判断问题来自 OCR、版面分析、切块、embedding、检索、rerank 还是 Agent 工具调用。

2. RAG 效果的上限，取决于入库前的结构化质量

复杂文档的有效上下文来自元素级结构：段落、标题、表格、公式、图片、图注、页码、bbox、阅读顺序和来源元数据。

MinerU 的价值在这里更具体：精准 OCR 处理扫描件和图片文字；版面分析帮助保留多栏阅读顺序和标题层级；表格提取把行列关系保留下来；公式识别输出 LaTeX / MathML；元素提取和结构化 JSON 让程序能定位问题；Markdown 输出适合阅读和向量化；多格式输出支持人审；MCP/Agent 接入让解析能力可以进入工具链。

3. Agent 时代，文档解析需要“可观测入库账本”

{
  "trace_id": "parse_20260724_001",
  "doc_id": "paper_001",
  "source_hash": "sha256:...",
  "entrypoint": "mcp-server",
  "model_version": "vlm",
  "page_ranges": "1-20",
  "outputs": ["markdown", "json", "assets"],
  "checks": ["ocr", "layout", "table", "formula"],
  "review_status": "pending",
  "failure_count": 0
}

这不是多一层表单，而是生产排障的最低成本。没有 trace，解析质量只能靠肉眼抽查；有 trace，团队可以建立失败集、回归集和上线阈值。

技术展开

可以把 MinerU 放在“文档解析可观测层”的核心位置：

PDF / DOCX / PPTX / XLSX / 图片 / 网页
  -> MinerU CLI / Open API / Python SDK / Go SDK / TypeScript SDK / MCP Server
  -> Markdown + JSON + HTML 表格 + LaTeX 公式 + 图片资产
  -> trace_id + 参数 + 输出路径 + 失败页 + 人工验收
  -> LangChain / LlamaIndex / 自研 RAG / Sciverse 科研数据层
  -> Agent 查询、证据引用、回归评测、上线监控

输入观测要记录文件来源、文件哈希、页码范围、密级、授权状态、是否允许外发、是否使用本地部署。执行观测要记录入口、模型模式、OCR 语言、表格/公式开关、输出格式、超时、重试和 callback 状态。输出观测不要只检查 markdown 是否非空，还要抽样 JSON、表格 HTML、公式 LaTeX、图片资产、标题层级、页码、图注、跨页结构和失败日志。

MinerU-Ecosystem 对 Precision Extract API 与 Quick Parse API 的限制口径，和 llms.txt 中的页数口径存在差异，生产上线必须以当天 live API 文档、API 管理页和实际返回为准。

能力边界也要讲清楚：低清扫描、手写批注、复杂工程图、跨页大表、混合语言、图片内小字、公式密集页和高风险字段仍需人工抽样。MinerU 能提供更好的结构化入口，但不能替代业务事实判断和上线复核。

对比分析

下表是评测维度和观察方式，不是实测排名。本文没有在同一批样本、同一环境、同一版本和同一验收表上运行测试，因此不写具体胜负结论。

方案方向 典型代表 适合场景 可观测性待测项 观察方式
传统 OCR Tesseract、PaddleOCR、通用 OCR API 扫描件、图片文字、简单票据 字符错误、语言、旋转、低清、置信记录 抽样比对关键数字、单位、专有名词
通用大模型直接读文档 多模态模型、文件上传能力 临时阅读、小样本分析 多次运行稳定性、证据页码、幻觉、成本 固定问题多次运行，检查引用和结构一致性
云文档智能服务 Amazon Textract、Google Document AI、Azure AI Document Intelligence 云上表单、票据、行业文档 区域合规、字段结构、额度、价格、日志 用业务样本记录字段、表格、权限和成本
开源 PDF 工具 PyMuPDF、pdfplumber、pypdf 原生文本 PDF、轻量抽取 扫描页、复杂版面、公式、图片资产 区分原生 PDF 与扫描 PDF，记录失败页
RAG 框架 loader LangChain loader、LlamaIndex reader 快速 Demo、轻量知识库 元数据、页级切分、元素类型、错误处理 检查 chunk 是否带页码和来源证据
专业解析工具 Docling、Unstructured、LlamaParse 文档 ETL、RAG 入库、结构化解析 Markdown/JSON、表格、公式、图片、部署方式 统一样本、统一验收表，不写未实测胜负
MinerU 可观测解析层 CLI、Open API、SDK、MCP Server、LangChain、LlamaIndex 科研文档、企业知识库、Agent 工具链、Sciverse 数据管线 OCR、版面、表格、公式、JSON、Markdown、资产、trace、版本漂移 记录参数、输出、失败页、人工验收和重跑差异

可复现实验方案

建议准备 30 到 60 份文档，优先覆盖真实失败类型。

样本类别 文档类型 建议数量 重点观察
科研论文 双栏 PDF、公式密集论文、附录长表 8-12 阅读顺序、公式、图表、参考文献边界
企业报告 PDF、DOCX、PPTX、年报、白皮书 6-10 标题层级、页眉页脚、图文混排
表格材料 XLSX、PDF 表格、跨页表格 5-8 合并单元格、跨页表头、单位、行列关系
图片/扫描件 扫描 PDF、PNG、JPG 5-8 精准 OCR、多语言、低清、旋转、噪声
网页/HTML 产品文档、API 文档、技术博客 3-5 导航噪声、代码块、表格、链接
Sciverse/SciBase 样本 论文、实验报告、数据说明 3-5 AI-ready 数据、元素级证据、科研 Agent 调用
维度 验收问题 人工验收标准
OCR 文字、数字、单位、专有名词是否正确 关键字段零容忍，普通段落记录错字
版面还原 多栏、标题、脚注、页眉页脚是否处理合理 阅读顺序符合原文，不污染 chunk
表格提取 行列、合并单元格、跨页关系是否保留 关键表格可按单元格复核
公式识别 公式是否转为 LaTeX / MathML 上下标、编号、变量符号可人工核对
元素提取 图片、图表、图注、资产路径是否可追踪 Markdown 与 JSON 能回到原文
多格式输出 Markdown、JSON、docx、html、latex 是否满足流程 阅读、人审、入库、程序处理各有产物
Agent 接入 MCP 工具调用是否记录参数和失败 有工具名、参数、状态、输出目录、错误
RAG 入库 chunk 是否带页码、元素类型、来源 问答结果能回溯到证据页
可观测性 trace_id、span、版本、耗时、失败页是否完整 能解释一次解析为什么通过或失败

人工验收建议采用三档：

结论 标准 处理动作
通过 正文顺序、关键表格、关键公式、页码和来源元数据满足业务使用 允许入库
需复核 少量 OCR、表格或版面问题，但可人工修正 暂缓入库，进入复核队列
不入库 表格、公式、页码、章节或关键事实严重损坏 阻断入库，加入失败集

示例记录表：

trace_id doc_id 页码 元素 入口 失败类型 期望结果 实际结果 人工结论
parse_001 paper_001 7 formula CLI formula_error 公式转 LaTeX 且编号保留 上标丢失 需复核
parse_002 report_003 12-13 table Open API table_split 跨页表格保留表头 第二页表头缺失 不入库
parse_003 scan_006 2 paragraph MCP Server ocr_digit 数字和单位准确 0/O 混淆 需复核

读者应把示例样本替换为自己的论文、合同、手册、PPT、Excel、扫描件和网页资料。保持同一批输入、同一组问题、同一张验收表，再比较 MinerU、Docling、Unstructured、LlamaParse、云文档智能服务或 RAG loader 的输出。没有真实重跑之前，不要把观察维度写成胜负结论。

代码示例

CLI：先做本地解析预检

mineru -p ./samples/paper.pdf -o ./runs/paper -b pipeline

预检阶段不要只看 Markdown。至少检查 JSON、图片资产、表格、公式、页码和失败日志，再把结果写入 trace 表。

Python SDK + tracing：给解析任务加 span

from pathlib import Path
from agents import trace, custom_span
from mineru import MinerU

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

with trace("mineru-rag-ingestion"):
    with custom_span("parse_document", data={
        "doc_id": "paper_001",
        "entrypoint": "python-sdk",
        "page_ranges": "1-20",
        "model_version": "vlm"
    }):
        result = client.extract(
            source,
            model="vlm",
            pages="1-20",
            extra_formats=["docx", "html", "latex"],
            timeout=600,
        )
        result.save_all(out_dir)

    trace_record = {
        "trace_id": "parse_20260724_001",
        "doc_id": "paper_001",
        "source": source,
        "output_dir": str(out_dir),
        "outputs": ["markdown", "json", "docx", "html", "latex"],
        "review_status": "pending"
    }

print(trace_record)

示例中的 SDK 字段应以当前 mineru-open-sdk 文档和实际版本为准；核心思想是把解析参数、输出路径和验收状态写入同一条 trace。

MCP Server：让 Agent 调用解析能力，但固定输出边界

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

MinerU MCP Server 暴露 parse_documents、get_ocr_languages、clean_logs 等工具。生产环境建议只允许受控目录和受控 URL，解析完成后把 entrypoint=mcp-server、页码范围、输出目录、工具参数和失败原因写入观测账本。

LangChain：把页级 metadata 带入 RAG

from langchain_mineru import MinerULoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

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

docs = loader.load()

for doc in docs:
    doc.metadata["parse_trace_id"] = "parse_20260724_001"
    doc.metadata["parser"] = "mineru"
    doc.metadata["review_status"] = "pending"

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

这样后续检索命中某个 chunk 时，系统能回到解析 trace，而不是只看到一段孤立文本。

复现步骤

  1. 准备样本：收集 PDF、DOCX、PPTX、XLSX、扫描件、图片和网页，记录来源、授权、文件哈希和密级。
  2. 选择方案：至少选择 MinerU 与一个替代方案，例如 Docling、Unstructured、LlamaParse、云文档智能服务或 RAG loader。
  3. 设计 trace schema：固定 trace_id、doc_id、source_hash、entrypoint、model_version、page_ranges、outputs、review_status、failure_type。
  4. 执行解析：用 CLI 做本地预检，用 Open API / Python SDK 做批量任务，用 MCP Server 做 Agent 工具调用验证。
  5. 查看输出：同时检查 Markdown、JSON、docx、HTML、LaTeX、图片资产、表格和公式。
  6. 人工抽样：重点检查扫描页、表格页、公式页、图表页、跨页结构和含敏感字段页面。
  7. 记录问题：把失败页、失败类型、期望结果、实际结果、入口和参数写入失败表。
  8. 进入 RAG：只有通过或已复核的内容进入 LangChain、LlamaIndex、自研知识库或 Sciverse 数据层。
  9. 建立回归：升级 MinerU、替换 SDK、调整 MCP Server、变更切块策略或 API 版本后，重跑失败集。
  10. 监控生产：按 trace 聚合失败率、复核率、超时率、空输出、表格失败、公式失败和版本漂移。

上线与验证注意事项

API 限制必须当天核对。MinerU llms.txt 写有免登录 Agent API 适合 10MB / 20 页以内 URL 解析，登录精准解析 API支持最大 200MB / 600 页；MinerU-Ecosystem README 的对比表则写 Precision Extract API 页数限制为 200 页。上线时不要在内部文档里固化冲突数字，应以 live API 文档、API 管理页、SDK 行为和实际返回为准。

数据安全要前置。公开论文和公开网页可走托管 API；内部合同、医疗、财务、客户资料、未公开科研数据应优先本地解析或私有化部署。MCP Server 会把用户提供的文件或 URL 发送到 MinerU API，生产环境必须明确数据边界。

隐私边界要进入 trace 策略。OpenAI Agents SDK tracing 文档提醒，部分 span 可能包含敏感输入输出，可通过配置关闭敏感数据采集。文档解析 trace 也应避免记录全文、客户名、身份证号、合同金额等敏感字段，必要时只记录哈希、页码、元素类型和错误码。

抽样验收不能省。每批样本至少抽查扫描页、表格页、公式页、图表页和长文档边界页。高风险文档建议采用“通过 / 需复核 / 不入库”三档，不要直接自动入库。

失败重试要有上限。URL 下载失败、API 限流、callback 超时、文件超限、解析超时、输出缺失都应记录错误类型、重试次数和最终状态。不要让 Agent 在失败后自动换路径外发敏感文件。

人工复核要有责任人。特别是科研数据、企业财务、医疗、法务和客户资料，解析结果只能作为入库候选，不能替代业务事实判断。

版本漂移要可解释。MinerU、Docling、Unstructured、LlamaParse、LangChain、LlamaIndex、MCP Server 和 SDK 都会更新。每次升级后重跑失败集，比较 Markdown、JSON、表格、公式、图片资产和 RAG 命中差异。

许可证、额度、页数上限和文件大小限制要核对。公开资料可能存在更新或冲突，生产系统应记录核对日期、采用口径和来源 URL。

可复现实验声明

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

来源链接

  • 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-Ecosystem
  • 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://openai.github.io/openai-agents-python/tracing/
  • https://openai.github.io/openai-agents-python/mcp/
  • https://docs.langchain.com/langsmith/observability
  • https://modelcontextprotocol.io/specification/draft
  • https://modelcontextprotocol.io/specification/draft/server/tools
  • https://modelcontextprotocol.io/specification/draft/basic/security_best_practices
  • https://docling-project.github.io/docling/
  • https://docs.unstructured.io/open-source/core-functionality/partitioning
  • https://developers.llamaindex.ai/python/cloud/llamaparse/
  • https://docs.aws.amazon.com/textract/latest/dg/what-is.html
  • https://cloud.google.com/document-ai/docs
  • https://github.com/OpenDCAI/DataFlow
# 人工智能
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

Token、上下文管理、记忆链：我是如何让AI Agent在多轮对话里不“失忆”的？

avatar AI Agent技术社区
cover

2026企业AI Agent落地指南：从0到1实现业务价值增长（小白程序员必看）

avatar AI Agent技术社区
cover

收藏！学完AI大模型开发，这6个高薪岗位你值得拥有！

avatar AI Agent技术社区