跳转至

Health、Models 与 Tiers

状态: Draft 读者: API 使用者、服务端开发者、SDK 开发者 范围: 服务健康检查、模型发现、解析档位发现 来源: 由根目录旧 Unified API 底稿迁移整理而来

GET /v1/health

健康检查无需鉴权。它只表示 API 服务是否可达,以及当前部署公开哪些外围能力;它不要求对每个下游模型执行深度推理探测。

请求:

GET /v1/health HTTP/1.1

官方 API 响应:

{
  "status": "ok",
  "version": "1.0.0",
  "features": {
    "webhook": true,
    "output_formats": ["markdown", "middle_json", "structured_content", "html", "latex", "docx", "zip"],
    "sources": ["file_id", "url", "inline"]
  }
}

响应字段:

字段 类型 必带 说明
status string 是 固定为 "ok"。如果服务不可用,应由 HTTP 状态码表达,而不是返回其他 status。
version string 是 API 服务版本。
features object 是 当前部署支持的外围能力。
features.webhook bool 是 是否支持 Webhook 回调。
features.output_formats array 是 当前部署支持的 parse job output_formats 值。
features.sources array 是 当前部署允许的 parse job source 类型。

错误:

HTTP code 场景
503 engine_error 类模型预加载错误码 模型预加载未成功,服务尚不能处理请求。本地实现返回 model_preload_dependency_missing、model_preload_files_missing、model_preload_device_unavailable 或 model_preload_failed,type 固定为 engine_error。

GET /v1/models

列出当前服务可发现的模型。该 endpoint 对齐 OpenAI Models API 的基础形态,无需鉴权。anonymous 与 registered 看到同一份模型列表;是否可使用某个能力由具体 endpoint 和 access level 校验。

请求:

GET /v1/models HTTP/1.1

响应:

{
  "object": "list",
  "data": [
    {
      "id": "mineru-4.0.11",
      "object": "model",
      "created": 1700000000,
      "owned_by": "mineru",
      "description": "MinerU virtual model. Quality is selected per request via tier (flash|basic|standard|advanced); this id identifies the server version, not a specific engine."
    }
  ]
}
  • /v1/models 只广告一个虚拟模型:id 为 mineru-<服务版本>,标识服务端版本,不对应任何可单独调用的引擎。解析质量始终通过 parse job 的 tier 字段选择,模型 id 不参与路由。
  • created 为该部署的注册时间(本地 server 取进程启动时刻),同一部署内多次请求返回相同值。
  • 模型列表与启动 --tier、tier 禁用开关无关:档位增减只反映在 /v1/tiers,虚拟模型恒在列表中。
  • 服务端升级后 id 随版本变化(如 mineru-4.0.11 → mineru-4.0.12)。客户端应重新发现,不要缓存 id 硬编码进请求。
  • 历史上广告过的 MinerU-Flash、Hybrid-Basic、MinerU-HTML、MinerU2.5-Pro-2605-1.2B 已从列表移除;这些名字从来不是可传入的参数。其中 MinerU2.5-Pro-2605-1.2B 仍是 standard/advanced 档背后的真实 VLM 权重仓库名,只是不再出现在本 endpoint。

模型对象字段:

字段 类型 必带 说明
id string 是 虚拟模型 ID,mineru-<服务版本>。
object string 是 固定为 "model"。
created integer 是 Unix 秒级时间戳,表示被当前部署注册的时间。
owned_by string 是 官方 API 固定为 "mineru";自部署可使用组织名。
description string 否 模型说明,注明虚拟模型语义与 tier 路由方式。

GET /v1/models/{model}

查询单个模型。

请求:

GET /v1/models/mineru-4.0.11 HTTP/1.1

响应:

{
  "id": "mineru-4.0.11",
  "object": "model",
  "created": 1700000000,
  "owned_by": "mineru",
  "description": "MinerU virtual model. Quality is selected per request via tier (flash|basic|standard|advanced); this id identifies the server version, not a specific engine."
}

仅接受当前部署广告的虚拟模型 id(精确匹配),其余一律 404;服务端升级后旧版本 id 同样返回 404,客户端应重新发现。

错误:

HTTP code 场景
404 model_not_found 模型不存在。

GET /v1/tiers

列出当前服务提供的解析档位。客户端应优先使用 tier,而不是绑定具体模型 ID。服务端可以在不破坏客户端的情况下升级某个 tier 背后的模型版本。

请求:

GET /v1/tiers HTTP/1.1

官方 API 响应:

{
  "object": "list",
  "data": [
    {
      "id": "standard",
      "description": null,
      "current_model": "mineru-4.0.11"
    }
  ]
}

Tier 对象字段:

字段 类型 必带 说明
id string 是 当前服务提供的真实质量 tier,例如 basic、standard 或 advanced。
description string 是 档位说明。
current_model string 或 null 是 当前 tier 背后的模型 ID,与 /v1/models 广告的虚拟模型一致:各档共用同一 id,差异由 id(档位)表达。

Tier 选择语义

v1 协议中面向用户读取文档的质量档位以 解析 Tier 为准。具体服务当前支持哪些 tier,以 /v1/tiers 返回为准。

请求创建 parse job 时,客户端可以省略 tier 或传 null,表示使用 解析 Tier 中定义的默认选择策略。对 PDF/image 这类支持多 tier 的输入,默认选择不能等价于 flash;OFD/EPUB/Office/HTML/MHTML/CSV 按 ADR-0024 与 ADR-0028 的批量规则归一为 flash,其它 text 不作为解析输入。

更完整产品语义见 解析 Tier。

本地 Server 差异

Local Parse Server 的 health 通常返回:

{
  "status": "ok",
  "version": "1.0.0",
  "features": {
    "webhook": false,
    "output_formats": ["markdown", "middle_json", "structured_content", "zip"],
    "sources": ["file_id", "url", "inline"]
  }
}

如果 Local Parse Server 启动时开启 --allow-local-source,features.sources 额外包含 local。

本地 GET /v1/models 和 GET /v1/tiers 必须反映当前 server 实际可用能力。常见组合:

本地 api-server 进程能力 /v1/tiers 应返回
--tier flash flash;默认选择请求应失败,除非显式请求 Flash。
--tier basic flash、basic
--tier basic --no-flash basic
--tier basic --no-advanced flash、basic
--tier standard flash、basic、standard、advanced
--tier standard --no-flash basic、standard、advanced
--tier standard --no-advanced flash、basic、standard
--tier standard --no-flash --no-advanced basic、standard

本地或兼容服务应以 /v1/tiers 返回值作为能力发现事实。客户端不应根据启动参数猜测具体能力。

本地 GET /v1/models 恒返回当前版本的单一虚拟模型。经 Router 聚合多 worker 时,不同版本的 worker 会各自贡献 mineru-<version> 条目:Router 的 /v1/models 出现多个 mineru-* id 表示集群内存在版本漂移(滚动升级未完成),属预期诊断信号而非错误。

如果本地 server 支持 flash,它可以用于显式 flash、仅支持 flash tier 的输入归一化、watch 或索引机制,但不应出现在 PDF/image 面向用户质量解析的默认选择候选中。

mineru.net/api 在相当长时间内只提供 standard。远端 /v1/tiers 因此应返回 standard;省略 tier 或传 null 等价于使用 standard。

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