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