Skip to content

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

feat(gradio): unify automatic startup and default tier selection

myhloli955be0a1c08a
diff --git a/docs/en/usage/cli_tools.md b/docs/en/usage/cli_tools.md
index 4741e36a..bc592659 100644
--- a/docs/en/usage/cli_tools.md
+++ b/docs/en/usage/cli_tools.md
@@ -95,6 +95,8 @@ mineru-kit webui --server-name 127.0.0.1 --server-port 7860
Without `--api-url`, Gradio manages a loopback `mineru-kit api-server`. With `--api-url`, it connects only to that V1 service. `mineru-webui` is retained as a command-name alias and accepts the same modern options; it does not restore legacy Gradio options or HTTP routes.
+Gradio accepts only `--tier auto|flash|basic|standard|advanced`, defaulting to `auto`, for the managed API Server ceiling. The old `--api-server-tier` option has been removed. The UI and Tasks share the Standard → Basic → Flash → Advanced default order; Advanced is automatic only when it is the sole available tier.
+
### Router and VLM server
```bash
diff --git a/docs/en/usage/file_parse.md b/docs/en/usage/file_parse.md
index 4c134633..dd34730f 100644
--- a/docs/en/usage/file_parse.md
+++ b/docs/en/usage/file_parse.md
@@ -40,7 +40,7 @@ The wrapper has its own `/docs` and `/openapi.json`. The routes below exist only
| `wait_timeout` | `3600` | Integer seconds, 0–3600. |
| `request_id` | Generated | 1–64 letters, digits, underscores, or hyphens; supply and save it before submission to recover after a disconnect. |
-Omitting tier lets the upstream choose Standard → Basic → Flash for PDFs/images; Advanced requires an explicit request. An explicitly unsupported PDF/image tier returns an error without substitution. Existing native documents always use Flash, even when a valid requested tier is not advertised upstream. Empty form strings and the literal string `"null"` are invalid tiers, not omissions.
+Omitting tier lets the upstream choose Standard → Basic → Flash → Advanced for PDFs/images; Advanced is selected automatically only when it is the sole available tier. An explicitly unsupported PDF/image tier returns an error without substitution. Existing native documents always use Flash, even when a valid requested tier is not advertised upstream. Empty form strings and the literal string `"null"` are invalid tiers, not omissions.
`output_formats` is neither a JSON string nor a comma-separated value: use repeated form fields. `include_model_output` is removed and returns 400 when supplied.
diff --git a/docs/en/usage/tasks.md b/docs/en/usage/tasks.md
index b29f9fbb..9fe9284b 100644
--- a/docs/en/usage/tasks.md
+++ b/docs/en/usage/tasks.md
@@ -45,7 +45,7 @@ Requests must omit `file_id/client_file_id`, including null values. The server a
### Tier selection
-- For PDFs/images, an omitted or null tier selects the first supported value in **standard → basic → flash** order. Advanced requires an explicit request. An Advanced-only service returns `503 quality_tier_unavailable` when the tier is omitted.
+- For PDFs/images, an omitted or null tier selects the first supported value in **standard → basic → flash → advanced** order. Advanced is selected automatically only when it is the sole available tier.
- An explicitly unsupported PDF/image tier rejects the entire creation request with `400 invalid_request`, `error.param="tier"`. No work is accepted and no tier substitution occurs.
- Every normally available compatible service supports existing native document formats. Office, HTML, and other native documents always use Flash, regardless of `/v1/tiers` or a valid requested tier. Empty strings and unknown enum values are still invalid.
- Mixed batches select tiers per file. On a Standard-capable service, a PDF + DOCX request without a tier uses Standard and Flash respectively. Selection is fixed at admission, not repeated during queuing or forwarding. Successful files report the actual value in `parse.tier`.
diff --git a/docs/en/usage/tiers.md b/docs/en/usage/tiers.md
index cc181e9b..6bcae6eb 100644
--- a/docs/en/usage/tiers.md
+++ b/docs/en/usage/tiers.md
@@ -23,10 +23,10 @@ mineru-kit parse saved-page.mhtml -o saved-page.md --tier flash
- `mineru-kit parse` and local Python `parse()` default to Standard for PDFs.
- After discovering service capabilities, the document library prefers Standard, then Basic for PDF/images. If neither is available, it returns `quality_tier_unavailable` rather than silently choosing Flash or uploading to the official service.
-- Advanced requires an explicit request. It shares models with Standard rather than downloading separate Advanced weights; the service must enable Advanced to accept corresponding PDF/image requests.
+- Tasks and Gradio share the Standard → Basic → Flash → Advanced preference, selecting Advanced automatically only when it is the sole available tier. Advanced shares models with Standard rather than downloading separate Advanced weights; the service must enable Advanced to accept corresponding PDF/image requests.
- Library `read` consumes cached results without starting a new parse. Without an explicit tier, it prefers cached Advanced, Standard, then Basic results.
-The API startup `--tier` is a ceiling including itself and lower tiers; `--tier standard` does not enable Advanced. Omission or `--tier auto` recommends a ceiling from the effective backend and hardware, potentially calibrating ONNX at startup. HTTP requests without a tier choose Standard → Basic → Flash. Native documents always use Flash, independently of the enabled PDF/image tiers. See [Tasks](tasks.md) for the full rules.
+The API startup `--tier` is a ceiling including itself and lower tiers; `--tier standard` does not enable Advanced. Omission or `--tier auto` recommends a ceiling from the effective backend and hardware, potentially calibrating ONNX at startup. HTTP requests without a tier choose Standard → Basic → Flash → Advanced. Native documents always use Flash, independently of the enabled PDF/image tiers. See [Tasks](tasks.md) for the full rules.
## Backends and engines
diff --git a/docs/next/api/file-parse.md b/docs/next/api/file-parse.md
index e4d38590..8ad17e72 100644
--- a/docs/next/api/file-parse.md
+++ b/docs/next/api/file-parse.md
@@ -38,7 +38,7 @@ MINERU_API_URL=https://mineru.net/api MINERU_API_KEY=your-key \
| `wait_timeout` | `3600` | 整数秒,范围 `0–3600`。 |
| `request_id` | 自动生成 | 1–64 个字母、数字、下划线或短横线。提前指定并保存它,可在连接中断后查询。 |
-未提供 tier 表单字段时,包装层在上游 Tasks 请求中省略该字段,由上游按 **standard → basic → flash** 选择默认档位;advanced 必须显式指定。
+未提供 tier 表单字段时,包装层在上游 Tasks 请求中省略该字段,由上游按 **standard → basic → flash → advanced** 选择默认档位;仅开放 advanced 时自动选择 advanced。
显式值原样传递,PDF/图片请求的档位不受上游支持时返回错误,不自动升降档。
所有正常可用服务都支持 Office、HTML 等现有原生格式,固定使用 flash,即使传入上游未开放的合法档位也不改变原生解析路径。
表单空字符串或字符串 `"null"` 不是省略字段,属于非法值;OpenAPI 将 tier 声明为可省略的字符串枚举,不声明可空值。完整规则见 [Tasks tier 语义](tasks.md#tier默认选择与文件作用范围)。
diff --git a/docs/next/api/health-models.md b/docs/next/api/health-models.md
index ba76cd3f..aaf0545c 100644
--- a/docs/next/api/health-models.md
+++ b/docs/next/api/health-models.md
@@ -156,7 +156,7 @@ Tier 对象字段:
v1 协议中面向用户读取文档的质量档位以 [解析 Tier](../tiers.md) 为准。具体服务当前支持哪些 tier,以 `/v1/tiers` 返回为准。
-请求创建 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 不作为解析输入。
+请求创建 Task 时,客户端可以省略 `tier` 或传 `null`,表示使用 [解析 Tier](../tiers.md) 中定义的默认选择策略。对 PDF/image 按 `standard -> basic -> flash -> advanced` 选择默认值,仅开放 advanced 时自动选择 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)。
diff --git a/docs/next/api/tasks.md b/docs/next/api/tasks.md
index 6afcbb9f..81e0cee0 100644
--- a/docs/next/api/tasks.md
+++ b/docs/next/api/tasks.md
@@ -42,8 +42,8 @@ ModelJson 仅用于内部解析与后处理,不属于 HTTP 或 SDK 结果。
### tier:默认选择与文件作用范围
-省略 `tier` 或传入 JSON `null` 时,服务端从支持的档位中按 **standard → basic → flash** 选择第一个,advanced 只能显式指定。
-仅开放 flash 的服务可以直接接收未指定 tier 的 PDF/图片;仅开放 advanced 时,未指定 tier 返回 `503 quality_tier_unavailable`,需显式传入 `advanced`。
+省略 `tier` 或传入 JSON `null` 时,服务端从支持的档位中按 **standard → basic → flash → advanced** 选择第一个;仅服务只开放 advanced 时默认选择 advanced。
+仅开放 flash 的服务可以直接接收未指定 tier 的 PDF/图片;仅开放 advanced 时,未指定 tier 默认使用 `advanced`。
请求包含 PDF/图片且显式提供 tier 时,服务支持该档位就原样使用;不支持则在创建阶段返回 `400 invalid_request`,`error.param="tier"`,整个请求不接单、不分配上传链接,也不自动升档或降档。
空字符串和未知枚举始终是参数错误,包括纯原生文档请求。
diff --git a/docs/next/cli/mineru-kit-api-server.md b/docs/next/cli/mineru-kit-api-server.md
index ddb1e61f..ea5999fe 100644
--- a/docs/next/cli/mineru-kit-api-server.md
+++ b/docs/next/cli/mineru-kit-api-server.md
@@ -50,7 +50,7 @@ api-server 必须提供能力发现接口,让 doclib 或客户端知道当前
| `--tier standard` | `flash`、`basic`、`standard` | `standard` |
| `--tier advanced` | 全部四档 | `standard` |
-Tasks 的请求 `tier` 仍可选,只对 PDF/图片生效。省略或 JSON `null` 时按 `standard -> basic -> flash` 选择,advanced 必须显式请求。所有服务均支持 OFD/EPUB/Office/HTML/MHTML/CSV/TSV 等现有原生格式,固定使用 flash,不检查公开列表中是否有 flash。非法枚举或空字符串仍报错。完整规则见 [Tasks](../api/tasks.md#tier默认选择与文件作用范围)。
+Tasks 的请求 `tier` 仍可选,只对 PDF/图片生效。省略或 JSON `null` 时按 `standard -> basic -> flash -> advanced` 选择,仅开放 advanced 时也可使用默认值。所有服务均支持 OFD/EPUB/Office/HTML/MHTML/CSV/TSV 等现有原生格式,固定使用 flash,不检查公开列表中是否有 flash。非法枚举或空字符串仍报错。完整规则见 [Tasks](../api/tasks.md#tier默认选择与文件作用范围)。
### 自动推荐
@@ -99,7 +99,7 @@ SaaS 可按共同契约仅发布 standard,原生文档由同一服务解析。
非连续精确集合只用于 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 模型配置。
+WebUI、Router、Doclib 的托管 standard 均只开放到 standard,不再隐含 advanced;需要时显式配置 advanced。WebUI 默认配置为 auto,Router、Doclib 仍为 standard。Doclib 的 `parse_server.local.managed_tier` 支持 basic、standard、advanced,其原生执行路径保持现状。Advanced 的模型检查与下载使用 Standard 模型配置。
## 4. self-hosted 与 managed
diff --git a/docs/next/cli/mineru-kit-webui.md b/docs/next/cli/mineru-kit-webui.md
index bb2bc574..86c50c26 100644
--- a/docs/next/cli/mineru-kit-webui.md
+++ b/docs/next/cli/mineru-kit-webui.md
@@ -37,6 +37,10 @@ pip install mineru
```bash
mineru-kit webui
+# 与省略参数等价,自动推荐自托管服务上限
+mineru-kit webui --tier auto
+# 显式限制最高档位
+mineru-kit webui --tier basic
```
连接已有 self-hosted 或 remote V1 API server:
@@ -47,7 +51,7 @@ mineru-kit webui \
--api-key "$MINERU_API_KEY"
```
-未指定 `--api-url` 时,Gradio 会启动一个 loopback `mineru-kit api-server`。本地 server 默认使用 Standard 能力上限,PDF/图片开放 flash、basic、standard;需要 Advanced 时显式配置。原生文档始终支持并固定 flash。所有文件通过 Tasks 提交 hash 清单,缓存未命中时上传,同机也不使用路径免上传。
+未指定 `--api-url` 时,Gradio 会启动一个 loopback `mineru-kit api-server`。本地 server 默认使用 `--tier auto`,由 API Server 按硬件和有效后端推荐 PDF/图片上限;可用 `--tier flash|basic|standard|advanced` 显式指定上限。原生文档始终支持并固定 flash。所有文件通过 Tasks 提交 hash 清单,缓存未命中时上传,同机也不使用路径免上传。
未指定 `--server-port` 时,界面由 Gradio 从 `7860` 开始寻找空闲端口;可通过 `GRADIO_SERVER_PORT` 设置起始端口、`GRADIO_NUM_PORTS` 设置尝试数量(默认 `100`)。显式指定 `--server-port 7861` 时只尝试该端口,覆盖环境变量;该端口已被占用则启动失败。界面最终访问地址以启动输出为准,与内部 API server 的端口不同。
@@ -60,14 +64,14 @@ mineru-kit webui \
| `--server-name` / `--server-port` | Gradio UI 的监听地址和端口;省略端口时自动寻找空闲端口。 |
| `--output-dir` | 本地 UI 产物根目录,默认 `./output`。 |
| `--max-pages` | 单次 PDF 解析的最多页数,必须为正整数;省略则不限制。不限制非 PDF。 |
-| `--api-server-tier` | 自动启动 server 的最高档位:`flash`、`basic`、`standard`、`advanced`。 |
+| `--tier` | 自托管 API Server 的上限:`auto`(默认)、`flash`、`basic`、`standard`、`advanced`;指定 `--api-url` 时忽略。 |
| `--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 与 WebUI 的单值托管配置统一表示能力上限,并包含自身和全部较低档位。
+Gradio 只保留 `--tier`,不接受旧名 `--api-server-tier`。Gradio 不接受 `--api-server-no-flash`、`--no-flash`、`--api-server-no-advanced`、`--no-advanced`;传入会报错。独立 API 与 WebUI 的单值托管配置统一表示能力上限,并包含自身和全部较低档位。
指定外部 `--api-url` 时,Gradio 校验 `/v1/health` 和 `/v1/tiers` 后直接使用该服务。公开 tiers 只约束 PDF/图片;原生文档同样上传给远端,不因列表中缺少 flash 而启动本地补充服务或增加 PDF 档位。认证只用于所连接服务,连接或解析失败保持原错误。
@@ -75,7 +79,7 @@ Gradio 不接受 `--api-server-no-flash`、`--no-flash`、`--api-server-no-advan
界面一次提交一个文件,支持 `filetypes.PARSEABLE_EXTENSIONS` 中的 PDF、图片、Office/ODF、RTF、HTML、MHTML/MHT、CSV/TSV、EPUB 和 OFD。
-解析 tier 使用原生离散滑块选择,上方即时显示当前档位。滑块按 `flash → basic → standard → advanced` 排列,只包含所连接服务发布的 PDF/图片档位。默认优先选择 `standard`,否则选择最高可用档位;仅有一个档位时隐藏滑块,保留固定档位说明。
+解析 tier 使用原生离散滑块选择,上方即时显示当前档位。滑块按 `flash → basic → standard → advanced` 排列,只包含所连接服务发布的 PDF/图片档位。界面与 Tasks 省略 tier 共用 `standard → basic → flash → advanced` 选择规则,仅服务只开放 advanced 时默认选 advanced;仅有一个档位时隐藏滑块,保留固定档位说明。
上传 Office/ODF、RTF、HTML、MHTML/MHT、CSV/TSV、EPUB、OFD 时,显示固定 `flash` 并隐藏滑块,不要求服务在 tiers 中发布 flash。界面记住本会话最后一次未锁定的档位,连续更换这类文件不会覆盖记忆;切回 PDF/图片或清除文件时恢复此前选择。PDF/图片之间切换继续保留当前档位。锁定与恢复同时更新档位标签、页码控件和转换按钮,无需向 Python 发送滑块拖动请求。
diff --git a/docs/next/sdk/api-parser.md b/docs/next/sdk/api-parser.md
index 7b4f358a..63331719 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`。
-`/v1/tiers` 仅描述 PDF/图片档位,原生文档始终可提交给所连接服务并使用 flash。SDK 不自行选择默认 tier:PDF/图片由服务端按 **standard → basic → flash** 选择支持的档位,advanced 必须显式指定。
+`/v1/tiers` 仅描述 PDF/图片档位,原生文档始终可提交给所连接服务并使用 flash。SDK 不自行选择默认 tier:PDF/图片由服务端按 **standard → basic → flash → advanced** 选择支持的档位,仅开放 advanced 时自动选择 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 047a2d04..68dbf31d 100644
--- a/docs/next/tiers.md
+++ b/docs/next/tiers.md
@@ -94,8 +94,8 @@ Doclib 主动解析 PDF/image 的默认选择策略不会解析为 `flash`。如
### 3.3 HTTP Tasks 的默认选择
-Tasks(包括 HTTP `MinerUApiParser` 和 file_parse)省略 tier 时,由接单服务按 `standard -> basic -> flash` 选择支持的档位。JSON Tasks 的 `null` 也表示省略;file_parse 使用 multipart,应直接省略表单字段。
-advanced 只接受显式选择:只有 advanced 时没有默认档位,返回结构化错误。显式指定的 PDF/image 档位不受支持时拒绝请求,不自动升降档。
+Tasks(包括 HTTP `MinerUApiParser` 和 file_parse)省略 tier 时,由接单服务按 `standard -> basic -> flash -> advanced` 选择支持的档位。Gradio 初始选档共享同一函数。JSON Tasks 的 `null` 也表示省略;file_parse 使用 multipart,应直接省略表单字段。
+advanced 仅在它是服务唯一可用档位时自动选择。显式指定的 PDF/image 档位不受支持时拒绝请求,不自动升降档。
已支持的原生文档固定使用 flash,忽略合法的显式 tier。任务受理后固定选档,实际结果逐文件记录在 `files[].parse.tier`。该策略不改变 Doclib 的主动阅读和缓存选择规则,详见 [Tasks](api/tasks.md#tier默认选择与文件作用范围)。
### 3.4 API 服务启动推荐
@@ -106,7 +106,7 @@ advanced 只接受显式选择:只有 advanced 时没有默认档位,返回
显存按原始字节比较,不取整、不累加多卡,不使用虚拟显存覆盖。统一/共享内存使用 Metal 推荐工作集、DXGI 本地预算或 Vulkan `heapBudget`,不以系统总内存替代。最终集合在启动时固定;`mineru-kit hardware detect` 共享推荐与内存证据,`hardware info` 只读收集环境信息。
-`--tier standard` 等显式上限开放自身和全部较低档位,允许覆盖硬件推荐。`/v1/tiers` 只约束 PDF/图片,原生文档在任何正常可用服务上均固定使用 flash。请求默认仍优先 standard,advanced 不参与默认选档。详见 [启动配置与迁移说明](cli/mineru-kit-api-server.md)。
+`--tier standard` 等显式上限开放自身和全部较低档位,允许覆盖硬件推荐。`/v1/tiers` 只约束 PDF/图片,原生文档在任何正常可用服务上均固定使用 flash。请求默认仍优先 standard;仅开放 advanced 的精确集合以 advanced 为默认档位。详见 [启动配置与迁移说明](cli/mineru-kit-api-server.md)。
## 4. Flash
@@ -182,12 +182,12 @@ MinerU 的 tier 策略同时遵守隐私优先和质量优先。
| 请求 | 默认执行路径 |
|------|--------------|
| watch 自动发现文件 | 本地 `flash` |
-| `mineru-kit api-server` 未传 `--tier` | 硬件推荐开放集合;HTTP 请求按 standard → basic → flash 选档 |
+| `mineru-kit api-server` 未传 `--tier` | 硬件推荐开放集合;HTTP 请求按 standard → basic → flash → advanced 选档 |
| `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 只入库和索引 |
| Doclib 用户主动 parse,未指定 tier | PDF/image 有能力发现上下文时按 `standard` -> `basic` 选择;OFD/EPUB/Office/HTML/MHTML/CSV/TSV 按 [ADR-0024](decisions/0024-file-type-tier-normalization.md) 与 [ADR-0028](decisions/0028-csv-structured-flash-parsing.md) 归一为 `flash`;其它 text 不进入解析 |
-| HTTP Tasks 省略 tier 或传 JSON `null`;HTTP SDK 传 `None`;file_parse 省略 tier | PDF/image 按 `standard` -> `basic` -> `flash` 选择;已支持的原生文档固定 flash;advanced 必须显式指定 |
+| HTTP Tasks 省略 tier 或传 JSON `null`;HTTP SDK 传 `None`;file_parse 省略 tier | PDF/image 按 `standard` -> `basic` -> `flash` -> `advanced` 选择;已支持的原生文档固定 flash;仅开放 advanced 时默认选 advanced |
| 用户主动指定 `--tier flash` | 本地 `flash` |
| 用户主动指定 `--tier basic` | 本地 basic;不可用时报错 |
| 用户主动指定 `--tier standard` | 本地 standard;显式 remote 时使用 `mineru.net/api` standard |
@@ -203,9 +203,9 @@ CLI、API 和 SDK 暴露 tier 时,应遵守同一语义:
- 对用户显示 tier,不显示具体 backend 名称作为主要选择项。
- 公开 tier 取值包括 `flash`、`basic`、`standard`、`advanced`。
- CLI 不传 `--tier`、HTTP API 省略 `tier` 或传 JSON `null`、Python SDK 传 `None`,表示使用当前入口按文件类型定义的默认选择策略。
-- 没有能力列表的启动服务或直接解析场景默认使用 `standard`。
+- 直接本地解析默认使用 `standard`;API Server 和 Gradio 自托管服务启动默认使用 `auto` 推荐上限。
- Doclib 主动解析 PDF/image 时按 `standard` -> `basic` 选择,默认阅读质量不能静默降级到 `flash`。
-- HTTP Tasks 及其客户端默认按 `standard` -> `basic` -> `flash` 选择,不自动选择 advanced。
+- HTTP Tasks 及其客户端默认按 `standard` -> `basic` -> `flash` -> `advanced` 选择,仅开放 advanced 时默认选 advanced。
- 显式请求的 PDF/image tier 不可用时,应返回结构化错误,不自动升降档。
- 当用户显式选择 `flash` 时,可以返回 `flash` 内容。
- `--remote` 或等价字段必须是显式选择。
diff --git a/docs/zh/usage/cli_tools.md b/docs/zh/usage/cli_tools.md
index d2c89398..166f85da 100644
--- a/docs/zh/usage/cli_tools.md
+++ b/docs/zh/usage/cli_tools.md
@@ -95,6 +95,8 @@ mineru-kit webui --server-name 127.0.0.1 --server-port 7860
未传 `--api-url` 时,Gradio 会托管 loopback `mineru-kit api-server`;传入后只连接指定的 V1 服务。`mineru-webui` 保留为命令名兼容别名,接受相同的新版参数,不恢复旧 Gradio 参数或 HTTP 路由。
+Gradio 只保留 `--tier auto|flash|basic|standard|advanced`,默认 `auto`,仅用于自托管 API Server 的上限。旧参数 `--api-server-tier` 已移除。界面与 Tasks 共享默认选档顺序 Standard → Basic → Flash → Advanced;仅开放 Advanced 时自动选择它。
+
### Router 与 VLM Server
```bash
diff --git a/docs/zh/usage/file_parse.md b/docs/zh/usage/file_parse.md
index b3d9048e..0a7862e1 100644
--- a/docs/zh/usage/file_parse.md
+++ b/docs/zh/usage/file_parse.md
@@ -40,7 +40,7 @@ mineru-kit file-parse-server --api-url http://127.0.0.1:8000
| `wait_timeout` | `3600` | 整数秒,范围 0–3600。 |
| `request_id` | 自动生成 | 1–64 位字母、数字、下划线或短横线;预先指定并保存以便断连后恢复。 |
-省略 tier 时由上游按 Standard → Basic → Flash 选择 PDF/图片档位;Advanced 必须显式请求。显式不支持的 PDF/图片档位返回错误,不自动改档。现有原生文档固定使用 Flash,即使传入上游未开放的合法档位。表单空字符串或字符串 `"null"` 不等于省略,均为非法 tier。
+省略 tier 时由上游按 Standard → Basic → Flash → Advanced 选择 PDF/图片档位;仅开放 Advanced 时默认选择 Advanced。显式不支持的 PDF/图片档位返回错误,不自动改档。现有原生文档固定使用 Flash,即使传入上游未开放的合法档位。表单空字符串或字符串 `"null"` 不等于省略,均为非法 tier。
`output_formats` 不接受 JSON 字符串或逗号分隔值;多格式使用多个同名表单字段。`include_model_output` 已移除,传入即返回 400。
diff --git a/docs/zh/usage/tasks.md b/docs/zh/usage/tasks.md
index daf51ffb..09deb653 100644
--- a/docs/zh/usage/tasks.md
+++ b/docs/zh/usage/tasks.md
@@ -45,7 +45,7 @@ mineru-kit api-server --host 127.0.0.1 --port 8000 --tier auto
### 档位选择
-- PDF/图片省略 `tier` 或传入 null,按 **standard → basic → flash** 选择支持的默认值;Advanced 必须显式指定。仅支持 Advanced 的服务在省略档位时返回 `503 quality_tier_unavailable`。
+- PDF/图片省略 `tier` 或传入 null,按 **standard → basic → flash → advanced** 选择支持的默认值;仅支持 Advanced 的服务在省略档位时默认选择 Advanced。
- 显式请求不支持的 PDF/图片档位,整次创建返回 `400 invalid_request`,`error.param="tier"`,不会接单或自动升降档。
- 所有正常可用的兼容服务都支持现有原生文档格式。Office、HTML 等固定使用 Flash,不受 `/v1/tiers` 或合法请求档位限制;空字符串和未知枚举仍非法。
- 混合批次分别确定档位。例如服务支持 Standard,未指定 tier 的 PDF + DOCX 分别使用 Standard、Flash。档位在接单时确定,排队或转发时不重新选择;实际执行值见成功文件的 `parse.tier`。
diff --git a/docs/zh/usage/tiers.md b/docs/zh/usage/tiers.md
index 9a7e53e1..c51b9dec 100644
--- a/docs/zh/usage/tiers.md
+++ b/docs/zh/usage/tiers.md
@@ -23,10 +23,10 @@ mineru-kit parse saved-page.mhtml -o saved-page.md --tier flash
- `mineru-kit parse` 和本地 Python `parse()` 的 PDF 默认档位为 Standard。
- 文档库发现服务能力后,PDF/图片默认优先 Standard,其次 Basic;不可用时报 `quality_tier_unavailable`,不会静默降为 Flash 或上传到官网。
-- Advanced 需要显式请求;它与 Standard 共用模型,不单独下载一套 Advanced 权重。服务需开放 Advanced 才能接受相应 PDF/图片请求。
+- Tasks 与 Gradio 默认按 Standard → Basic → Flash → Advanced 选档,仅开放 Advanced 时自动选择它;Advanced 与 Standard 共用模型,不单独下载一套 Advanced 权重。服务需开放 Advanced 才能接受相应 PDF/图片请求。
- 文档库 `read` 读取已有缓存,不发起新解析;未指定档位时优先已有的 Advanced、Standard、Basic 结果。
-API 启动 `--tier` 表示开放上限,包含自身和较低档位;`--tier standard` 不开放 Advanced。省略或 `--tier auto` 按实际后端和硬件推荐,ONNX 路径可能在启动时执行设备校准。HTTP 请求省略 tier 时按 Standard → Basic → Flash 选择;原生文档固定 Flash,不受 PDF/图片开放档位限制。完整规则见 [Tasks](tasks.md)。
+API 启动 `--tier` 表示开放上限,包含自身和较低档位;`--tier standard` 不开放 Advanced。省略或 `--tier auto` 按实际后端和硬件推荐,ONNX 路径可能在启动时执行设备校准。HTTP 请求省略 tier 时按 Standard → Basic → Flash → Advanced 选择;原生文档固定 Flash,不受 PDF/图片开放档位限制。完整规则见 [Tasks](tasks.md)。
## 后端与引擎
diff --git a/mineru/kit/commands/webui.py b/mineru/kit/commands/webui.py
index c12db0db..6e70309b 100644
--- a/mineru/kit/commands/webui.py
+++ b/mineru/kit/commands/webui.py
@@ -9,7 +9,7 @@ from importlib.metadata import version
import typer
from packaging.specifiers import SpecifierSet
-from ...types import SERVER_TIERS, ServerTier
+from ...types import SERVER_STARTUP_TIERS, ServerStartupTier
from ...utils.i18n import t
from ...utils.logger import configure_global_log_level
from ...utils.stdio import configure_standard_streams
@@ -30,17 +30,17 @@ def _require_gradio_dependencies() -> None:
)
-def _validate_server_tier(value: str) -> ServerTier:
+def _validate_server_tier(value: str) -> ServerStartupTier:
"""校验自动启动的本地 API server 能力档位。"""
- if value not in SERVER_TIERS:
+ if value not in SERVER_STARTUP_TIERS:
exit_with_message(
"invalid_request",
t(
"Unsupported API server tier '{tier}'. Supported tiers: {tiers}",
tier=value,
- tiers=", ".join(SERVER_TIERS),
+ tiers=", ".join(SERVER_STARTUP_TIERS),
),
- "api_server_tier",
+ "tier",
)
return value # type: ignore[return-value]
@@ -70,8 +70,10 @@ def webui_cmd(
max_pages: int | None = typer.Option(None, "--max-pages", help=t("Maximum pages per PDF conversion; omitted: unlimited")),
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 tier ceiling")
+ tier: str = typer.Option(
+ "auto",
+ "--tier",
+ help=t("Managed API server tier ceiling: auto, flash, basic, standard, advanced; ignored with --api-url"),
),
api_server_concurrency: int = typer.Option(
1, "--api-server-concurrency", "--concurrency", help=t("Managed server job concurrency")
@@ -93,7 +95,7 @@ def webui_cmd(
if max_pages is not None:
_validate_positive_option(max_pages, name="max_pages")
_validate_positive_option(api_server_concurrency, name="api_server_concurrency")
- normalized_tier = _validate_server_tier(api_server_tier)
+ normalized_tier = _validate_server_tier(tier)
from ..gradio.app import launch_gradio
@@ -108,7 +110,7 @@ def webui_cmd(
max_pages=max_pages,
enable_example=enable_example,
enable_api=enable_api,
- api_server_tier=normalized_tier,
+ tier=normalized_tier,
api_server_concurrency=api_server_concurrency,
api_server_disable_image_analysis=api_server_disable_image_analysis,
api_server_preload_models=api_server_preload_models,
diff --git a/mineru/kit/file_parse/app.py b/mineru/kit/file_parse/app.py
index 2bacba07..752cb9d1 100644
--- a/mineru/kit/file_parse/app.py
+++ b/mineru/kit/file_parse/app.py
@@ -102,8 +102,9 @@ def _request_schema() -> dict[str, Any]:
"type": "string",
"enum": list(TIERS),
"description": (
- "Optional PDF/image tier. Omit this multipart field to let the server choose standard, basic, then flash; "
- "advanced requires an explicit request. Explicit unsupported PDF/image tiers are rejected. "
+ "Optional PDF/image tier. Omit this multipart field to let the server choose "
+ "standard, basic, flash, then advanced; "
+ "advanced is automatic only when it is the sole available tier. Explicit unsupported PDF/image tiers are rejected. "
"Supported native documents always use flash. Empty strings and the literal string 'null' are invalid."
),
}
diff --git a/mineru/kit/gradio/app.py b/mineru/kit/gradio/app.py
index 6296cb3f..d018c525 100644
--- a/mineru/kit/gradio/app.py
+++ b/mineru/kit/gradio/app.py
@@ -22,7 +22,7 @@ from ...filetypes import (
PARSEABLE_EXTENSIONS,
PDF_EXTENSIONS,
)
-from ...types import TIERS
+from ...types import TIERS, ServerStartupTier, Tier, select_default_task_tier
from ...utils.logger import configure_global_log_level
from ...utils.stdio import configure_standard_streams
from .artifacts import RunArtifacts, render_download
@@ -72,7 +72,6 @@ _DOWNLOAD_ICON_PATHS: dict[str, str] = {
"epub": "M12 6c-3-2-6-2-10-2v15c4 0 7 0 10 2 3-2 6-2 10-2V4c-4 0-7 0-10 2v15",
"pdf": "M14 3H5v18h14V8l-5-5v5h5M8 17c3-4 5-8 4-8-2 0-1 7 4 7 3 0-5-3-8 1-1 2 1 1 2 0",
}
-_DEFAULT_TIER = "standard"
_DOWNLOAD_ICON_HTML = f"""
<button type="button" class="mineru-kit-download-icon" title="Download results" aria-label="Download results"
data-mineru-i18n-key="download_results" data-mineru-i18n-attr="title aria-label"
@@ -308,14 +307,12 @@ def _supported_file_types() -> list[str]:
return [f".{extension}" for extension in sorted(PARSEABLE_EXTENSIONS)]
-def _default_tier(capabilities: V1ServerCapabilities) -> str:
- """按服务能力选择默认 tier,优先保持 Standard 语义。"""
- if _DEFAULT_TIER in capabilities.tiers:
- return _DEFAULT_TIER
- for tier in ("advanced", "standard", "basic", "flash"):
- if tier in capabilities.tiers:
- return tier
- return capabilities.tiers[0]
+def _default_tier(capabilities: V1ServerCapabilities) -> Tier:
+ """根据服务能力复用 Tasks 默认选档,空能力集合无法构建解析界面。"""
+ tier = select_default_task_tier(capabilities.tiers)
+ if tier is None:
+ raise ValueError("V1 API server did not advertise any parsing tier")
+ return tier
def _file_suffix(path_value: str | Path | None) -> str:
@@ -1124,7 +1121,7 @@ def launch_gradio(
output_dir: str,
enable_example: bool,
enable_api: bool,
- api_server_tier: str,
+ tier: ServerStartupTier = "auto",
api_server_concurrency: int,
api_server_disable_image_analysis: bool,
api_server_preload_models: bool,
@@ -1142,7 +1139,7 @@ def launch_gradio(
try:
if resolved_api_url is None:
managed_server = ManagedLocalApiServer(
- tier=api_server_tier, # type: ignore[arg-type]
+ tier=tier,
concurrency=api_server_concurrency,
disable_image_analysis=api_server_disable_image_analysis,
preload_models=api_server_preload_models,
diff --git a/mineru/kit/gradio/client.py b/mineru/kit/gradio/client.py
index 0cc0ecd7..6a72db19 100644
--- a/mineru/kit/gradio/client.py
+++ b/mineru/kit/gradio/client.py
@@ -20,7 +20,7 @@ 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 SERVER_TIERS, TIERS, ServerTier, Tier
+from ...types import SERVER_STARTUP_TIERS, TIERS, ServerStartupTier, Tier
from ...filetypes import is_flash_only_parse_extension
from ...utils.stdio import utf8_subprocess_env
from .status import (
@@ -303,14 +303,14 @@ class ManagedLocalApiServer:
def __init__(
self,
*,
- tier: ServerTier = "standard",
+ tier: ServerStartupTier = "auto",
concurrency: int = 1,
disable_image_analysis: bool = False,
preload_models: bool = False,
api_key: str | None = None,
) -> None:
"""保存显式启动配置,但不在构造阶段创建目录或启动进程。"""
- if tier not in SERVER_TIERS:
+ if tier not in SERVER_STARTUP_TIERS:
raise ValueError(f"Unsupported API server tier: {tier}")
if concurrency <= 0:
raise ValueError("API server concurrency must be positive")
diff --git a/mineru/model/runtime/tier_recommendation.py b/mineru/model/runtime/tier_recommendation.py
index cef6dc49..17f87168 100644
--- a/mineru/model/runtime/tier_recommendation.py
+++ b/mineru/model/runtime/tier_recommendation.py
@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING
from loguru import logger
-from ...types import TIERS, Tier
+from ...types import TIERS, Tier, select_default_task_tier
from .cpu_threads import effective_cpu_count
from .device import resolve_small_model_backend, resolve_torch_device
from .gpu import is_discrete_gpu, match_gpu_identities
@@ -247,7 +247,8 @@ def recommend_tiers(*, vlm_config: VlmConfig | None = None) -> TierRecommendatio
hardware.reason,
)
ordered = tuple(tier for tier in TIERS if tier in tiers)
- default = next(tier for tier in ("standard", "basic", "flash") if tier in tiers)
+ default = select_default_task_tier(tiers)
+ assert default is not None # 硬件推荐始终包含 Flash,必定存在请求默认档位。
return TierRecommendation(
ordered[-1],
ordered,
diff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.py
index 8acaa497..511f29ab 100644
--- a/mineru/parser/api_server.py
+++ b/mineru/parser/api_server.py
@@ -50,7 +50,7 @@ from ..filetypes import (
file_type_for_extension,
is_flash_only_parse_extension,
)
-from ..types import DeploymentTier, PageInfo, Tier
+from ..types import DeploymentTier, PageInfo, Tier, select_default_task_tier
from ..utils.async_utils import drain_future, run_sync
from ..model.runtime.ownership import RuntimeOwner, runtime_owner
from ..model.vlm.errors import is_fatal_engine_error
@@ -1818,7 +1818,7 @@ def create_app(
server_tiers = resolve_server_tiers(tiers, vlm_config=vlm_config)
model_tier = model_tier_for_server_tiers(server_tiers)
tier_runtime_options = _runtime_options_for_server_tiers(server_tiers)
- default_tier = next((tier for tier in ("standard", "basic", "flash") if tier in server_tiers), None)
+ default_tier = select_default_task_tier(server_tiers)
_preflight_tier_dependencies(model_tier, vlm_config)
_api_key: str | None = api_key or None
_upload_dir = pathlib.Path(upload_dir) if upload_dir else pathlib.Path(tempfile.mkdtemp(prefix="mineru_"))
diff --git a/mineru/tasks/contracts.py b/mineru/tasks/contracts.py
index c41ff9ed..82121995 100644
--- a/mineru/tasks/contracts.py
+++ b/mineru/tasks/contracts.py
@@ -84,8 +84,9 @@ class UploadTaskOptions(BaseModel):
tier: Tier | None = Field(
default=None,
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. "
+ "PDF/image tier only. Omitted or null selects the first supported tier in the order "
+ "standard, basic, flash, advanced; advanced is automatic only when it is the sole available tier. "
+ "Explicit unsupported tiers are rejected. "
"All servers support native document formats with flash, independently of /v1/tiers "
"and ignoring any valid tier value."
),
diff --git a/mineru/tasks/service.py b/mineru/tasks/service.py
index c0c24b00..ee492992 100644
--- a/mineru/tasks/service.py
+++ b/mineru/tasks/service.py
@@ -15,7 +15,7 @@ from pathlib import Path
from ..filetypes import is_flash_only_parse_extension
from ..task_types import TaskFileState, TaskStatus
-from ..types import Tier
+from ..types import Tier, select_default_task_tier
from ..utils.async_utils import drain_future, run_sync
from .contracts import ErrorDetail, TaskFileInput, TaskFileItem, UploadTaskOptions
from .errors import ApiServerError, invalid_task_request
@@ -23,7 +23,6 @@ from .execution import TaskBackend, TaskExecution, TaskUpload, execution_timesta
TASK_UPLOAD_TTL = 3600
TERMINAL_TASK_STATUSES = frozenset({"completed", "partial", "failed", "canceled"})
-_DEFAULT_TASK_TIER_SELECTION_ORDER: tuple[Tier, ...] = ("standard", "basic", "flash")
logger = logging.getLogger(__name__)
@@ -36,11 +35,11 @@ def resolve_task_tier(options: UploadTaskOptions, inputs: list[TaskFileInput], t
if options.tier not in tiers:
invalid_task_request(f"Tier '{options.tier}' is not available", param="tier")
return options.tier
- for tier in _DEFAULT_TASK_TIER_SELECTION_ORDER:
- if tier in tiers:
- return tier
+ default_tier = select_default_task_tier(tiers)
+ if default_tier is not None:
+ return default_tier
invalid_task_request(
- "No default tier is available (standard, basic, or flash); pass tier explicitly",
+ "No parsing tier is available for PDF/image tasks",
code="quality_tier_unavailable",
status_code=503,
)
diff --git a/mineru/types.py b/mineru/types.py
index c012f538..93b9da00 100644
--- a/mineru/types.py
+++ b/mineru/types.py
@@ -119,6 +119,10 @@ SERVER_TIERS: tuple[ServerTier, ...] = (
"advanced",
)
+# 启动模式包含自动推荐;实体档位与上限映射仍只包含四个解析档位。
+ServerStartupTier = Literal["auto", "flash", "basic", "standard", "advanced"]
+SERVER_STARTUP_TIERS: tuple[ServerStartupTier, ...] = ("auto", *SERVER_TIERS)
+
TIERS_BY_SERVER_TIER: dict[ServerTier, tuple[Tier, ...]] = {
"flash": ("flash",),
"basic": ("flash", "basic"),
@@ -142,6 +146,7 @@ DEPLOYMENT_TIERS: tuple[DeploymentTier, ...] = (
DEFAULT_QUALITY_TIER_SELECTION_ORDER: tuple[Tier, ...] = ("standard", "basic")
+DEFAULT_TASK_TIER_SELECTION_ORDER: tuple[Tier, ...] = ("standard", "basic", "flash", "advanced")
QUALITY_TIERS: frozenset[Tier] = frozenset(("basic", "standard", "advanced"))
CACHED_TIER_SELECTION_ORDER: tuple[Tier, ...] = ("advanced", "standard", "basic", "flash")
PARSING_RULE_TIER_SELECTION_ORDER: tuple[Tier, ...] = (*DEFAULT_QUALITY_TIER_SELECTION_ORDER, "flash")
@@ -161,6 +166,12 @@ def _validated_tier_set(available_tiers: Iterable[object] | str) -> set[Tier]:
return {validate_tier(str(item)) for item in available_tiers}
+def select_default_task_tier(available_tiers: Iterable[object] | str) -> Tier | None:
+ """共享 Tasks 与界面的默认选档;仅剩 Advanced 时才自动选择该档位。"""
+ available = _validated_tier_set(available_tiers)
+ return next((tier for tier in DEFAULT_TASK_TIER_SELECTION_ORDER if tier in available), None)
+
+
def select_default_quality_tier(available_tiers: Iterable[object] | str) -> Tier | None:
"""Select the default quality tier from discovered parse-server capabilities."""
available = _validated_tier_set(available_tiers)
@@ -316,17 +327,21 @@ __all__ = [
"TIER_ORDER",
"ServerTier",
"SERVER_TIERS",
+ "ServerStartupTier",
+ "SERVER_STARTUP_TIERS",
"TIERS_BY_SERVER_TIER",
"ManagedServerTier",
"MANAGED_SERVER_TIERS",
"DeploymentTier",
"DEPLOYMENT_TIERS",
"DEFAULT_QUALITY_TIER_SELECTION_ORDER",
+ "DEFAULT_TASK_TIER_SELECTION_ORDER",
"QUALITY_TIERS",
"CACHED_TIER_SELECTION_ORDER",
"PARSING_RULE_TIER_SELECTION_ORDER",
"validate_tier",
"select_default_quality_tier",
+ "select_default_task_tier",
"select_highest_cached_tier",
"select_parsing_rule_tier",
]
diff --git a/mineru/utils/translations.py b/mineru/utils/translations.py
index a6708545..5bb80159 100644
--- a/mineru/utils/translations.py
+++ b/mineru/utils/translations.py
@@ -480,7 +480,9 @@ ZH_MESSAGES: dict[str, str] = {
"Maximum pages per PDF conversion; omitted: unlimited": "PDF 单次转换的最大页数;省略时不限制",
"Show local examples": "显示本地示例",
"Expose the Gradio event API": "开放 Gradio 事件 API",
- "Managed API server tier ceiling": "托管 API server 的档位上限",
+ "Managed API server tier ceiling: auto, flash, basic, standard, advanced; ignored with --api-url": (
+ "托管 API server 的档位上限:auto、flash、basic、standard、advanced;指定 --api-url 时忽略"
+ ),
"Managed server job concurrency": "托管服务的任务并发数",
"Disable managed server image analysis": "禁用托管服务的图像分析",
"Preload managed server models": "预加载托管服务的模型",
diff --git a/tests/unittest/test_file_parse.py b/tests/unittest/test_file_parse.py
index 56d995a1..947374f3 100644
--- a/tests/unittest/test_file_parse.py
+++ b/tests/unittest/test_file_parse.py
@@ -335,7 +335,7 @@ def test_unknown_creation_is_never_replayed(tmp_path: Path, failure: str) -> Non
@pytest.mark.parametrize(
"tiers,tier,code,upstream_status",
[
- (("advanced",), None, "quality_tier_unavailable", 503),
+ (("advanced",), "standard", "invalid_request", 400),
(("flash",), "basic", "invalid_request", 400),
],
)
diff --git a/tests/unittest/test_kit_commands.py b/tests/unittest/test_kit_commands.py
index 49333787..10d6d698 100644
--- a/tests/unittest/test_kit_commands.py
+++ b/tests/unittest/test_kit_commands.py
@@ -163,7 +163,7 @@ def test_standalone_vlm_main_configures_streams_and_forwards_extra_args(monkeypa
@pytest.mark.parametrize(
("script", "entrypoint", "expected_options"),
[
- ("mineru-webui", webui.main, ("--api-url", "--api-server-tier")),
+ ("mineru-webui", webui.main, ("--api-url", "--tier")),
("mineru-openai-server", vlm_server.main, ("--engine",)),
(
"mineru-models-download",
@@ -367,7 +367,7 @@ def test_top_level_commands_register_implementation_callbacks_directly() -> None
("command", "expected_options"),
[
("parse", ("--output", "--format", "--tier")),
- ("webui", ("--api-url", "--server-name", "--api-server-tier")),
+ ("webui", ("--api-url", "--server-name", "--tier")),
("api-server", ("--host", "--port", "--tier", "--preload-models")),
("vlm-server", ("--engine",)),
("router", ("--host", "--upstream-url", "--local-gpus")),
diff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.py
index 2f8d96b2..25bdff91 100644
--- a/tests/unittest/test_kit_gradio.py
+++ b/tests/unittest/test_kit_gradio.py
@@ -6,6 +6,7 @@ import json
import subprocess
import sys
import zipfile
+from itertools import combinations
from pathlib import Path
from types import SimpleNamespace
from typing import Any
@@ -45,7 +46,19 @@ from mineru.kit.gradio.status import STATUS_COMPLETED, ParseStatusUpdate, Status
from mineru.parser import api_client as parser_api_client
from mineru.parser import api_server as parser_api_server
from mineru.parser.base import ParseResult
-from mineru.types import BlockType, ImageBlock, ImageBodyBlock, MiddleJson, ModelJson, PageInfo, TextBlock, TextSpan
+from mineru.types import (
+ SERVER_STARTUP_TIERS,
+ TIERS,
+ BlockType,
+ ImageBlock,
+ ImageBodyBlock,
+ MiddleJson,
+ ModelJson,
+ PageInfo,
+ TextBlock,
+ TextSpan,
+ select_default_task_tier,
+)
from mineru.version import __version__
runner = CliRunner()
@@ -153,7 +166,8 @@ def test_webui_command_is_registered_and_help_is_available() -> None:
# CI 强制彩色输出时,Rich 会在参数名内部插入 ANSI 样式码。
help_text = unstyle(gradio_result.output)
assert "--api-url" in help_text
- assert "--api-server-tier" in help_text
+ assert "--tier" in help_text
+ assert "--api-server-tier" not in help_text
assert "Disable Advanced on" not in help_text
assert "Disable Flash on" not in help_text
@@ -172,6 +186,7 @@ def test_gradio_managed_tier_disable_option_names_are_removed() -> None:
@pytest.mark.parametrize(
"flag",
[
+ "--api-server-tier",
"--api-server-no-flash",
"--no-flash",
"--api-server-no-advanced",
@@ -179,12 +194,12 @@ def test_gradio_managed_tier_disable_option_names_are_removed() -> None:
],
)
@pytest.mark.parametrize("standalone", [False, True])
-def test_gradio_rejects_removed_tier_disable_options(
+def test_gradio_rejects_removed_tier_options(
monkeypatch: pytest.MonkeyPatch,
flag: str,
standalone: bool,
) -> None:
- """验证两个命令入口在启动服务前拒绝所有已移除的禁用档位参数。"""
+ """验证两个命令入口在启动服务前拒绝旧档位参数名及禁用开关。"""
launch = Mock()
monkeypatch.setattr(gradio_app, "launch_gradio", launch)
@@ -200,6 +215,38 @@ def test_gradio_rejects_removed_tier_disable_options(
launch.assert_not_called()
[email protected]("standalone", [False, True])
[email protected]("tier", [None, *SERVER_STARTUP_TIERS, "unknown"])
+def test_webui_startup_tier_options(monkeypatch: pytest.MonkeyPatch, standalone: bool, tier: str | None) -> None:
+ """两个入口统一默认 auto,并将合法档位原样交给托管启动链。"""
+ launch = Mock()
+ monkeypatch.setattr(gradio_app, "launch_gradio", launch)
+ options = [] if tier is None else ["--tier", tier]
+ expected_code = 1 if tier == "unknown" else 0
+ if standalone:
+ monkeypatch.setattr(sys, "argv", ["mineru-webui", *options])
+ with pytest.raises(SystemExit) as stopped:
+ webui_command.main()
+ assert stopped.value.code == expected_code
+ else:
+ result = runner.invoke(app, ["webui", *options])
+ assert result.exit_code == expected_code, result.output
+ if expected_code:
+ launch.assert_not_called()
+ else:
+ launch.assert_called_once()
+ assert launch.call_args.kwargs["tier"] == (tier or "auto")
+ assert "api_server_tier" not in launch.call_args.kwargs
+
+
[email protected]("tier", [None, *SERVER_STARTUP_TIERS])
+def test_gradio_managed_startup_tier_command(tier: str | None, tmp_path: Path) -> None:
+ """托管服务默认与显式 auto 都传给正式 API 命令,不在 Gradio 内重复探测。"""
+ server = ManagedLocalApiServer() if tier is None else ManagedLocalApiServer(tier=tier)
+ command = server._command(8123, tmp_path)
+ assert command[command.index("--tier") + 1] == (tier or "auto")
+
+
@pytest.mark.parametrize(("port_args", "expected_port"), [([], None), (["--server-port", "7861"], 7861)])
def test_webui_command_preserves_automatic_or_explicit_port(
monkeypatch: pytest.MonkeyPatch, port_args: list[str], expected_port: int | None
@@ -1166,13 +1213,10 @@ def test_build_gradio_app_exposes_html_tab_and_download_menu(tmp_path: Path) ->
@pytest.mark.parametrize(
("tiers", "default_position", "default_tier", "maximum"),
[
- (("advanced", "flash", "standard", "basic"), 2, "standard", 3),
- (("advanced", "standard", "basic"), 1, "standard", 2),
- (("flash", "basic", "standard"), 2, "standard", 2),
- (("advanced", "flash"), 1, "advanced", 1),
- (("basic", "flash"), 1, "basic", 1),
- (("flash",), 0, "flash", 1),
- (("advanced",), 0, "advanced", 1),
+ (tuple(reversed(tiers)), tiers.index(default), default, max(1, len(tiers) - 1))
+ for size in range(1, 5)
+ for tiers in combinations(TIERS, size)
+ for default in [next(tier for tier in ("standard", "basic", "flash", "advanced") if tier in tiers)]
],
)
def test_gradio_tier_slider_uses_available_tiers_and_preserves_selection(
@@ -1187,6 +1231,7 @@ def test_gradio_tier_slider_uses_available_tiers_and_preserves_selection(
label = next(block for block in demo.blocks.values() if "mineru-tier-label" in (block.elem_classes or []))
assert (slider.minimum, slider.maximum, slider.step, slider.precision) == (0, maximum, 1, 0)
assert slider.value == default_position
+ assert default_tier == select_default_task_tier(tiers)
assert slider.interactive is (len(tiers) > 1)
assert slider.visible is (len(tiers) > 1)
assert (
diff --git a/tests/unittest/test_kit_gradio_page_range.py b/tests/unittest/test_kit_gradio_page_range.py
index 5a731e0f..35f43912 100644
--- a/tests/unittest/test_kit_gradio_page_range.py
+++ b/tests/unittest/test_kit_gradio_page_range.py
@@ -85,7 +85,7 @@ def test_launch_forwards_limit_and_versioned_assets(monkeypatch: pytest.MonkeyPa
output_dir=str(tmp_path),
enable_example=False,
enable_api=True,
- api_server_tier="standard",
+ tier="standard",
api_server_concurrency=1,
api_server_disable_image_analysis=False,
api_server_preload_models=False,
@@ -132,7 +132,7 @@ def test_launch_forwards_managed_options_and_stops_server(monkeypatch: pytest.Mo
output_dir=str(tmp_path),
enable_example=False,
enable_api=True,
- api_server_tier="standard",
+ tier="standard",
api_server_concurrency=2,
api_server_disable_image_analysis=False,
api_server_preload_models=False,
@@ -186,7 +186,7 @@ def test_launch_remote_preserves_capabilities_without_local_fallback(
"output_dir": str(tmp_path),
"enable_example": False,
"enable_api": True,
- "api_server_tier": "standard",
+ "tier": "standard",
"api_server_concurrency": 2,
"api_server_disable_image_analysis": True,
"api_server_preload_models": True,
diff --git a/tests/unittest/test_managed_tier_ceiling.py b/tests/unittest/test_managed_tier_ceiling.py
index 2ac0ae8c..cd6102df 100644
--- a/tests/unittest/test_managed_tier_ceiling.py
+++ b/tests/unittest/test_managed_tier_ceiling.py
@@ -14,7 +14,7 @@ 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 mineru.types import SERVER_STARTUP_TIERS, ManagedServerTier, ServerStartupTier
from pathlib import Path
@@ -56,7 +56,10 @@ def test_advanced_missing_models_suggests_standard_download(monkeypatch: pytest.
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:
[email protected]("tier", SERVER_STARTUP_TIERS)
+def test_remote_standard_only_gradio_never_starts_local_server(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, tier: ServerStartupTier
+) -> None:
"""连接 SaaS 仅 Standard 能力时只使用远端,不补起本地服务或扩展档位。"""
capabilities = V1ServerCapabilities("http://remote.test", ("standard",), ("default",), ("upload",))
client = SimpleNamespace(capabilities=capabilities, discover=AsyncMock(return_value=capabilities))
@@ -74,7 +77,7 @@ def test_remote_standard_only_gradio_never_starts_local_server(monkeypatch: pyte
output_dir=str(tmp_path),
enable_example=False,
enable_api=True,
- api_server_tier="standard",
+ tier=tier,
api_server_concurrency=1,
api_server_disable_image_analysis=False,
api_server_preload_models=False,
diff --git a/tests/unittest/test_parser_api_contract.py b/tests/unittest/test_parser_api_contract.py
index 7cc40f46..344da841 100644
--- a/tests/unittest/test_parser_api_contract.py
+++ b/tests/unittest/test_parser_api_contract.py
@@ -41,6 +41,7 @@ from mineru.types import (
PARSING_RULE_TIER_SELECTION_ORDER,
QUALITY_TIERS,
SERVER_TIERS,
+ SERVER_STARTUP_TIERS,
TIER_ORDER,
TIERS,
TIERS_BY_SERVER_TIER,
@@ -426,6 +427,7 @@ 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", "advanced")
+ assert SERVER_STARTUP_TIERS == ("auto", "flash", "basic", "standard", "advanced")
assert DEPLOYMENT_TIERS == ("basic", "standard")
assert TIERS_BY_SERVER_TIER == {
"flash": ("flash",),
@@ -779,7 +781,7 @@ def test_api_server_standard_no_flash_state_and_metadata(tmp_path: Path, monkeyp
(("standard",), "standard"),
(("basic",), "basic"),
(("flash",), "flash"),
- (("advanced",), None),
+ (("advanced",), "advanced"),
],
)
def test_api_server_explicit_capability_matrix(
diff --git a/tests/unittest/test_server_tiers.py b/tests/unittest/test_server_tiers.py
index bb35deb2..99a127b3 100644
--- a/tests/unittest/test_server_tiers.py
+++ b/tests/unittest/test_server_tiers.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import asyncio
from itertools import combinations
from pathlib import Path
from types import SimpleNamespace
@@ -10,15 +11,18 @@ from unittest.mock import Mock
from click.testing import CliRunner
from fastapi.testclient import TestClient
+import httpx
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.kit.gradio.app import build_gradio_app
+from mineru.kit.gradio.client import ManagedLocalApiServer, V1ArtifactClient
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
+from mineru.types import TIERS, TIERS_BY_SERVER_TIER, Tier, select_default_task_tier
@pytest.fixture
@@ -47,7 +51,12 @@ def test_every_explicit_subset_is_exact(
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)
+ expected_default = next(t for t in ("standard", "basic", "flash", "advanced") if t in tiers)
+ assert app.state.default_tier == select_default_task_tier(tiers) == expected_default
+ for options in ({}, {"tier": None}):
+ 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_default
recommend.assert_not_called()
@@ -81,6 +90,30 @@ def test_auto_server_accepts_task_with_standard_default(
assert app.state.task_store._records[response.json()["task_id"]].options.tier == expected
[email protected]("tiers,expected", [(("flash",), "flash"), (("flash", "basic"), "basic"), (TIERS, "standard")])
+def test_gradio_discovers_auto_server_and_matches_task_default(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, preflight: Mock, tiers: tuple[Tier, ...], expected: Tier
+) -> None:
+ """串联托管命令、自动推荐、真实能力发现、界面构建与 Tasks 默认接单。"""
+ recommend = Mock(return_value=SimpleNamespace(pdf_image_tiers=tiers))
+ monkeypatch.setattr(tier_recommendation, "recommend_tiers", recommend)
+ command = ManagedLocalApiServer()._command(8000, tmp_path)
+ startup_tier = command[command.index("--tier") + 1]
+ assert startup_tier == "auto"
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=parse_server_tier(startup_tier))
+ with TestClient(app) as client:
+ artifact_client = V1ArtifactClient(api_url="http://testserver", transport=httpx.ASGITransport(app=app))
+ capabilities = asyncio.run(artifact_client.discover())
+ assert capabilities.tiers == tiers
+ demo = build_gradio_app(artifact_client, capabilities, output_root=tmp_path, enable_example=False)
+ slider = next(block for block in demo.blocks.values() if block.__class__.__name__ == "Slider")
+ assert tiers[int(slider.value)] == app.state.default_tier == expected
+ response = client.post("/v1/tasks", json={"files": [{"file_name": "test.pdf", "bytes": 1}]})
+ assert response.status_code == 202, response.text
+ assert app.state.task_store._records[response.json()["task_id"]].options.tier == expected
+ recommend.assert_called_once_with(vlm_config=app.state.vlm_config)
+
+
@pytest.mark.parametrize("value", ["", ",", "standard,", "flash,,basic", "ultra", "auto,flash"])
def test_invalid_cli_lists(value: str) -> None:
"""拒绝空列表、空项、未知名称及 auto 混用。"""
diff --git a/tests/unittest/test_task_tiers.py b/tests/unittest/test_task_tiers.py
index b8f23967..f1e57e60 100644
--- a/tests/unittest/test_task_tiers.py
+++ b/tests/unittest/test_task_tiers.py
@@ -25,7 +25,7 @@ from mineru.parser.tier import runtime_options_for_tier
from mineru.tasks.contracts import TaskFileInput, UploadTaskOptions
from mineru.tasks.errors import ApiServerError
from mineru.tasks.service import TERMINAL_TASK_STATUSES, resolve_task_tier
-from mineru.types import TIERS, MiddleJson, PageInfo, Tier, select_default_quality_tier
+from mineru.types import TIERS, MiddleJson, PageInfo, Tier, select_default_task_tier
class _RecordingTransport(httpx.AsyncBaseTransport):
@@ -47,7 +47,7 @@ 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.default_tier = select_default_task_tier(tiers)
@asynccontextmanager
@@ -154,19 +154,19 @@ def _stub_inference(monkeypatch: pytest.MonkeyPatch) -> list[tuple[str, Tier]]:
(("flash", "basic"), "basic"),
(("flash",), "flash"),
(("flash", "advanced"), "flash"),
- (("advanced",), None),
+ (("advanced",), "advanced"),
((), None),
],
)
def test_task_default_tier_matrix(tiers: tuple[Tier, ...], expected: Tier | None) -> None:
- """覆盖非连续能力集合,Tasks 默认值包含 flash 且永远不自动选 advanced。"""
+ """覆盖非连续能力集合,仅剩 Advanced 时才默认选择该档位。"""
inputs = [TaskFileInput(file_name="input.pdf", bytes=1)]
if expected is None:
with pytest.raises(ApiServerError) as error:
resolve_task_tier(UploadTaskOptions(), inputs, set(tiers))
assert error.value.status_code == 503
assert error.value.error.code == "quality_tier_unavailable"
- assert "pass tier explicitly" in str(error.value)
+ assert "No parsing tier is available" in str(error.value)
else:
assert resolve_task_tier(UploadTaskOptions(), inputs, set(tiers)) == expected
@@ -193,7 +193,7 @@ def test_task_explicit_tier_is_not_upgraded_or_downgraded(tier: Tier) -> None:
(("flash",), {"tier": "advanced"}, ["input.pdf", "input.docx"], 400, "tier"),
(("flash",), {"tier": ""}, ["input.docx"], 400, "tier"),
(("flash",), {"tier": "unknown"}, ["input.docx"], 400, "tier"),
- (("advanced",), {}, ["input.pdf"], 503, None),
+ (("advanced",), {}, ["input.pdf"], 202, None),
(("standard",), {}, ["input.pdf", "input.docx"], 202, None),
(("standard",), {"tier": "flash"}, ["input.pdf", "input.docx"], 400, "tier"),
(("standard",), {"tier": "basic"}, ["input.png"], 400, "tier"),
@@ -222,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 == ("standard" if "standard" in tiers else "flash")
+ assert record.options.tier == select_default_task_tier(tiers)
else:
assert "type" not in response.json()["error"]
if param is None:
@@ -237,6 +237,27 @@ def test_task_tier_preflight_and_schema(
asyncio.run(scenario())
[email protected]("deployment", ["api", "router", "cascade"])
+ "tiers,expected",
+ [(("advanced", "flash"), "flash"), (("advanced", "basic"), "basic"), (("advanced",), "advanced")],
+)
[email protected]("options", [{}, {"tier": None}])
+def test_non_contiguous_default_tier_across_deployments(
+ tmp_path: Path, deployment: str, tiers: tuple[Tier, ...], expected: Tier, options: dict[str, None]
+) -> None:
+ """真实 API 与两层 Router 接单时共享缺档默认顺序,不把 Advanced 提前。"""
+
+ async def scenario() -> None:
+ """通过公开接口创建任务并检查持久到接单记录中的实际档位。"""
+ async with _deployment(tmp_path, deployment, {"worker": tiers}) as (client, app, _apps, _calls):
+ response = await 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
+
+ asyncio.run(scenario())
+
+
@pytest.mark.parametrize("deployment", ["api", "router", "cascade"])
@pytest.mark.parametrize(
"options,expected", [({}, "standard"), ({"tier": None}, "standard"), ({"tier": "advanced"}, "advanced")]