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 质量排序从低到高为:
针对 parse-server 能力列表的默认质量选择为:
按以下顺序选择最高缓存非 Flash 结果:
解析规则回退仍以质量为导向,但可能最终落到 Flash:
未进行能力发现时的直接本地解析默认为 Standard。Watch 和仅轻量文件行为根据现有文件类型规则继续使用 Flash。
运行时架构¶
权威 Tier 定义负责公共验证和排序。一个单独的显式映射将模型支持的 Tier 转换为 Hybrid 消耗:
根据专家选择的 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;测试依赖使用独立的testextra。详见 当前档位说明。
可选依赖组变为:
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 字面量,不应机械改写。
验证¶
验证必须涵盖:
- Tier 验证、顺序、默认值和 effort 映射。
- 所有四个公共 Tier 的解析器路由。
- API 模式、发现元数据、默认值和无效值。
- Doclib 解析、搜索、缓存、定位器、配置和遥测。
- CLI、mineru-kit、模型命令和 Gradio 选项。
- 打包 extras 和 Docker 命令。
- 文档和捆绑的 Skill 示例。
- 从包含已退役 Tier 值的数据库迁移,包括幂等初始化和迁移后的类型化 API 响应。
- 最终残留审计显示,
medium、high和xhigh仅作为 Hybrid effort 术语、迁移兼容性数据或普通非 Tier 英语出现。
历史定位器和已解析产物仍有意不支持;迁移测试覆盖数据库安全性,但不断言缓存兼容性。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU