Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

refactor(api): unify tier handling for native documents and update CLI options

myhloli4c9f9df910a3
diff --git a/docs/next/api/changes.md b/docs/next/api/changes.md
index c779a9a0..f7e504f4 100644
--- a/docs/next/api/changes.md
+++ b/docs/next/api/changes.md
@@ -1,5 +1,18 @@
# Tasks 唯一异步接口迁移
+## 单 tier 上限与原生文档统一契约
+
+API 启动改为 `--tier auto|flash|basic|standard|advanced`,移除 `--tiers`,不支持 `--no-flash` 或 `--no-advanced`。上限包含自身和较低档位;standard 不再隐含 advanced,WebUI、Router、Doclib 托管配置同样遵循该规则。
+
+`/v1/tiers` 的响应结构不变,作用范围收敛为 PDF/图片。所有兼容服务均支持现有原生文档格式,固定使用 flash;无需原生能力声明。SaaS 可以只发布 standard,原生文件仍由同一服务处理。Gradio 不再因远端缺少 flash 而启动本地补充服务。
+
+Python `create_app(tiers=...)` 保留精确 PDF/图片集合,模型依赖及预加载仍按实际需求合并。HTTP 请求默认、逐文件实际档位和产物协议保持原规则。
+
+这是一轮能力语义和启动参数升级:先停收并排空在途任务,再协调更新 worker、Router 和客户端。SaaS Go 服务由部署方同步对齐,避免新客户端把原生文件交给仍限制 Flash 的旧服务。模型故障恢复、Doclib 原生执行路径及缓存语义不属于本轮改动。
+
+## 既有 Tasks 接口迁移
+
+
这是破坏性 HTTP 接口升级:独立 `/v1/uploads` 全部路由及 `/v1/parse/jobs` 创建、列表、查询和取消路由已移除,返回 404;不保留别名或客户端自动回退。
| 旧方式 | 新方式 |
diff --git a/docs/next/api/file-parse.md b/docs/next/api/file-parse.md
index 1c7e5265..5edc114b 100644
--- a/docs/next/api/file-parse.md
+++ b/docs/next/api/file-parse.md
@@ -40,7 +40,7 @@ MINERU_API_URL=https://mineru.net/api MINERU_API_KEY=your-key \
未提供 tier 表单字段时,包装层在上游 Tasks 请求中省略该字段,由上游按 **standard → basic → flash** 选择默认档位;advanced 必须显式指定。
显式值原样传递,PDF/图片请求的档位不受上游支持时返回错误,不自动升降档。
-Office、HTML 等已支持的原生文档固定使用 flash,即使传入上游未开放的合法档位也不改变原生解析路径。
+所有正常可用服务都支持 Office、HTML 等现有原生格式,固定使用 flash,即使传入上游未开放的合法档位也不改变原生解析路径。
表单空字符串或字符串 `"null"` 不是省略字段,属于非法值;OpenAPI 将 tier 声明为可省略的字符串枚举,不声明可空值。完整规则见 [Tasks tier 语义](tasks.md#tier默认选择与文件作用范围)。
```bash
diff --git a/docs/next/api/health-models.md b/docs/next/api/health-models.md
index 3724f922..1c2bb9de 100644
--- a/docs/next/api/health-models.md
+++ b/docs/next/api/health-models.md
@@ -67,7 +67,7 @@ GET /v1/models HTTP/1.1
"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."
+ "description": "MinerU virtual model. PDF/image quality is selected per request via tier; native documents always use flash. this id identifies the server version, not a specific engine."
}
]
}
@@ -75,7 +75,7 @@ GET /v1/models HTTP/1.1
- `/v1/models` 只广告一个**虚拟模型**:id 为 `mineru-<服务版本>`,标识服务端版本,不对应任何可单独调用的引擎。解析质量始终通过 Task 的 `tier` 字段选择,模型 id 不参与路由。
- `created` 为该部署的注册时间(本地 server 取进程启动时刻),同一部署内多次请求返回相同值。
-- 模型列表与启动 `--tier`、tier 禁用开关无关:档位增减只反映在 `/v1/tiers`,虚拟模型恒在列表中。
+- 模型列表与启动 `--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。
@@ -107,7 +107,7 @@ GET /v1/models/mineru-4.0.11 HTTP/1.1
"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."
+ "description": "MinerU virtual model. PDF/image quality is selected per request via tier; native documents always use flash. this id identifies the server version, not a specific engine."
}
```
@@ -121,7 +121,7 @@ GET /v1/models/mineru-4.0.11 HTTP/1.1
## GET `/v1/tiers`
-列出当前服务提供的解析档位。客户端应优先使用 tier,而不是绑定具体模型 ID。服务端可以在不破坏客户端的情况下升级某个 tier 背后的模型版本。
+列出当前服务允许 PDF/图片选择的解析档位;所有服务均支持现有原生文档格式并固定使用 flash。客户端应优先使用 tier,而不是绑定具体模型 ID。服务端可以在不破坏客户端的情况下升级某个 tier 背后的模型版本。
请求:
@@ -148,7 +148,7 @@ Tier 对象字段:
| 字段 | 类型 | 必带 | 说明 |
|------|------|:--:|------|
-| `id` | string | 是 | 当前服务提供的真实质量 tier,例如 `basic`、`standard` 或 `advanced`。 |
+| `id` | string | 是 | 当前服务对 PDF/图片开放的质量 tier,例如 `basic`、`standard` 或 `advanced`。 |
| `description` | string | 是 | 档位说明。 |
| `current_model` | string 或 null | 是 | 当前 tier 背后的模型 ID,与 `/v1/models` 广告的虚拟模型一致:各档共用同一 id,差异由 `id`(档位)表达。 |
@@ -156,7 +156,7 @@ Tier 对象字段:
v1 协议中面向用户读取文档的质量档位以 [解析 Tier](../tiers.md) 为准。具体服务当前支持哪些 tier,以 `/v1/tiers` 返回为准。
-请求创建 Task 时,客户端可以省略 `tier` 或传 `null`,表示使用 [解析 Tier](../tiers.md) 中定义的默认选择策略。对 PDF/image 这类支持多 tier 的输入,默认选择不能等价于 `flash`;OFD/EPUB/Office/HTML/MHTML/CSV 按 [ADR-0024](../decisions/0024-file-type-tier-normalization.md) 与 [ADR-0028](../decisions/0028-csv-structured-flash-parsing.md) 的批量规则归一为 `flash`,其它 text 不作为解析输入。
+请求创建 Task 时,客户端可以省略 `tier` 或传 `null`,表示使用 [解析 Tier](../tiers.md) 中定义的默认选择策略。对 PDF/image 按 `standard -> basic -> flash` 选择默认值,advanced 只接受显式请求;OFD/EPUB/Office/HTML/MHTML/CSV 按 [ADR-0024](../decisions/0024-file-type-tier-normalization.md) 与 [ADR-0028](../decisions/0028-csv-structured-flash-parsing.md) 的批量规则归一为 `flash`,其它 text 不作为解析输入。
更完整产品语义见 [解析 Tier](../tiers.md)。
@@ -179,20 +179,19 @@ Local Parse Server 的 `health` 通常返回:
本地 `GET /v1/models` 和 `GET /v1/tiers` 必须反映当前 server 实际可用能力。常见组合:
-| 本地 api-server 进程能力 | `/v1/tiers` 应返回 |
-|-------------------------|-------------------|
-| `--tiers flash` | `flash`;Tasks 省略请求 tier 时使用 flash |
-| `--tiers basic` | `basic` |
-| `--tiers standard` | `standard` |
-| `--tiers flash,standard` | `flash`、`standard` |
-| `--tiers advanced` | `advanced`;请求必须显式指定 tier |
-| `--tiers flash,basic,standard,advanced` | 全部四档;Tasks 默认 standard |
-| `--tiers auto` 或省略 | 启动时的硬件推荐集合,详见 [API 启动文档](../cli/mineru-kit-api-server.md#自动推荐) |
+| 本地 api-server 配置 | `/v1/tiers` 应返回 |
+|----------------------|-------------------|
+| `--tier flash` | `flash` |
+| `--tier basic` | `flash`、`basic` |
+| `--tier standard` | `flash`、`basic`、`standard` |
+| `--tier advanced` | 全部四档;Tasks 默认 standard |
+| `--tier auto` 或省略 | 根据硬件推荐的最高档及全部较低档位 |
+| Python `create_app(tiers={"standard"})` / SaaS 固定策略 | 仅 `standard`;原生文件仍可解析并返回 flash |
本地或兼容服务应以 `/v1/tiers` 返回值作为能力发现事实。客户端不应根据启动参数猜测具体能力。
本地 `GET /v1/models` 恒返回当前版本的单一虚拟模型。经 Router 聚合多 worker 时,不同版本的 worker 会各自贡献 `mineru-<version>` 条目:Router 的 `/v1/models` 出现多个 `mineru-*` id 表示集群内存在版本漂移(滚动升级未完成),属预期诊断信号而非错误。
-如果本地 server 支持 `flash`,它可以用于显式 `flash`、仅支持 flash tier 的输入归一化、watch 或索引机制,但不应出现在 PDF/image 面向用户质量解析的默认选择候选中。
+公开列表中的 flash 只表示 PDF/图片允许显式选择 Flash。原生文档是所有正常可用服务的必备解析能力,不依赖该列表,也不增加独立能力字段。
-`mineru.net/api` 在相当长时间内只提供 `standard`。远端 `/v1/tiers` 因此应返回 `standard`;省略 `tier` 或传 `null` 等价于使用 `standard`。
+`mineru.net/api` 在相当长时间内只提供 `standard`。远端 `/v1/tiers` 因此只返回 `standard`;PDF/图片省略 `tier` 或传 `null` 使用 standard,原生文档固定 flash。
diff --git a/docs/next/api/tasks.md b/docs/next/api/tasks.md
index d7e304a4..682d2d40 100644
--- a/docs/next/api/tasks.md
+++ b/docs/next/api/tasks.md
@@ -1,6 +1,8 @@
# V1 Tasks:JSON 清单、逐文件上传与下载
`/v1/tasks` 是本地 API Server、Router 和 SaaS 的共同异步客户端契约。
+
+`/v1/tiers` 只约束 PDF/图片。所有正常可用的兼容服务均支持现有原生文档格式并固定使用 flash,无需额外能力字段。Router 转发原生文件时省略 tier;PDF/图片转发已确定的档位。
客户端用 JSON 创建任务,按 `files[].upload` 上传缺失文件,再通过固定路径 `GET /v1/tasks/{task_id}` 轮询。
每个文件就绪后立即执行,完成后在 `files[].result_url` 返回独立下载链接。
客户端不拼接存储路径,也不要求 SaaS 实现本地 Files API。
@@ -46,8 +48,8 @@ ModelJson 仅用于内部解析与后处理,不属于 HTTP 或 SDK 结果。
请求包含 PDF/图片且显式提供 tier 时,服务支持该档位就原样使用;不支持则在创建阶段返回 `400 invalid_request`,`error.param="tier"`,整个请求不接单、不分配上传链接,也不自动升档或降档。
空字符串和未知枚举始终是参数错误,包括纯原生文档请求。
-Office、HTML 等已支持的原生文档固定使用 flash,不受请求 tier 影响。纯原生文档批次忽略合法的显式 tier,不要求服务开放该 PDF/图片档位;但仍要求服务具备 flash 原生解析能力。
-例如,部署开放 standard 和 flash 时:
+Office、HTML 等已支持的原生文档固定使用 flash,不受请求 tier 影响。纯原生文档批次忽略合法的显式 tier,不要求服务开放该 PDF/图片档位;原生解析是所有正常可用服务的必备能力,不从 `/v1/tiers` 判断。
+例如,部署只对 PDF/图片开放 standard 时:
| 输入 | 请求 tier | 执行结果 |
|---|---|---|
diff --git a/docs/next/cli/mineru-kit-api-server.md b/docs/next/cli/mineru-kit-api-server.md
index dce6329e..ace7967f 100644
--- a/docs/next/cli/mineru-kit-api-server.md
+++ b/docs/next/cli/mineru-kit-api-server.md
@@ -8,7 +8,7 @@
## 1. 定位
-`mineru-kit api-server` 是正式的 self-hosted parse-server 启动入口。`--tiers` 接受逗号分隔的精确档位集合(`flash/basic/standard/advanced`),或 `auto`;不传时按硬件自动推荐开放集合。
+`mineru-kit api-server` 是正式的 self-hosted parse-server 启动入口。`--tier` 是 PDF/图片的最高开放档位,接受 `flash/basic/standard/advanced/auto`;省略时根据硬件推荐上限。所有服务都支持现有原生文档格式,固定使用 flash。
`mineru doclib` 可以通过 HTTP 调用它执行解析任务。
@@ -41,54 +41,53 @@ api-server 负责:
api-server 必须提供能力发现接口,让 doclib 或客户端知道当前服务支持哪个 tier。
-启动时确定开放集合,能力发现、请求校验和实际执行使用同一集合。显式列表不自动补齐其他档位,并跳过硬件推荐;依赖预检仍照常执行。
+启动上限包含自身及全部较低档位。`/v1/tiers` 仅发布 PDF/图片可选档位,不用于判断原生文档能否解析。
-| api-server 启动配置 | `/v1/tiers` | PDF/image 请求未指定 tier 时 |
+| api-server 启动配置 | PDF/图片公开档位 | PDF/image 请求未指定 tier 时 |
|---------------------|-------------|--------------------|
-| `--tiers flash` | `flash` | `flash` |
-| `--tiers basic` | `basic` | `basic` |
-| `--tiers standard` | `standard` | `standard` |
-| `--tiers flash,standard` | `flash`、`standard` | `standard` |
-| `--tiers advanced` | `advanced` | `503 quality_tier_unavailable`,须显式指定 |
-| `--tiers flash,basic,standard,advanced` | 全部四档 | `standard` |
+| `--tier flash` | `flash` | `flash` |
+| `--tier basic` | `flash`、`basic` | `basic` |
+| `--tier standard` | `flash`、`basic`、`standard` | `standard` |
+| `--tier advanced` | 全部四档 | `standard` |
-Tasks 省略 tier 或传 JSON `null` 时按 `standard -> basic -> flash` 选择默认档位,advanced 必须显式指定。HTTP SDK 和 file_parse 使用同一请求策略。原生文档固定使用 flash;列表未包含 flash 时,OFD/EPUB/Office/HTML/MHTML/CSV/TSV 等需要 Flash 的输入会被拒绝。完整规则见 [Tasks](../api/tasks.md#tier默认选择与文件作用范围)。
+Tasks 的请求 `tier` 仍可选,只对 PDF/图片生效。省略或 JSON `null` 时按 `standard -> basic -> flash` 选择,advanced 必须显式请求。所有服务均支持 OFD/EPUB/Office/HTML/MHTML/CSV/TSV 等现有原生格式,固定使用 flash,不检查公开列表中是否有 flash。非法枚举或空字符串仍报错。完整规则见 [Tasks](../api/tasks.md#tier默认选择与文件作用范围)。
### 自动推荐
-省略 `--tiers` 等价于 `--tiers auto`:
+省略 `--tier` 等价于 `--tier auto`。启动时取推荐集合的最高档作为上限并展开,运行中不重新选档:
-| 硬件条件 | 推荐开放集合 |
-|----------|--------------|
-| 进程可用 CPU 数不足 4,且无达标 GPU | `flash` |
-| 进程可用 CPU 数至少 4,且无达标 GPU | `flash,basic,standard` |
-| 有可用独显、OCR 校准达标的集显,或 Metal 可用的 Apple Silicon | 全部四档 |
+| 硬件条件 | 启动上限 | PDF/图片公开集合 |
+|----------|----------|------------------|
+| 进程可用 CPU 数不足 4,且无达标 GPU | flash | `flash` |
+| 进程可用 CPU 数至少 4,且无达标 GPU | standard | `flash,basic,standard` |
+| 有可用独显、OCR 校准达标的集显,或 Metal 可用的 Apple Silicon | advanced | 全部四档 |
-CPU 数按逻辑 CPU 计算,并考虑进程亲和性和 Linux cgroup 配额。集显沿用现有 OCR 校准的有效性及 GPU 时间不高于 CPU 时间 0.8 倍的判定。Apple Silicon 的 Metal 集显按已知能力直接推荐。探测失败或设备身份不明确时按 CPU 条件推荐。
+CPU 数按逻辑 CPU 计算,并考虑进程亲和性和 Linux cgroup 配额。集显沿用有效 OCR 校准的 GPU 时间不高于 CPU 时间 0.8 倍的判定。探测失败或设备身份不明确时按 CPU 条件推荐。显式上限可以覆盖推荐,随后仍执行正常依赖预检。
-推荐阶段只探测设备并读取已有校准记录,不下载模型、不执行 OCR/VLM 性能测试、不写配置,也不增加内存分级门槛。模型的正常惰性加载和显式 `--preload-models` 行为独立于推荐阶段。
+推荐阶段只探测设备并读取已有校准记录,不下载模型、不执行 OCR/VLM 性能测试、不写配置,也不增加内存分级门槛。实际 OCR 校准把证据保存在 `<配置文件路径>.onnx-calibration.json`,仅复用设备、运行时版本与 CPU 配置匹配的有效结果;旧 cpu/gpu 偏好及手动 GPU 设置不视为校准证据。新证据在下次启动时生效。
-真实 OCR 校准会在当前配置文件旁保存 `<配置文件路径>.onnx-calibration.json`。只有设备身份、后端版本和 CPU 配置匹配、输出一致且结果稳定的记录可用于集显推荐。旧的 `model.onnx_device=cpu/gpu` 偏好及手动 GPU 设置不作为校准证据。记录缺失、损坏或失效时集显不自动开放 advanced,用户仍可通过显式列表启用。新校准结果在下次启动时生效,运行中的服务不会动态增减档位。
+远程 VLM 配置不自动扩大推荐上限。模型正常惰性加载及显式 `--preload-models` 行为与推荐阶段独立。
-远程 VLM 配置不自动扩大推荐集合;部署者可显式指定所需列表。服务开放 advanced 不代表请求默认使用 advanced。
+### 内嵌部署与 SaaS
-### 旧命令迁移
+Python 工厂保留 `create_app(tiers={"standard"})` 的非空精确集合接口。这里的集合只约束 PDF/图片:上述服务只发布 standard,却仍能解析原生文档并返回实际 flash 结果。`tiers=None` 使用硬件推荐上限。空集合、裸字符串和未知档位均报错。
-旧启动参数 `--tier`、`--no-flash`、`--no-advanced` 已移除,传入直接报错。等价迁移如下:
+SaaS 可按共同契约仅发布 standard,原生文档由同一服务解析。无需新增原生能力声明、额外请求字段或本地补充服务。Router 对原生文件仅检查 worker 健康状态、来源和输出格式,转发时省略 tier;PDF/图片继续携带已确定的档位。
-| 旧参数 | 新参数 |
-|--------|--------|
-| `--tier flash` | `--tiers flash` |
-| `--tier basic` | `--tiers flash,basic` |
-| `--tier basic --no-flash` | `--tiers basic` |
-| `--tier standard` | `--tiers flash,basic,standard,advanced` |
-| `--tier standard --no-flash` | `--tiers basic,standard,advanced` |
-| `--tier standard --no-advanced` | `--tiers flash,basic,standard` |
-| `--tier standard --no-flash --no-advanced` | `--tiers basic,standard` |
+### 参数与托管迁移
-Python 工厂使用 `create_app(tiers={"flash", "standard"})`;`tiers=None` 自动推荐。空集合、裸字符串、未知档位及 CLI 中的空项或 `auto` 混用均报错。集合去重后按 `flash/basic/standard/advanced` 顺序发布。
+`--tiers`、`--no-flash`、`--no-advanced` 均不接受,也不保留别名。
-Doclib、WebUI 和 Router 保留现有托管配置语义,启动子进程时转换成等价列表。Doclib 的 basic/standard 分别传入 `basic`、`basic,standard,advanced`,Flash 仍由 Doclib 进程内执行;WebUI 和 Router 继续展开原有 flash/basic/standard 预设。
+| 原完整集合 | 新启动上限 |
+|------------|------------|
+| `--tiers flash` | `--tier flash` |
+| `--tiers flash,basic` | `--tier basic` |
+| `--tiers flash,basic,standard` | `--tier standard` |
+| `--tiers flash,basic,standard,advanced` | `--tier advanced` |
+
+非连续精确集合只用于 Python 工厂或部署方自己的服务配置,不能通过本地 CLI 表达。原 `--tiers standard` 只开放 standard,与新 `--tier standard` 的上限展开语义不同。
+
+WebUI、Router、Doclib 的托管 standard 均只开放到 standard,不再隐含 advanced;需要时显式配置 advanced。默认配置值仍为 standard。Doclib 的 `parse_server.local.managed_tier` 支持 basic、standard、advanced,其原生执行路径保持现状。Advanced 的模型检查与下载使用 Standard 模型配置。
## 4. self-hosted 与 managed
@@ -101,22 +100,22 @@ managed 是生命周期管理方式,不是用户直接执行的命令模式。
## 5. Usage
-api-server 可自动推荐,也可显式指定精确集合:
+启动示例:
```bash
mineru-kit api-server
-mineru-kit api-server --tiers auto
-mineru-kit api-server --tiers flash,standard --port 8000
-mineru-kit api-server --tiers advanced --preload-models
-mineru-api --tiers flash,basic,standard,advanced
-python -m mineru.parser.api_server --tiers flash
+mineru-kit api-server --tier auto
+mineru-kit api-server --tier standard --port 8000
+mineru-kit api-server --tier advanced --preload-models
+mineru-api --tier basic
+python -m mineru.parser.api_server --tier flash
```
-显式集合包含 standard 或 advanced 时,依赖检查与预加载合并使用现有 Standard 模型配置;只有 basic 时使用 Basic 配置。共享模型只加载一次,发布集合仍严格等于指定列表。
+Standard/Advanced 上限复用 Standard 模型配置,Basic 上限使用 Basic 配置,共享模型只预加载一次。原生文档始终保留独立 Flash 执行路径,内部 Flash 能力不会额外开放 PDF 的 Flash 请求。
OCR 模式通过每次 `POST /v1/tasks` 请求的 `ocr_mode` 设置,可选 `auto`、`txt`、`ocr`,省略时为 `auto`。启动参数 `--ocr-mode` 已移除,传入会报错;Python `create_app()` 同样不再接受该参数。
-模型默认在首次解析时懒加载。`--preload-models` 会在 Basic 或 Standard 服务启动时提前初始化所需模型或 VLM 客户端,并在失败时让能力接口返回明确错误;Flash 没有本地模型,该参数对 Flash 无操作。Doclib managed parse-server 会自动启用模型预加载。
+模型默认在首次解析时懒加载。`--preload-models` 会在 Basic、Standard 或 Advanced 服务启动时提前初始化所需模型或 VLM 客户端,并在失败时让能力接口返回明确错误;Flash 没有本地模型,该参数对 Flash 无操作。Doclib managed parse-server 会自动启用模型预加载。
### 服务日志级别
@@ -143,7 +142,7 @@ HTTP 访问日志刷屏。连接外部服务时,其日志级别由服务部署
### 使用远程 MinerU VLM 服务
```bash
-mineru-kit api-server --tiers flash,standard --vlm-server-url http://127.0.0.1:30000/v1
+mineru-kit api-server --tier standard --vlm-server-url http://127.0.0.1:30000/v1
mineru-api --vlm-server-url https://vlm.example.com/proxy/v1 --vlm-model mineru-model --preload-models
```
@@ -189,9 +188,7 @@ Python 可使用 `create_app(vlm_config=VlmConfig(...))` 完整覆盖全局配
### 稳定公开参数
- host / port
-- tier,单值 `flash` / `basic` / `standard`
-- no-flash
-- no-advanced
+- tier,单值 `auto` / `flash` / `basic` / `standard` / `advanced`
- preload-models
- API key
- vlm-server-url / vlm-api-key / vlm-model / vlm-http-timeout / vlm-max-concurrency
diff --git a/docs/next/cli/mineru-kit-parse.md b/docs/next/cli/mineru-kit-parse.md
index 3a5b15f1..ce6977eb 100644
--- a/docs/next/cli/mineru-kit-parse.md
+++ b/docs/next/cli/mineru-kit-parse.md
@@ -151,6 +151,6 @@ remote 模式通过以下参数进入:
| remote 模式 | remote、remote-url、api-key |
| 输出控制 | format、output |
-local 模式的 `ocr-mode`、`disable-image-analysis` 与 `mineru-kit api-server` 一致;`mineru-kit parse --tier` 选择单次解析档位,`api-server --tiers` 则配置四个档位中的任意非空集合,或通过 auto 推荐。`--language` OCR 语言参数已从全部命令移除,传入会报错。
+local 模式的 `ocr-mode`、`disable-image-analysis` 与 `mineru-kit api-server` 一致;`mineru-kit parse --tier` 选择单次解析档位,`api-server --tier` 则选择最高开放档位并包含较低档位,或通过 auto 推荐。`--language` OCR 语言参数已从全部命令移除,传入会报错。
完整决策背景见 [ADR-0016](../decisions/0016-mineru-kit-parse-command.md)。
diff --git a/docs/next/cli/mineru-kit-webui.md b/docs/next/cli/mineru-kit-webui.md
index 529d7456..bb2bc574 100644
--- a/docs/next/cli/mineru-kit-webui.md
+++ b/docs/next/cli/mineru-kit-webui.md
@@ -47,7 +47,7 @@ mineru-kit webui \
--api-key "$MINERU_API_KEY"
```
-未指定 `--api-url` 时,Gradio 会启动一个 loopback `mineru-kit api-server`。本地 server 默认使用 Standard 能力上限、开启 Flash 和 Advanced。所有文件通过 Tasks 提交 hash 清单,缓存未命中时上传,同机也不使用路径免上传。
+未指定 `--api-url` 时,Gradio 会启动一个 loopback `mineru-kit api-server`。本地 server 默认使用 Standard 能力上限,PDF/图片开放 flash、basic、standard;需要 Advanced 时显式配置。原生文档始终支持并固定 flash。所有文件通过 Tasks 提交 hash 清单,缓存未命中时上传,同机也不使用路径免上传。
未指定 `--server-port` 时,界面由 Gradio 从 `7860` 开始寻找空闲端口;可通过 `GRADIO_SERVER_PORT` 设置起始端口、`GRADIO_NUM_PORTS` 设置尝试数量(默认 `100`)。显式指定 `--server-port 7861` 时只尝试该端口,覆盖环境变量;该端口已被占用则启动失败。界面最终访问地址以启动输出为准,与内部 API server 的端口不同。
@@ -60,28 +60,26 @@ mineru-kit webui \
| `--server-name` / `--server-port` | Gradio UI 的监听地址和端口;省略端口时自动寻找空闲端口。 |
| `--output-dir` | 本地 UI 产物根目录,默认 `./output`。 |
| `--max-pages` | 单次 PDF 解析的最多页数,必须为正整数;省略则不限制。不限制非 PDF。 |
-| `--api-server-tier` | 自动启动 server 的能力档位:`flash`、`basic`、`standard`。 |
+| `--api-server-tier` | 自动启动 server 的最高档位:`flash`、`basic`、`standard`、`advanced`。 |
| `--api-server-concurrency` | 自动启动 server 的最大并发任务数。 |
| `--api-server-preload-models` | 在自动启动阶段预加载模型。 |
| `--api-server-disable-image-analysis` | 自动启动 server 时关闭图片分析。 |
| `--enable-example` | 显示当前工作目录 `examples/` 中的示例文件。 |
| `--enable-api` | 暴露 Gradio 转换事件 API。 |
-Gradio 不接受 `--api-server-no-flash`、`--no-flash`、`--api-server-no-advanced`、`--no-advanced`;传入会报错。独立 API 启动命令使用 `--tiers` 精确列表;WebUI 的既有单值托管配置会转换为等价列表。
+Gradio 不接受 `--api-server-no-flash`、`--no-flash`、`--api-server-no-advanced`、`--no-advanced`;传入会报错。独立 API 与 WebUI 的单值托管配置统一表示能力上限,并包含自身和全部较低档位。
-指定外部 `--api-url` 时,Gradio 先校验 `/v1/health` 和 `/v1/tiers`。远程已提供 Flash 时,全部请求使用远程;远程缺少 Flash 时,在运行 Gradio 的机器上自动启动仅提供 Flash 的 loopback V1 API,并完成能力发现后启动界面。Flash 请求只上传至本地服务,其他档位继续使用远程;远程未提供的 Advanced 不会补充。
-
-补充服务固定使用 `--tier flash`,其余托管配置沿用上述参数;远程 API Key 只用于远程客户端,本地服务和客户端使用空密钥。本地服务启动失败会报告启动错误,Gradio 退出时自动清理托管进程和临时目录。能力判断以启动时的声明为准,远程连接或解析失败仍报告原错误,不触发本地重试。
+指定外部 `--api-url` 时,Gradio 校验 `/v1/health` 和 `/v1/tiers` 后直接使用该服务。公开 tiers 只约束 PDF/图片;原生文档同样上传给远端,不因列表中缺少 flash 而启动本地补充服务或增加 PDF 档位。认证只用于所连接服务,连接或解析失败保持原错误。
## 解析流程
界面一次提交一个文件,支持 `filetypes.PARSEABLE_EXTENSIONS` 中的 PDF、图片、Office/ODF、RTF、HTML、MHTML/MHT、CSV/TSV、EPUB 和 OFD。
-解析 tier 使用原生离散滑块选择,上方即时显示当前档位。滑块按 `flash → basic → standard → advanced` 排列,包含远程档位与补充的本地 Flash;未指定远程时使用托管服务的档位。默认优先选择 `standard`,否则选择最高可用档位;仅有一个档位时禁用滑块。
+解析 tier 使用原生离散滑块选择,上方即时显示当前档位。滑块按 `flash → basic → standard → advanced` 排列,只包含所连接服务发布的 PDF/图片档位。默认优先选择 `standard`,否则选择最高可用档位;仅有一个档位时隐藏滑块,保留固定档位说明。
-上传 Office/ODF、RTF、HTML、MHTML/MHT、CSV/TSV、EPUB、OFD 时,tier 自动切到 `flash` 并锁定滑块。界面记住本会话最后一次未锁定的档位,连续更换这类文件不会覆盖记忆;切回 PDF/图片或清除文件时恢复此前选择。PDF/图片之间切换继续保留当前档位。锁定与恢复同时更新档位标签、页码控件和转换按钮,无需向 Python 发送滑块拖动请求。
+上传 Office/ODF、RTF、HTML、MHTML/MHT、CSV/TSV、EPUB、OFD 时,显示固定 `flash` 并隐藏滑块,不要求服务在 tiers 中发布 flash。界面记住本会话最后一次未锁定的档位,连续更换这类文件不会覆盖记忆;切回 PDF/图片或清除文件时恢复此前选择。PDF/图片之间切换继续保留当前档位。锁定与恢复同时更新档位标签、页码控件和转换按钮,无需向 Python 发送滑块拖动请求。
-远程未提供 Flash 时,上述格式自动使用本地 Flash,可以正常转换。转换事件仍校验 `tier_position` 的合法性,并对这些格式强制使用 `flash`。直接调用 Python 构建界面而未接入补充服务时,仍会拒绝不可用档位。
+原生文档不校验隐藏滑块的位置,实际请求固定走原生解析路径;PDF/图片继续校验位置及服务公开的档位。
上传原始 PDF 时,tier 下方显示“强制 OCR”开关,所有档位(包括 Flash)均可使用。默认关闭,提交 `ocr_mode:"auto"` 自动判断;开启时提交 `ocr_mode:"ocr"`,忽略 PDF 文本层并进行 OCR。更换或清除文件会重置开关,同一文件切换 tier 保留选择。图片与其他格式隐藏开关,提交时固定使用 `auto`。
@@ -89,7 +87,7 @@ Gradio 转换事件新增 `force_ocr` 布尔参数,默认 `false`,位于 `ra
OCR 模式由每次 V1 解析任务决定;API Server 不再提供启动时的 OCR 配置,Gradio 的 `--api-server-ocr-mode` 及其 `--ocr-mode` 别名已移除,传入会报错。连接外部 V1 服务时,需要该服务支持任务级 `ocr_mode` 字段。
-启用 Gradio 事件 API 时,转换事件的 `tier_position` 参数为从 `0` 开始的整数位置,替代原来的 tier 字符串。例如四档齐全时 `3` 对应 `advanced`;远程仅支持 `basic/standard` 时,本地补充 Flash 后 `0` 对应 `flash`,`2` 对应 `standard`。位置始终按照上述顺序对实际可用档位编号,越界位置会报错。V1 API 的 `tier` 参数仍使用字符串。
+启用 Gradio 事件 API 时,转换事件的 `tier_position` 参数为从 `0` 开始的整数位置,替代原来的 tier 字符串。例如四档齐全时 `3` 对应 `advanced`;远端仅支持 `basic/standard` 时,`0` 对应 `basic`,`1` 对应 `standard`。位置始终按照上述顺序对实际可用档位编号,越界位置会报错。V1 API 的 `tier` 参数仍使用字符串。
仅在已上传原始 PDF 时显示页码双滑块,所有档位(包括 Flash)一致。轨道范围由 `pypdfium2` 读取的实际页数确定,为 `1~n`,两端对应包含首尾页的连续选区。其他文件格式隐藏控件,并始终全部解析。
diff --git a/docs/next/cli/mineru-kit.md b/docs/next/cli/mineru-kit.md
index 0c0ab9db..1973024f 100644
--- a/docs/next/cli/mineru-kit.md
+++ b/docs/next/cli/mineru-kit.md
@@ -42,7 +42,7 @@
```bash
mineru-openai-server --engine vllm --host 127.0.0.1 --port 30000
mineru-models-download --tier standard --source modelscope
-mineru-api --host 127.0.0.1 --port 8000 --tiers flash,standard
+mineru-api --host 127.0.0.1 --port 8000 --tier standard
```
`mineru-openai-server` 保留向底层引擎透传额外参数的能力。`mineru-models-download` 后直接填写模型仓库名或 `--tier` 等下载参数,不需要再输入 `download`。
@@ -90,7 +90,7 @@ mineru-api --host 127.0.0.1 --port 8000 --tiers flash,standard
- 入口参数包括 `--host`、`--port`、`--reload`、`--upstream-url`、`--local-gpus`、`--worker-host`、`--worker-tier`、`--worker-concurrency`、`--preload-models`。
- `--upstream-url` 可重复,用于接入已有 MinerU V1 API base URL。
- `--local-gpus` 支持 `auto`、`none` 或 GPU CSV,例如 `0,1,2`。
-- 本地 worker 统一启动 `mineru-kit api-server`;`--worker-tier` 默认 `standard`,`--worker-concurrency` 默认 `1`。
+- 本地 worker 统一启动 `mineru-kit api-server`;`--worker-tier` 是包含较低档位的上限,可选 flash/basic/standard/advanced,默认 standard;`--worker-concurrency` 默认 `1`。
- Router 提供 V1 health、models、tiers、usage、按 ID 操作 Files,以及 `/v1/tasks` JSON 创建、按 ID 查询/取消、逐文件上传和结果下载;不提供任务或文件列表。
- Router 只接受显式声明的参数,不再透传未知模型引擎参数;需要额外调优时应部署独立 upstream。
- tasks 与 files 的公共路由状态保存在当前进程内,Router 重启后不保证旧公共 ID 继续可用。
diff --git a/docs/next/config.md b/docs/next/config.md
index 154244ea..52e83337 100644
--- a/docs/next/config.md
+++ b/docs/next/config.md
@@ -250,7 +250,7 @@ SDK client 显式参数属于当前调用方传入的请求上下文;当它最
| key | 默认值 | 说明 |
|-----|--------|------|
| `parse_server.local.mode` | `disabled` | 本地 parse-server 模式 |
-| `parse_server.local.managed_tier` | `standard` | managed 模式启动能力上限,只接受 `basic` 或 `standard`;Standard 同时提供 Advanced 请求能力 |
+| `parse_server.local.managed_tier` | `standard` | managed 模式启动能力上限,接受 `basic`、`standard`、`advanced`,包含自身及较低档位;Advanced 复用 Standard 模型配置 |
| `parse_server.remote.url` | `https://mineru.net/api` | 默认远端 API 地址 |
## 5. Parse-server 配置
diff --git a/docs/next/decisions/0017-mineru-kit-api-server-command.md b/docs/next/decisions/0017-mineru-kit-api-server-command.md
index 2c37a4fe..dc473c79 100644
--- a/docs/next/decisions/0017-mineru-kit-api-server-command.md
+++ b/docs/next/decisions/0017-mineru-kit-api-server-command.md
@@ -44,15 +44,15 @@ managed 是生命周期管理方式,不是用户直接操作的独立命令产
### 3. 单进程 tier 规则
-一个 API 服务进程使用 `--tiers` 配置精确开放集合,接受 `flash/basic/standard/advanced` 的逗号分隔列表,省略等价于 `auto`。旧 `--tier`、`--no-flash`、`--no-advanced` 参数直接移除。
+一个 API 服务进程使用 `--tier auto|flash|basic|standard|advanced` 表示 PDF/图片的最高开放档位,上限包含自身及全部较低档位;省略等价于 auto,取硬件推荐集合的最高档。Standard 上限不再隐含 Advanced。`--tiers`、`--no-flash`、`--no-advanced` 均直接移除。
-自动推荐规则:所有设备推荐 flash;进程可用逻辑 CPU 至少 4 时增加 basic、standard;可用独显、有效 OCR 校准判定更优的集显,或 Metal 可用的 Apple Silicon,推荐全部四档。设备探测失败或校准记录不可用时按 CPU 条件推荐。推荐不加载模型或运行性能测试,不增加内存门槛。
+自动推荐沿用现有 CPU、独显、有效 OCR 校准和 Apple Silicon Metal 规则;不引入新的模型实测或内存门槛。依赖预检与可选预加载仍执行,Advanced 复用 Standard 模型配置。
-显式列表精确决定能力集合,可以覆盖推荐;依赖预检和可选模型预加载仍执行。Standard 与 Advanced 共用模型配置,模型需求合并不扩展公开档位。空集合、未知值、空项和 auto 混用均报错。
+`/v1/tiers` 仅发布 PDF/图片可选档位。所有服务都支持现有原生文档格式,固定使用 flash;原生支持不再从公开 flash 档位推断,不新增原生能力声明。Tasks 请求 tier 继续可选,PDF/图片按 `standard -> basic -> flash` 默认选择,advanced 仅显式使用。
-开放集合在启动时固定。Tasks 请求的单数 `tier` 保持可选,默认顺序为 `standard -> basic -> flash`,advanced 仅显式使用;原生文档始终要求 flash 能力。
+Python 工厂保留非空精确集合 `create_app(tiers=...)`,供内嵌部署和 SaaS 模拟使用;`tiers={"standard"}` 仍支持原生文档。WebUI、Router 和 Doclib 托管配置统一按上限解释,增加显式 advanced 选项;客户端不再补起本地 Flash 服务。
-Python 工厂改为 `create_app(tiers=...)`,None 自动推荐。Doclib、WebUI 和 Router 的托管配置保持原有语义,只把子进程参数转换为等价列表。详细规则及旧命令迁移见 [API 启动文档](../cli/mineru-kit-api-server.md)。
+详细规则及迁移见 [API 启动文档](../cli/mineru-kit-api-server.md)。
### 4. backend 的公开边界
@@ -73,7 +73,7 @@ backend 不是普通 API 协议层字段。
- `--host`
- `--port`
-- `--tiers`
+- `--tier`
- `--api-key`
#### 稳定解析参数
diff --git a/docs/next/decisions/0024-file-type-tier-normalization.md b/docs/next/decisions/0024-file-type-tier-normalization.md
index 27c7c783..982564b5 100644
--- a/docs/next/decisions/0024-file-type-tier-normalization.md
+++ b/docs/next/decisions/0024-file-type-tier-normalization.md
@@ -73,7 +73,7 @@ EPUB、Office、HTML 和 CSV 即使通过高层接口传入了 `basic`、`standa
批量操作中,EPUB/Office/HTML/CSV 的实际 parse row、缓存目录、locator 和 metadata 必须记录 `flash`,不能记录用户传入的质量 tier。其它 text 不得生成这些解析产物。
Tasks 的顶层请求 `tier` 可选,只对 PDF/image 生效。省略或 JSON `null` 时,接单服务按 `standard -> basic -> flash` 选择支持的档位;advanced 必须显式指定,仅有 advanced 时省略 tier 返回 `503 quality_tier_unavailable`。
-显式档位不受支持且批次包含 PDF/image 时,整个创建请求返回 `400 invalid_request`,不自动升降档。纯原生文档忽略合法的显式 tier,固定使用 flash;非法枚举或空字符串仍报参数错误,flash 被禁用时不能解析原生文档。
+显式档位不受支持且批次包含 PDF/image 时,整个创建请求返回 `400 invalid_request`,不自动升降档。纯原生文档忽略合法的显式 tier,固定使用 flash;非法枚举或空字符串仍报参数错误,原生解析是所有正常可用服务的必备能力,不依赖 `/v1/tiers` 是否发布 flash。
选档在接单时保存,后续逐文件执行和 Router 转发使用有效档位,不随 worker 默认值变化。成功结果通过 `files[].parse.tier` 返回真实执行档位,不在顶层回显请求 tier,也不产生伪质量缓存。其它 text 不进入 Tasks 解析。
Tasks 默认选择独立于 Doclib 主动操作的默认质量策略,不改变后者必须显式选择 flash 的规则。
diff --git a/docs/next/glossary.md b/docs/next/glossary.md
index 0f890872..b4189406 100644
--- a/docs/next/glossary.md
+++ b/docs/next/glossary.md
@@ -83,7 +83,7 @@
- 对普通用户只显示 `tier`,不要把 `backend` 作为主选择项。
- 任何 CLI / SDK / API 入口都不接受 `backend` 入参;运行差异由 tier 派生的 effort 表达,不要重新引入 `--backend` 类参数或 backend 派生函数。
- API-backed parser、Doclib SDK、doclib server API 和 v1 API 只面向 `tier`,不应要求用户理解或选择 `backend`。
-- `mineru-kit api-server` 使用 `--tiers` 指定精确开放集合或 auto 硬件推荐;启动后的 HTTP API 通过 `/v1/tiers` 发布实际开放档位。
+- `mineru-kit api-server` 使用 `--tier` 指定包含较低档位的能力上限或 auto 硬件推荐;启动后的 HTTP API 通过 `/v1/tiers` 发布实际开放档位。
- Middle JSON schema 2.0 不记录 `_meta.backend`;产物 metadata 不包含 backend 字段,用户可见语义只记录 `tier`。
- `backend` 不应承担隐私语义;隐私由 `privacy` / `remote` / `via` 描述。
diff --git a/docs/next/open-questions.md b/docs/next/open-questions.md
index fc2607d7..cee3a95f 100644
--- a/docs/next/open-questions.md
+++ b/docs/next/open-questions.md
@@ -38,7 +38,7 @@
| doclib HTTP API | 本地 doclib HTTP API 使用 `/docs`、`/parses`、`/search` 和 `POST /invalidate`,详见 [ADR-0004](decisions/0004-doclib-http-api-resources.md)。 |
| 本地 `standard` | `standard` 本地运行是正式支持能力,不是实验能力;当前代码基本 ready。 |
| mineru.net tier | `mineru.net/api` 在相当长时间内默认提供 `standard` 解析;`standard` 是绝大多数场景足够好的高质量档位,但不是最高档。 |
-| api-server tier | `mineru-kit api-server --tiers` 配置精确集合;省略等价于 auto,按硬件和已有 OCR 校准推荐,HTTP 请求默认仍优先 standard。 |
+| api-server tier | `mineru-kit api-server --tier` 配置最高开放档位;省略等价于 auto,按硬件和已有 OCR 校准推荐上限,HTTP 请求默认仍优先 standard。 |
| managed 生命周期 | managed 模式下,模型下载、预热、重试和退避由 `mineru-kit api-server` 负责。 |
| 本地 api-server 安全 | 本地 api-server 默认监听 loopback;可通过 `--api-key` 设置固定 API Key,默认不设置。 |
| P0 主链路 | P0 包含完整 watch、rules、search,不再把它们标为可选主链路。 |
diff --git a/docs/next/sdk/api-parser.md b/docs/next/sdk/api-parser.md
index 2ccbee32..7b4f358a 100644
--- a/docs/next/sdk/api-parser.md
+++ b/docs/next/sdk/api-parser.md
@@ -13,7 +13,7 @@ print(result.markdown())
构造参数保留 `api_url/api_key/tier/ocr_mode/include_images`。
地址默认读取 `MINERU_API_URL`,否则使用 `https://mineru.net/api`;密钥默认读取 `MINERU_API_KEY`。
`tier=None` 和 `ocr_mode=None` 省略对应请求字段;服务默认 OCR 模式是 `auto`。
-SDK 不自行选择默认 tier:PDF/图片由服务端按 **standard → basic → flash** 选择支持的档位,advanced 必须显式指定。
+`/v1/tiers` 仅描述 PDF/图片档位,原生文档始终可提交给所连接服务并使用 flash。SDK 不自行选择默认 tier:PDF/图片由服务端按 **standard → basic → flash** 选择支持的档位,advanced 必须显式指定。
显式 tier 原样发送,服务不支持该 PDF/图片档位时返回错误,不自动升降档。
Office、HTML 等已支持的原生文档始终使用 flash,忽略合法的显式 tier;单文件 HTTP 调用也遵循 [Tasks 规则](../api/tasks.md#tier默认选择与文件作用范围),与直接本地解析及 Doclib 的选档策略独立。
`parse()` 和 `parse_async()` 均接收 `page_range/status_callback/duration_callback`。
diff --git a/docs/next/tiers.md b/docs/next/tiers.md
index 8c9489f2..80bc48ae 100644
--- a/docs/next/tiers.md
+++ b/docs/next/tiers.md
@@ -19,7 +19,7 @@ MinerU 当前定义四个公开 tier。文档中使用面向用户的显示名
| Standard | `standard` | 标准解析 | 使用少量 VLM 工作,CPU 可运行、GPU 可加速,也是 MinerU 线上 API 提供的档位 |
| Advanced | `advanced` | 高级解析 | 与 Standard 硬件要求相同,但消耗更多算力和时间,困难文档质量更高 |
-`auto` 不是解析请求的公开 tier 值;API 启动参数 `--tiers auto` 专门表示硬件推荐开放集合。CLI 中不传 `--tier`、HTTP API 中省略 `tier` 或传 JSON `null`、Python SDK 中传 `None`,都表示使用当前入口的默认选择策略。
+`auto` 不是解析请求的公开 tier 值;API 启动参数 `--tier auto` 专门表示硬件推荐开放集合。CLI 中不传 `--tier`、HTTP API 中省略 `tier` 或传 JSON `null`、Python SDK 中传 `None`,都表示使用当前入口的默认选择策略。
核心原则:
@@ -54,7 +54,7 @@ MinerU 当前定义四个公开 tier。文档中使用面向用户的显示名
### 3.1 无能力列表的场景
-直接本地解析时,如果当前入口没有可用 tier 列表可参考,默认 tier 是 `standard`。API 服务启动的开放集合独立按 `--tiers` 配置或硬件推荐确定。
+直接本地解析时,如果当前入口没有可用 tier 列表可参考,默认 tier 是 `standard`。API 服务启动的开放集合独立按 `--tier` 上限或硬件推荐确定。
典型场景:
@@ -73,7 +73,7 @@ Doclib 主动解析调用某个 parse-server,或有等价的可用 tier 上下
standard -> basic -> 报错
```
-也就是说,`standard` 是默认优先档位;没有 `standard` 时回退到 `basic`。`advanced` 必须由用户显式指定,不参与默认选择。API 服务可以显式只开放 `advanced`;Doclib 既有 Standard 托管预设仍同时开放 standard 和 advanced。
+也就是说,`standard` 是默认优先档位;没有 `standard` 时回退到 `basic`。`advanced` 必须由用户显式指定,不参与默认选择。内嵌服务可以使用精确集合只开放 advanced;Doclib 的 standard 上限只开放到 standard,需要高级档位时显式配置 advanced。
| 可发现能力 | 默认解析结果 |
|------------|-----------------|
@@ -100,9 +100,9 @@ advanced 只接受显式选择:只有 advanced 时没有默认档位,返回
### 3.4 API 服务启动推荐
-`--tiers auto` 或省略启动参数时:进程可用逻辑 CPU 不足 4 且没有达标 GPU,只开放 flash;CPU 至少 4 时开放 flash、basic、standard;可用独显、有效 OCR 校准达标的集显、或 Metal 可用的 Apple Silicon 开放全部四档。推荐集合在启动时固定,不进行模型性能实测或额外内存分级。
+`--tier auto` 或省略启动参数时:进程可用逻辑 CPU 不足 4 且没有达标 GPU,只开放 flash;CPU 至少 4 时开放 flash、basic、standard;可用独显、有效 OCR 校准达标的集显、或 Metal 可用的 Apple Silicon 开放全部四档。推荐集合在启动时固定,不进行模型性能实测或额外内存分级。
-`--tiers flash,standard` 等显式列表只开放指定档位,允许覆盖推荐。请求默认仍优先 standard,advanced 不参与默认选档。详见 [启动配置与迁移说明](cli/mineru-kit-api-server.md)。
+`--tier standard` 等显式上限开放自身和全部较低档位,允许覆盖硬件推荐。`/v1/tiers` 只约束 PDF/图片,原生文档在任何正常可用服务上均固定使用 flash。请求默认仍优先 standard,advanced 不参与默认选档。详见 [启动配置与迁移说明](cli/mineru-kit-api-server.md)。
## 4. Flash
@@ -124,7 +124,7 @@ Doclib 只有在用户明确指定 `flash` 时,才返回 `flash` 的解析内
`basic` 的核心价值是本地隐私解析:当用户不接受把文档发送到远端解析,同时硬件又不是特别高端时,`basic` 应成为本地可用的最佳默认方案。
-本地 managed parse server 只有 `basic` 和 `standard` 两个启动能力上限,两者建议配置至少 16GB 总内存(建议值,代码不做硬件检查)。Standard 服务同时提供 Standard 和 Advanced 请求能力。低于该基线时,不建议启用本地 managed 质量 tier;应考虑远端解析,或在用户明确接受低质量时显式使用 `flash`。
+本地 Doclib managed parse server 支持 basic、standard、advanced 三个质量上限,standard 不包含 advanced;advanced 复用 Standard 模型配置。内存建议不作为自动推荐的分级门槛。低于该基线时,不建议启用本地 managed 质量 tier;应考虑远端解析,或在用户明确接受低质量时显式使用 `flash`。
## 6. Standard
@@ -153,7 +153,7 @@ Doclib 只有在用户明确指定 `flash` 时,才返回 `flash` 的解析内
- vLLM / LMDeploy 使用 `mineru[full]`,其中 Linux 安装 vLLM,Windows 安装 LMDeploy。
- 显式选择 MLX 时,单独安装 `mlx-vlm>=0.7.0,<0.8.0`。
-使用 `mineru-kit models download --tier standard` 准备模型,并以 Standard 启动 parse-server;解析请求再显式选择 `--tier advanced`。Advanced 不需要也不支持独立的服务启动配置。
+使用 `mineru-kit models download --tier standard` 准备模型,并以 `mineru-kit api-server --tier advanced` 启动服务;解析请求再显式选择 advanced。模型下载档位与服务启动上限是不同概念。
## 8. 隐私优先与质量优先
@@ -178,7 +178,7 @@ MinerU 的 tier 策略同时遵守隐私优先和质量优先。
| 请求 | 默认执行路径 |
|------|--------------|
| watch 自动发现文件 | 本地 `flash` |
-| `mineru-kit api-server` 未传 `--tiers` | 硬件推荐开放集合;HTTP 请求按 standard → basic → flash 选档 |
+| `mineru-kit api-server` 未传 `--tier` | 硬件推荐开放集合;HTTP 请求按 standard → basic → flash 选档 |
| `mineru-kit parse` local 模式未传 `--tier` | PDF/image 直接按 `standard` 解析;OFD/EPUB/Office/HTML/MHTML/CSV/TSV 按 `flash` 语义处理;其它 text 不作为解析输入 |
| watch 命中 parsing-rule 且 rule 指定 tier | PDF 按 rule 中的 tier、页码范围和 remote 配置执行;image 按 tier 和 remote 整文件执行并忽略 page_range;OFD/EPUB/Office/HTML/MHTML/CSV/TSV 忽略 rule tier、page_range 和 remote,按 `flash` 整本解析;其它 text 只入库和索引 |
| watch 命中 parsing-rule 但 rule 未指定 tier | PDF/image 按 `standard` -> `basic` -> `flash` 选择;OFD/EPUB/Office/HTML/MHTML/CSV/TSV 按 `flash`;其它 text 只入库和索引 |
diff --git a/mineru/doclib/background/parse_server_health.py b/mineru/doclib/background/parse_server_health.py
index 90d6e288..1e5f7a15 100644
--- a/mineru/doclib/background/parse_server_health.py
+++ b/mineru/doclib/background/parse_server_health.py
@@ -17,7 +17,7 @@ import httpx
from ...config import LogConfig, ManagedParseServerConfig, get_config
from ...parser.api_client import should_trust_env_for_url
-from ...types import TIERS_BY_SERVER_TIER, DEPLOYMENT_TIERS, TIERS, DeploymentTier, Tier
+from ...types import MANAGED_SERVER_TIERS, TIERS, ManagedServerTier, Tier
from ...parser.process_control import ManagedProcessControl
from ...utils.stdio import utf8_subprocess_env
from ..config_defaults import CONFIG_DEFAULTS
@@ -44,25 +44,25 @@ _NON_RETRYABLE_MODEL_PRELOAD_ERRORS = frozenset(
)
-async def get_managed_parse_server_tier(config_svc: "ConfigService") -> DeploymentTier:
+async def get_managed_parse_server_tier(config_svc: "ConfigService") -> ManagedServerTier:
"""读取 managed parse-server tier;忽略非法存量值并回退到默认值。"""
key = "parse_server.local.managed_tier"
raw_tier = await config_svc.get(key) or CONFIG_DEFAULTS[key]
- if raw_tier in DEPLOYMENT_TIERS:
- return cast(DeploymentTier, raw_tier)
+ if raw_tier in MANAGED_SERVER_TIERS:
+ return cast(ManagedServerTier, raw_tier)
logger.warning(
"Ignoring invalid managed parse-server tier override %r and using default %r",
raw_tier,
CONFIG_DEFAULTS[key],
)
- return cast(DeploymentTier, CONFIG_DEFAULTS[key])
+ return cast(ManagedServerTier, CONFIG_DEFAULTS[key])
-def api_server_args_for_tier(tier: DeploymentTier, *, host: str, port: int) -> list[str]:
- """把既有 Doclib 托管配置转换为等价的显式档位集合,继续排除 Flash。"""
+def api_server_args_for_tier(tier: ManagedServerTier, *, host: str, port: int) -> list[str]:
+ """按统一上限启动托管服务,原生文档解析不受公开档位限制。"""
return [
- "--tiers",
- ",".join(item for item in TIERS_BY_SERVER_TIER[tier] if item != "flash"),
+ "--tier",
+ tier,
"--host",
host,
"--port",
@@ -142,7 +142,7 @@ def open_managed_parse_server_logs(*, marker: str, log_cfg: LogConfig | None = N
def start_managed_parse_server(
*,
- tier: DeploymentTier,
+ tier: ManagedServerTier,
managed_cfg: ManagedParseServerConfig,
log_cfg: LogConfig | None,
marker: str,
@@ -425,7 +425,7 @@ class ParseServerHealthCheck:
async def _try_restart_managed_for_tier_change(
self,
health: ParseServerHealth,
- desired_managed_tier: DeploymentTier,
+ desired_managed_tier: ManagedServerTier,
) -> bool:
running_managed_tier = health.running_managed_tier
if running_managed_tier is None or running_managed_tier == desired_managed_tier:
diff --git a/mineru/doclib/config_schema.py b/mineru/doclib/config_schema.py
index 27688c3f..eaab91dc 100644
--- a/mineru/doclib/config_schema.py
+++ b/mineru/doclib/config_schema.py
@@ -5,7 +5,7 @@ from __future__ import annotations
from urllib.parse import urlparse
from ..errors import InvalidRequestError
-from ..types import DEPLOYMENT_TIERS
+from ..types import MANAGED_SERVER_TIERS
from .config_defaults import CONFIG_DEFAULTS
LOCAL_PARSE_SERVER_MODES = ("disabled", "managed", "self_hosted")
@@ -23,7 +23,7 @@ def validate_config_value(key: str, value: str) -> None:
_validate_enum_value(key, value, LOCAL_PARSE_SERVER_MODES)
return
if key == "parse_server.local.managed_tier":
- _validate_enum_value(key, value, DEPLOYMENT_TIERS)
+ _validate_enum_value(key, value, MANAGED_SERVER_TIERS)
return
if key in URL_CONFIG_KEYS:
allow_empty = key == "parse_server.local.self_hosted_url"
diff --git a/mineru/doclib/parse_server_state.py b/mineru/doclib/parse_server_state.py
index a77fda7d..30dd8c1b 100644
--- a/mineru/doclib/parse_server_state.py
+++ b/mineru/doclib/parse_server_state.py
@@ -6,7 +6,7 @@ import subprocess
from dataclasses import dataclass, field
from typing import TYPE_CHECKING
-from ..types import DeploymentTier, Tier
+from ..types import ManagedServerTier, Tier
if TYPE_CHECKING:
from ..parser.process_control import ManagedProcessControl
@@ -45,15 +45,15 @@ class ParseServerHealth:
local_mode: str = "disabled"
self_hosted_url: str | None = None
managed_url: str = DEFAULT_MANAGED_URL
- managed_tier: DeploymentTier | None = None
- running_managed_tier: DeploymentTier | None = None
+ managed_tier: ManagedServerTier | None = None
+ running_managed_tier: ManagedServerTier | None = None
restart_count: int = 0
managed_proc: subprocess.Popen | None = None
managed_control: ManagedProcessControl | None = None
managed_tier_transition: bool = False
local_generation: int = 0
- def begin_managed_tier_transition(self, tier: DeploymentTier) -> None:
+ def begin_managed_tier_transition(self, tier: ManagedServerTier) -> None:
"""立即撤销旧服务的可用状态;保留子进程真实启动状态以正确计算停止预算。"""
self.managed_tier = tier
self.managed_tier_transition = True
diff --git a/mineru/doclib/server.py b/mineru/doclib/server.py
index a0ae64ff..42040132 100644
--- a/mineru/doclib/server.py
+++ b/mineru/doclib/server.py
@@ -28,9 +28,10 @@ from ..parser.page_range import (
parse_page_range_set,
)
from ..parser.tier import TierDependencyError, ensure_tier_runtime_dependencies
+from ..parser.server_tiers import model_tier_for_server_tiers
from ..types import (
- DEPLOYMENT_TIERS,
- DeploymentTier,
+ MANAGED_SERVER_TIERS,
+ ManagedServerTier,
Tier,
)
from ..version import __version__
@@ -1193,17 +1194,23 @@ def _parse_server_status(
)
-def _ensure_managed_parse_server_tier_available(tier: DeploymentTier, param: str) -> None:
+def _ensure_managed_parse_server_tier_available(tier: ManagedServerTier, param: str) -> None:
+ """按托管上限检查模型配置,Advanced 复用 Standard 依赖。"""
+ model_tier = model_tier_for_server_tiers((tier,))
+ assert model_tier is not None
try:
- ensure_tier_runtime_dependencies(tier)
+ ensure_tier_runtime_dependencies(model_tier)
except TierDependencyError as exc:
raise InvalidRequestError("parse_server_dependency_missing", str(exc), param) from exc
_ensure_managed_parse_server_models_ready(tier, param)
-def _ensure_managed_parse_server_models_ready(tier: DeploymentTier, param: str) -> None:
+def _ensure_managed_parse_server_models_ready(tier: ManagedServerTier, param: str) -> None:
+ """检查上限所需的共享模型,并给出真实可用的模型下载参数。"""
+ model_tier = model_tier_for_server_tiers((tier,))
+ assert model_tier is not None
missing_repos: list[str] = []
- for repo in model_repos_for_tier(tier):
+ for repo in model_repos_for_tier(model_tier):
result = verify_model_repo(repo)
if result.ready:
continue
@@ -1216,7 +1223,7 @@ def _ensure_managed_parse_server_models_ready(tier: DeploymentTier, param: str)
raise InvalidRequestError(
"parse_server_model_not_ready",
f"Local managed tier '{tier}' requires model files that are not ready. {details}. "
- f"Run: mineru-kit models download --tier {tier}",
+ f"Run: mineru-kit models download --tier {model_tier}",
param,
)
@@ -1226,14 +1233,14 @@ def _format_missing_model_repo(repo: ModelRepo, missing_paths: list[str]) -> str
return f"{repo.name} missing: {missing}"
-def _validate_managed_parse_server_tier(value: str, param: str) -> DeploymentTier:
- if value not in DEPLOYMENT_TIERS:
+def _validate_managed_parse_server_tier(value: str, param: str) -> ManagedServerTier:
+ if value not in MANAGED_SERVER_TIERS:
raise InvalidRequestError(
"invalid_config_value",
- "parse_server.local.managed_tier must be one of: basic, standard.",
+ "parse_server.local.managed_tier must be one of: basic, standard, advanced.",
param,
)
- return cast(DeploymentTier, value)
+ return cast(ManagedServerTier, value)
def _port_from_url(url: str | None) -> int | None:
diff --git a/mineru/kit/commands/api_server.py b/mineru/kit/commands/api_server.py
index aeda3e21..3570808a 100644
--- a/mineru/kit/commands/api_server.py
+++ b/mineru/kit/commands/api_server.py
@@ -14,8 +14,8 @@ def api_server_cmd(
host: str = typer.Option("127.0.0.1", "--host", help=t("Server host")),
port: int = typer.Option(8000, "--port", help=t("Server port")),
upload_dir: str = typer.Option("", "--upload-dir", help=t("Upload directory")),
- tiers: str = typer.Option(
- "auto", "--tiers", help=t("Exact tiers: flash,basic,standard,advanced; or auto for hardware recommendations")
+ tier: str = typer.Option(
+ "auto", "--tier", help=t("PDF/image tier ceiling: flash, basic, standard, advanced; or auto")
),
retention_seconds: int | None = typer.Option(
None,
@@ -77,8 +77,8 @@ def api_server_cmd(
str(concurrency),
"--url-timeout",
str(url_timeout),
- "--tiers",
- tiers,
+ "--tier",
+ tier,
*vlm_args,
*(["--allow-http-source"] if allow_http_source else []),
*(["--upload-dir", upload_dir] if upload_dir else []),
diff --git a/mineru/kit/commands/webui.py b/mineru/kit/commands/webui.py
index 45847430..c12db0db 100644
--- a/mineru/kit/commands/webui.py
+++ b/mineru/kit/commands/webui.py
@@ -71,7 +71,7 @@ def webui_cmd(
enable_example: bool = typer.Option(True, "--enable-example/--no-enable-example", help=t("Show local examples")),
enable_api: bool = typer.Option(True, "--enable-api/--no-enable-api", help=t("Expose the Gradio event API")),
api_server_tier: str = typer.Option(
- "standard", "--api-server-tier", "--tier", help=t("Managed API server capability tier")
+ "standard", "--api-server-tier", "--tier", help=t("Managed API server tier ceiling")
),
api_server_concurrency: int = typer.Option(
1, "--api-server-concurrency", "--concurrency", help=t("Managed server job concurrency")
diff --git a/mineru/kit/gradio/app.py b/mineru/kit/gradio/app.py
index 52cb1d0b..6296cb3f 100644
--- a/mineru/kit/gradio/app.py
+++ b/mineru/kit/gradio/app.py
@@ -422,6 +422,7 @@ def build_gradio_app(
step=1,
precision=0,
interactive=len(tier_choices) > 1,
+ visible=len(tier_choices) > 1,
label=i18n("mineru.tier"),
show_label=False,
elem_classes=["mineru-tier-slider"],
@@ -1129,7 +1130,7 @@ def launch_gradio(
api_server_preload_models: bool,
max_pages: int | None = None,
) -> None:
- """启动 Gradio,并在外部服务缺少 Flash 时托管本地 Flash V1 服务。"""
+ """连接外部服务或托管一个本地服务,原生文档始终由同一服务解析。"""
configure_standard_streams()
configure_global_log_level()
validate_max_pages(max_pages)
@@ -1149,19 +1150,8 @@ def launch_gradio(
)
resolved_api_url = managed_server.start()
client = V1ArtifactClient(api_url=resolved_api_url, api_key=resolved_api_key)
- capabilities = asyncio.run(client.discover())
- local_flash: V1ArtifactClient | None = None
- if api_url is not None and "flash" not in capabilities.tiers:
- managed_server = ManagedLocalApiServer(
- tier="flash",
- concurrency=api_server_concurrency,
- disable_image_analysis=api_server_disable_image_analysis,
- preload_models=api_server_preload_models,
- api_key="",
- )
- local_flash = V1ArtifactClient(api_url=managed_server.start(), api_key="")
- asyncio.run(local_flash.discover())
- routed_client = GradioArtifactClient(client, local_flash=local_flash)
+ asyncio.run(client.discover())
+ routed_client = GradioArtifactClient(client)
demo = build_gradio_app(
routed_client,
routed_client.capabilities,
diff --git a/mineru/kit/gradio/client.py b/mineru/kit/gradio/client.py
index e4a65097..0cc0ecd7 100644
--- a/mineru/kit/gradio/client.py
+++ b/mineru/kit/gradio/client.py
@@ -10,7 +10,7 @@ import sys
import tempfile
import time
from collections.abc import Callable
-from dataclasses import dataclass, replace
+from dataclasses import dataclass
from pathlib import Path
from typing import Any, Literal, cast
@@ -20,7 +20,8 @@ from ...parser.api_client import ApiTaskStatus, MinerUApiParser, should_trust_en
from ...parser.base import ParseResult
from ...parser.page_range import normalize_page_range_input
from ...parser.process_control import ManagedProcessControl
-from ...types import TIERS_BY_SERVER_TIER, SERVER_TIERS, TIERS, ServerTier, Tier
+from ...types import SERVER_TIERS, TIERS, ServerTier, Tier
+from ...filetypes import is_flash_only_parse_extension
from ...utils.stdio import utf8_subprocess_env
from .status import (
STATUS_CHECKING_SERVER,
@@ -200,14 +201,15 @@ class V1ArtifactClient:
if self._capabilities is None:
emit(STATUS_CHECKING_SERVER)
await self.discover()
- if self._capabilities is None or tier not in self._capabilities.tiers:
+ native_document = is_flash_only_parse_extension(path)
+ if self._capabilities is None or (not native_document and tier not in self._capabilities.tiers):
raise V1ArtifactError(f"Tier '{tier}' is not available in the configured V1 API server", code="tier_unavailable")
emit(STATUS_SUBMITTING_TASK)
parser = MinerUApiParser(
api_url=self.base_url,
api_key=self.api_key,
- tier=cast(Tier, tier),
+ tier=None if native_document else cast(Tier, tier),
ocr_mode=ocr_mode,
include_images=True,
)
@@ -252,23 +254,18 @@ class V1ArtifactClient:
class GradioArtifactClient:
- """合并已发现的服务能力,并将缺失的 Flash 请求路由到本地 V1 服务。"""
+ """使用唯一连接服务解析文件,公开档位只约束 PDF/图片。"""
- def __init__(self, primary: V1ArtifactClient, *, local_flash: V1ArtifactClient | None = None) -> None:
- """根据独立能力快照建立明确的档位映射,不修改任何服务声明。"""
- capabilities = primary.capabilities
- if capabilities is None:
+ def __init__(self, primary: V1ArtifactClient) -> None:
+ """保存已发现的服务与能力快照,不合并额外的本地 Flash 服务。"""
+ if primary.capabilities is None:
raise ValueError("Discover the primary V1 API capabilities before constructing the Gradio client")
- self._clients_by_tier = dict.fromkeys(capabilities.tiers, primary)
- if local_flash is not None and "flash" not in self._clients_by_tier:
- if local_flash.capabilities is None or "flash" not in local_flash.capabilities.tiers:
- raise V1ArtifactError("The local V1 API server did not advertise Flash", code="tier_unavailable")
- self._clients_by_tier["flash"] = local_flash
- self._capabilities = replace(capabilities, tiers=tuple(tier for tier in TIERS if tier in self._clients_by_tier))
+ self._primary = primary
+ self._capabilities = primary.capabilities
@property
def capabilities(self) -> V1ServerCapabilities:
- """返回供界面使用的有效档位集合,主服务地址和协议能力保持原值。"""
+ """返回所连接服务实际发布的 PDF/图片档位及协议能力。"""
return self._capabilities
async def parse_file(
@@ -280,13 +277,8 @@ class GradioArtifactClient:
ocr_mode: Literal["auto", "txt", "ocr"] = "auto",
status_callback: Callable[[str | ParseStatusUpdate], None] | None = None,
) -> ParseResult:
- """仅向该档位对应的服务提交文件,复用原有状态、取消和产物流程。"""
- if tier not in TIERS:
- raise V1ArtifactError(f"Unsupported parse tier: {tier}", code="invalid_request")
- client = self._clients_by_tier.get(tier)
- if client is None:
- raise V1ArtifactError(f"Tier '{tier}' is not available in Gradio", code="tier_unavailable")
- return await client.parse_file(
+ """文件类型与档位校验由唯一 V1 客户端完成,复用取消和产物流程。"""
+ return await self._primary.parse_file(
path, tier=tier, page_range=page_range, ocr_mode=ocr_mode, status_callback=status_callback
)
@@ -428,8 +420,8 @@ class ManagedLocalApiServer:
str(port),
"--upload-dir",
str(upload_dir),
- "--tiers",
- ",".join(TIERS_BY_SERVER_TIER[self.tier]),
+ "--tier",
+ self.tier,
"--concurrency",
str(self.concurrency),
"--log-level",
diff --git a/mineru/kit/gradio/conversion_service.py b/mineru/kit/gradio/conversion_service.py
index 81448fef..57c5af13 100644
--- a/mineru/kit/gradio/conversion_service.py
+++ b/mineru/kit/gradio/conversion_service.py
@@ -144,14 +144,14 @@ class ConversionService:
suffix = source_path.suffix.lower().lstrip(".")
if suffix not in PARSEABLE_EXTENSIONS:
raise ValueError(f"unsupported file type '.{suffix}'")
- position = inputs.tier_position
- if isinstance(position, bool) or position not in range(len(self.tier_choices)):
- raise ValueError("Invalid tier slider position")
- selected_tier = self.tier_choices[int(position)]
if suffix in FLASH_ONLY_PARSE_EXTENSIONS:
- if "flash" not in self.tier_choices:
- raise ValueError("tier_unavailable: 该格式仅支持 Flash,当前服务不可用")
- selected_tier = "flash"
+ # 原生文档独立于 PDF/图片滑块,隐藏控件的旧值不能影响提交。
+ selected_tier: Tier = "flash"
+ else:
+ position = inputs.tier_position
+ if isinstance(position, bool) or position not in range(len(self.tier_choices)):
+ raise ValueError("Invalid tier slider position")
+ selected_tier = self.tier_choices[int(position)]
return _ValidatedInput(source_path, suffix, selected_tier)
async def _convert(
diff --git a/mineru/kit/router/cli.py b/mineru/kit/router/cli.py
index beeebdd0..6c003351 100644
--- a/mineru/kit/router/cli.py
+++ b/mineru/kit/router/cli.py
@@ -28,7 +28,9 @@ def router_cmd(
),
local_gpus: str = typer.Option("auto", "--local-gpus", help=t("Local workers: auto, none, or GPU CSV")),
worker_host: str = typer.Option("127.0.0.1", "--worker-host", help=t("Host for managed api-server workers")),
- worker_tier: str = typer.Option("standard", "--worker-tier", help=t("Managed worker tier: flash, basic, standard")),
+ worker_tier: str = typer.Option(
+ "standard", "--worker-tier", help=t("Managed worker tier ceiling: flash, basic, standard, advanced")
+ ),
worker_concurrency: int = typer.Option(1, "--worker-concurrency", help=t("Concurrency per managed worker")),
retention_seconds: int | None = typer.Option(
None,
diff --git a/mineru/kit/router/tasks.py b/mineru/kit/router/tasks.py
index b23f11d6..f65197fa 100644
--- a/mineru/kit/router/tasks.py
+++ b/mineru/kit/router/tasks.py
@@ -293,12 +293,11 @@ class RouterTaskBackend:
checked_workers: set[str] = set()
for item in inputs:
lightweight = is_flash_only_parse_extension(item.file_name)
- selection_tier = batch_effective_parse_tier(options.tier, item.file_name)
+ selection_tier = None if lightweight else options.tier
candidates = self.pool.capable_workers(
tier=selection_tier,
required_sources={"url" if item.url is not None else "upload"},
required_task_outputs=set(options.output_formats),
- require_flash=lightweight,
)
if not candidates:
raise_api_error(
@@ -391,10 +390,9 @@ class RouterTaskBackend:
lightweight = is_flash_only_parse_extension(item.file_name)
tier = batch_effective_parse_tier(options.tier, item.file_name)
reservation = self.pool.reserve_job(
- tier=tier,
+ tier=None if lightweight else tier,
required_sources={"url" if item.url is not None else "upload"},
required_task_outputs=set(options.output_formats),
- require_flash=lightweight,
)
if reservation is None:
raise_api_error(
@@ -418,7 +416,7 @@ class RouterTaskBackend:
request=self.request,
json_body={
"files": [worker_input],
- "tier": tier,
+ **({"tier": tier} if not lightweight else {}),
"ocr_mode": options.ocr_mode,
"output_formats": options.output_formats,
},
diff --git a/mineru/kit/router/workers.py b/mineru/kit/router/workers.py
index 36f7d13e..36caf6ea 100644
--- a/mineru/kit/router/workers.py
+++ b/mineru/kit/router/workers.py
@@ -21,7 +21,7 @@ from loguru import logger
from ...model.runtime.device import get_device
from ...parser.process_control import ManagedProcessControl
-from ...types import TIERS_BY_SERVER_TIER, SERVER_TIERS, ServerTier, Tier
+from ...types import SERVER_TIERS, ServerTier, Tier
from ...utils.stdio import utf8_subprocess_env
from ...utils.retention import resolve_retention_seconds
@@ -205,8 +205,8 @@ class ManagedLocalWorker:
str(port),
"--upload-dir",
str(upload_dir),
- "--tiers",
- ",".join(TIERS_BY_SERVER_TIER[self.settings.worker_tier]),
+ "--tier",
+ self.settings.worker_tier,
"--concurrency",
str(self.settings.worker_concurrency),
"--retention-seconds",
@@ -519,7 +519,6 @@ class WorkerPool:
required_sources: set[str] | None = None,
preferred_worker_id: str | None = None,
required_task_outputs: set[str] | None = None,
- require_flash: bool = False,
selection_kind: Literal["upload", "job"] = "job",
) -> WorkerState | None:
"""按能力和负载选取目标,文件归属仅在最低负载候选中优先。"""
@@ -527,7 +526,6 @@ class WorkerPool:
tier=tier,
required_sources=required_sources,
required_task_outputs=required_task_outputs,
- require_flash=require_flash,
)
if not eligible:
return None
@@ -553,7 +551,6 @@ class WorkerPool:
tier: Tier | None,
required_sources: set[str] | None = None,
required_task_outputs: set[str] | None = None,
- require_flash: bool = False,
) -> list[WorkerState]:
"""只读过滤完整能力组合,供预检复用;不改变轮询游标或预占负载。"""
return [
@@ -562,17 +559,15 @@ class WorkerPool:
if (tier is None or tier in worker.tiers)
and (required_sources or set()).issubset(set(worker.features.get("sources") or []))
and (required_task_outputs or set()).issubset(set(worker.features.get("task_output_formats") or []))
- and (not require_flash or "flash" in worker.tiers)
]
def reserve_job(
self,
*,
- tier: Tier,
+ tier: Tier | None,
required_sources: set[str],
preferred_worker_id: str | None = None,
required_task_outputs: set[str] | None = None,
- require_flash: bool = False,
) -> JobReservation | None:
"""在第一次网络等待前同步选择并预占解析 worker。"""
worker = self.select(
@@ -580,7 +575,6 @@ class WorkerPool:
required_sources=required_sources,
preferred_worker_id=preferred_worker_id,
required_task_outputs=required_task_outputs,
- require_flash=require_flash,
)
if worker is None:
return None
diff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.py
index 8cfd24c3..9a87b762 100644
--- a/mineru/parser/api_server.py
+++ b/mineru/parser/api_server.py
@@ -69,7 +69,7 @@ from .page_range import (
format_page_range as _compact_page_numbers,
)
from .process_control import ManagedProcessControlWatcher
-from .server_tiers import model_tier_for_server_tiers, parse_server_tiers, resolve_server_tiers
+from .server_tiers import model_tier_for_server_tiers, parse_server_tier, resolve_server_tiers
from .tier import (
ParserRuntimeOptions,
TierDependencyError,
@@ -208,7 +208,7 @@ class HealthResponse(BaseModel):
# 不对应任何可单独调用的引擎。
_VIRTUAL_MODEL_ID = f"mineru-{__version__}"
_VIRTUAL_MODEL_DESCRIPTION = (
- "MinerU virtual model. Quality is selected per request via tier (flash|basic|standard|advanced); "
+ "MinerU virtual model. PDF/image quality is selected per request via tier; native documents always use flash. "
"this id identifies the server version, not a specific engine."
)
@@ -1205,7 +1205,6 @@ async def _run_execution(
url_timeout: int = 60,
allow_http_source: bool = False,
max_url_bytes: int = _MAX_URL_BYTES_DEFAULT,
- flash_enabled: bool = True,
vlm_config: VlmConfig | None = None,
execution_store: ExecutionStore | None = None,
) -> None:
@@ -1243,8 +1242,6 @@ async def _run_execution(
suffix = ".html"
if not stype:
raise ValueError(f"Unsupported file type: {req.file_name}")
- if not flash_enabled and is_flash_only_parse_extension(stype):
- raise ValueError("Flash parsing is disabled in this server, but this input requires the Flash backend")
suffix = suffix or ".pdf"
tmp_path = pathlib.Path(tmpdir) / f"input_0{suffix}"
@@ -1450,7 +1447,7 @@ async def get_model(
tags=["Tiers"],
)
async def list_tiers(request: Request) -> TierListResponse:
- """List all available parser tiers."""
+ """发布 PDF/图片可选档位;原生文档的固定 Flash 能力不由该列表控制。"""
_require_model_preload_ready(request)
tiers: list[TierInfoData] = request.app.state.tiers
return TierListResponse(
@@ -1545,14 +1542,9 @@ async def submit_execution(
_require_model_preload_ready(request)
default_tier: Tier | None = request.app.state.default_tier
can_default_to_flash = _execution_can_default_to_flash(body)
- if not request.app.state.flash_enabled and _execution_requires_flash(body):
- raise_api_error(
- 400,
- error_type="invalid_request_error",
- code="invalid_request",
- message="Flash parsing is disabled in this server, but one or more inputs require the Flash backend",
- param="files",
- )
+ native_document = _execution_requires_flash(body)
+ if native_document:
+ body.tier = "flash"
if body.tier is None and default_tier is None:
if can_default_to_flash:
body.tier = "flash"
@@ -1569,9 +1561,10 @@ async def submit_execution(
else:
body.tier = body.tier or default_tier
runtime_options: dict[Tier, ParserRuntimeOptions] = request.app.state.tier_runtime_options
- runtime = runtime_options.get(body.tier)
+ # 公开 runtime 表仅约束 PDF/图片;原生文档始终走独立 Flash 路径。
+ runtime = runtime_options_for_tier("flash") if native_document else runtime_options.get(body.tier)
if runtime is None and can_default_to_flash:
- runtime = runtime_options.get("flash") or runtime_options_for_tier("flash")
+ runtime = runtime_options_for_tier("flash")
if runtime is None:
raise_api_error(
400,
@@ -1587,7 +1580,6 @@ async def submit_execution(
url_timeout_val: int = request.app.state.url_timeout
allow_http_source_val: bool = request.app.state.allow_http_source
max_url_bytes_val: int = request.app.state.max_url_bytes
- flash_enabled_val: bool = request.app.state.flash_enabled
image_analysis_val: bool = request.app.state.image_analysis
vlm_config_val: VlmConfig = request.app.state.vlm_config
@@ -1600,7 +1592,6 @@ async def submit_execution(
url_timeout=url_timeout_val,
allow_http_source=allow_http_source_val,
max_url_bytes=max_url_bytes_val,
- flash_enabled=flash_enabled_val,
vlm_config=vlm_config_val,
execution_store=execution_store,
)
@@ -1819,8 +1810,9 @@ def create_app(
upload_dir:
Directory for uploaded files and parse artifacts.
tiers:
- Exact non-empty set of advertised request tiers. ``None`` recommends
- tiers from available hardware and existing OCR calibration evidence.
+ Exact non-empty set of PDF/image request tiers. ``None`` recommends
+ a capability ceiling from hardware and existing OCR calibration evidence.
+ Native documents always use Flash independently of this set.
concurrency:
Maximum concurrent parse jobs (default 1).
url_timeout:
@@ -1864,7 +1856,6 @@ def create_app(
application.state.server_tiers = server_tiers
application.state.model_tier = model_tier
application.state.default_tier = default_tier
- application.state.flash_enabled = "flash" in server_tiers
application.state.tier_runtime_options = tier_runtime_options
application.state.model_ids = [_VIRTUAL_MODEL_ID]
application.state.model_registered_at = _model_registered_at
@@ -1993,7 +1984,6 @@ def create_app(
application.state.server_tiers = server_tiers
application.state.model_tier = model_tier
application.state.default_tier = default_tier
- application.state.flash_enabled = "flash" in server_tiers
application.state.tier_runtime_options = tier_runtime_options
application.state.model_ids = [_VIRTUAL_MODEL_ID]
application.state.model_registered_at = _model_registered_at
@@ -2120,10 +2110,10 @@ def _build_server_log_config(log_level: str) -> dict[str, Any]:
type=click.Path(file_okay=False, writable=True, resolve_path=True),
)
@click.option(
- "--tiers",
+ "--tier",
default="auto",
type=str,
- help="Exact comma-separated tiers (flash,basic,standard,advanced), or auto for hardware recommendations (default).",
+ help="PDF/image tier ceiling: flash, basic, standard, advanced, or auto (default). Native documents always use Flash.",
)
@click.option(
"--concurrency",
@@ -2177,7 +2167,7 @@ def main(
host: str,
port: int,
upload_dir: str,
- tiers: str,
+ tier: str,
concurrency: int,
url_timeout: int,
max_url_bytes: int,
@@ -2231,7 +2221,7 @@ def main(
)
application = create_app(
upload_dir=upload_dir,
- tiers=parse_server_tiers(tiers),
+ tiers=parse_server_tier(tier),
concurrency=concurrency,
url_timeout=url_timeout,
max_url_bytes=max_url_bytes,
diff --git a/mineru/parser/server_tiers.py b/mineru/parser/server_tiers.py
index 478c5386..acccb67b 100644
--- a/mineru/parser/server_tiers.py
+++ b/mineru/parser/server_tiers.py
@@ -1,10 +1,10 @@
-"""API 服务的精确档位集合、CLI 参数解析与共享模型配置。"""
+"""PDF/图片的启动上限、内嵌精确集合与共享模型配置。"""
from __future__ import annotations
from collections.abc import Collection
-from ..types import TIERS, DeploymentTier, Tier, validate_tier
+from ..types import TIERS, TIERS_BY_SERVER_TIER, DeploymentTier, Tier, validate_tier
def normalize_server_tiers(tiers: Collection[Tier]) -> tuple[Tier, ...]:
@@ -17,11 +17,11 @@ def normalize_server_tiers(tiers: Collection[Tier]) -> tuple[Tier, ...]:
return tuple(tier for tier in TIERS if tier in selected)
-def parse_server_tiers(value: str) -> tuple[Tier, ...] | None:
- """解析 auto 或逗号分隔列表;空项及 auto 混用均明确报错。"""
+def parse_server_tier(value: str) -> tuple[Tier, ...] | None:
+ """解析单档上限或 auto;上限包含自身及全部较低 PDF/图片档位。"""
if value.strip().lower() == "auto":
return None
- return normalize_server_tiers(value.split(",")) # type: ignore[arg-type]
+ return TIERS_BY_SERVER_TIER[validate_tier(value)]
def resolve_server_tiers(tiers: Collection[Tier] | None) -> tuple[Tier, ...]:
@@ -29,7 +29,8 @@ def resolve_server_tiers(tiers: Collection[Tier] | None) -> tuple[Tier, ...]:
if tiers is None:
from ..model.runtime.tier_recommendation import recommend_tiers
- tiers = recommend_tiers()
+ recommended = normalize_server_tiers(recommend_tiers())
+ tiers = TIERS_BY_SERVER_TIER[recommended[-1]]
return normalize_server_tiers(tiers)
@@ -42,4 +43,4 @@ def model_tier_for_server_tiers(tiers: Collection[Tier]) -> DeploymentTier | Non
return None
-__all__ = ["model_tier_for_server_tiers", "normalize_server_tiers", "parse_server_tiers", "resolve_server_tiers"]
+__all__ = ["model_tier_for_server_tiers", "normalize_server_tiers", "parse_server_tier", "resolve_server_tiers"]
diff --git a/mineru/resources/gradio_page_range.js b/mineru/resources/gradio_page_range.js
index f4fcb75e..5623bbe0 100644
--- a/mineru/resources/gradio_page_range.js
+++ b/mineru/resources/gradio_page_range.js
@@ -13,11 +13,9 @@
})[char]);
const path = (typeof file === "string" ? file : file?.path) || "";
const flashOnly = flashOnlyExtensions.some((extension) => path.toLowerCase().endsWith(`.${extension}`));
- const flashPosition = tiers.indexOf("flash");
- const flashUnavailable = flashOnly && flashPosition < 0;
// 只记住未锁定时的用户选择;文件切换和晚到元数据不能把临时 Flash 写回偏好。
- if (!tierSelection.locked) tierSelection.tier = tiers[position];
- const effectivePosition = flashOnly && !flashUnavailable ? flashPosition : tiers.indexOf(tierSelection.tier);
+ if (!tierSelection.locked && tiers[position] !== undefined) tierSelection.tier = tiers[position];
+ const effectivePosition = Math.max(0, tiers.indexOf(tierSelection.tier));
const selectedTier = flashOnly ? "flash" : tiers[effectivePosition];
tierSelection.locked = flashOnly;
const isPdf = path.toLowerCase().endsWith(".pdf");
@@ -74,8 +72,7 @@
+ `<span class="mineru-page-selection">${selectionText}</span>`
+ `</div>`
+ `<div class="mineru-page-axis"><span>1</span><span>${limitText}</span><span>${count || "–"}</span></div>`;
- const notice = flashUnavailable ? text("flash_unavailable")
- : needsRange && !count ? message(state.error) : "";
+ const notice = needsRange && !count ? message(state.error) : "";
const range = count ? (start === end ? String(start) : `${start}-${end}`) : "";
// 新版 Gradio 要求非零跨度;单页时禁用滑块,实际页数和提交范围仍为 1。
const slider = (value, label) => update({ minimum: 1, maximum: Math.max(2, count), value, interactive, label });
@@ -83,11 +80,11 @@
slider(state.handle_a, state.start_handle === "a" ? text("start_page") : text("end_page")),
slider(state.handle_b, state.start_handle === "b" ? text("start_page") : text("end_page")),
summary, range, JSON.stringify(state),
- update({ interactive: Boolean(path) && !flashUnavailable && (!needsRange || count > 0) }),
+ update({ interactive: Boolean(path) && (!needsRange || count > 0) }),
update({ value: escapeHtml(notice), visible: Boolean(notice) }),
// 同一事件同时更新值、标签和页码,程序赋值无需再触发 tier.input。
- update({ value: effectivePosition, interactive: !flashOnly && tiers.length > 1 }),
- text("tier_value", { tier: text(`tier_${selectedTier}`), notice: flashUnavailable ? text("tier_unavailable_suffix") : "" }),
+ update({ value: effectivePosition, interactive: !flashOnly && tiers.length > 1, visible: !flashOnly && tiers.length > 1 }),
+ text("tier_value", { tier: text(`tier_${selectedTier}`), notice: "" }),
JSON.stringify(tierSelection),
];
}
diff --git a/mineru/tasks/contracts.py b/mineru/tasks/contracts.py
index 2306e4b5..197fb69f 100644
--- a/mineru/tasks/contracts.py
+++ b/mineru/tasks/contracts.py
@@ -85,7 +85,8 @@ class UploadTaskOptions(BaseModel):
description=(
"PDF/image tier only. Omitted or null selects the highest supported tier in the order "
"standard, basic, flash; advanced requires an explicit request. Explicit unsupported tiers are rejected. "
- "Supported native document formats always use flash, ignoring any valid tier value."
+ "All servers support native document formats with flash, independently of /v1/tiers "
+ "and ignoring any valid tier value."
),
)
ocr_mode: Literal["auto", "txt", "ocr"] = "auto"
diff --git a/mineru/tasks/service.py b/mineru/tasks/service.py
index 866721ca..262f99e7 100644
--- a/mineru/tasks/service.py
+++ b/mineru/tasks/service.py
@@ -30,8 +30,6 @@ logger = logging.getLogger(__name__)
def resolve_task_tier(options: UploadTaskOptions, inputs: list[TaskFileInput], tiers: set[Tier]) -> Tier:
"""接单时固定 PDF/图片档位;纯原生文档归一为 flash,显式档位不升降级。"""
lightweight = [is_flash_only_parse_extension(item.file_name) for item in inputs]
- if any(lightweight) and "flash" not in tiers:
- invalid_task_request("Flash parsing is disabled, but an input requires it", param="files")
if all(lightweight):
return "flash"
if options.tier is not None:
diff --git a/mineru/types.py b/mineru/types.py
index 90a12066..c012f538 100644
--- a/mineru/types.py
+++ b/mineru/types.py
@@ -109,20 +109,27 @@ ServerTier = Literal[
"flash",
"basic",
"standard",
+ "advanced",
]
SERVER_TIERS: tuple[ServerTier, ...] = (
"flash",
"basic",
"standard",
+ "advanced",
)
TIERS_BY_SERVER_TIER: dict[ServerTier, tuple[Tier, ...]] = {
"flash": ("flash",),
"basic": ("flash", "basic"),
- "standard": ("flash", "basic", "standard", "advanced"),
+ "standard": ("flash", "basic", "standard"),
+ "advanced": ("flash", "basic", "standard", "advanced"),
}
+# Doclib 托管质量档位是服务上限,与下方的模型准备配置分开。
+ManagedServerTier = Literal["basic", "standard", "advanced"]
+MANAGED_SERVER_TIERS: tuple[ManagedServerTier, ...] = ("basic", "standard", "advanced")
+
DeploymentTier = Literal[
"basic",
"standard",
@@ -310,6 +317,8 @@ __all__ = [
"ServerTier",
"SERVER_TIERS",
"TIERS_BY_SERVER_TIER",
+ "ManagedServerTier",
+ "MANAGED_SERVER_TIERS",
"DeploymentTier",
"DEPLOYMENT_TIERS",
"DEFAULT_QUALITY_TIER_SELECTION_ORDER",
diff --git a/tests/unittest/test_doclib_cache_semantics.py b/tests/unittest/test_doclib_cache_semantics.py
index b5e682a3..d66125bc 100644
--- a/tests/unittest/test_doclib_cache_semantics.py
+++ b/tests/unittest/test_doclib_cache_semantics.py
@@ -336,8 +336,8 @@ def test_load_pages_from_done_batches_keeps_newest_page_idx(tmp_path: Path) -> N
def test_managed_api_server_args_use_tier_and_selected_port_for_process_start() -> None:
assert api_server_args_for_tier("standard", host="127.0.0.1", port=16580) == [
- "--tiers",
- "basic,standard,advanced",
+ "--tier",
+ "standard",
"--host",
"127.0.0.1",
"--port",
@@ -347,7 +347,7 @@ def test_managed_api_server_args_use_tier_and_selected_port_for_process_start()
"warning",
]
assert api_server_args_for_tier("basic", host="127.0.0.2", port=16581) == [
- "--tiers",
+ "--tier",
"basic",
"--host",
"127.0.0.2",
@@ -618,8 +618,8 @@ def test_start_managed_parse_server_selects_port_and_writes_logs(monkeypatch: py
def _popen(*args: Any, **kwargs: Any) -> _Proc:
popen_calls.append({"args": args, "kwargs": kwargs})
cmd = args[0]
- assert "--tiers" in cmd
- assert cmd[cmd.index("--tiers") + 1] == "basic,standard,advanced"
+ assert "--tier" in cmd
+ assert cmd[cmd.index("--tier") + 1] == "standard"
assert "--host" in cmd
assert cmd[cmd.index("--host") + 1] == "127.0.0.2"
assert "--port" in cmd
@@ -804,8 +804,8 @@ def test_managed_parse_server_restart_ignores_invalid_tier_override(monkeypatch:
def _popen(*args: Any, **kwargs: Any) -> _Proc:
cmd = args[0]
- assert "--tiers" in cmd
- assert cmd[cmd.index("--tiers") + 1] == "basic,standard,advanced"
+ assert "--tier" in cmd
+ assert cmd[cmd.index("--tier") + 1] == "standard"
events.append("start")
return _Proc()
diff --git a/tests/unittest/test_flash_html.py b/tests/unittest/test_flash_html.py
index 3edd7789..c4d9e039 100644
--- a/tests/unittest/test_flash_html.py
+++ b/tests/unittest/test_flash_html.py
@@ -211,11 +211,11 @@ def test_html_parse_server_flash_only_admits_extensionless_url(
assert app.state.task_store._records[response.json()["task_id"]].options.tier == "flash"
-def test_html_parse_server_no_flash_rejects_extensionless_text_html_after_fetch(
+def test_html_parse_server_normalizes_extensionless_text_html_after_fetch(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
- """验证无扩展名 URL 下载为 HTML 后仍执行禁用 Flash 的后置策略检查。"""
+ """验证无扩展名 URL 识别为原生 HTML 后固定 Flash,不受原请求档位影响。"""
url = "https://example.com/article"
response = httpx.Response(
200,
@@ -224,19 +224,18 @@ def test_html_parse_server_no_flash_rejects_extensionless_text_html_after_fetch(
request=httpx.Request("GET", url),
)
client = _url_stream_client(response)
- parse_async_mock = AsyncMock()
+ parse_async_mock = AsyncMock(wraps=api_server.parse_async)
monkeypatch.setattr(api_server, "httpx", SimpleNamespace(AsyncClient=lambda **_: client))
monkeypatch.setattr(api_server, "parse_async", parse_async_mock)
file_store = FileStore(tmp_path / "api-files")
request = execution_request(file_store, {"type": "url", "url": url}, tier="standard")
record = api_server.ExecutionStore().create(request, file_store)
- asyncio.run(api_server._run_execution(record, file_store, image_analysis=True, flash_enabled=False))
+ asyncio.run(api_server._run_execution(record, file_store, image_analysis=True))
- assert record.status == "failed"
- assert record.error is not None
- assert record.error.message == ("Flash parsing is disabled in this server, but this input requires the Flash backend")
- parse_async_mock.assert_not_awaited()
+ assert record.status == "completed"
+ parse_async_mock.assert_awaited_once()
+ assert parse_async_mock.call_args.kwargs["tier"] == "flash"
def test_url_source_aborts_when_exceeding_max_url_bytes(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
diff --git a/tests/unittest/test_kit_commands.py b/tests/unittest/test_kit_commands.py
index b31e97a3..64e40cc7 100644
--- a/tests/unittest/test_kit_commands.py
+++ b/tests/unittest/test_kit_commands.py
@@ -173,7 +173,7 @@ def test_standalone_vlm_main_configures_streams_and_forwards_extra_args(monkeypa
(
"mineru-api",
api_server.main,
- ("--host", "--port", "--tiers", "--preload-models"),
+ ("--host", "--port", "--tier", "--preload-models"),
),
],
)
@@ -207,7 +207,7 @@ def test_standalone_command_help(
"0.0.0.0",
"--port",
"18000",
- "--tiers",
+ "--tier",
"basic",
"--preload-models",
],
@@ -318,7 +318,7 @@ def test_standalone_vlm_mlx_matches_kit(monkeypatch: pytest.MonkeyPatch) -> None
("script", "entrypoint", "args", "prefix", "exit_code"),
[
("mineru-api", api_server.main, ["--backend", "hybrid-engine"], ["api-server"], 2),
- ("mineru-api", api_server.main, ["--tier", "advanced"], ["api-server"], 2),
+ ("mineru-api", api_server.main, ["--tiers", "advanced"], ["api-server"], 2),
("mineru-models-download", models.download_main, [], ["models", "download"], 1),
("mineru-models-download", models.download_main, ["--tier", "flash"], ["models", "download"], 1),
("mineru-openai-server", vlm_server.main, ["--engine", "sglang"], ["vlm-server"], 1),
@@ -368,7 +368,7 @@ def test_top_level_commands_register_implementation_callbacks_directly() -> None
[
("parse", ("--output", "--format", "--tier")),
("webui", ("--api-url", "--server-name", "--api-server-tier")),
- ("api-server", ("--host", "--port", "--tiers", "--preload-models")),
+ ("api-server", ("--host", "--port", "--tier", "--preload-models")),
("vlm-server", ("--engine",)),
("router", ("--host", "--upstream-url", "--local-gpus")),
("version", ("--json",)),
@@ -661,13 +661,13 @@ def test_api_server_forwards_explicit_tier_list(monkeypatch: Any) -> None:
result = runner.invoke(
app,
- ["api-server", "--tiers", "standard", "--preload-models"],
+ ["api-server", "--tier", "standard", "--preload-models"],
)
assert result.exit_code == 0
assert seen["prog_name"] == "mineru-kit api-server"
assert seen["standalone_mode"] is False
- assert [seen["args"][index + 1] for index, item in enumerate(seen["args"]) if item == "--tiers"] == ["standard"]
+ assert [seen["args"][index + 1] for index, item in enumerate(seen["args"]) if item == "--tier"] == ["standard"]
assert "--no-flash" not in seen["args"]
assert "--no-advanced" not in seen["args"]
assert "--preload-models" in seen["args"]
@@ -691,16 +691,16 @@ def test_api_server_without_tiers_forwards_auto(monkeypatch: Any) -> None:
assert result.exit_code == 0
assert seen["prog_name"] == "mineru-kit api-server"
assert seen["standalone_mode"] is False
- assert seen["args"][seen["args"].index("--tiers") + 1] == "auto"
- assert "--tier" not in seen["args"]
+ assert seen["args"][seen["args"].index("--tier") + 1] == "auto"
+ assert "--tiers" not in seen["args"]
assert "--no-flash" not in seen["args"]
assert "--no-advanced" not in seen["args"]
assert "--preload-models" not in seen["args"]
-def test_api_server_rejects_removed_tier_option() -> None:
+def test_api_server_rejects_removed_tiers_option() -> None:
"""旧单值 API 启动参数明确报错。"""
- result = runner.invoke(app, ["api-server", "--tier", "advanced"])
+ result = runner.invoke(app, ["api-server", "--tiers", "advanced"])
assert result.exit_code == 2
assert "No such option" in result.output
diff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.py
index 49845d6d..2f8d96b2 100644
--- a/tests/unittest/test_kit_gradio.py
+++ b/tests/unittest/test_kit_gradio.py
@@ -466,74 +466,54 @@ def test_v1_client_full_asgi_upload_job_poll_and_zip(
assert parse_calls[0]["page_range"] == "1"
-def test_gradio_routes_real_v1_jobs_and_isolates_remote_auth(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
- """贯通两套真实 V1 路由,验证本地 Flash 不上传远程且环境密钥只用于远程任务。"""
+def test_gradio_routes_native_and_pdf_to_standard_only_server(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+ """仅发布 Standard 的同一服务接收原生与 PDF 请求,鉴权和逐文件档位一致。"""
+ from test_task_tiers import _stub_inference
+
source = tmp_path / "report.pdf"
source.write_bytes(_pdf_bytes())
+ native = tmp_path / "native.html"
+ native.write_text("<h1>Native on standard-only server</h1>", encoding="utf-8")
monkeypatch.setenv("MINERU_API_KEY", "remote-secret")
monkeypatch.setattr(parser_api_server, "_preflight_tier_dependencies", Mock())
-
- async def fake_parse_async(path: str, **kwargs: Any) -> ParseResult:
- """只替换模型推理,保留两套服务各自的上传、任务和 ZIP 打包流程。"""
- return ParseResult(middle_json=_middle_json(with_image=False))
-
- monkeypatch.setattr(parser_api_server, "parse_async", fake_parse_async)
+ _stub_inference(monkeypatch)
remote_api = parser_api_server.create_app(
- upload_dir=str(tmp_path / "remote"), tiers=("basic", "standard"), api_key="remote-secret"
+ upload_dir=str(tmp_path / "remote"), tiers=("standard",), api_key="remote-secret"
)
- local_api = parser_api_server.create_app(upload_dir=str(tmp_path / "local"), tiers=("flash",))
requests: list[tuple[str, str, str, str | None]] = []
+ submissions: list[dict[str, Any]] = []
with TestClient(remote_api, base_url="http://remote.test") as remote_http:
- with TestClient(local_api, base_url="http://local.test") as local_http:
-
- async def handle(request: httpx.Request) -> httpx.Response:
- """按目标主机转入对应 ASGI 服务,记录完整请求目的地和鉴权头。"""
- host = request.url.host
- requests.append((host, request.method, request.url.path, request.headers.get("authorization")))
- target = {"remote.test": remote_http, "local.test": local_http}[host]
- response = target.request(
- request.method,
- str(request.url),
- headers=dict(request.headers),
- content=request.content,
- )
- # TestClient 已解压响应,转交 MockTransport 时同步移除原压缩头。
- headers = {
- key: value for key, value in response.headers.items() if key not in {"content-encoding", "content-length"}
- }
- return httpx.Response(response.status_code, headers=headers, content=response.content)
-
- def async_client(**kwargs: Any) -> httpx.AsyncClient:
- """为能力发现和 API parser 注入同一双服务传输层。"""
- kwargs["transport"] = httpx.MockTransport(handle)
- return httpx.AsyncClient(**kwargs)
-
- proxy = SimpleNamespace(**{**vars(httpx), "AsyncClient": async_client})
- monkeypatch.setattr(gradio_client, "httpx", proxy)
- monkeypatch.setattr(parser_api_client, "httpx", proxy)
- remote = V1ArtifactClient(api_url="http://remote.test")
- local = V1ArtifactClient(api_url="http://local.test", api_key="")
- remote_capabilities = asyncio.run(remote.discover())
- local_capabilities = asyncio.run(local.discover())
- routed = GradioArtifactClient(remote, local_flash=local)
- assert routed.capabilities.tiers == ("flash", "basic", "standard")
- assert remote.capabilities is remote_capabilities
- assert remote_capabilities.tiers == ("basic", "standard")
- assert local.capabilities is local_capabilities
- requests.clear()
-
- flash_result = asyncio.run(routed.parse_file(source, tier="flash", page_range=""))
- assert not hasattr(flash_result, "_model_output")
- assert requests and all(host == "local.test" and auth is None for host, _method, _path, auth in requests)
- assert any(method == "POST" and path == "/v1/tasks" for _host, method, path, _auth in requests)
- requests.clear()
-
- remote_result = asyncio.run(routed.parse_file(source, tier="standard", page_range="1"))
- assert not hasattr(remote_result, "_model_output")
- assert requests and all(
- host == "remote.test" and auth == "Bearer remote-secret" for host, _method, _path, auth in requests
+ async def handle(request: httpx.Request) -> httpx.Response:
+ """将能力发现、上传和下载都交给唯一远端服务,保留完整请求供断言。"""
+ requests.append((request.url.host, request.method, request.url.path, request.headers.get("authorization")))
+ if request.method == "POST" and request.url.path == "/v1/tasks":
+ submissions.append(json.loads(request.content))
+ response = remote_http.request(
+ request.method, str(request.url), headers=dict(request.headers), content=request.content
)
- assert any(method == "POST" and path == "/v1/tasks" for _host, method, path, _auth in requests)
+ headers = {
+ key: value for key, value in response.headers.items() if key not in {"content-encoding", "content-length"}
+ }
+ return httpx.Response(response.status_code, headers=headers, content=response.content)
+
+ def async_client(**kwargs: Any) -> httpx.AsyncClient:
+ """为能力发现和 SDK 注入同一服务传输层。"""
+ kwargs["transport"] = httpx.MockTransport(handle)
+ return httpx.AsyncClient(**kwargs)
+
+ proxy = SimpleNamespace(**{**vars(httpx), "AsyncClient": async_client})
+ monkeypatch.setattr(gradio_client, "httpx", proxy)
+ monkeypatch.setattr(parser_api_client, "httpx", proxy)
+ remote = V1ArtifactClient(api_url="http://remote.test")
+ asyncio.run(remote.discover())
+ routed = GradioArtifactClient(remote)
+ assert routed.capabilities.tiers == ("standard",)
+ native_result = asyncio.run(routed.parse_file(native, tier="flash", page_range=""))
+ pdf_result = asyncio.run(routed.parse_file(source, tier="standard", page_range="1"))
+ assert native_result.middle_json.extensions["mineru"]["tier"] == "flash"
+ assert pdf_result.middle_json.extensions["mineru"]["tier"] == "standard"
+ assert "tier" not in submissions[0] and submissions[1]["tier"] == "standard"
+ assert requests and all(host == "remote.test" and auth == "Bearer remote-secret" for host, _, _, auth in requests)
@pytest.mark.parametrize("failure", [None, V1ArtifactError("remote failed", code="parse_failed"), asyncio.CancelledError()])
@@ -543,8 +523,7 @@ def test_gradio_router_preserves_remote_flash_results_errors_and_cancellation(fa
primary = Mock(spec=V1ArtifactClient)
primary.capabilities = V1ServerCapabilities("http://remote.test", ("standard", "flash"), ("default",), ("upload",))
primary.parse_file = AsyncMock(return_value=result, side_effect=failure)
- local = Mock(spec=V1ArtifactClient)
- routed = GradioArtifactClient(primary, local_flash=local)
+ routed = GradioArtifactClient(primary)
callback = Mock()
request = routed.parse_file(Path("report.pdf"), tier="flash", page_range="1-2", ocr_mode="ocr", status_callback=callback)
@@ -561,23 +540,22 @@ def test_gradio_router_preserves_remote_flash_results_errors_and_cancellation(fa
primary.parse_file.assert_awaited_once_with(
Path("report.pdf"), tier="flash", page_range="1-2", ocr_mode="ocr", status_callback=callback
)
- local.parse_file.assert_not_called()
[email protected](("tier", "code"), [("advanced", "tier_unavailable"), ("unknown", "invalid_request")])
-def test_gradio_router_rejects_unavailable_tiers(tier: str, code: str) -> None:
- """验证路由层只补充 Flash,拒绝未声明的 Advanced 及未知档位。"""
- primary = Mock(spec=V1ArtifactClient)
- primary.capabilities = V1ServerCapabilities("http://remote.test", ("standard",), ("default",), ("upload",))
- local = Mock(spec=V1ArtifactClient)
- local.capabilities = V1ServerCapabilities("http://local.test", ("flash", "advanced"), ("default",), ("upload",))
- routed = GradioArtifactClient(primary, local_flash=local)
- assert routed.capabilities.tiers == ("flash", "standard")
+ ("tier", "code"), [("flash", "tier_unavailable"), ("advanced", "tier_unavailable"), ("unknown", "invalid_request")]
+)
+def test_gradio_rejects_unavailable_pdf_tiers(tmp_path: Path, tier: str, code: str) -> None:
+ """原生 Flash 能力不能成为 PDF 绕过公开档位限制的路径。"""
+ source = tmp_path / "report.pdf"
+ source.write_bytes(_pdf_bytes())
+ primary = V1ArtifactClient(api_url="http://remote.test")
+ primary._capabilities = V1ServerCapabilities(primary.base_url, ("standard",), ("default",), ("upload",))
+ routed = GradioArtifactClient(primary)
+ assert routed.capabilities.tiers == ("standard",)
with pytest.raises(V1ArtifactError) as error:
- asyncio.run(routed.parse_file(Path("report.pdf"), tier=tier, page_range=""))
+ asyncio.run(routed.parse_file(source, tier=tier, page_range=""))
assert error.value.code == code
- primary.parse_file.assert_not_called()
- local.parse_file.assert_not_called()
def test_api_client_upload_auth_is_limited_to_same_origin() -> None:
@@ -768,7 +746,7 @@ def test_managed_local_api_command_uses_kit_entrypoint() -> None:
command = server._command(8123, Path("/tmp/mineru-upload"))
assert command[command.index("--log-level") + 1] == "warning"
assert command[:4] == [server._command(8123, Path("/tmp/mineru-upload"))[0], "-m", "mineru.kit.main", "api-server"]
- assert "--tiers" in command and command[command.index("--tiers") + 1] == "flash,basic,standard,advanced"
+ assert "--tier" in command and command[command.index("--tier") + 1] == "standard"
assert "--no-flash" not in command
assert "--no-advanced" not in command
assert "--preload-models" in command
@@ -1210,6 +1188,7 @@ def test_gradio_tier_slider_uses_available_tiers_and_preserves_selection(
assert (slider.minimum, slider.maximum, slider.step, slider.precision) == (0, maximum, 1, 0)
assert slider.value == default_position
assert slider.interactive is (len(tiers) > 1)
+ assert slider.visible is (len(tiers) > 1)
assert (
label.value
== "解析等级:"
@@ -1262,11 +1241,11 @@ def test_gradio_conversion_enforces_file_type_tier(tmp_path: Path, extension: st
@pytest.mark.parametrize("tiers", [("standard",), ("advanced", "basic"), ("basic", "standard", "advanced")])
-def test_gradio_flash_only_input_requires_available_flash(tmp_path: Path, tiers: tuple[str, ...]) -> None:
- """服务缺少 Flash 时在事件入口报错,不发起解析请求,也不保留旧下载。"""
+def test_gradio_native_input_ignores_pdf_tier_list(tmp_path: Path, tiers: tuple[str, ...]) -> None:
+ """未发布 Flash 的服务仍可接收原生文件,不受 PDF/图片滑块约束。"""
source = tmp_path / "source.csv"
source.write_text("name,value\na,1\n", encoding="utf-8")
- client = SimpleNamespace(parse_file=AsyncMock())
+ client = SimpleNamespace(parse_file=AsyncMock(side_effect=V1ArtifactError("stop after request")))
capabilities = V1ServerCapabilities("http://127.0.0.1:1", tiers, ("default",), ("upload",))
demo = build_gradio_app(client, capabilities, output_root=tmp_path / "output", enable_example=False)
handler = next(fn.fn for fn in demo.fns.values() if fn.name == "convert_handler")
@@ -1276,11 +1255,9 @@ def test_gradio_flash_only_input_requires_available_flash(tmp_path: Path, tiers:
return [await handler(str(source), 0, "")]
updates = asyncio.run(convert())
- assert "tier_unavailable" in updates[-1][0]
- assert "该格式仅支持 Flash,当前服务不可用" in updates[-1][0]
- assert updates[-1][6] is None
- assert all(item["interactive"] is False for item in updates[-1][8:15])
- client.parse_file.assert_not_called()
+ assert "stop after request" in updates[-1][0]
+ client.parse_file.assert_awaited_once()
+ assert client.parse_file.call_args.kwargs["tier"] == "flash"
@pytest.mark.parametrize(
@@ -1389,8 +1366,8 @@ def test_gradio_epub_conversion_preserves_source_preview(tmp_path: Path) -> None
)
def test_gradio_conversion_rejects_invalid_tier_position(tmp_path: Path, tiers: tuple[str, ...], position: int | float) -> None:
"""验证非法位置会清除结果且不会向解析服务提交请求,包括单档位的占位上界。"""
- source = tmp_path / "demo.csv"
- source.write_text("name,value\na,1\n", encoding="utf-8")
+ source = tmp_path / "demo.pdf"
+ source.write_bytes(_pdf_bytes())
client = SimpleNamespace(parse_file=AsyncMock())
capabilities = V1ServerCapabilities("http://127.0.0.1:1", tiers, ("default",), ("upload",))
demo = build_gradio_app(client, capabilities, output_root=tmp_path, enable_example=False)
diff --git a/tests/unittest/test_kit_gradio_page_range.cjs b/tests/unittest/test_kit_gradio_page_range.cjs
index 61c6b260..6ab863df 100644
--- a/tests/unittest/test_kit_gradio_page_range.cjs
+++ b/tests/unittest/test_kit_gradio_page_range.cjs
@@ -51,15 +51,16 @@ for (const extension of flashOnlyExtensions.flatMap((extension) => [extension, e
const ui = createUi();
ui.step("tier", { position: 3 });
const out = ui.step("file", { file: { path: `/source.${extension}` } });
- assert.equal(out[7].value, 0);
+ assert.equal(out[7].value, 3);
assert.equal(out[7].interactive, false);
+ assert.equal(out[7].visible, false);
assert.equal(out[8], "解析等级:flash(极速)");
assert.equal(out[5].interactive, true);
assert.equal(out[3], "");
assert.match(out[2], /data-range-visible="false"/);
assert.deepEqual(ui.state.tierSelection, { tier: "advanced", locked: true });
// 即使模拟一个已经排队的高档位 input,也不能改变锁定值或恢复偏好。
- assert.equal(ui.step("tier", { position: 1 })[7].value, 0);
+ assert.equal(ui.step("tier", { position: 1 })[7].value, 3);
ui.step("file", { file: `/another.${extension}` });
assert.equal(ui.state.tierSelection.tier, "advanced");
const cleared = ui.step("clear");
@@ -81,23 +82,21 @@ for (const extension of tieredExtensions.flatMap((extension) => [extension, exte
assert.deepEqual(ui.state.tierSelection, { tier: "standard", locked: false });
}
-// 缺少 Flash 不伪造滑杆位置,始终阻止提交;恢复可分档文件后沿用原先能力和选择。
-for (const availableTiers of [["basic", "standard", "advanced"], ["advanced"], ["flash"], ["flash", "advanced"]]) {
+// 原生文档独立于 PDF 档位集合,隐藏滑杆但允许提交;切回后恢复合法选择。
+for (const availableTiers of [["standard"], ["basic", "standard", "advanced"], ["advanced"], ["flash"], ["flash", "advanced"]]) {
const ui = createUi(20, availableTiers);
const originalPosition = ui.state.position;
- const available = availableTiers.includes("flash");
const out = ui.step("file", { file: "/source.csv" });
assert.equal(out[7].interactive, false);
- assert.equal(out[7].value, available ? availableTiers.indexOf("flash") : originalPosition);
- assert.equal(out[5].interactive, available);
- assert.equal(out[6].visible, !available);
- if (!available) {
- assert.equal(out[6].value, "该格式仅支持 Flash,当前服务不可用");
- assert.match(out[8], /flash.*当前服务不可用/);
- }
+ assert.equal(out[7].value, originalPosition);
+ assert.equal(out[7].visible, false);
+ assert.equal(out[5].interactive, true);
+ assert.equal(out[6].visible, false);
+ assert.equal(out[8], "解析等级:flash(极速)");
const restored = ui.step("file", { file: "/source.png" });
assert.equal(restored[7].value, originalPosition);
assert.equal(restored[7].interactive, availableTiers.length > 1);
+ assert.equal(restored[7].visible, availableTiers.length > 1);
assert.equal(restored[5].interactive, true);
assert.equal(restored[6].visible, false);
}
@@ -109,7 +108,7 @@ for (const availableTiers of [["basic", "standard", "advanced"], ["advanced"], [
ui.step("tier", { position: 3 });
ui.step("file", { file: "/source.csv" });
ui.step("metadata", { metadata: { path: "/report.pdf", page_count: 100, error: "" } });
- assert.equal(ui.state.position, 0);
+ assert.equal(ui.state.position, 3);
assert.equal(ui.state.tierSelection.tier, "advanced");
let out = ui.step("file", { file: "/new.pdf" });
assert.equal(out[7].value, 3);
diff --git a/tests/unittest/test_kit_gradio_page_range.py b/tests/unittest/test_kit_gradio_page_range.py
index 0e57bb05..5a731e0f 100644
--- a/tests/unittest/test_kit_gradio_page_range.py
+++ b/tests/unittest/test_kit_gradio_page_range.py
@@ -149,21 +149,15 @@ def test_launch_forwards_managed_options_and_stops_server(monkeypatch: pytest.Mo
assert captured["stopped"] is True
[email protected]("remote_tiers", [("basic", "standard"), ("basic", "standard", "advanced"), ("flash", "standard")])
[email protected]("failure_stage", [None, "remote", "start", "local", "missing_flash", "build", "launch"])
-def test_launch_remote_flash_fallback_and_cleanup(
[email protected]("remote_tiers", [("standard",), ("basic", "standard"), ("flash", "standard")])
[email protected]("failure_stage", [None, "remote", "build", "launch"])
+def test_launch_remote_preserves_capabilities_without_local_fallback(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path, remote_tiers: tuple[str, ...], failure_stage: str | None
) -> None:
- """验证能力发现决定是否补充 Flash,且发现、启动、构建和运行失败均清理托管进程。"""
- needs_local = "flash" not in remote_tiers
- if not needs_local and failure_stage in {"start", "local", "missing_flash"}:
- pytest.skip("远程已有 Flash 时不进入本地服务阶段")
+ """所有远端档位集合均使用唯一服务,发现或界面失败也不会补起本地进程。"""
events: list[str] = []
failure = V1ArtifactError("startup failure", code="server_start_failed")
- remote_cap = V1ServerCapabilities("http://remote.test", remote_tiers, ("zip",), ("file_id",))
- local_tiers = ("basic",) if failure_stage == "missing_flash" else ("flash",)
- local_cap = V1ServerCapabilities("http://local.test", local_tiers, ("zip",), ("file_id",))
-
+ remote_cap = V1ServerCapabilities("http://remote.test", remote_tiers, ("default",), ("upload",))
async def discover_remote() -> V1ServerCapabilities:
"""记录主服务完成能力发现的时间点。"""
events.append("remote")
@@ -171,25 +165,9 @@ def test_launch_remote_flash_fallback_and_cleanup(
raise failure
return remote_cap
- async def discover_local() -> V1ServerCapabilities:
- """记录本地服务完成能力发现的时间点。"""
- events.append("local")
- if failure_stage == "local":
- raise failure
- return local_cap
-
- def start() -> str:
- """记录本地进程启动,并可模拟启动失败。"""
- events.append("start")
- if failure_stage == "start":
- raise failure
- return local_cap.base_url
-
remote = SimpleNamespace(capabilities=remote_cap, discover=AsyncMock(side_effect=discover_remote))
- local = SimpleNamespace(capabilities=local_cap, discover=AsyncMock(side_effect=discover_local))
- factory = Mock(side_effect=[remote, local])
- server = Mock(start=Mock(side_effect=start))
- server_factory = Mock(return_value=server)
+ factory = Mock(return_value=remote)
+ server_factory = Mock(side_effect=AssertionError("must not start local fallback"))
demo = SimpleNamespace(launch=Mock(), _mineru_kit_launch_kwargs={})
build = Mock(return_value=demo)
if failure_stage == "build":
@@ -218,23 +196,12 @@ def test_launch_remote_flash_fallback_and_cleanup(
gradio_app.launch_gradio(**options)
else:
gradio_app.launch_gradio(**options)
- expected = tuple(tier for tier in ("flash", "basic", "standard", "advanced") if tier in (*remote_tiers, "flash"))
- assert build.call_args.args[1].tiers == expected
+ assert build.call_args.args[1].tiers == remote_tiers
assert remote.capabilities is remote_cap
assert factory.call_args_list[0].kwargs == {"api_url": remote_cap.base_url, "api_key": "remote-secret"}
- if needs_local and failure_stage != "remote":
- server_factory.assert_called_once_with(
- tier="flash", concurrency=2, disable_image_analysis=True, preload_models=True, api_key=""
- )
- server.stop.assert_called_once()
- assert events[:2] == ["remote", "start"]
- if failure_stage != "start":
- assert events == ["remote", "start", "local"]
- assert factory.call_args_list[1].kwargs == {"api_url": local_cap.base_url, "api_key": ""}
- else:
- server_factory.assert_not_called()
- assert events == ["remote"]
- if failure_stage in {"remote", "start", "local", "missing_flash", "build"}:
+ server_factory.assert_not_called()
+ assert factory.call_count == 1 and events == ["remote"]
+ if failure_stage in {"remote", "build"}:
demo.launch.assert_not_called()
diff --git a/tests/unittest/test_managed_tier_ceiling.py b/tests/unittest/test_managed_tier_ceiling.py
new file mode 100644
index 00000000..2ac0ae8c
--- /dev/null
+++ b/tests/unittest/test_managed_tier_ceiling.py
@@ -0,0 +1,83 @@
+"""托管上限及模型配置分离,覆盖 WebUI、Router 与 Doclib 的 Advanced 启动。"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from mineru.doclib import server
+from mineru.doclib.background.parse_server_health import api_server_args_for_tier
+from mineru.doclib.config_schema import validate_config_value
+from mineru.errors import InvalidRequestError
+from mineru.kit.gradio import app as gradio_app
+from mineru.kit.gradio.client import ManagedLocalApiServer, V1ServerCapabilities
+from mineru.kit.router.workers import ManagedLocalWorker, RouterSettings
+from mineru.types import ManagedServerTier
+from pathlib import Path
+
+
[email protected]("tier", ["basic", "standard", "advanced"])
+def test_managed_ceiling_is_forwarded(tier: ManagedServerTier, tmp_path: Path) -> None:
+ """所有托管方原样传递单档上限,不额外展开或补齐 Advanced。"""
+ validate_config_value("parse_server.local.managed_tier", tier)
+ assert server._validate_managed_parse_server_tier(tier, "tier") == tier
+ commands = [
+ api_server_args_for_tier(tier, host="127.0.0.1", port=8000),
+ ManagedLocalApiServer(tier=tier)._command(8000, tmp_path),
+ ManagedLocalWorker("worker", "127.0.0.1", None, RouterSettings(worker_tier=tier)).command(8000, tmp_path),
+ ]
+ for command in commands:
+ assert command[command.index("--tier") + 1] == tier
+ assert not {"--tiers", "--no-flash", "--no-advanced"}.intersection(command)
+
+
[email protected](("tier", "model_tier"), [("basic", "basic"), ("standard", "standard"), ("advanced", "standard")])
+def test_managed_model_preparation_uses_shared_profile(
+ monkeypatch: pytest.MonkeyPatch, tier: ManagedServerTier, model_tier: str
+) -> None:
+ """Advanced 的依赖和模型检查复用 Standard,产品上限仍保留 Advanced。"""
+ dependencies, models = Mock(), Mock(return_value=[])
+ monkeypatch.setattr(server, "ensure_tier_runtime_dependencies", dependencies)
+ monkeypatch.setattr(server, "model_repos_for_tier", models)
+ server._ensure_managed_parse_server_tier_available(tier, "tier")
+ dependencies.assert_called_once_with(model_tier)
+ models.assert_called_once_with(model_tier)
+
+
+def test_advanced_missing_models_suggests_standard_download(monkeypatch: pytest.MonkeyPatch) -> None:
+ """模型下载入口只有模型配置档位,Advanced 缺文件时不能提示不存在的参数。"""
+ monkeypatch.setattr(server, "model_repos_for_tier", Mock(return_value=[SimpleNamespace(name="shared-vlm")]))
+ monkeypatch.setattr(server, "verify_model_repo", Mock(return_value=SimpleNamespace(ready=False, missing_paths=["weights"])))
+ with pytest.raises(InvalidRequestError) as error:
+ server._ensure_managed_parse_server_models_ready("advanced", "tier")
+ assert "--tier standard" in str(error.value)
+ assert "--tier advanced" not in str(error.value)
+
+
+def test_remote_standard_only_gradio_never_starts_local_server(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+ """连接 SaaS 仅 Standard 能力时只使用远端,不补起本地服务或扩展档位。"""
+ capabilities = V1ServerCapabilities("http://remote.test", ("standard",), ("default",), ("upload",))
+ client = SimpleNamespace(capabilities=capabilities, discover=AsyncMock(return_value=capabilities))
+ managed = Mock(side_effect=AssertionError("must not start local fallback"))
+ build = Mock(return_value=object())
+ monkeypatch.setattr(gradio_app, "V1ArtifactClient", Mock(return_value=client))
+ monkeypatch.setattr(gradio_app, "ManagedLocalApiServer", managed)
+ monkeypatch.setattr(gradio_app, "build_gradio_app", build)
+ monkeypatch.setattr(gradio_app, "_launch_gradio_app", Mock())
+ gradio_app.launch_gradio(
+ api_url=capabilities.base_url,
+ api_key=None,
+ server_name="127.0.0.1",
+ server_port=None,
+ output_dir=str(tmp_path),
+ enable_example=False,
+ enable_api=True,
+ api_server_tier="standard",
+ api_server_concurrency=1,
+ api_server_disable_image_analysis=False,
+ api_server_preload_models=False,
+ )
+ managed.assert_not_called()
+ assert build.call_args.args[1].tiers == ("standard",)
diff --git a/tests/unittest/test_native_server_contract.py b/tests/unittest/test_native_server_contract.py
new file mode 100644
index 00000000..a548d275
--- /dev/null
+++ b/tests/unittest/test_native_server_contract.py
@@ -0,0 +1,52 @@
+"""仅公开 Standard 的服务经真实 TCP 支持 SDK 原生文档解析。"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from unittest.mock import Mock
+
+import httpx
+import pytest
+from test_http_api_example_script import _Server
+from test_task_response_contract import _mixed_inputs
+
+from mineru.kit.router import RouterSettings, create_app as create_router
+from mineru.parser import MinerUApiParser, api_server
+
+
[email protected]("asynchronous", [False, True])
[email protected]("native_index", [1, 2])
[email protected]("deployment", ["api", "router"])
+def test_native_sdk_uses_standard_only_server(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, asynchronous: bool, native_index: int, deployment: str
+) -> None:
+ """同步和异步 SDK 均能上传、轮询、下载真实 HTML/DOCX,PDF Flash 仍被拒绝。"""
+ monkeypatch.setattr(api_server, "ensure_tier_runtime_dependencies", Mock())
+ worker = _Server(api_server.create_app(upload_dir=str(tmp_path / "worker"), tiers=("standard",)))
+ worker.start()
+ router = None
+ try:
+ url = worker.url
+ if deployment == "router":
+ router = _Server(
+ create_router(RouterSettings(upstream_urls=(url,), local_gpus="none", worker_refresh_interval_seconds=0))
+ )
+ router.start()
+ url = router.url
+ name, content = _mixed_inputs()[native_index]
+ source = tmp_path / name
+ source.write_bytes(content)
+ with httpx.Client(base_url=url, trust_env=False) as client:
+ assert [item["id"] for item in client.get("/v1/tiers").json()["data"]] == ["standard"]
+ rejected = client.post("/v1/tasks", json={"files": [{"file_name": "test.pdf", "bytes": 1}], "tier": "flash"})
+ assert rejected.status_code == 400
+ assert rejected.json()["error"]["param"] == "tier"
+ parser = MinerUApiParser(api_url=url)
+ result = asyncio.run(parser.parse_async(source)) if asynchronous else parser.parse(source)
+ assert result.middle_json.extensions["mineru"]["tier"] == "flash"
+ assert ("Mixed task HTML" if native_index == 1 else "Mixed task DOCX") in result.markdown()
+ finally:
+ if router is not None:
+ router.stop()
+ worker.stop()
diff --git a/tests/unittest/test_parser_api_contract.py b/tests/unittest/test_parser_api_contract.py
index d3532f38..38abb862 100644
--- a/tests/unittest/test_parser_api_contract.py
+++ b/tests/unittest/test_parser_api_contract.py
@@ -422,12 +422,13 @@ def test_public_tier_literals_match_product_contract() -> None:
def test_server_and_deployment_tier_constants_match_product_contract() -> None:
- assert SERVER_TIERS == ("flash", "basic", "standard")
+ assert SERVER_TIERS == ("flash", "basic", "standard", "advanced")
assert DEPLOYMENT_TIERS == ("basic", "standard")
assert TIERS_BY_SERVER_TIER == {
"flash": ("flash",),
"basic": ("flash", "basic"),
- "standard": ("flash", "basic", "standard", "advanced"),
+ "standard": ("flash", "basic", "standard"),
+ "advanced": ("flash", "basic", "standard", "advanced"),
}
@@ -762,7 +763,7 @@ def test_api_server_standard_no_flash_state_and_metadata(tmp_path: Path, monkeyp
assert app.state.model_tier == "standard"
assert app.state.default_tier == "standard"
assert app.state.tier_runtime_options["standard"].effort == "high"
- assert app.state.flash_enabled is False
+ assert not hasattr(app.state, "flash_enabled")
assert [tier["id"] for tier in app.state.tiers] == ["basic", "standard", "advanced"]
assert app.state.model_ids == [api_server._VIRTUAL_MODEL_ID]
assert api_server._VIRTUAL_MODEL_ID == f"mineru-{api_server.__version__}"
@@ -1152,8 +1153,8 @@ def test_api_server_stores_parser_runtime_options(tmp_path: Path, monkeypatch: p
def test_api_server_cli_exposes_parser_runtime_options() -> None:
option_names = {name for param in main.params for name in param.opts}
- assert "--tiers" in option_names
- assert "--tier" not in option_names
+ assert "--tier" in option_names
+ assert "--tiers" not in option_names
assert "--backend" not in option_names
assert "--language" not in option_names
assert "--ocr-mode" not in option_names
@@ -1184,7 +1185,7 @@ def test_api_server_cli_defaults_to_hardware_recommendation(monkeypatch: pytest.
seen: dict[str, object] = {}
def _fake_run(server: Any) -> None:
- """记录无 --tiers 启动后的自动推荐能力,不启动真实服务。"""
+ """记录无 --tier 启动后的自动推荐能力,不启动真实服务。"""
seen["tiers"] = [tier["id"] for tier in server.config.app.state.tiers]
seen["default_tier"] = server.config.app.state.default_tier
seen["effort_by_tier"] = {
@@ -1203,8 +1204,8 @@ def test_api_server_cli_defaults_to_hardware_recommendation(monkeypatch: pytest.
}
-def test_api_server_cli_accepts_quality_tier_list(monkeypatch: pytest.MonkeyPatch) -> None:
- """显式质量档位列表无需禁用开关即可排除 Flash。"""
+def test_api_server_cli_accepts_advanced_ceiling(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Advanced 上限包含全部 PDF/图片档位。"""
seen: dict[str, object] = {}
def _fake_run(server: Any) -> None:
@@ -1217,13 +1218,13 @@ def test_api_server_cli_accepts_quality_tier_list(monkeypatch: pytest.MonkeyPatc
monkeypatch.setattr("uvicorn.Server.run", _fake_run)
- result = runner.invoke(main, ["--tiers", "basic,standard,advanced", "--host", "0.0.0.0", "--port", "15984"])
+ result = runner.invoke(main, ["--tier", "advanced", "--host", "0.0.0.0", "--port", "15984"])
assert result.exit_code == 0
assert seen == {
- "tiers": ["basic", "standard", "advanced"],
+ "tiers": ["flash", "basic", "standard", "advanced"],
"default_tier": "standard",
- "effort_by_tier": {"basic": "medium", "standard": "high", "advanced": "xhigh"},
+ "effort_by_tier": {"flash": "flash", "basic": "medium", "standard": "high", "advanced": "xhigh"},
}
@@ -1241,7 +1242,7 @@ def test_api_server_cli_accepts_list_without_advanced(monkeypatch: pytest.Monkey
monkeypatch.setattr("uvicorn.Server.run", _fake_run)
- result = runner.invoke(main, ["--tiers", "flash,basic,standard", "--host", "0.0.0.0", "--port", "15984"])
+ result = runner.invoke(main, ["--tier", "standard", "--host", "0.0.0.0", "--port", "15984"])
assert result.exit_code == 0
assert seen == {
@@ -1259,14 +1260,14 @@ def test_api_server_cli_enables_model_preload(monkeypatch: pytest.MonkeyPatch) -
monkeypatch.setattr("uvicorn.Server.run", _fake_run)
- result = runner.invoke(main, ["--tiers", "flash,basic", "--preload-models"])
+ result = runner.invoke(main, ["--tier", "basic", "--preload-models"])
assert result.exit_code == 0
assert seen == {"preload_models": True}
def test_api_server_cli_rejects_invalid_tier_names() -> None:
- result = runner.invoke(main, ["--tiers", "ultra"])
+ result = runner.invoke(main, ["--tier", "ultra"])
assert result.exit_code != 0
assert "Unsupported tier 'ultra'" in result.output
@@ -1293,7 +1294,8 @@ def test_api_server_cli_help_exposes_tier_only_runtime_selection() -> None:
normalized_output = result.output.replace("-\n ", "-")
assert result.exit_code == 0
- assert "--tiers" in normalized_output
+ assert "--tier" in normalized_output
+ assert "--tiers" not in normalized_output
assert "flash" in normalized_output
assert "basic" in normalized_output
assert "standard" in normalized_output
diff --git a/tests/unittest/test_resource_retention.py b/tests/unittest/test_resource_retention.py
index ddb594c5..be5a87aa 100644
--- a/tests/unittest/test_resource_retention.py
+++ b/tests/unittest/test_resource_retention.py
@@ -339,7 +339,7 @@ def test_kit_cli_forwards_explicit_retention(monkeypatch: pytest.MonkeyPatch) ->
forwarded = MagicMock()
monkeypatch.setattr(api_server.main, "main", forwarded)
response = CliRunner().invoke(
- app, ["api-server", "--tiers", "flash", "--retention-seconds", "0"], env={"MINERU_API_RETENTION_SECONDS": "7200"}
+ app, ["api-server", "--tier", "flash", "--retention-seconds", "0"], env={"MINERU_API_RETENTION_SECONDS": "7200"}
)
assert response.exit_code == 0, response.output
args = forwarded.call_args.kwargs["args"]
diff --git a/tests/unittest/test_server_tiers.py b/tests/unittest/test_server_tiers.py
new file mode 100644
index 00000000..e553db0c
--- /dev/null
+++ b/tests/unittest/test_server_tiers.py
@@ -0,0 +1,153 @@
+"""API 精确档位集合、自动推荐、模型合并及三个命令入口的契约。"""
+
+from __future__ import annotations
+
+from itertools import combinations
+from pathlib import Path
+from typing import Any
+from unittest.mock import Mock
+
+from click.testing import CliRunner
+from fastapi.testclient import TestClient
+import pytest
+from typer.testing import CliRunner as TyperRunner
+
+from mineru.kit.commands.api_server import main as standalone_main
+from mineru.kit.main import app as kit_app
+from mineru.model.runtime import tier_recommendation
+from mineru.parser import api_server
+from mineru.parser.server_tiers import parse_server_tier
+from mineru.types import TIERS, TIERS_BY_SERVER_TIER, Tier
+
+
+def preflight(monkeypatch: pytest.MonkeyPatch) -> Mock:
+ """只记录实际模型依赖需求,避免启动真实推理模型。"""
+ check = Mock()
+ monkeypatch.setattr(api_server, "ensure_tier_runtime_dependencies", check)
+ return check
+
+
[email protected]("tiers", [subset for size in range(1, 5) for subset in combinations(TIERS, size)])
+def test_every_explicit_subset_is_exact(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, preflight: Mock, tiers: tuple[Tier, ...]
+) -> None:
+ """所有非空集合都只发布指定档位,advanced 复用共享模型而不补齐其他档位。"""
+ recommend = Mock(side_effect=AssertionError("explicit tiers must skip hardware discovery"))
+ monkeypatch.setattr(tier_recommendation, "recommend_tiers", recommend)
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=tiers)
+ expected_model = "standard" if {"standard", "advanced"}.intersection(tiers) else "basic" if "basic" in tiers else None
+ if expected_model:
+ assert preflight.call_count == 1
+ assert preflight.call_args.args[0] == expected_model
+ else:
+ preflight.assert_not_called()
+ with TestClient(app) as client:
+ assert tuple(item["id"] for item in client.get("/v1/tiers").json()["data"]) == tiers
+ assert tuple(app.state.tier_runtime_options) == tiers
+ assert not hasattr(app.state, "flash_enabled")
+ assert app.state.default_tier == next((t for t in ("standard", "basic", "flash") if t in tiers), None)
+ recommend.assert_not_called()
+
+
[email protected]("tiers", [("flash",), ("basic",), TIERS])
+def test_auto_recommendation_is_fixed_at_creation(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, preflight: Mock, tiers: tuple[Tier, ...]
+) -> None:
+ """自动推荐每个服务只计算一次,生命周期启动与能力查询不重新选择。"""
+ recommend = Mock(return_value=frozenset(tiers))
+ monkeypatch.setattr(tier_recommendation, "recommend_tiers", recommend)
+ app = api_server.create_app(upload_dir=str(tmp_path))
+ recommend.return_value = frozenset({"advanced"})
+ with TestClient(app) as client:
+ for _ in range(2):
+ assert tuple(row["id"] for row in client.get("/v1/tiers").json()["data"]) == TIERS_BY_SERVER_TIER[tiers[-1]]
+ recommend.assert_called_once_with()
+
+
+ ("options", "expected"), [({}, "standard"), ({"tier": None}, "standard"), ({"tier": "advanced"}, "advanced")]
+)
+def test_auto_server_accepts_task_with_standard_default(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, preflight: Mock, options: dict[str, str | None], expected: str
+) -> None:
+ """硬件推荐四档后,经公共接单接口固定默认 standard 或调用方指定的 advanced。"""
+ monkeypatch.setattr(tier_recommendation, "recommend_tiers", lambda: frozenset(TIERS))
+ app = api_server.create_app(upload_dir=str(tmp_path))
+ with TestClient(app) as client:
+ response = client.post("/v1/tasks", json={"files": [{"file_name": "test.pdf", "bytes": 1}], **options})
+ assert response.status_code == 202, response.text
+ assert app.state.task_store._records[response.json()["task_id"]].options.tier == expected
+
+
[email protected]("value", ["", ",", "standard,", "flash,,basic", "ultra", "auto,flash"])
+def test_invalid_cli_lists(value: str) -> None:
+ """拒绝空列表、空项、未知名称及 auto 混用。"""
+ with pytest.raises(ValueError):
+ parse_server_tier(value)
+
+
+def test_cli_normalization() -> None:
+ """大小写及空白规范化,上限包含自身和较低档位。"""
+ assert parse_server_tier(" AUTO ") is None
+ assert parse_server_tier(" STANDARD ") == ("flash", "basic", "standard")
+
+
[email protected]("options", [["--tiers", "standard"], ["--no-flash"], ["--no-advanced"]])
+def test_removed_cli_options(options: list[str]) -> None:
+ """复数列表与禁用开关不作为旧配置别名保留。"""
+ result = CliRunner().invoke(api_server.main, options)
+ assert result.exit_code != 0 and "No such option" in result.output
+ result = TyperRunner().invoke(kit_app, ["api-server", *options])
+ assert result.exit_code != 0 and "No such option" in result.output
+
+
[email protected]("value", [(), [], set(), "standard", ["auto"], [""], [1]])
+def test_invalid_python_collection(tmp_path: Path, value: Any) -> None:
+ """Python 工厂必须收到非空集合,不能把字符串逐字符解释成档位。"""
+ with pytest.raises(ValueError):
+ api_server.create_app(upload_dir=str(tmp_path), tiers=value)
+
+
[email protected]("option", ["tier", "no_flash", "no_advanced"])
+def test_old_python_options_removed(option: str) -> None:
+ """旧工厂参数直接报错,不保留混合配置入口。"""
+ with pytest.raises(TypeError, match="unexpected keyword argument"):
+ api_server.create_app(**{option: "standard"})
+
+
[email protected]("entry", ["module", "kit", "standalone"])
[email protected]("options", [[], ["--tier", "auto"], *[["--tier", tier] for tier in TIERS]])
+def test_cli_entrypoints(monkeypatch: pytest.MonkeyPatch, preflight: Mock, entry: str, options: list[str]) -> None:
+ """三个入口共享自动推荐与单档上限,不启动监听进程。"""
+ seen: list[tuple[Tier, ...]] = []
+ monkeypatch.setattr(tier_recommendation, "recommend_tiers", lambda: frozenset(TIERS))
+ monkeypatch.setattr("uvicorn.Server.run", lambda server: seen.append(server.config.app.state.server_tiers))
+ if entry == "module":
+ result = CliRunner().invoke(api_server.main, options)
+ elif entry == "kit":
+ result = TyperRunner().invoke(kit_app, ["api-server", *options])
+ else:
+ monkeypatch.setattr("sys.argv", ["mineru-api", *options])
+ with pytest.raises(SystemExit) as stopped:
+ standalone_main()
+ assert stopped.value.code == 0
+ assert seen == [TIERS_BY_SERVER_TIER[options[1]] if options and options[1] != "auto" else TIERS]
+ return
+ assert result.exit_code == 0, result.output
+ assert seen == [TIERS_BY_SERVER_TIER[options[1]] if options and options[1] != "auto" else TIERS]
+
+
[email protected]("tiers", [("advanced",), ("flash", "standard", "advanced"), ("basic",)])
+def test_preload_shared_models_once(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, preflight: Mock, tiers: tuple[Tier, ...]
+) -> None:
+ """多个开放档位共享一次模型预加载,只有 advanced 时也可启动。"""
+ expected = "standard" if "advanced" in tiers else "basic"
+ preload = Mock(return_value=api_server._ModelPreloadResult(expected, "test"))
+ monkeypatch.setattr(api_server, "_preload_server_models", preload)
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=tiers, preload_models=True)
+ with TestClient(app):
+ assert tuple(app.state.tier_runtime_options) == tiers
+ assert preload.call_count == 1
+ assert preload.call_args.args[0] == expected
diff --git a/tests/unittest/test_task_http.py b/tests/unittest/test_task_http.py
index a9130472..09c2f456 100644
--- a/tests/unittest/test_task_http.py
+++ b/tests/unittest/test_task_http.py
@@ -33,6 +33,11 @@ from test_http_api_example_script import _Server
from mineru.kit.router import RouterSettings
from mineru.kit.router import create_app as create_router
from mineru.parser import api_server
+from mineru.filetypes import batch_effective_parse_tier
+from mineru.tasks.contracts import TaskFileInput, UploadTaskOptions
+from mineru.tasks.errors import ApiServerError
+from mineru.tasks.service import resolve_task_tier
+from mineru.types import TIERS, Tier
from mineru.utils.async_utils import run_sync
SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "http_task_example.sh"
@@ -621,6 +626,7 @@ class _CloudState:
gateway_url: str = ""
storage_url: str = ""
+ pdf_tiers: tuple[Tier, ...] = ("standard",)
tasks: dict[str, dict[str, Any]] = field(default_factory=dict)
cache: dict[str, bytes] = field(default_factory=dict)
requests: list[tuple[str, str, str, str | None]] = field(default_factory=list)
@@ -668,6 +674,11 @@ class _CloudState:
},
"status": status,
"result_url": result_url,
+ "parse": {
+ "tier": batch_effective_parse_tier(record["tier"], item["file_name"]),
+ "duration_ms": 0,
+ "parser_version": "test",
+ } if status == "completed" else None,
}
)
states = [item["status"] for item in files]
@@ -706,6 +717,19 @@ def _cloud_apps(state: _CloudState) -> tuple[FastAPI, FastAPI]:
return JSONResponse({"error": {"code": "invalid_api_key"}}, status_code=401)
return await call_next(request)
+ @gateway.get("/v1/health")
+ async def health() -> dict[str, Any]:
+ """原生支持是共同契约,不增加格式能力字段。"""
+ return {
+ "status": "ok", "version": "test",
+ "features": {"webhook": False, "task_output_formats": ["default"], "sources": ["upload"]},
+ }
+
+ @gateway.get("/v1/tiers")
+ async def tiers() -> dict[str, Any]:
+ """SaaS 默认只发布 PDF/图片 Standard 档位。"""
+ return {"object": "list", "data": [{"id": tier, "description": tier} for tier in state.pdf_tiers]}
+
@gateway.post("/v1/tasks")
async def create_task(request: Request) -> Response:
"""只接收体积很小的 JSON 元数据,用 hash 判断哪些文件需要独立上传。"""
@@ -716,11 +740,19 @@ def _cloud_apps(state: _CloudState) -> tuple[FastAPI, FastAPI]:
assert len(body) < 4096
submitted = await request.json()
manifest = submitted["files"]
+ try:
+ selected_tier = resolve_task_tier(
+ UploadTaskOptions.model_validate({key: value for key, value in submitted.items() if key != "files"}),
+ [TaskFileInput.model_validate(item) for item in manifest], set(state.pdf_tiers),
+ )
+ except ApiServerError as error:
+ return JSONResponse({"error": error.error.model_dump()}, status_code=error.status_code)
task_id = f"cloud_{len(state.tasks) + 1}"
assert all({"client_file_id", "file_id"}.isdisjoint(item) for item in manifest)
manifest = [{**item, "file_id": f"file-{task_id}-{index + 1}"} for index, item in enumerate(manifest)]
state.tasks[task_id] = {
"request": submitted,
+ "tier": selected_tier,
"files": manifest,
"ready": {item["file_id"] for item in manifest if item.get("sha256sum") in state.cache},
"upload_version": 0,
@@ -823,6 +855,7 @@ def cloud() -> Iterator[_CloudState]:
@pytest.mark.parametrize("tier", [None, "basic", "advanced"])
def test_example_script_forwards_optional_tier(cloud: _CloudState, tmp_path: Path, tier: str | None) -> None:
"""执行真实示例脚本,验证缺省不发送 tier、显式选档不由客户端替换。"""
+ cloud.pdf_tiers = TIERS
source = tmp_path / "input.pdf"
source.write_bytes(b"%PDF-script-protocol")
env = _script_env(tmp_path, cloud.gateway_url)
@@ -861,6 +894,32 @@ def test_same_client_works_with_saas_and_oss(cloud: _CloudState, tmp_path: Path,
assert _members((tmp_path / "results/file-cloud_1-1/a.zip").read_bytes())["markdown.md"] == b"# OSS result file-cloud_1-1\n"
+def test_saas_standard_only_with_native_and_oss(cloud: _CloudState) -> None:
+ """SaaS 仅发布 Standard,混合请求仍逐文件返回 Standard/Flash 并从 OSS 下载。"""
+ with httpx.Client(base_url=cloud.gateway_url, headers={"Authorization": "Bearer test-key"}, trust_env=False) as client:
+ assert [item["id"] for item in client.get("/v1/tiers").json()["data"]] == ["standard"]
+ assert "native_extensions" not in client.get("/v1/health").json()["features"]
+ for tier in ("flash", "basic", "advanced"):
+ rejected = client.post("/v1/tasks", json={"files": [{"file_name": "test.pdf", "bytes": 1}], "tier": tier})
+ assert rejected.status_code == 400 and rejected.json()["error"]["param"] == "tier"
+ assert not cloud.tasks
+ receipt = client.post("/v1/tasks", json={
+ "files": [{"file_name": name, "bytes": 1} for name in ("test.pdf", "test.docx")],
+ "output_formats": ["default"],
+ })
+ assert receipt.status_code == 202, receipt.text
+ for item in receipt.json()["files"]:
+ upload = item["upload"]
+ response = httpx.put(upload["url"], content=b"x", headers=upload["headers"], trust_env=False)
+ assert response.status_code == 200
+ result = client.get("/v1/tasks/" + receipt.json()["task_id"]).json()
+ assert result["status"] == "completed"
+ assert [item["parse"]["tier"] for item in result["files"]] == ["standard", "flash"]
+ for item in result["files"]:
+ download = httpx.get(item["result_url"], trust_env=False)
+ assert download.status_code == 200 and "markdown.md" in _members(download.content)
+
+
@pytest.mark.parametrize("failure", ["transient_upload", "lost_upload_response", "expired_download", "api_download_redirect"])
def test_client_recovers_links_and_uncertain_uploads(cloud: _CloudState, tmp_path: Path, failure: str) -> None:
"""恢复原任务和刷新地址不创建新任务;跨源重定向不能转发 API Key。"""
diff --git a/tests/unittest/test_task_tiers.py b/tests/unittest/test_task_tiers.py
index b458dd45..0d3a392f 100644
--- a/tests/unittest/test_task_tiers.py
+++ b/tests/unittest/test_task_tiers.py
@@ -48,7 +48,6 @@ def _set_tiers(app: FastAPI, tiers: tuple[Tier, ...]) -> None:
app.state.tier_runtime_options = {tier: runtime_options_for_tier(tier) for tier in tiers}
app.state.tiers = api_server._tiers_for_server_tiers(list(tiers))
app.state.default_tier = select_default_quality_tier(tiers)
- app.state.flash_enabled = "flash" in tiers
@asynccontextmanager
@@ -195,7 +194,10 @@ def test_task_explicit_tier_is_not_upgraded_or_downgraded(tier: Tier) -> None:
(("flash",), {"tier": ""}, ["input.docx"], 400, "tier"),
(("flash",), {"tier": "unknown"}, ["input.docx"], 400, "tier"),
(("advanced",), {}, ["input.pdf"], 503, None),
- (("standard",), {}, ["input.pdf", "input.docx"], 400, "files"),
+ (("standard",), {}, ["input.pdf", "input.docx"], 202, None),
+ (("standard",), {"tier": "flash"}, ["input.pdf", "input.docx"], 400, "tier"),
+ (("standard",), {"tier": "basic"}, ["input.png"], 400, "tier"),
+ (("standard",), {"tier": "advanced"}, ["input.pdf"], 400, "tier"),
],
)
def test_task_tier_preflight_and_schema(
@@ -220,7 +222,7 @@ def test_task_tier_preflight_and_schema(
assert response.status_code == status, response.text
if status == 202:
record = app.state.task_store._records[response.json()["task_id"]]
- assert record.options.tier == "flash"
+ assert record.options.tier == ("standard" if "standard" in tiers else "flash")
else:
assert response.json()["error"]["param"] == param
assert response.json()["error"]["code"] == ("quality_tier_unavailable" if status == 503 else "invalid_request")
@@ -244,7 +246,9 @@ def test_mixed_task_tiers_across_deployments(
async def scenario() -> None:
"""检查接单记录、各跳请求、推理参数和最终产物中的档位。"""
capabilities = (
- {"worker": TIERS} if deployment == "api" else {"quality": ("basic", "standard", "advanced"), "native": ("flash",)}
+ {"worker": ("standard", "advanced")}
+ if deployment == "api"
+ else {"quality": ("standard", "advanced"), "native": ("basic",)}
)
async with _deployment(tmp_path, deployment, capabilities) as (client, app, apps, submissions):
inputs = _mixed_inputs()
@@ -266,8 +270,8 @@ def test_mixed_task_tiers_across_deployments(
assert len(submissions) == {"api": 0, "router": 4, "cascade": 8}[deployment]
for host, body in submissions:
native = Path(body["files"][0]["file_name"]).suffix in {".html", ".docx"}
- assert body["tier"] == ("flash" if native else expected)
- assert host == "inner" or host == ("native" if native else "quality")
+ assert body.get("tier") == (None if native else expected)
+ assert host == "inner" or host in ({"native", "quality"} if native else {"quality"})
for service in apps:
if hasattr(service.state, "execution_store"):
for execution in service.state.execution_store._executions.values():
@@ -283,7 +287,7 @@ def test_native_only_task_ignores_unavailable_explicit_tier(tmp_path: Path, depl
async def scenario() -> None:
"""使用真实 HTML 和 DOCX 验证单一 flash 部署的参数作用域。"""
- async with _deployment(tmp_path, deployment, {"native": ("flash",)}) as (client, app, _apps, submissions):
+ async with _deployment(tmp_path, deployment, {"native": ("standard",)}) as (client, app, _apps, submissions):
inputs = _mixed_inputs()[1:3]
response = await client.post("/v1/tasks", json=_request_body(inputs, {"tier": "advanced"}))
assert response.status_code == 202, response.text
@@ -292,7 +296,7 @@ def test_native_only_task_ignores_unavailable_explicit_tier(tmp_path: Path, depl
result = await _complete(client, task, inputs)
assert result["status"] == "completed", result
assert all(item["parse"]["tier"] == "flash" for item in result["files"])
- assert all(body["tier"] == "flash" for _host, body in submissions)
+ assert all("tier" not in body for _host, body in submissions)
asyncio.run(scenario())
diff --git a/tests/unittest/test_tier_recommendation.py b/tests/unittest/test_tier_recommendation.py
new file mode 100644
index 00000000..e4fdb1cd
--- /dev/null
+++ b/tests/unittest/test_tier_recommendation.py
@@ -0,0 +1,194 @@
+"""硬件推荐与 OCR 校准证据的回归,不依赖测试机器的 GPU 或模型。"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import Mock
+
+import pytest
+
+from mineru.model.runtime import onnx_calibration_cache as cache
+from mineru.model.runtime import tier_recommendation as recommendation
+from mineru.model.runtime.llama_probe import LlamaDevice
+from mineru.model.runtime.webgpu import WebGPUDevice
+from mineru.model.runtime.windows_gpu import GpuAdapter
+from mineru.types import TIERS
+
+
+ ("cores", "gpu", "expected"),
+ [
+ (1, False, {"flash"}),
+ (3, False, {"flash"}),
+ (4, False, set(TIERS[:-1])),
+ (32, False, set(TIERS[:-1])),
+ (1, True, set(TIERS)),
+ (4, True, set(TIERS)),
+ ],
+)
+def test_recommendation_matrix(cores: int, gpu: bool, expected: set[str]) -> None:
+ """验证 CPU 边界及 GPU 对全部档位的开放规则。"""
+ assert recommendation.tiers_for_hardware(recommendation.TierHardware(cores, gpu)) == expected
+
+
+ ("affinity", "quota", "expected"), [(2, "max 100000", 2), (8, "300000 100000", 3), (8, "400000 100000", 4)]
+)
+def test_recommendation_respects_affinity_and_quota(
+ monkeypatch: pytest.MonkeyPatch, affinity: int, quota: str, expected: int
+) -> None:
+ """使用真实有效 CPU 计数逻辑,保证亲和性与容器配额限制进入推荐。"""
+ from mineru.model.runtime import cpu_threads
+
+ monkeypatch.setattr(cpu_threads.os, "cpu_count", lambda: 16)
+ monkeypatch.setattr(cpu_threads.os, "sched_getaffinity", lambda pid: set(range(affinity)), raising=False)
+ monkeypatch.setattr(cpu_threads.Path, "read_text", lambda path: quota if path.name == "cpu.max" else "-1")
+ monkeypatch.setattr(recommendation, "_advanced_gpu_reason", lambda: None)
+ hardware = recommendation.detect_tier_hardware()
+ assert hardware.cpu_count == expected
+ assert recommendation.tiers_for_hardware(hardware) == frozenset(TIERS[:-1] if expected >= 4 else ("flash",))
+
+
+def evidence_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ """每个测试使用独立证据文件,避免写入用户配置目录。"""
+ path = tmp_path / "settings.yaml.onnx-calibration.json"
+ monkeypatch.setattr(cache, "calibration_record_path", lambda: path)
+ monkeypatch.setattr(cache, "effective_cpu_count", lambda: 8)
+ monkeypatch.setattr(cache, "_runtime_version", lambda distribution: "1.0")
+ monkeypatch.delenv("MINERU_INTRA_OP_NUM_THREADS", raising=False)
+ monkeypatch.delenv("MINERU_INTER_OP_NUM_THREADS", raising=False)
+ return path
+
+
+def _adapter() -> GpuAdapter:
+ """构造具有稳定物理身份的集显。"""
+ return GpuAdapter(0, "physical-id", "integrated", 0x8086, 0x7D51, True, 0)
+
+
+def _measurement(**overrides: Any) -> dict[str, Any]:
+ """构造校准 worker 已验证的最小持久化数据。"""
+ return {
+ "intra_threads": 4,
+ "inter_threads": 1,
+ "cpu_elapsed": 2.0,
+ "gpu_elapsed": 1.0,
+ "decision_threshold": 0.8,
+ "outputs_match": True,
+ "decision_valid": True,
+ "model_sha256": "model-hash",
+ **overrides,
+ }
+
+
[email protected](("ratio", "valid", "expected"), [(0.8, True, True), (0.801, True, False), (0.5, False, False)])
+def test_calibration_threshold_and_validity(evidence_path: Path, ratio: float, valid: bool, expected: bool) -> None:
+ """读取实际保存的证据,保留既有阈值和稳定性判定。"""
+ cache.save_calibration_record(_adapter(), _measurement(gpu_elapsed=2.0 * ratio, decision_valid=valid))
+ assert cache.calibrated_gpu_is_faster(_adapter(), 0.8) is expected
+ assert cache.calibrated_gpu_is_faster(_adapter(), 0.75) is False
+
+
[email protected]("change", ["device", "runtime", "threads", "cpu", "backend"])
+def test_stale_evidence_is_ignored(evidence_path: Path, monkeypatch: pytest.MonkeyPatch, change: str) -> None:
+ """设备、运行时和 CPU 配置改变时,不复用旧的性能结论。"""
+ adapter = _adapter()
+ cache.save_calibration_record(adapter, _measurement())
+ assert cache.calibrated_gpu_is_faster(adapter, 0.8)
+ if change == "device":
+ adapter = replace(adapter, device_id=2)
+ elif change == "runtime":
+ monkeypatch.setattr(cache, "_runtime_version", lambda distribution: "2.0")
+ elif change == "threads":
+ monkeypatch.setenv("MINERU_INTRA_OP_NUM_THREADS", "8")
+ elif change == "cpu":
+ monkeypatch.setattr(cache, "effective_cpu_count", lambda: 2)
+ else:
+ adapter = WebGPUDevice(adapter.vendor_id, adapter.device_id)
+ assert not cache.calibrated_gpu_is_faster(adapter, 0.8)
+
+
+def test_adapter_reordering_and_webgpu_metadata(evidence_path: Path) -> None:
+ """设备排序不作为物理身份,WebGPU 元数据经过 JSON 后仍可匹配。"""
+ cache.save_calibration_record(_adapter(), _measurement())
+ assert cache.calibrated_gpu_is_faster(replace(_adapter(), index=7, preference=2), 0.8)
+ adapter = WebGPUDevice(0x8086, 0x7D51, (("driver", "v1"),))
+ cache.save_calibration_record(adapter, _measurement())
+ assert cache.calibrated_gpu_is_faster(adapter, 0.8)
+ assert not cache.calibrated_gpu_is_faster(replace(adapter, metadata=(("driver", "v2"),)), 0.8)
+
+
[email protected]("content", [None, "broken", '{"device":"gpu"}', '{"schema_version":0}'])
+def test_missing_and_invalid_evidence_is_read_only(evidence_path: Path, content: str | None) -> None:
+ """缺失、旧偏好和损坏记录均不授予高级能力,也不修写文件。"""
+ if content is not None:
+ evidence_path.write_text(content, encoding="utf-8")
+ assert not cache.calibrated_gpu_is_faster(_adapter(), 0.8)
+ assert evidence_path.read_text(encoding="utf-8") == content if content is not None else not evidence_path.exists()
+ assert list(evidence_path.parent.iterdir()) == ([evidence_path] if content is not None else [])
+
+
+def test_unwritable_record_does_not_break_calibration(evidence_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """证据写入失败不能影响校准完成后的运行设备选择。"""
+ monkeypatch.setattr(cache.os, "replace", Mock(side_effect=PermissionError("read only")))
+ cache.save_calibration_record(_adapter(), _measurement())
+ assert not list(evidence_path.parent.iterdir())
+
+
[email protected](("platform", "metal"), [("darwin", True), ("darwin", False), ("other", False)])
+def test_apple_metal_recommendation(monkeypatch: pytest.MonkeyPatch, platform: str, metal: bool) -> None:
+ """Apple Silicon 按 Metal 可用性推荐,不要求 Windows/Linux 校准记录。"""
+ from mineru.model.runtime import llama_device
+
+ monkeypatch.delenv("MINERU_LLAMA_CPP_BACKEND", raising=False)
+ monkeypatch.setattr(recommendation, "sys", SimpleNamespace(platform=platform))
+ monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: 4)
+ monkeypatch.setattr(recommendation, "_apple_metal_available", lambda: metal)
+ monkeypatch.setattr(llama_device, "discover_llama_devices", lambda: ())
+ assert recommendation.recommend_tiers() == frozenset(TIERS if metal else TIERS[:-1])
+
+
[email protected]("platform", ["win32", "linux"])
[email protected]("kind", ["discrete", "calibrated", "slow", "unknown", "mismatch", "hidden", "failure"])
+def test_gpu_discovery_uses_only_existing_evidence(
+ evidence_path: Path, monkeypatch: pytest.MonkeyPatch, platform: str, kind: str
+) -> None:
+ """以真实证据读取验证跨平台 GPU 路由,并禁止推荐路径调用校准。"""
+ from mineru.model.runtime import llama_device, onnx_device, webgpu, windows_gpu
+
+ monkeypatch.delenv("MINERU_LLAMA_CPP_BACKEND", raising=False)
+ monkeypatch.setattr(recommendation, "sys", SimpleNamespace(platform=platform))
+ monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: 4)
+ monkeypatch.setattr(onnx_device, "resolve_onnx_device", Mock(side_effect=AssertionError("must not calibrate")))
+ descriptor = LlamaDevice("Vulkan0", "test", "vulkan", kind != "discrete", 0x8086, 0x7D51)
+ if kind == "mismatch":
+ descriptor = replace(descriptor, device_id=1)
+ inventory = () if kind == "hidden" else (descriptor,)
+ monkeypatch.setattr(
+ llama_device,
+ "discover_llama_devices",
+ Mock(
+ return_value=inventory,
+ side_effect=RuntimeError("driver") if kind == "failure" else None,
+ ),
+ )
+ adapter = _adapter() if platform == "win32" else WebGPUDevice(0x8086, 0x7D51)
+ monkeypatch.setattr(windows_gpu, "discover_gpus", lambda: (adapter,))
+ monkeypatch.setattr(webgpu, "discover_webgpu_devices", lambda: (adapter,))
+ monkeypatch.setattr(webgpu, "select_webgpu_device", lambda devices: devices[0])
+ if kind != "unknown":
+ cache.save_calibration_record(adapter, _measurement(gpu_elapsed=3.0 if kind == "slow" else 1.0))
+ before = evidence_path.read_bytes() if evidence_path.exists() else None
+ assert recommendation.recommend_tiers() == frozenset(TIERS if kind in {"discrete", "calibrated"} else TIERS[:-1])
+ assert (evidence_path.read_bytes() if evidence_path.exists() else None) == before
+ onnx_device.resolve_onnx_device.assert_not_called()
+
+
+def test_explicit_cpu_and_discovery_failure(monkeypatch: pytest.MonkeyPatch) -> None:
+ """显式 CPU 禁止 GPU 推荐,CPU 探测失败时只推荐基础档位。"""
+ monkeypatch.setenv("MINERU_LLAMA_CPP_BACKEND", "cpu")
+ monkeypatch.setattr(recommendation, "effective_cpu_count", Mock(side_effect=OSError("affinity")))
+ assert recommendation.recommend_tiers() == {"flash"}
diff --git a/tests/unittest/test_v1_router.py b/tests/unittest/test_v1_router.py
index 8330a4f8..f5b9949d 100644
--- a/tests/unittest/test_v1_router.py
+++ b/tests/unittest/test_v1_router.py
@@ -82,6 +82,24 @@ def _make_router(
return create_app(settings, transport=httpx.MockTransport(_handler)), by_host
+def test_native_routing_requires_one_worker_with_complete_capabilities() -> None:
+ """原生文档绕过 tier 筛选,但来源和输出能力必须由同一个健康 worker 满足。"""
+ app, _ = _make_router(_FakeV1Upstream("worker-a", ("standard",)), _FakeV1Upstream("worker-b", ("basic",)))
+ with TestClient(app) as client:
+ first, second = app.state.worker_pool.workers
+ first.features = {"sources": ["upload"], "task_output_formats": ["default"]}
+ second.features = {"sources": ["url"], "task_output_formats": ["html"]}
+ body = {"files": [{"file_name": "native.docx", "bytes": 1}], "tier": "advanced", "output_formats": ["html"]}
+ rejected = client.post("/v1/tasks", json=body)
+ assert rejected.status_code == 503
+ assert not app.state.task_store._records
+ assert first.active_jobs == second.active_jobs == 0
+ first.features["task_output_formats"].append("html")
+ accepted = client.post("/v1/tasks", json=body)
+ assert accepted.status_code == 202, accepted.text
+ assert app.state.task_store._records[accepted.json()["task_id"]].options.tier == "flash"
+
+
def test_v1_router_preserves_upstream_tier_metadata() -> None:
"""验证 Router 不再从全局 models 列表推断各 tier 的 current_model。"""
upstream = _FakeV1Upstream(
@@ -120,7 +138,7 @@ def test_managed_router_worker_builds_new_api_server_command(tmp_path: Path) ->
assert command[:5] == [command[0], "-m", "mineru.kit.main", "api-server", "--host"]
assert command[0].endswith("python")
- assert ["--tiers", "flash,basic"] == command[command.index("--tiers") : command.index("--tiers") + 2]
+ assert ["--tier", "basic"] == command[command.index("--tier") : command.index("--tier") + 2]
assert ["--concurrency", "3"] == command[command.index("--concurrency") : command.index("--concurrency") + 2]
assert "--preload-models" in command