API 服务器启动层级设计¶
日期:2026-07-21
目标¶
将解析服务器的启动能力层级与公开请求层级分离。服务器以一个能力上限启动,并接受该上限所覆盖的所有请求层级。公开请求 API 继续暴露 flash、basic、standard 和 advanced。
Standard 和 Advanced 具有相同的安装、模型和硬件要求。因此,启动 Standard 服务器也会启用 Advanced 请求。Flash 仍然可用于独立部署和 Gradio 部署,而 Doclib 托管的解析服务器会禁用它,因为 Doclib 在进程内执行 Flash 解析。
启动配置¶
启动级层级是单个值:
flashbasicstandard
Advanced 不是启动级值。它仍然是有效的请求级层级。
当未提供启动层级时,服务器使用 standard。命令行额外暴露一个标志 --no-flash,其默认值为 false。
启动能力扩展如下:
| 启动配置 | 公布的请求层级 |
|---|---|
--tier flash |
flash |
--tier basic |
flash, basic |
--tier basic --no-flash |
basic |
--tier standard |
flash, basic, standard, advanced |
--tier standard --no-flash |
basic, standard, advanced |
--tier flash --no-flash 是无效的,因为它会使服务器不具任何能力。服务器启动必须失败并给出明确的参数冲突错误。
python -m mineru.parser.api_server 和 mineru-kit api-server 都使用这些语义。启动层级选项不再可重复指定。
内部模型¶
实现将启动类型与公开请求类型区分开来。启动类型仅接受 flash、basic 和 standard;请求 Tier 继续接受全部四个公开解析层级。
一个显式且静态可见的映射将启动层级扩展为请求能力。create_app() 接收一个启动层级和一个 no_flash 标志,然后构建:
- 公布的
/v1/tiers元数据; - 请求层级到运行时的映射;
- 默认请求层级;
- 已启用能力的模型元数据。
app.state.tier 表示单一的启动层级。app.state.tiers 和 app.state.tier_runtime_options 表示扩展后的请求能力。app.state.default_tier 保持独立。
依赖预检检查启动上限,而不是每个扩展后的请求层级。Standard 可选依赖组包含 Basic 依赖,Standard 模型集包含 Basic 模型集。Standard 还涵盖 Advanced,因为 Advanced 复用 Standard 的依赖和模型。
请求行为¶
CreateJobRequest.tier、MinerUApiParser.tier 和公开 REST 负载保持不变。
请求路由根据扩展后的启动能力校验请求层级:
- Standard 服务器接受 Basic、Standard 和 Advanced 请求;
- Basic 服务器拒绝 Standard 和 Advanced 请求;
- 使用
--no-flash启动的服务器拒绝显式的 Flash 请求。
--no-flash 具有严格的执行语义。它不仅仅是把 Flash 从 /v1/tiers 中隐藏;它阻止进程运行 Flash 后端。需要 Flash 归一化的输入(如 Office 或 HTML 文件)会被 no-Flash 服务器拒绝,而不是被静默转换为 Flash 执行。
在没有 --no-flash 的情况下,现有的文件类型归一化行为保持不变。
默认请求行为保持不变:
- Standard 服务器默认为 Standard;
- Basic 服务器默认为 Basic;
- 仅 Flash 的服务器保留现有的对 PDF 和图像请求的显式 Flash 要求。
部署模式¶
独立 API 服务器默认以启用 Flash 的 Standard 启动,因此它公布全部四个请求层级。
Gradio 的内嵌 API 服务器使用启用 Flash 的 Standard。因此,其层级发现和下拉菜单继续暴露全部四个公开层级。
Doclib 托管的解析服务器只接受 basic 或 standard 作为 parse_server.local.managed_tier。其子进程命令始终包含 --no-flash:
- 托管的 Basic 公布
basic; - 托管的 Standard 公布
basic、standard和advanced。
数据库中basic 和 standard 之外的值(包括之前的 advanced 值)不会被迁移、删除或重写。它们在运行时被忽略,有效的托管启动层级回退到默认的 standard。新的配置写入会拒绝 basic 和 standard 之外的值。
错误¶
启动时拒绝:
- 不支持的启动层级,包括
advanced; - 冲突的组合
--tier flash --no-flash。
请求处理时拒绝:
- 超出服务器扩展能力的请求层级;
- 在 Flash 被禁用时的显式 Flash 请求;
- 在 Flash 被禁用时需要 Flash 执行的输入。
错误使用现有的 API 错误封装,并标识相关的 tier 或输入参数。不引入任何请求 schema 变更。
文档¶
规范性文档必须将启动层级描述为单一能力上限,将请求层级描述为四值解析选择。更新 API 服务器 CLI 文档、架构与层级文档、相关 ADR 文本、根目录 README.md 和 skills/mineru/SKILL.md。
Advanced 设置说明必须说明要安装 Standard 附加依赖、下载并校验 Standard 模型集、启动或配置 Standard 服务器,并在请求时选择 Advanced。文档不得指示用户启动 Advanced 服务器或设置 parse_server.local.managed_tier advanced。
验证¶
测试覆盖:
- Flash、Basic 和 Standard 启动层级的能力扩展。
- 通过
--no-flash严格移除 Flash。 - 拒绝
--tier flash --no-flash。 - Standard 接受 Advanced 请求,而 Basic 拒绝它们。
- 两个 API 服务器 CLI 入口点中的语义一致。
- 托管子进程接收
--no-flash。 - 托管配置仅接受 Basic 和 Standard。
- 无效的已存储托管层级在不写入数据库的情况下回退到 Standard。
- Gradio 继续发现全部四个公开请求层级。
- 对可重复的启动
--tier、Advanced 启动命令和parse_server.local.managed_tier advanced的文档残留检查。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU