跳转至

API 服务器启动层级设计

日期:2026-07-21

目标

将解析服务器的启动能力层级与公开请求层级分离。服务器以一个能力上限启动,并接受该上限所覆盖的所有请求层级。公开请求 API 继续暴露 flash、basic、standard 和 advanced。

Standard 和 Advanced 具有相同的安装、模型和硬件要求。因此,启动 Standard 服务器也会启用 Advanced 请求。Flash 仍然可用于独立部署和 Gradio 部署,而 Doclib 托管的解析服务器会禁用它,因为 Doclib 在进程内执行 Flash 解析。

启动配置

启动级层级是单个值:

  • flash
  • basic
  • standard

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。

验证

测试覆盖:

  1. Flash、Basic 和 Standard 启动层级的能力扩展。
  2. 通过 --no-flash 严格移除 Flash。
  3. 拒绝 --tier flash --no-flash。
  4. Standard 接受 Advanced 请求,而 Basic 拒绝它们。
  5. 两个 API 服务器 CLI 入口点中的语义一致。
  6. 托管子进程接收 --no-flash。
  7. 托管配置仅接受 Basic 和 Standard。
  8. 无效的已存储托管层级在不写入数据库的情况下回退到 Standard。
  9. Gradio 继续发现全部四个公开请求层级。
  10. 对可重复的启动 --tier、Advanced 启动命令和 parse_server.local.managed_tier advanced 的文档残留检查。

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