MinerU 不该只选一个后端：把 pipeline、VLM 与 hybrid 做成文档分流系统

MinerU 的价值不只是把 PDF 或 Office 文档转成 Markdown。它同时提供 pipeline、VLM 与 hybrid 路线，这意味着团队可以把文档解析从“选一个模型跑到底”改成按页面难度分流的成本—质量系统。真正需要设计的不是默认后端，而是每份文档在哪些证据下升级处理、如何复用结果，以及失败时是否能解释。

官方仓库把 MinerU 定位为面向 LLM、RAG 与 Agent 工作流的文档解析引擎，输入覆盖 PDF、图片、DOCX、PPTX 与 XLSX，输出包括 Markdown 和 JSON。当前项目还提供 CLI、FastAPI、Gradio 与 mineru-router。能力面很宽，但系统边界也更清楚：解析引擎只负责产生候选结构，业务仍要负责排队、鉴权、质量判定和入库。

三种后端不该变成三个手工按钮

官方说明把 pipeline 描述为快、稳定，并可在 CPU 或 GPU 上运行；VLM 路线面向更复杂的视觉理解；hybrid 则把原生文本提取和视觉解析组合起来。生产系统不该让用户每次猜后端，而应先收集便宜的文档信号：是否有可用文本层、页面是否为扫描件、栏数是否复杂、表格和公式密度、输出是否出现空页或阅读顺序异常。

普通数字文档可以从 pipeline 开始；扫描、图表密集或结构异常的页面再交给 VLM/hybrid。若要按页升级，需要由业务编排层先拆分或抽取页面，分别调用 MinerU，再核对页码、坐标和合并后的产物；这不是一个内置的一键混合后端功能。只有在这层重组可验证时，才值得避免因单页复杂而重跑整本文档。路由规则必须记录原因，否则成本突然上升时只能猜。

批处理架构要先解决幂等

上传接口收到文件后，先计算内容哈希，建立不可变的 source artifact，再创建解析任务。幂等键至少应包含文件哈希、MinerU 版本、后端、模型或配置版本和输出选项。相同键已经成功时直接复用；需要重跑时生成新版本，不能覆盖旧结果。

upload → quarantine → fingerprint → queue
       → pipeline parse → quality checks
       → orchestrator splits pages → separate VLM/hybrid jobs → verified reassembly
       → immutable artifacts → index approval

任务表需要区分 queued、running、retryable、needs-review、accepted 和 rejected。重试只处理可恢复错误；损坏文件、密码保护、超限和持续空输出应该进入明确的终态。这样队列不会反复烧算力，也不会把坏结果悄悄送入知识库。

保存 Markdown 还不够

每次解析至少保留原文件哈希、页数、后端选择、解析器版本、配置摘要、开始/结束时间、Markdown、结构化 JSON、抽取图片及逐页诊断。下游 chunk 还要能反查页码和原始坐标。没有这些数据，表格错列或引用失真时就无法定位是解析、切块还是索引造成的。

3.4.4 release修正了 PDF 字体分析与重复字符检测，也说明输出可能随版本变化。升级应先在固定回归集上比较阅读顺序、标题层级、表格、公式、重复文本和空内容，再决定是否重建索引。

指标必须反映质量和成本

按格式、来源和后端统计成功率、耗时、队列等待与重试次数；
记录页面升级到 VLM/hybrid 的比例及触发原因；
监控空页、重复段落、标题断层、表格缺失、公式缺失和人工退回；
把解析版本写入索引元数据，支持发现回归后定向重跑；
给人工复核保留原页与解析结果并排视图，而不是只看 Markdown。

隐私和许可证不是上线后的补丁

合同、简历、财务资料等文档进入解析服务前要做数据分级。敏感文件应在受控网络内处理，限制任务日志和中间产物的留存，下载模型或调用远端服务也要经过出站策略。解析容器不能默认拥有业务网络和长期凭据。

MinerU 使用的是基于 Apache 2.0、带附加条款的 MinerU Open Source License，不是纯 Apache-2.0。许可证写明：合并月活跃用户超过 1 亿，或上一个自然月合并月收入超过 2000 万美元时，需要另行取得商业许可；向第三方提供基于 MinerU 的在线服务还需进行显著的 MinerU 标识。产品设计、公开文档和法务复核应在上线前完成。

可维护的选择标准

MinerU 适合需要复杂版面、Office 输入、结构化输出和自托管编排的团队。若文档主要是带干净文本层的简单 PDF，本地轻量解析器可能更便宜。若业务不能建立回归集、留存版本信息或提供复核路径，再强的解析模型也只会让错误更难追踪。

选择 pipeline、VLM 或 hybrid 不应是一场一次性的基准测试。把路由、质量门槛、产物版本和许可证边界写进系统，MinerU 才会成为可运营的摄取层，而不是又一个无法解释的转换黑盒。更多参数与部署方式应以官方文档为准。