跳转至

Tier 命名设计

状态:已批准

日期:2026-07-21

目标

将公共解析 Tier 词汇表替换为四个面向用户的级别:

公共字面量 显示名称 中文显示名称 Hybrid 消耗
flash Flash 极速解析 N/A
basic Basic 基础解析 medium
standard Standard 标准解析 high
advanced Advanced 高级解析 xhigh

公共 Tier 与 Hybrid 运行时消耗是两个独立概念。Hybrid 保留其现有的 medium、high 和 xhigh 消耗值、内部分支以及特定于消耗的实现名称。

兼容性策略

这是一次有意的破坏性变更,并附带一次性的数据库安全迁移。

  • 公共输入仅接受 flash、basic、standard 和 advanced。
  • 公共输出仅输出这四个字面量。
  • 已退役的公共 Tier 字面量不会作为别名被接受。
  • 现有 doclib 数据库会被迁移,因此已退役的 Tier 值不会破坏类型化 API 响应。
  • 现有已解析缓存目录不会被重命名或合并,已退役的缓存解析结果会失效。
  • 使用已退役 Tier 字面量的历史定位符将变为无效。
  • 打包 extras 将直接重命名,不提供兼容性 extras。

初始数据库模式在结构上仍然有效,因为 Tier 列是文本字段。模式迁移 v002 会移除对不兼容缓存解析结果的引用,清除已退役的元数据和搜索索引 Tier,并将持久化用户配置映射到新的字面量。代码默认值以及所有新写入的值都使用新的字面量。

数据库迁移

迁移 v002 使现有 doclib 数据库无需保留旧解析产物即可安全打开:

  • 删除 Tier 为 medium、high 或 xhigh 的 parses 行。
  • 删除 Tier 为 medium、high 或 xhigh 的 fts_contents 行。
  • 当 docs.meta_tier 包含已退役 Tier 时,将其设为 NULL。
  • 将解析规则从 medium 映射到 basic,从 high 映射到 standard,从 xhigh 映射到 advanced。
  • 将受管 parse-server 配置从 medium 映射到 basic,并将 high 或 xhigh 映射到 standard。

该迁移不会检查、移动或删除旧缓存目录。这些目录会成为未被引用的产物,可单独删除。历史定位符仍然无效,旧解析结果必须在新 Tier 下重新生成。

选择语义

Tier 质量排序从低到高为:

flash < basic < standard < advanced

针对 parse-server 能力列表的默认质量选择为:

standard -> basic -> error

按以下顺序选择最高缓存非 Flash 结果:

advanced -> standard -> basic

解析规则回退仍以质量为导向,但可能最终落到 Flash:

standard -> basic -> flash

未进行能力发现时的直接本地解析默认为 Standard。Watch 和仅轻量文件行为根据现有文件类型规则继续使用 Flash。

运行时架构

权威 Tier 定义负责公共验证和排序。一个单独的显式映射将模型支持的 Tier 转换为 Hybrid 消耗:

HYBRID_EFFORT_BY_TIER = {
    "basic": "medium",
    "standard": "high",
    "advanced": "xhigh",
}

根据专家选择的 Hybrid 消耗进行反向推断,会返回对应的公共 Tier。代码不得通过将消耗值传给公共 Tier 验证器来校验消耗值。

后端映射保持不变:

  • Flash 使用 Flash 后端。
  • Basic、Standard 和 Advanced 使用 Hybrid 后端及其映射后的消耗值。
  • 旧版专家后端别名保留其运行时含义,但解析为新的公共 Tier 名称。

特定于消耗的实现符号和消息可以在其明确描述 Hybrid 运行时行为时保留消耗字面量。公共 Tier 类型、参数、示例、包 extras、定位符、状态响应、遥测维度以及配置值必须使用新的词汇表。

API 与发现

可复用的本地/自托管 API 服务器继续暴露其配置为运行的任何 Tier。Tier 发现和默认选择逻辑不编码官方云产品策略。

官方 MinerU API 目前仅宣告 Standard。客户端继续信任服务器发现和现有的不匹配处理。自定义远程服务器可以宣告任何受支持的 Tier。

以下公共接口使用新的字面量:

  • Python 解析函数和 MinerUApiParser
  • 解析任务请求与响应模式
  • GET /v1/tiers
  • API 服务器启动选项
  • doclib 请求与响应模型
  • CLI 和 Gradio 选项
  • 模型下载与验证命令

带有 Tier 风格的公共模型元数据不得暴露已退役的 Tier 术语。实际稳定的模型仓库标识符在标识真实仓库而非 Tier 标签时保持不变。

持久化与定位符

新的 doclib 记录在以下位置使用重命名后的 Tier 值:

  • 解析记录
  • 文档元数据质量
  • FTS 内容元数据
  • 解析规则
  • 受管 parse-server 配置
  • 遥测维度

新解析产物继续将 Tier 用作目录组件,现在使用新的字面量。迁移 v002 会使引用旧目录的数据库行失效;不会检查、重命名或合并任何旧目录。

定位符解析器只接受新的字面量,规范定位符也只输出新的字面量:

doc:{short_id}/tier:{tier}
doc:{short_id}/tier:{tier}/page:{page_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}/char:{offset}

打包

历史说明:本节按 tier 划分 extras 的方案已被当前按后端安装的方案替代,下文保留设计历史,不作为安装指引。当前基础包提供 ONNX/llama.cpp,Torch 使用 mineru[torch],Linux vLLM / Windows LMDeploy 使用 mineru[full],显式 MLX 单独安装 mlx-vlm>=0.7.0,<0.8.0。basic、standard 和 advanced 均不是当前安装 extra;测试依赖使用独立的 test extra。详见 当前档位说明。

可选依赖组变为:

  • mineru[basic] 用于 Basic 运行时依赖集
  • mineru[standard] 用于 Basic 加上加速/VLM 依赖
  • Advanced 复用 mineru[standard];不暴露单独的 Advanced extra

Test、all-in-one、Docker 和文档引用使用重命名后的 extras。运行时依赖错误会为 Basic 推荐 Basic,为 Standard 和 Advanced 推荐 Standard。

文档规则

规范性文档、示例、ADR、实现计划、根目录 README 以及捆绑的 MinerU Skill 都使用新的 Tier 词汇。历史命令示例也已更新,因为它们仍然可以被搜索和复制。

对 Hybrid effort 的引用保留 effort 字面量,在可能产生歧义的地方应明确写出 effort。诸如 “high quality” 之类的普通英语短语不是 Tier 字面量,不应机械改写。

验证

验证必须涵盖:

  1. Tier 验证、顺序、默认值和 effort 映射。
  2. 所有四个公共 Tier 的解析器路由。
  3. API 模式、发现元数据、默认值和无效值。
  4. Doclib 解析、搜索、缓存、定位器、配置和遥测。
  5. CLI、mineru-kit、模型命令和 Gradio 选项。
  6. 打包 extras 和 Docker 命令。
  7. 文档和捆绑的 Skill 示例。
  8. 从包含已退役 Tier 值的数据库迁移,包括幂等初始化和迁移后的类型化 API 响应。
  9. 最终残留审计显示,medium、high 和 xhigh 仅作为 Hybrid effort 术语、迁移兼容性数据或普通非 Tier 英语出现。

历史定位器和已解析产物仍有意不支持;迁移测试覆盖数据库安全性,但不断言缓存兼容性。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU