私有解析沙箱：Agent 时代，文档入库要先过安全边界

m0_61134850

858人浏览 · 2026-07-22 10:28:27

m0_61134850 · 2026-07-22 10:28:27 发布

Agent、MCP 和企业 RAG 正把文档解析从“批量转 Markdown”推到安全工程前台。今天值得关注的不是某个 loader 多快，而是 PDF、Office、扫描件和科研资料在进入知识库前，是否经过权限、隐私、输出结构和人工验收。MinerU 的 CLI、Open API、SDK、MCP Server、OCR、版面分析、表格提取、公式识别与结构化 JSON，适合成为这层私有解析沙箱。

热点背景

近期公开技术讨论里，MCP 的授权、安全最佳实践、工具过滤、human-in-the-loop approval、Agent sandbox 和 OWASP LLM 风险都指向同一个问题：Agent 连接外部工具后，能力边界就是安全边界。MCP 官方授权草案强调 HTTP 传输下的 OAuth、资源标识、token audience、scope selection 和 step-up authorization；安全最佳实践明确列出 confused deputy、token passthrough、SSRF、本地 MCP Server 执行风险、stdio transport 代理风险和 scope minimization。OpenAI Agents SDK 的 MCP 文档也把 hosted MCP、Streamable HTTP、stdio、approval policy、tool filtering、tracing、失败重试和工具缓存作为一等接口。

这和文档解析直接相关。企业合同、科研论文、医疗资料、财务报表、专利、内部 PPT、Excel 和扫描件，一旦被 Agent 调用解析，就可能涉及文件路径、URL 抓取、API token、回调地址、临时文件、日志、结构化输出、人工复核和最终入库。传统做法常把解析当成入库前脚本；Agent 时代更合理的做法，是把解析放进一个“私有解析沙箱”：先做权限与数据边界检查，再执行 MinerU 解析，最后只把通过验收的 Markdown、JSON、表格、公式、图片资产和元数据写入 RAG 或 Sciverse 类科研数据基础设施。

MinerU 官方 llms.txt 将产品定义为面向 Agent、RAG 和 LLM 的智能文档解析平台，支持 PDF、Word、PPT、图片、HTML 等转 Markdown、JSON、LaTeX 和 HTML，并提供免登录 Agent API、登录精准解析 API、CLI/SDK、MCP、LangChain、LlamaIndex 等生态入口。GitHub README 进一步显示 3.x 已覆盖 PDF、图片、DOCX、PPTX、XLSX，支持本地部署、CPU/GPU、Docker、mineru-api、mineru-router、多格式输出与 109 语言 OCR。公开路径中未找到可核验的 llms-full、llms-full.txt 或 llms-full.md，本文仅使用 llms.txt、官网、GitHub README、MCP 官方文档、OpenAI Agents SDK 文档和 OWASP 公开资料。

核心观点

1. RAG 入库的安全边界，应该前移到文档解析层

很多团队把权限控制放在向量库或问答接口，但风险更早发生：文件上传、URL 拉取、OCR、图片抽取、表格导出、callback、临时目录和日志都会触碰原始数据。等文档已经变成 chunk，再谈隐私和权限，往往已经太晚。

私有解析沙箱要在解析前回答几个问题：谁提交了文件？文件来自本地、对象存储还是 URL？是否允许外发到 API？是否必须本地部署？页数、大小、格式、许可证和额度是否符合当天 live docs？解析结果是否包含敏感字段、图片资产、公式、表格和页码？哪些输出能入库，哪些只能人工查看？

2. Agent 能调用 MinerU，不等于 Agent 可以解析所有文档

MCP 让文档解析变成 Agent 可调用能力，这是生产效率的提升；但工具越自然，越需要策略层。Agent 不应获得“任意路径、任意 URL、任意 token、任意输出目录”的解析权限。更稳的做法是给 MinerU MCP Server、Open API 或 CLI 外面加一层策略：文件白名单、URL allowlist、页码范围、输出格式、敏感文档标记、审批流、失败重试、日志脱敏和版本记录。

OpenAI Agents SDK 文档中的 tool filtering、approval policy、tracing 和 MCPServerManager 思路，可以直接借鉴到 MinerU 工作流：只暴露必要工具，危险操作要求审批，连接失败不静默吞掉，每次工具调用都保留 trace。

3. 私有化部署不是万能答案，验收和审计才是生产能力

MinerU 支持本地部署、CLI、API、SDK、MCP Server、结构化 JSON、Markdown、多格式输出、OCR、版面还原、表格提取、公式识别、多语言支持、批量处理。这些能力能降低数据外发和供应商锁定风险，但本地部署本身不等于安全。真正需要上线的是一套可复现的解析验收流程：输入可追踪、参数可复现、输出可审计、失败可回归、版本漂移可解释。

对 Sciverse 或 SciBase 这类科研数据基础设施来说，这一点更重要。科研 Agent 不是只要“读懂论文摘要”，而是要把论文 PDF、实验报告、表格、公式和图表变成 AI-ready scientific data：可检索、可引用、可复核、可被工具调用，同时不突破数据授权边界。

技术展开

可以把 MinerU 私有解析沙箱拆成五层。

第一层是输入策略层。接收 PDF、DOCX、PPTX、XLSX、图片、网页 URL 或对象存储链接前，先记录 doc_id、提交人、来源、授权状态、文件哈希、密级、页码范围和业务用途。对内部文档、未公开论文、合同、医疗、财务和客户资料，默认禁止直接外发；如需调用 Open API，应有明确审批、脱敏或业务授权。

第二层是执行隔离层。低风险公开资料可以用 MinerU Open API 或 MCP remote mode；内部资料优先考虑本地 CLI、Python SDK、本地 mineru-api、Docker 或私有化部署。对 MCP stdio 或本地服务，应限制工作目录、网络访问和输出目录，不让 Agent 自由访问用户 home、SSH key、系统目录或任意临时文件。

第三层是结构化解析层。MinerU 的价值不只是精准 OCR，而是把复杂文档拆成可被系统消费的结构：Markdown 适合阅读和入库，JSON 适合元素级追踪，表格可导出 HTML，公式可转 LaTeX/MathML，图片和图表可作为资产保存，版面分析能处理多栏阅读顺序、页眉页脚、标题层级和跨页结构。

第四层是验收与入库层。解析成功只代表任务完成，不代表适合进入知识库。上线前应抽样检查 OCR、公式识别、表格提取、版面还原、多语言支持、元素提取、结构化 JSON、Markdown 输出和图片资产。只有通过验收的元素进入 LangChain、LlamaIndex、自研 RAG 或 Sciverse 数据层。

第五层是审计与版本层。记录 entrypoint 是 CLI、Open API、Python SDK、Go SDK、TypeScript SDK、LangChain、LlamaIndex 还是 MCP Server；记录 MinerU 版本、backend、模型模式、页码、开关、输出格式、API 限制核对日期、失败原因和人工结论。MinerU README 与 llms.txt 对许可、页数上限等口径存在差异时，应采用保守口径，并以 live docs、GitHub README、LICENSE 和实际 API 页面为准。

对比分析

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

方案方向	典型代表	适合场景	安全与结构待测项	观察方式
传统 OCR	Tesseract、PaddleOCR、通用 OCR API	扫描件、图片文字、简单版面	是否保留表格、公式、页码、阅读顺序	抽样核对关键字段、表格行列和 OCR 错字
通用大模型直接读文档	多模态聊天模型、文件上传功能	临时阅读、小样本问答	数据是否外发、证据页码是否稳定、是否可复现	固定问题多次运行，检查引用和幻觉
云厂商文档智能	Azure AI Document Intelligence、Google Document AI、Amazon Textract	云上表单、票据、行业文档	区域合规、价格、限额、字段结构、私有数据边界	用业务样本核对字段、权限、日志和成本
开源 PDF 工具	PyMuPDF、pdfplumber、pypdf	原生文本 PDF、轻量抽取	扫描页 OCR、复杂版面、公式、图片资产	区分原生 PDF 与扫描 PDF 记录失败
RAG 框架 loader	LangChain loader、LlamaIndex reader	快速 Demo、轻量知识库	元数据、页码、元素类型、错误处理	检查 chunk 是否能回溯原文
专业文档解析工具	Docling、Unstructured、LlamaParse	文档 ETL、RAG 入库、结构化解析	Markdown/JSON、表格、公式、OCR、部署方式、费用	统一样本和人工验收表，不写未实测胜负
MinerU 私有解析沙箱	MinerU CLI、Open API、SDK、MCP Server、本地部署	企业知识库、科研数据管线、Agent 工具调用	OCR、版面、表格、公式、JSON、Markdown、MCP 权限、私有化部署	跨入口重跑同一批样本，记录参数、输出和审计日志

客观选型的重点不是“谁更强”，而是看风险是否可控：数据能否留在本地、输出是否结构化、失败是否可见、许可证和额度是否明确、Agent 工具权限是否最小化。

可复现实验方案

样本集设计

样本类别	文档类型	建议数量	重点观察
公开科研论文	PDF、双栏论文、公式密集论文	8-12	公式识别、图表、页码、参考文献边界
内部企业资料	DOCX、PPTX、PDF 报告	8-12	数据边界、标题层级、页眉页脚、图文混排
表格材料	XLSX、PDF 表格、跨页表	5-8	表格提取、合并单元格、单位、行列关系
扫描件	扫描 PDF、PNG、JPG	5-8	精准 OCR、多语言、低清噪声、旋转页
高风险资料	合同、财务、医疗、专利	3-5	隐私边界、人工复核、是否禁止外发
Sciverse/SciBase 样本	论文、实验报告、数据说明	3-5	AI-ready 数据、元素级证据、科研 Agent 调用

评测维度

维度	验收问题	人工验收标准
数据安全	文件是否允许外发或必须本地解析	每个样本有密级、授权和执行模式
OCR	扫描页文字、数字、单位是否正确	关键字段零容忍，普通段落记录错字
版面还原	多栏、标题、脚注、页眉页脚是否正确	阅读顺序符合原文，不污染 chunk
表格提取	行列、合并单元格、跨页关系是否保留	关键表格可人工复核
公式识别	公式是否输出 LaTeX/MathML	上下标、编号、变量符号正确
元素提取	图片、图表、图注、资产路径是否可追踪	JSON 和 Markdown 能定位到原文
Agent 接入	MCP 工具权限、approval、trace 是否完整	有工具名、参数、审批、状态和失败原因
RAG 入库	chunk 是否带页码、元素类型、来源	问答结果能回到原文证据

示例记录表

doc_id	密级	执行模式	页码	输出	风险项	人工结论	是否入库
paper_001	public	Open API	1-12	MD+JSON+LaTeX	无	通过	是
contract_003	internal	local CLI	1-20	MD+JSON	含客户信息	需复核	暂缓
scan_006	restricted	local API	2	MD+JSON	OCR 数字疑似错误	不入库	否
dataset_note_002	public	MCP Server	1-8	MD+JSON+assets	图表需复核	需复核	暂缓

失败案例记录方式

{
  "doc_id": "contract_003",
  "classification": "internal",
  "entrypoint": "local-cli",
  "page_range": "1-20",
  "mineru_backend": "pipeline",
  "outputs": ["markdown", "json"],
  "failure_type": "privacy_review_required",
  "expected": "内部合同只能在本地解析，结果需人工确认后入库",
  "observed": "解析成功，但包含客户名称和签署信息",
  "review_status": "needs_review",
  "action": "脱敏后重新验收"
}

待读者替换样本运行说明：把上表样本替换为自己的 PDF、Office、扫描件和科研资料，保持同一批输入、同一组参数、同一张验收表，再比较 MinerU、Docling、Unstructured、LlamaParse、云服务或 RAG loader 的输出。

代码示例

CLI：把敏感样本留在本地预检

# 公开资料可先跑默认解析；内部资料建议固定输出目录和参数
mineru -p ./samples/internal-contract.pdf -o ./runs/internal-contract -b pipeline

预检时不要只看 Markdown。至少同时检查 JSON、图片资产、表格、公式、页码和失败日志，再决定是否进入知识库。

Open API：提交公开样本并记录回调

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/public-paper.pdf",
    "model_version": "vlm",
    "page_ranges": "1-20",
    "extra_formats": ["docx", "html", "latex"],
    "callback": "https://your-service.example/mineru/callback"
  }'

上线时记录 task_id、data_id、model_version、page_ranges、callback 验签状态、重试次数和当天核对到的 API 限制。涉及非公开资料时，先确认是否允许外发。

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"
      }
    }
  }
}

OpenAI Agents SDK：用 tool filter 和 approval 包一层策略

from pathlib import Path
from agents import Agent
from agents.mcp import MCPServerStdio, create_static_tool_filter

allowed_output = Path("/absolute/path/to/mineru-runs")

server = MCPServerStdio(
    name="mineru",
    params={
        "command": "uvx",
        "args": ["mineru-open-mcp"],
        "env": {
            "MINERU_API_TOKEN": "your_key_here",
            "OUTPUT_DIR": str(allowed_output),
        },
    },
    tool_filter=create_static_tool_filter(
        allowed_tool_names=["parse_documents", "get_ocr_languages"]
    ),
    require_approval="always",
)

agent = Agent(
    name="Document Ingestion Reviewer",
    instructions=(
        "Only parse documents that have an approved classification record. "
        "Reject unknown local paths and external URLs outside the allowlist."
    ),
    mcp_servers=[server],
)

实际工具名以 MCP Server list_tools() 返回为准。示例重点是策略：限制工具、固定输出目录、要求审批、记录 trace，而不是让 Agent 自由解析任意文件。

复现步骤

准备样本：收集 PDF、DOCX、PPTX、XLSX、图片 PDF、网页 URL 和科研资料，记录来源、授权、文件哈希和密级。
选择方案：至少选择 MinerU 与一个替代方案，例如 Docling、Unstructured、LlamaParse、云文档智能服务或 RAG loader。
设定安全策略：决定 public/internal/restricted 三档样本分别走 Open API、本地 CLI、本地 API 还是私有化部署。
固定解析参数：明确页码范围、OCR、表格、公式、语言、backend、输出格式和超时时间。
执行解析：用 CLI 做本地预检，用 Open API 或 MCP Server 处理允许外发的公开样本，用本地部署处理敏感样本。
查看输出：同时检查 Markdown、JSON、docx、HTML、LaTeX、图片资产、表格和公式。
人工抽样：重点检查扫描页、表格页、公式页、图表页、跨页结构和含敏感字段的页面。
记录问题：把失败页、失败类型、期望结果、实际结果、入口和参数写入失败表。
决定是否上线：只有通过验收的文档或元素进入 LangChain、LlamaIndex、自研知识库或 Sciverse 数据层。
建立回归集：升级 MinerU、替换 SDK、调整 MCP Server、变更切块策略或 API 版本后，重新跑失败集。

上线与验证注意事项

API 限制核对必须当天完成。MinerU llms.txt 写有免登录 Agent API 适合 10MB/20 页以内 URL 解析、登录精准解析 API 支持最大 200MB/600 页；GitHub README 与 SDK、API 页面可能随版本更新而变化。上线前以 live API 文档、API 管理页面、README、SDK 行为和 LICENSE 为准，并在验收表记录核对日期。

数据安全要前置。公开论文和公开网页可走托管 API；内部合同、医疗、财务、客户资料、未公开科研数据应优先本地解析或私有化部署。不要让 Agent 自动把未知文件或 URL 发往外部服务。

隐私边界要写成策略。限制输入目录、输出目录、URL allowlist、callback 域名、token scope、日志字段和临时文件保留时间。MCP Server 不应默认拥有用户主目录、SSH key、系统目录或所有网络访问权限。

抽样验收不能省。解析成功不等于表格、公式、版面和证据链适合入库。高风险样本至少抽查关键表格、关键公式、扫描页、图表页和敏感字段页。

失败重试要可观察。记录失败阶段、错误码、页码范围、重试次数、工具参数、MCP trace、API task_id 和输出目录。不要让 Agent 把半成品 Markdown 自动写入生产知识库。

人工复核要有出口。对“需复核”的样本，应允许人工脱敏、排除页码、补充元数据、修正文档或标记不入库。

版本漂移要可追踪。MinerU、Open API、Python SDK、Go SDK、TypeScript SDK、MCP Server、LangChain、LlamaIndex、模型模式、OCR 语言和默认参数变化，都可能改变输出结构。生产系统应保留解析版本，并在升级前重跑固定回归集。

许可证、额度和页数上限要保守处理。公开资料出现冲突时，标注冲突，不写死不可核验的商业承诺；内部合规以 live docs、官方 GitHub、LICENSE 和采购/服务协议为准。