Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
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.mdindex 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 7860Without `--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```bashdiff --git a/docs/en/usage/file_parse.md b/docs/en/usage/file_parse.mdindex 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.mdindex 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.mdindex 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 enginesdiff --git a/docs/next/api/file-parse.md b/docs/next/api/file-parse.mdindex 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.mdindex 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.mdindex 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.mdindex 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 与 manageddiff --git a/docs/next/cli/mineru-kit-webui.md b/docs/next/cli/mineru-kit-webui.mdindex 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```bashmineru-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.mdindex 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.mdindex 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.mdindex 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```bashdiff --git a/docs/zh/usage/file_parse.md b/docs/zh/usage/file_parse.mdindex 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.mdindex 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.mdindex 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.pyindex c12db0db..6e70309b 100644--- a/mineru/kit/commands/webui.py+++ b/mineru/kit/commands/webui.py@@ -9,7 +9,7 @@ from importlib.metadata import versionimport typerfrom packaging.specifiers import SpecifierSet-from ...types import SERVER_TIERS, ServerTier+from ...types import SERVER_STARTUP_TIERS, ServerStartupTierfrom ...utils.i18n import tfrom ...utils.logger import configure_global_log_levelfrom ...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.pyindex 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.pyindex 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_tierfrom ...utils.logger import configure_global_log_levelfrom ...utils.stdio import configure_standard_streamsfrom .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 tierdef _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.pyindex 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_enfrom ...parser.base import ParseResultfrom ...parser.page_range import normalize_page_range_inputfrom ...parser.process_control import ManagedProcessControl-from ...types import SERVER_TIERS, TIERS, ServerTier, Tier+from ...types import SERVER_STARTUP_TIERS, TIERS, ServerStartupTier, Tierfrom ...filetypes import is_flash_only_parse_extensionfrom ...utils.stdio import utf8_subprocess_envfrom .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.pyindex 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_CHECKINGfrom loguru import logger-from ...types import TIERS, Tier+from ...types import TIERS, Tier, select_default_task_tierfrom .cpu_threads import effective_cpu_countfrom .device import resolve_small_model_backend, resolve_torch_devicefrom .gpu import is_discrete_gpu, match_gpu_identities@@ -247,7 +247,8 @@ def recommend_tiers(*, vlm_config: VlmConfig | None = None) -> TierRecommendatiohardware.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.pyindex 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_tierfrom ..utils.async_utils import drain_future, run_syncfrom ..model.runtime.ownership import RuntimeOwner, runtime_ownerfrom ..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.pyindex 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.pyindex c0c24b00..ee492992 100644--- a/mineru/tasks/service.py+++ b/mineru/tasks/service.py@@ -15,7 +15,7 @@ from pathlib import Pathfrom ..filetypes import is_flash_only_parse_extensionfrom ..task_types import TaskFileState, TaskStatus-from ..types import Tier+from ..types import Tier, select_default_task_tierfrom ..utils.async_utils import drain_future, run_syncfrom .contracts import ErrorDetail, TaskFileInput, TaskFileItem, UploadTaskOptionsfrom .errors import ApiServerError, invalid_task_request@@ -23,7 +23,6 @@ from .execution import TaskBackend, TaskExecution, TaskUpload, execution_timestaTASK_UPLOAD_TTL = 3600TERMINAL_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], tif 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_tierinvalid_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.pyindex 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.pyindex 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.pyindex 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.pyindex 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.pyindex 2f8d96b2..25bdff91 100644--- a/tests/unittest/test_kit_gradio.py+++ b/tests/unittest/test_kit_gradio.py@@ -6,6 +6,7 @@ import jsonimport subprocessimport sysimport zipfile+from itertools import combinationsfrom pathlib import Pathfrom types import SimpleNamespacefrom typing import Any@@ -45,7 +46,19 @@ from mineru.kit.gradio.status import STATUS_COMPLETED, ParseStatusUpdate, Statusfrom mineru.parser import api_client as parser_api_clientfrom mineru.parser import api_server as parser_api_serverfrom 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_textassert "Disable Advanced on" not in help_textassert "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.pyindex 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.MonkeyPaoutput_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.Mooutput_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.pyindex 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 InvalidRequestErrorfrom mineru.kit.gradio import app as gradio_appfrom mineru.kit.gradio.client import ManagedLocalApiServer, V1ServerCapabilitiesfrom mineru.kit.router.workers import ManagedLocalWorker, RouterSettings-from mineru.types import ManagedServerTier+from mineru.types import SERVER_STARTUP_TIERS, ManagedServerTier, ServerStartupTierfrom 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: pyteoutput_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.pyindex 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.pyindex 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 asynciofrom itertools import combinationsfrom pathlib import Pathfrom types import SimpleNamespace@@ -10,15 +11,18 @@ from unittest.mock import Mockfrom click.testing import CliRunnerfrom fastapi.testclient import TestClient+import httpximport pytestfrom typer.testing import CliRunner as TyperRunnerfrom mineru.kit.commands.api_server import main as standalone_mainfrom mineru.kit.main import app as kit_app+from mineru.kit.gradio.app import build_gradio_app+from mineru.kit.gradio.client import ManagedLocalApiServer, V1ArtifactClientfrom mineru.model.runtime import tier_recommendationfrom mineru.parser import api_serverfrom 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"]) == tiersassert tuple(app.state.tier_runtime_options) == tiersassert 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_defaultrecommend.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.pyindex 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_tierfrom mineru.tasks.contracts import TaskFileInput, UploadTaskOptionsfrom mineru.tasks.errors import ApiServerErrorfrom 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_tierclass _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 == 503assert 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.textif 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")]