Skip to content

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

refactor(api): update tier handling to support multiple tiers in API calls

myhlolia243103fae12
diff --git a/docs/next/api/file-parse.md b/docs/next/api/file-parse.md
index a2786d9b..1c7e5265 100644
--- a/docs/next/api/file-parse.md
+++ b/docs/next/api/file-parse.md
@@ -31,13 +31,18 @@ MINERU_API_URL=https://mineru.net/api MINERU_API_KEY=your-key \
| 字段 | 默认值 | 说明 |
|---|---|---|
| `file` | 必填 | 一个非空文件,保留扩展名;不接受多文件。 |
-| `tier` | 上游默认 | `flash/basic/standard/advanced`。 |
+| `tier` | 上游默认 | 可选,仅对 PDF/图片生效;`flash/basic/standard/advanced`。 |
| `ocr_mode` | `auto` | `auto/txt/ocr`。 |
| `page_range` | 整本 | 与 Tasks 一致,PDF 支持 `1-5`、`r1`、`all`;格式支持范围由上游校验。 |
| `output_formats` | `default` | `default/docx/html/latex`;重复同名字段表达列表,重复值按首次出现去重。 |
| `wait_timeout` | `3600` | 整数秒,范围 `0–3600`。 |
| `request_id` | 自动生成 | 1–64 个字母、数字、下划线或短横线。提前指定并保存它,可在连接中断后查询。 |
+未提供 tier 表单字段时,包装层在上游 Tasks 请求中省略该字段,由上游按 **standard → basic → flash** 选择默认档位;advanced 必须显式指定。
+显式值原样传递,PDF/图片请求的档位不受上游支持时返回错误,不自动升降档。
+Office、HTML 等已支持的原生文档固定使用 flash,即使传入上游未开放的合法档位也不改变原生解析路径。
+表单空字符串或字符串 `"null"` 不是省略字段,属于非法值;OpenAPI 将 tier 声明为可省略的字符串枚举,不声明可空值。完整规则见 [Tasks tier 语义](tasks.md#tier默认选择与文件作用范围)。
+
```bash
# 成功时 response.body 是附件;超时或错误时是 JSON,请同时检查 response.headers。
curl --max-time 7200 -D response.headers -o response.body \
@@ -283,6 +288,8 @@ Content-Type: application/json
| 502 | `submission_unknown`、`upstream_unreachable`、`upstream_protocol_error`、`invalid_result`、下载错误码或上游错误码 | 上游创建、查询、传输或解析失败,或结果校验失败。 |
上游认证失败以包装层的 `502` 返回,例如 `error.code="invalid_api_key"`、`error.upstream_status=401`;包装入口本身没有 API Key 认证,不把上游配置错误伪报为入口鉴权失败。
+上游明确拒绝档位请求时也沿用包装层 `502`:显式 tier 不受支持保留 `error.code="invalid_request"`、`error.upstream_status=400`;没有可用默认档位的标准 Tasks 错误响应保留 `error.code="quality_tier_unavailable"`、`error.upstream_status=503`。两者记录为 `failed`,`task_id=null`,不标记为提交结果未知。
+创建阶段的 5xx 响应中,仅符合共享错误结构的 `503 quality_tier_unavailable` 可确认为档位拒单;其余 5xx、408、畸形响应或网络异常仍按 `submission_unknown` 处理。明确拒单和提交结果未知都不会自动重放创建,保留期内相同 request_id 的重复请求和重启恢复沿用原记录。
`submission_unknown` 首次创建失败通常返回 `502`;后续请求仍可能得到 `409/502`,应查询原恢复记录,不自动重放创建。
## 等待、超时与断连后查询
diff --git a/docs/next/api/health-models.md b/docs/next/api/health-models.md
index 052db14c..3724f922 100644
--- a/docs/next/api/health-models.md
+++ b/docs/next/api/health-models.md
@@ -181,14 +181,13 @@ Local Parse Server 的 `health` 通常返回:
| 本地 api-server 进程能力 | `/v1/tiers` 应返回 |
|-------------------------|-------------------|
-| `--tier flash` | `flash`;默认选择请求应失败,除非显式请求 Flash。 |
-| `--tier basic` | `flash`、`basic` |
-| `--tier basic --no-flash` | `basic` |
-| `--tier basic --no-advanced` | `flash`、`basic` |
-| `--tier standard` | `flash`、`basic`、`standard`、`advanced` |
-| `--tier standard --no-flash` | `basic`、`standard`、`advanced` |
-| `--tier standard --no-advanced` | `flash`、`basic`、`standard` |
-| `--tier standard --no-flash --no-advanced` | `basic`、`standard` |
+| `--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#自动推荐) |
本地或兼容服务应以 `/v1/tiers` 返回值作为能力发现事实。客户端不应根据启动参数猜测具体能力。
diff --git a/docs/next/api/tasks.md b/docs/next/api/tasks.md
index f3d4891f..d7e304a4 100644
--- a/docs/next/api/tasks.md
+++ b/docs/next/api/tasks.md
@@ -31,13 +31,46 @@ Task ID 是父任务标识;内部逐文件执行 ID 不属于公共契约。
| JSON 字段 | 默认值 | 说明 |
|---|---|---|
| `files` | 必填 | 1–100 个文件组成的 JSON 数组,不接受 JSON 字符串。 |
-| `tier` | 服务默认值 | `flash/basic/standard/advanced`,受部署能力约束。 |
+| `tier` | 服务默认值 | 可选,仅对 PDF/图片生效;`flash/basic/standard/advanced`,规则见下文。 |
| `ocr_mode` | `auto` | `auto/txt/ocr`。 |
| `page_range` | 整本 | 全局 PDF 页范围,支持 `1-5`、`r1`、`all` 等现有语法。 |
| `output_formats` | `["default"]` | 非空列表,值为 `default/docx/html/latex` 中一个或多个;重复值按首次出现去重。 |
ModelJson 仅用于内部解析与后处理,不属于 HTTP 或 SDK 结果。请求携带已删除的 `include_model_output` 字段(包括值为 `false`)返回 400。
+### tier:默认选择与文件作用范围
+
+省略 `tier` 或传入 JSON `null` 时,服务端从支持的档位中按 **standard → basic → flash** 选择第一个,advanced 只能显式指定。
+仅开放 flash 的服务可以直接接收未指定 tier 的 PDF/图片;仅开放 advanced 时,未指定 tier 返回 `503 quality_tier_unavailable`,需显式传入 `advanced`。
+
+请求包含 PDF/图片且显式提供 tier 时,服务支持该档位就原样使用;不支持则在创建阶段返回 `400 invalid_request`,`error.param="tier"`,整个请求不接单、不分配上传链接,也不自动升档或降档。
+空字符串和未知枚举始终是参数错误,包括纯原生文档请求。
+
+Office、HTML 等已支持的原生文档固定使用 flash,不受请求 tier 影响。纯原生文档批次忽略合法的显式 tier,不要求服务开放该 PDF/图片档位;但仍要求服务具备 flash 原生解析能力。
+例如,部署开放 standard 和 flash 时:
+
+| 输入 | 请求 tier | 执行结果 |
+|---|---|---|
+| PDF + DOCX | 省略或 `null` | PDF 使用 standard,DOCX 使用 flash。 |
+| PDF + DOCX | `standard` | PDF 使用 standard,DOCX 使用 flash。 |
+| PDF + DOCX | `basic` 或 `advanced` | 创建时返回 400。 |
+| 只有 DOCX | `basic` 或 `advanced` | DOCX 使用 flash。 |
+
+可在一个请求中混合提交文件,客户端无需预先拆分档位:
+
+```json
+{
+ "files": [
+ {"file_name": "report.pdf", "bytes": 12000},
+ {"file_name": "contract.docx", "bytes": 8000}
+ ]
+}
+```
+
+服务在接单时确定并保存选档,等待上传、排队和后续转发不重新选择默认值。Router 按每个文件的有效档位选择 worker,并显式传给下游;原档位后来不可用时按文件报告失败,不自动改档。
+实际执行档位始终读取成功文件的 `files[].parse.tier`,同一批次允许不同档位。
+该规则也适用于 HTTP SDK 和 file_parse 提交的单文件 Tasks;直接本地解析和 Doclib 保持各自的选档策略。
+
### files[]:输入清单
请求体的 `files` 数组中,每个条目包含以下字段:
diff --git a/docs/next/architecture-optimization-status.md b/docs/next/architecture-optimization-status.md
new file mode 100644
index 00000000..9a1ab4ab
--- /dev/null
+++ b/docs/next/architecture-optimization-status.md
@@ -0,0 +1,287 @@
+# 代码结构优化任务状态
+
+状态:**本轮结构优化及合入收尾全部完成;PR #5665 已合入 dev,合入前后跨平台 CI、文档和 CLA 验证通过,保留一项非阻断后续项**。记录日期:2026-10-25。
+
+## 工作区与改动边界
+
+- 仓库:`/Volumes/2TB/projects/20240809magic_pdf/Magic-PDF`
+- 分支:`codex/architecture-lifecycle-refactor`;HEAD:`968ee71a6bfc802f92345f51f6554e0845bf606d`,基于 `ec6c23cff`。
+- 前八批、集中复审 5 文件修复及单文件测试等待预算调整均已推送至 upstream 同名分支;各批验收 wheel 已保存,未进行合并或 PyPI 发布。
+- 用户原有改动必须保留:`tests/unittest/test_pdf_text_styles.py`(当前相对 HEAD 为 49 行新增、7 行删除)和未跟踪的 `examples/`。本任务没有修改它们。
+- 新增生产模块和测试均已纳入提交。本状态文件为本地检查点;`examples/` 和用户原有测试改动未混入提交。
+- Python 环境:`/Users/myhloli/projects/20240809magic_pdf/Magic-PDF/.venv4`。命令在本仓库根目录执行。
+
+## 第一批:已完成并验证
+
+- SQLite 连接级参数在每次 `_connect()` 时应用;WAL 仅在初始化时设置。
+- 配置导入不再读取文件或校验环境;使用 `get_config()` 首次装载进程默认配置,`load_config()` 独立装载。
+- 删除旧模块级 `config` 实例,生产代码、脚本和测试已迁移;依赖 `MINERU_HOME` 的默认路径改为构造时解析。
+- Doclib 应用保存配置副本,日志默认级别取自该应用配置。
+- 非 Torch 回归累计 4013 项通过(包含 6 项修正后重跑),3 项跳过。
+
+## 第二批:已完成并验证
+
+- `mineru/tasks/` 分离 contracts、errors、execution、service、http;本地适配位于 `parser/task_backend.py`。
+- 删除旧 `parser/task_api.py`,Router 不再依赖本地 API Server。
+- SDK/file_parse 共享文件身份、上传描述和解析选项,保留各自响应接受边界和恢复语义。
+- 新增 `doclib/services/content_read_svc.py`,承担定位、渐进 Markdown、图片读取与导出。
+- `doclib/core/parse_artifacts.py` 统一缓存路径、读写、页选择和 coverage。
+- 历史协议读取入口固定为 `doclib/core/middle_json.py:read_cached_middle_json()`。
+- 16 个协议模型 JSON Schema、本地 API 与 Router 完整 OpenAPI 和改动前一致。
+- 完整非 Torch 回归:4044 passed、3 skipped、108 deselected。
+
+## 第三批:已完成并通过最终本地验收
+
+### 单文件执行
+
+- `TaskExecution` 为有类型的单文件快照,`TaskBackend.submit()` 接收一个文件和可选上传。
+- 本地使用 `ExecutionStore`、`_ExecutionRecord`、`_ExecutionRequest`、`_run_execution`;旧多文件 Job 模型、循环和索引映射已移除。
+- 父 Task 负责批次进度和 `partial` 聚合;公开结果 ID 与内部源文件 ID 分离。
+- 并发、准备限流、取消排空、结果保留期及公开 usage 字段语义保持。
+- 本地 API 与 Router 的完整 OpenAPI 再次与第三批前基线一致。
+
+### 模型生命周期
+
+- `model/runtime/ownership.py` 提供应用、文档和初始化租约,以及统一 `release_runtime_owner()`。
+- Hybrid/Atom 通过 `local_cache.py` 记录应用和模型依赖,支持共享、CLI 固定缓存及初始化失败回滚。
+- VLM `RuntimeHandle` 在创建时绑定明确的关闭动作,移除动态私有句柄和关闭方法猜测。
+- 关闭等待已接纳文档和初始化;失效应用的迟到结果不进入缓存。
+- VLM 构造、正常关闭及失败清理在缓存锁外执行;同键初始化/关闭有等待屏障。
+- `closing.py` 的关闭回调上下文拒绝阻塞式重入,覆盖同步、异步线程及直接句柄关闭。
+- `RuntimeHandle.aclose()` 被重复取消后仍排空客户端和引擎清理,再传播最早观察到的异常。
+- MLX 串行等待可取消,已开始的同步推理先排空再归还锁。
+- 小模型只承诺租约正确和宿主引用释放,没有宣称同键原生析构完全串行或 RSS 峰值改善。
+
+### Gradio 编排
+
+- `conversion_service.py` 接收显式依赖并返回具名转换结果。
+- `conversion_ui.py` 生成既有组件更新和浏览器回执。
+- 公开 4 入参、16 项输出和浏览器 15 项协议不变;保留会话隔离、迟到响应过滤和取消排空。
+- 会话不持有 `ParseResult`;有弱引用回归确认转换完成后可回收。
+
+### 第三批已完成的验证
+
+- Gradio 相关 Python:431 passed、3 skipped;7 个 Node 回归脚本通过。
+- 模型扩展聚焦曾通过 212 项;最终关闭竞争修正后,模型聚焦 70 项通过。
+- 新增 `test_runtime_shutdown_regressions.py` 的 10 项有超时保护回归全部通过;连同 ownership/native async/API 集成,共 48 passed。
+- `test_api_model_ownership.py` 使用真实 Tasks API 和微型 CPU ONNX 会话,验证两个应用共享、单个退出不误释放、最后退出后回收,以及新应用重新构造。无需下载模型。
+- 单文件执行经过独立源码复审;身份、取消、保留期、用量及 Router 续租未发现剩余阻断。
+- 最后静态检查:全仓 E9/F63/F7/F82 通过;累计 124 个改动 Python 文件没有新增 Ruff 诊断,67 条为对照 HEAD 的既有诊断;`git diff --check` 通过。
+- 此阶段未运行 GPU 大模型;后续已补充 llama.cpp/Metal 实机验收,详见交付记录。LMDeploy/vLLM/MLX 仍限于源码契约及替身验证。
+
+## 最终验收(恢复任务后)
+
+用户此前要求暂停时,第三批整套回归在 898 passed、108 deselected 处被 KeyboardInterrupt 停止。
+恢复后重新执行完整命令,最终结果为:
+
+- **4080 passed、3 skipped、108 deselected,exit 0**,耗时 203.31 秒。
+- 继续排除用户正在修改的 `tests/unittest/test_pdf_text_styles.py`;108 项为本轮非 Torch 筛选未选中的测试。
+- 当前本地 API、Router 完整 OpenAPI 与第三批前基线分别完全一致,各 11 条路径。
+- 全仓 E9/F63/F7/F82 通过;124 个改动 Python 文件对照 HEAD 没有新增 Ruff 诊断,67 条为既有诊断。
+- 16 个新增生产 Python 文件的函数、方法均有中文职责注释;`git diff --check` 通过。
+- 本轮观察到 63 条警告,包括已确认的 Gradio 事件循环回收基线问题,详见下节。
+- 三批约定的实现与本地回归没有剩余任务。后续提交、安装包、跨平台和实机验收结果见下节。
+
+最终验收命令:
+
+```bash
+/Users/myhloli/projects/20240809magic_pdf/Magic-PDF/.venv4/bin/python -m pytest \
+ -q -o addopts='' --strict-markers -m 'not torch' \
+ --ignore=tests/unittest/test_pdf_text_styles.py tests/unittest
+```
+
+后续若继续修改,应针对新改动选择回归范围。提交时保留用户原有改动,并确认新增未跟踪模块和测试均被正确纳入。
+
+## 交付收尾与实机验收
+
+### 提交与 CI
+
+- 提交:`afda7189de1debaf6482a1f430571d6ffeda267e`,标题为 `refactor: clarify task, document and model lifecycle boundaries`。
+- 分支:`upstream/codex/architecture-lifecycle-refactor`。
+- [跨平台 CI](https://github.com/opendatalab/MinerU/actions/runs/40171000355):**16 个任务全部成功**,检查的 head SHA 与上述提交一致。
+- Linux Python 3.11–3.14:每组 4090 passed、6 skipped(JUnit 共 4096 项)。
+- Windows/macOS Python 3.11–3.14:每组 123 项公开合同测试通过。
+- Ubuntu Torch CPU:106 项通过;本地 CI helper 测试另有 24 项通过。
+- 用户修改中的 PDF 样式测试未提交;额外提取其 HEAD 原始版本,在安装环境验证 10 项全部通过。
+
+### wheel 与完整隔离安装
+
+- 工作盘当时仅剩约 55 MiB,构建快照和环境放在内置盘临时目录,未清理用户工作盘文件。
+- wheel:`mineru-4.0.12-py3-none-any.whl`,3,774,304 字节。
+- SHA-256:`14bb9b9746123b7aa4f9fc290a505fe5d2a4ec0387ec99d0d19acf4006ea2dd2`。
+- 658 个包内文件逐字节匹配已提交源码;包含所有新增生产模块,不包含旧 `parser/task_api.py`。
+- 最终在完全隔离的 Python 3.14.4 环境安装所有依赖;126 个包通过 `uv pip check`,没有依赖开发环境的 site-packages。
+- DocVortex 使用 PyPI 二进制 wheel 0.6.1,没有源码构建。最终主要依赖包括 Torch 2.14.1、Gradio 6.30.0、ONNX Runtime 1.31.0、mineru-llama-cpp 0.2.0。
+- 安装后验证:两页真实 PDF 原生解析、九种渲染格式、结果包保存、Tasks 创建/上传/解析/下载/取消、Gradio 4 入参/16 输出、四个 CLI 的 `--help` 均通过。
+- 已核对实际导入路径来自安装环境,并验证原始语义树未被渲染修改。
+
+### Metal 实机模型生命周期
+
+- 后端:`llama-cpp-engine`,原生日志确认 `MTL0 (Apple M4), backend=MTL`。
+- 使用本地 MinerU2.5-Pro-2605-1.2B Q8_0 GGUF 与 mmproj,未下载权重;这项验收针对 VLM 资源层,不代表完整 OCR/Hybrid 模型集验收。
+- 两个 `RuntimeOwner` 共享同一模型实例;释放第一个后,第二个仍能正常提取图中文字。
+- 已开始的两页同步推理被取消后排空,再传播取消;在干净环境中等待约 12.72 秒,随后同一实例继续成功推理。
+- 最后持有者退出后缓存条目归零、原生引擎已关闭;新持有者能重新加载、推理并正常关闭。
+- 进程 Metal 驱动分配量:推理后约 1.50 GiB,最后持有者关闭后 737,280 字节(约 0.70 MiB);重建关闭后保持该值。
+- RSS 从推理后约 1.59 GiB 降到约 428 MiB,仍包含进程及框架缓存;未宣称 RSS 完全恢复到启动值。
+
+### 本地交付产物
+
+- 目录:`/Users/myhloli/Downloads/MinerU-architecture-afda7189-0d9iu402`。
+- `delivery.json`:提交、wheel、完整依赖版本、CI 矩阵及复现命令。
+- `wheel-provenance.json`、`wheel-smoke.json`、`gpu-lifecycle.json`:产物身份、安装验收和实机指标。
+- `ci-reports/`、`ci-torch/`、`ci-test-summary.json`:已下载的 JUnit 与覆盖率报告。
+- 同目录保存 wheel、验证脚本和原生日志,可独立核对。
+
+Gradio 构建期循环清理已在第四批完成,Router 状态类型化已在第五批完成实现。
+
+## 第四批:Gradio 构建期循环归属
+
+- 提交:`24661719f92b29506ed9bd3a2f9440127f2e9606`,`fix: manage Gradio setup event loop lifetime`,只包含 4 个任务文件。
+- `lifecycle.with_setup_loop()` 为同步构建和 MinerU 启动入口提供一个自有的临时循环,结束时排空并关闭;异步宿主已有运行循环时直接复用。
+- 显式 `loop_factory` 不覆盖或关闭宿主尚未运行的当前循环;不使用 `Runner.run()`,保留 Gradio 阻塞等待中首次 Ctrl+C 的行为。
+- 同时覆盖 `build_gradio_app()` 和 `launch()` 再次创建 Gradio App 的路径;没有修改、猴子补丁或屏蔽 Gradio 警告。
+- 原始同步构建探针为 10 个循环全部未关闭;修复后为 1 个循环已关闭。测试还覆盖异常时清理、后台任务排空、工作线程重复构建和异步宿主继续调度。
+- 真实监听端口验证两个独立会话上传、排队、原生 HTML 转换、关闭、重新构建和首次 Ctrl+C。公开 4 输入/16 输出和同会话取消语义保持原有测试覆盖。
+- 新增 7 项回归,已加入 Windows/macOS CI;本地 Gradio 相关回归为 **438 passed、3 skipped**。
+- 完整非 Torch 回归:**4087 passed、3 skipped、108 deselected、62 warnings**,206.25 秒。继续排除用户修改中的 PDF 样式测试;本次没有再出现事件循环析构告警。
+- Gradio 6.21.0 与配套 client 2.6.0 的 7 项回归通过;6.30.0 的真实上传/队列/中断验证通过。开发环境仍为 6.27.0,未修改依赖下限。
+- wheel 已在全新 Python 3.14 环境完整安装,126 个依赖通过 `uv pip check`;`-I` 验证实际导入安装包,并通过循环清理、真实队列和首次 Ctrl+C 验收。
+- wheel 共 659 个包内文件逐字节匹配上述提交;SHA-256 为 `2d851ca5ed331f999d698dfa7895011a4fe116557c4e5e6119be5a076f4cc32c`。
+- 新模块与测试 Ruff/格式、全仓 E9/F63/F7/F82、CI helper 24 项与 `git diff --check` 均通过。
+- 本地验收目录:`/private/tmp/mineru-gradio-lifecycle-delivery-844p9mld`;持久化报告、wheel 和复现脚本:`/Users/myhloli/Downloads/MinerU-gradio-lifecycle-24661719-2o68czuu`。
+- [本轮跨平台 CI](https://github.com/opendatalab/MinerU/actions/runs/40173191691):**16 个任务全部成功**,head SHA 确认为本轮提交。
+- 已下载并核对全部 13 份 JUnit:Linux Python 3.11–3.14 每组 **4097 passed、6 skipped**;Windows/macOS Python 3.11–3.14 每组 **130 passed**(包含新增生命周期回归);Torch CPU **106 passed**。Python 3.12 覆盖率 **63.49%**,高于要求的 58%。
+- 用户原有 PDF 样式补丁逐字节不变,三个 examples 文件 SHA-256 均与前三批验收记录一致。
+
+## 第五批:Router 路由、租约和预占状态类型化
+
+- 提交:`9f7f66412776482667ee2b0e3367a5f66a87b05b`,`refactor: type router route and result lease state`,15 个任务文件,用户原有改动未混入。
+- 新增 `route_state.py`:`ExecutionRouteState` 明确持有执行快照、下游文件身份、认证头和预占;`ResultLease` 明确持有结果保护、墙上时间期限和单调时钟续租顺序。
+- 文件与执行使用独立的 `FileRoute` / `ExecutionRoute`。资源种类为只读属性;执行注册必须同时提供完整执行状态,查询与枚举按资源种类返回具体类型。
+- 删除旧 `ResourceRoute.metadata` 和通用 `register()`,所有仓库内生产调用与测试迁移到明确字段及 `register_file()` / `register_execution()`,没有保留兼容转发。
+- 上游 HTTP payload 作为独立响应缓存保留原始扩展;内部租约、固定计数和认证不存放其中。文件元数据刷新保持租约和传输固定状态。
+- 预占对象是活动执行的归属依据,取消、终态和 worker 丢失统一幂等释放;移除 `active_counted`、代理层兜底计数以及无调用方的手工开始/结束计数方法。
+- 保留公开 Task/File ID、逐文件状态、worker generation 校验、结果保留和租约时长语义。Router/API 完整 OpenAPI(各 11 条路径)与全部 17 个协议模型 JSON Schema 均与第五批前基线完全一致。
+- 新增 6 项边界回归:重复与迟到预占释放、响应刷新和扩展隔离、注册冲突不覆盖旧归属、跨 worker 续租超时及强制释放清理。已加入 Windows/macOS CI。
+- 聚焦回归:改动前 **202 passed**,最终 **208 passed**;状态类型与注册表两个源文件通过定向 mypy(`--follow-imports=skip --ignore-missing-imports`),改动文件 Ruff/格式及全仓 E9/F63/F7/F82 通过,CI helper **24 passed**。
+- 本地完整非 Torch:**4093 passed、3 skipped、108 deselected、62 warnings**,213.86 秒;继续排除用户修改中的 PDF 样式测试。
+- wheel 在全新 Python 3.14 环境安装,126 个依赖通过 `uv pip check`。`-I` 验证导入安装包;真实启动两个 Flash API 子进程,经 HTTP 验证负载分配、ZIP 内容、元数据刷新、hash 缓存复用并产生新结果 ID、取消、私有认证清理和下游租约释放;两个子进程均以 0 正常退出。没有下载模型或运行推理模型。
+- wheel 660 个包文件逐字节匹配上述提交,SHA-256:`769a56606a287acb05d083424226b6ff1a71c36a782e0986d839a7f736f8ef25`。
+- [第五批跨平台 CI](https://github.com/opendatalab/MinerU/actions/runs/40175872292):**16 个任务全部成功**,head SHA 确认为本轮提交。已下载并核对全部 13 份 JUnit 与覆盖率报告。
+- Linux Python 3.11–3.14 每组 **4103 passed、6 skipped**;Windows/macOS Python 3.11–3.14 每组 **136 passed**;Torch CPU **106 passed**。Python 3.12 覆盖率 **63.58%**,高于要求的 58%。
+- 本地验收:`/private/tmp/mineru-router-state-9_p7f9tj`;持久化 wheel、报告和复现脚本:`/Users/myhloli/Downloads/MinerU-router-state-9f7f6641-ff9pbwhw`。
+- 用户原有 PDF 样式补丁与三个 examples 文件已按原始补丁及 SHA-256 核对保持不变。
+
+## 第六批:Doclib 文件刷新与入库职责拆分
+
+- 实现提交:`f18db4a3f7a76c9efe6f5a46d4648d7983ceb153`,`refactor: separate doclib file ingestion from parsing`,29 个任务文件;后续夹具修正为 `d129c237fb8bdfe6aa9c69ad135cf995806a2030`,只改一个测试文件。
+- `IngestService` 独立拥有文件刷新、状态分类、hash 去重、元数据、文件名/文本 FTS、短标识分配和初始解析入队;`ParseService` 从 1610 行减至 1063 行,显式注入入库服务后保留解析请求和执行职责。
+- 扫描、watch、后台入库、HTTP 文件接口和搜索探测直接使用应用的同一 `IngestService`;解析工作池仍只使用 `ParseService`。两个应用的数据库、FTS、规则和入库对象保持独立。
+- 不保留旧 `ParseService.refresh_file/ensure_ingested/ingest_file` 或旧私有模块转发;仓库内构造和调用全部迁移。既有 `services` 明确导出门面继续从新归属模块导出相应符号。
+- 公用默认页范围与后台规则档位放在 `services/parse_policy.py`,FTS 首尾截断归属 `core/fts.py`。队列 SQL、锁超时、默认初始解析策略及历史缓存兼容边界保持。
+- 10 个迁移方法经 AST 核对:忽略中文职责注释、规范模块名和局部可空类型标注后,SQL 与控制流完全一致。
+- 真实数据库前后回放:4 个文档、5 个文件、2 项原生解析与 2 份缓存;文件状态、去重、队列、FTS、缓存命中响应、指标事件及完整缓存 JSON 均相同。仅排除数据库墙上时间字段与缓存文件名的写入时间戳;原始回放 JSON 与数据库保留在本地验收目录。
+- 原有聚焦回归 **748 passed**;新增 4 项服务独立性、应用实例隔离和架构边界回归通过;新入库/策略模块定向 mypy 通过(`--follow-imports=skip --ignore-missing-imports`)。
+- 完整非 Torch 回归:**4097 passed、3 skipped、108 deselected、62 warnings**,223.78 秒;继续排除用户修改中的 PDF 样式测试。
+- Doclib 完整 OpenAPI **34 条路径**与 **79 个协议模型 JSON Schema**均与第六批前基线完全一致。改动 Python 文件没有新增 Ruff 诊断(42 条为已有诊断),新函数均有中文说明,全仓 E9/F63/F7/F82、格式及 `git diff --check` 通过;CI helper **24 passed**。
+- wheel 已在全新 Python 3.14 环境完整安装,126 个依赖通过 `uv pip check`。`-I` 验证导入安装包;真实后台扫描/入库/解析、HTTP 元数据和 Markdown 读取、缓存命中、FTS 搜索、watch 修改重入库与删除均通过;应用退出后后台任务全部结束。
+- wheel **662 个包文件**逐字节匹配上述提交;SHA-256:`8f142a6b10e6609b4b8d5c9d3eb32e74a6016d5c32fc4c6ee2adc9e8cbb32d75`。
+- [首轮 CI](https://github.com/opendatalab/MinerU/actions/runs/40178458709) 的 Linux 3.11 在 `test_file_parse.py::test_formats_are_returned_unchanged[formats9]` 失败:上游附件和预期 ZIP 分别使用当前时间构造,跨两秒边界后时间戳字节不同。
+- `d129c237` 固定该 ZIP 夹具时间戳,保留严格附件字节断言;`test_file_parse.py` **56 passed**,15 种格式组合在受控跨时间边界验证中均保持字节一致。wheel 662 个生产文件再次核对匹配该最终提交,未重新改动生产实现。
+- [第六批最终跨平台 CI](https://github.com/opendatalab/MinerU/actions/runs/40179228519):**16 个任务全部成功**,head SHA 为 `d129c237fb8bdfe6aa9c69ad135cf995806a2030`。首轮失败 JUnit 与最终结果分开保存在验收目录。
+- 已下载核对最终 13 份 JUnit 与覆盖率报告:Linux Python 3.11–3.14 每组 **4107 passed、6 skipped**;Windows/macOS Python 3.11–3.14 每组 **143 passed**;Torch CPU **106 passed**。Python 3.12 覆盖率 **63.62%**,高于要求的 58%。
+- 本地验收:`/private/tmp/mineru-doclib-ingest-awlirx1s`;持久化报告、wheel 与复现脚本:`/Users/myhloli/Downloads/MinerU-doclib-ingest-f18db4a3-yc6hbssm`。
+- 用户原有 PDF 样式补丁及三个 examples 文件均已核对保持不变。
+
+## 第七批:Doclib 解析队列与执行职责拆分
+
+- 提交:`680d56eef7d8e8333349a8c7b7ee15696e637b1d`,`refactor: separate doclib parse queue and execution`,32 个任务文件。
+- 删除旧 `ParseService` / `parse_svc.py`,没有保留委托壳或私有路径别名。仓库内生产调用、测试组装及当前架构/工作流/不变量/代码地图文档全部迁移。
+- `ParseQueueService`(450 行)负责请求校验、缓存覆盖、活动任务复用和提权、队列抢占、记录查询及失效后索引重建;`ParseExecutionService`(601 行)消费已抢占的行,负责本地/API 解析、产物写出、元数据/索引和终态更新。
+- 二者平级共享数据库、FTS 和数据目录。HTTP 层只依赖队列服务;工作池显式接收队列及执行服务,保持原有轮询、抢占 SQL、工作池异常兜底和停止行为。
+- 共享失败类型归属 `parse_errors.py`;默认档位及纯页范围策略归属 `parse_policy.py`。API 返回的内容页号和布局几何仍一起校验并原子重映射。
+- 20 个迁移方法经 AST 核对,除职责说明和规范策略模块名外,SQL 和控制流完全相同。
+- 真实数据库前后回放:4 文档、5 文件、3 次原生解析和 3 份缓存;状态、队列、强制重解析、活动任务复用、缓存失效、FTS、缓存命中响应、指标事件及完整缓存 JSON 一致,仅排除数据库墙上时间与缓存文件名写入时间戳。
+- 原有聚焦回归 **752 passed**;新增 5 项队列独立性、并发唯一抢占/优先级/过期锁、工作池异常解锁与架构依赖回归通过。队列/执行/策略/错误四个源文件定向 mypy 通过(`--follow-imports=skip --ignore-missing-imports`)。
+- 完整非 Torch:**4102 passed、3 skipped、108 deselected、62 warnings**,203.73 秒;继续排除用户修改中的 PDF 样式测试。CI helper **24 passed**,全仓 E9/F63/F7/F82、改动格式及 `git diff --check` 通过;无新增 Ruff 诊断(41 条为既有诊断)。新函数均有中文职责说明。
+- Doclib 完整 OpenAPI **34 条路径**和 **79 个协议模型 JSON Schema**均与第七批前基线一致。
+- wheel 在全新 Python 3.14 环境完整安装,126 个依赖通过 `uv pip check`;`-I` 验证实际导入安装包且旧模块不存在。真实后台队列/执行/扫描/入库、HTTP 内容读取、强制重解析、失效后重建、缓存、FTS 和 watch 修改/删除全部通过;后台任务退出完成。
+- wheel **664 个包文件**逐字节匹配上述提交;SHA-256:`7de7a5d6c0a60399e65b0b867378f2fb18603da05d28e7d42f2c793a1dee56fa`。
+- [第七批跨平台 CI](https://github.com/opendatalab/MinerU/actions/runs/40181892861):**16 个任务全部成功**,head SHA 已核对为上述提交;最终 13 份 JUnit 与覆盖率报告已下载核对。
+- Linux Python 3.11–3.14 每组 **4112 passed、6 skipped**;Windows/macOS Python 3.11–3.14 每组 **148 passed**;Torch CPU **106 passed**。Python 3.12 覆盖率 **63.68%**,高于要求的 58%。
+- 本地验收:`/private/tmp/mineru-doclib-parse-xssyghst`;持久化报告、wheel 和验证脚本:`/Users/myhloli/Downloads/MinerU-doclib-parse-680d56ee-t8q0j_4t`。
+- 用户原有 PDF 样式补丁及三个 examples 文件均已按原始补丁和 SHA-256 核对保持不变。
+
+## 第八批:Doclib 配置与健康状态的实例归属
+
+- 提交:`95f97619904c410eaf08601065b3c584a9fdf375`,`refactor: scope doclib configuration and health to each app`,29 个任务文件。
+- 新增轻量 `parse_server_state.py` 统一定义探测结果、目标探测状态及应用健康记录;删除模块级 `_parse_server_health` 和 `get_health()`。每个 `AppState` 构造独立状态,入库、策略、队列、执行、HTTP 与探测器显式共享同一实例。
+- `ParseServerHealthCheck` 显式接收健康对象、启动超时、托管配置和日志配置,不在构造或运行中读取进程默认值;应用关闭和探测器停止只处理各自持有的进程。原有探测、退避、generation、重启及停止控制流经 AST 归一核对保持一致。
+- 内容读取、完整 Markdown 导出和失效后的 FTS 重建使用宿主传入的公式定界符快照;`DoclibServer` 显式接收宿主配置和健康对象,数据目录与日志路径回落到该配置。
+- 保留应用/CLI 默认构造、endpoint 解析和独立日志工具的默认配置入口。内部 `_tail_log` 只读取明确传入的路径,状态接口负责提供本实例的正确日志路径;没有新增运行时兼容别名。
+- 单实例真实数据库/原生解析回放与第八批前一致:状态、队列、强制重解析、任务复用、失效、FTS、完整缓存 JSON、回执及指标均相同,仍只排除墙上时间字段和缓存文件名写入时间戳。
+- 新增 4 项实例隔离和架构回归。两个实际应用针对相同公式缓存按各自配置读取、导出和重建 FTS;原始配置构造后被外部修改不影响应用。健康/档位读取相互独立,关闭一方不影响另一方;探测器停止只清理自己的托管进程。
+- 测试禁止宿主路径读取进程默认配置,所有实例仍正常工作。原有 Doclib/格式聚焦 **760 passed**;最终聚焦 **791 passed**(含 27 项远端用量和新增 4 项),新状态/策略模块定向 mypy 通过(`--follow-imports=skip --ignore-missing-imports`)。
+- 完整非 Torch:**4106 passed、3 skipped、108 deselected、62 warnings**,205.57 秒;继续排除用户修改中的 PDF 样式测试。CI helper **24 passed**,全仓 E9/F63/F7/F82、格式和 `git diff --check` 通过;没有新增 Ruff 诊断(91 条为涉及文件的既有诊断)。
+- Doclib 完整 OpenAPI **34 条路径**与 **79 个协议模型 JSON Schema**均与第八批前基线相同。
+- wheel 在全新 Python 3.14 环境完整安装,126 个依赖通过 `uv pip check`;`-I` 验证包路径。实际后台解析、强制重解析、失效重建、内容读取及 watch 验收通过;安装环境内的双实例公式/索引/健康隔离也通过。
+- wheel **665 个包文件**逐字节匹配上述提交,SHA-256:`f3d02814755e72e2b75a24ed153e2c9327a9804cae692d68bf5c4d373af411ce`。
+- [第八批跨平台 CI](https://github.com/opendatalab/MinerU/actions/runs/40184436309):**16 个任务全部成功**,head SHA 已核对为上述提交;最终 13 份 JUnit 与覆盖率报告已下载核对。
+- Linux Python 3.11–3.14 每组 **4116 passed、6 skipped**;Windows/macOS Python 3.11–3.14 每组 **152 passed**;Torch CPU **106 passed**。Python 3.12 覆盖率 **63.69%**,高于要求的 58%。
+- 本地验收:`/private/tmp/mineru-doclib-instance-xg4kliwr`;持久化报告、wheel 与复现脚本:`/Users/myhloli/Downloads/MinerU-doclib-instance-95f97619-09_8qv_x`。
+- 用户原有 PDF 样式补丁与三个 examples 文件按原始补丁及 SHA-256 核对保持不变。
+
+## 第九轮:集中复审与 Doclib 生命周期修复
+
+- 实现提交:`73424fa72d231edffac74a15e19d583ffa6c5e6e`,`fix: complete doclib cleanup across lifespan failures`,仅 5 个任务文件;后续 `968ee71a` 只调整一个真实 PDF 功能测试的等待预算。
+- 集中核对真实入口、导入关系、资源关闭链、公开边界及文档:共享 Tasks、Doclib core、队列/执行、Router 与本地 API、模型 runtime 的关键分层检查通过;旧私有 `parser/task_api.py`、`services/parse_svc.py` 均不存在。
+- 349 个 Python 文件的静态导入清点和 9 个独立冷导入通过。公开入口不加载 Torch/Transformers/ONNX Runtime,导入没有创建默认 home 目录。静态清点包含惰性与 TYPE_CHECKING 边,不将包导出门面的回环当成缺陷。
+- 实证确认生命周期缺口:启动创建托管进程后失败会跳过清理;退出时在途健康探测能再次启动进程;单个停止错误或外部取消能截断后续清理。新增 5 个受控用例在旧代码全部失败,修复后全部通过(包含重复取消、主错误优先保留)。
+- 生命周期现在将启动纳入保护区;先取消并等待后台编排循环,再停止明确拥有的组件,继续处理错误后的其它资源。托管进程、数据库及发现信息最终清理;保留最早资源错误,启动/请求主错误不被清理错误覆盖。
+- 清理以独立任务执行并屏蔽外部取消,重复取消后先排空清理再传播取消;没有更改解析算法、任务策略、CLI/API 协议或同步 CPU 工作的终止边界。
+- 架构、资源归属与生命周期聚焦 **112 passed**;完整非 Torch **4111 passed、3 skipped、108 deselected、62 warnings**,210.30 秒。继续排除用户修改中的 PDF 样式测试。CI helper **24 passed**,本轮改动 Ruff/格式、全仓 E9/F63/F7/F82 和 `git diff --check` 通过。
+- Doclib 完整 OpenAPI **34 条路径**及 **79 个协议模型 JSON Schema**与复审前完全相同。
+- 隔离安装的 126 个依赖通过 `uv pip check`;实际后台解析/强制重解析/失效重建/watch 和 5 个安装态 CLI 帮助入口通过。额外创建真实 Python 子进程,确认启动失败由应用关闭它;重复取消退出后数据库仍完成清理。该进程不加载模型,使用正常终止信号退出,不将其描述为模型推理验收。
+- wheel **665 个包文件**逐字节匹配该提交;SHA-256:`2e5f7110decb32bbdbd865157a424b0462ce0f23dcb3c5b022842efecee56dac`。
+- 早期 `implementation-plan.md` 任务卡片仍引用已移除的组合服务,已加当前归属迁移说明,保留历史卡片内容。未发现值得继续大范围拆分的边界问题;`core/db.py` 导入时读取只读初始化 SQL 资源保留为低优先级可选项,本轮没有据此扩大修复范围。
+- [首轮复审 CI](https://github.com/opendatalab/MinerU/actions/runs/40187166784) 的 Linux 3.12 在一个真实 PDF 功能测试超出 5 秒等待预算;日志显示覆盖率插桩下三页推理已用 4.405871 秒,任务还需打包产物,其余格式及结果断言没有报错。
+- `968ee71a` 仅将该用例等待预算显式设为 20 秒,与其它真实端到端用例一致,保留全部实际页范围、逐文件终态及错误断言;本地覆盖率插桩重跑该文件 **73 passed**。生产代码及 wheel 不变,665 个生产文件再次核对匹配最终提交。
+- [复审最终 CI](https://github.com/opendatalab/MinerU/actions/runs/40188252418):**16 个任务全部成功**,head SHA 已核对为 `968ee71a6bfc802f92345f51f6554e0845bf606d`;首轮失败记录与最终报告分开归档。
+- 最终 13 份 JUnit 与覆盖率报告已下载核对:Linux Python 3.11–3.14 每组 **4121 passed、6 skipped**;Windows/macOS Python 3.11–3.14 每组 **157 passed**;Torch CPU **106 passed**。Python 3.12 覆盖率 **63.70%**,高于要求的 58%。
+- 本地验收:`/private/tmp/mineru-architecture-audit-8cicpvqf`;持久化报告、wheel 和复现脚本:`/Users/myhloli/Downloads/MinerU-architecture-audit-73424fa7-06zqur5w`。
+- 用户原有 PDF 样式补丁及三个 examples 文件按原始补丁与 SHA-256 核对保持不变。
+
+## 合入前最终审阅:已完成并收尾
+
+- 审阅 HEAD:`968ee71a6bfc802f92345f51f6554e0845bf606d`;已刷新目标 `upstream/dev` 至 `986416e4e4eb17fd63e5580408e9a9afc8480ec1`。
+- 相对目标共 176 个改动文件;范围包含优化起点已有的 `ec6c23cff` Gradio/SDK 取消增强提交,未将它混记为结构拆分的新行为。
+- 合并模拟无冲突,生成树与 HEAD 完全相同;没有执行实际合并。没有发现需要阻止本轮合入的新问题。
+- 本次针对性回归 **138 passed、2 warnings**,18.07 秒;全仓 E9/F63/F7/F82、分支补丁检查、新增生产函数中文说明核查通过。
+- 直接对比最新目标源码:API/Router 完整 OpenAPI 各 **11 条路径**、Doclib **34 条路径**与 **79 个模型 Schema**均完全一致。最终 CI 再次查询确认 **16 个任务成功**,head SHA 与审阅提交相同;生产代码没有新增改动,既有完整回归及隔离安装包验收继续适用。
+- 非阻断后续项 **P3(30/100)**:显式宿主使用自定义公式分隔符时,初次 FTS 索引仍通过 `ParseResult.markdown()` 读取进程默认配置,重建索引则使用宿主配置。真实数据库探针已确认;默认配置一致,公式正文未丢失。后续扩展嵌入式宿主配置隔离时,再将公式配置显式传入执行侧索引渲染,本轮不扩大范围。
+- 正式报告与证据:`/Users/myhloli/Downloads/MinerU-final-review-968ee71a-vb8q3e21/review.md`;包括目标对比、AST 差异、真实 FTS 探针、回归日志和审阅结论 JSON。
+- 用户原有 PDF 样式补丁及三个 examples 文件已再次按补丁与 SHA-256 核对保持不变。
+
+## 合入流程:已完成
+
+- [PR #5665](https://github.com/opendatalab/MinerU/pull/5665):`codex/architecture-lifecycle-refactor` → `dev`,已创建正式 PR 并附加到当前任务。
+- PR head:`968ee71a6bfc802f92345f51f6554e0845bf606d`;目标:`986416e4e4eb17fd63e5580408e9a9afc8480ec1`。
+- PR 跨平台 CI:[40190457124](https://github.com/opendatalab/MinerU/actions/runs/40190457124) 的 **16 个任务全部成功**,13 份 JUnit 已下载核对,覆盖率 **63.70%**;文档构建与 CLA 也通过。
+- 已于 `2026-10-25T12:00:58Z` 正常合并,提交 `c8028a89ff0de12ddd7c9d31827215e4599f3c3b`。GitHub PR 的 MERGED 状态及 upstream/dev 指向均已核对,合并树与已审阅 HEAD 完全一致。
+- 合入后跨平台 CI:[40191282151](https://github.com/opendatalab/MinerU/actions/runs/40191282151) 的 **16 个任务全部成功**;[文档构建](https://github.com/opendatalab/MinerU/actions/runs/40191282208) 通过。两者 head SHA 均核对为合并提交。
+- 合入后 13 份 JUnit 与覆盖率报告已下载核对:Linux Python 3.11–3.14 每组 **4121 passed、6 skipped**,Windows/macOS 每组 **157 passed**,Torch CPU **106 passed**,覆盖率 **63.71%**。
+- 合入记录:`/Users/myhloli/Downloads/MinerU-merge-5665-z32pkixt`。
+
+## 收尾状态
+
+- 计划内结构优化、集中复审、合入前审阅及 PR 合入与验收均已完成,本轮任务结束。
+- 低优先级项已记录,后续按实际需求独立处理;PR 已合入 dev,合入前后检查全部通过;发布和部署尚未执行。
+
+## 已确认的基线问题与辅助证据
+
+- 历史基线:Gradio 6.27.0 构建队列时可能遗留事件循环,并在退出/GC 时出现 `BaseEventLoop.__del__: Invalid file descriptor: -1`。第四批已在 MinerU 的构建和启动入口修复。
+- 使用第三批前原始 `app.py` 的同组 54 个测试也复现该警告;不导入 MinerU 的 `Blocks + queue` 探针同样观察到循环未关闭,说明它不是第三批转换服务引入。
+- 第三批 OpenAPI 基线临时目录:`/var/folders/tm/fmb8lj6d3sq28z7x0cgjmcrc0000gn/T/mineru-single-execution-jfur9eyr`。
+- Gradio 诊断临时目录:`/var/folders/tm/fmb8lj6d3sq28z7x0cgjmcrc0000gn/T/mineru-gradio-loop-diag-e8kxxwna`。
+- 临时目录可能被系统清理;恢复依据优先使用本状态文件、当前源码和持久化回归测试。
diff --git a/docs/next/cli/mineru-kit-api-server.md b/docs/next/cli/mineru-kit-api-server.md
index bfae0fab..dce6329e 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 启动入口。`--tier` 是单值启动能力上限,只接受 `flash`、`basic` 或 `standard`;不传时默认以 `standard` 启动,并暴露全部四个请求 tier。
+`mineru-kit api-server` 是正式的 self-hosted parse-server 启动入口。`--tiers` 接受逗号分隔的精确档位集合(`flash/basic/standard/advanced`),或 `auto`;不传时按硬件自动推荐开放集合。
`mineru doclib` 可以通过 HTTP 调用它执行解析任务。
@@ -41,26 +41,54 @@ api-server 负责:
api-server 必须提供能力发现接口,让 doclib 或客户端知道当前服务支持哪个 tier。
-裸 api-server 的请求默认 tier 由启动配置决定:
+启动时确定开放集合,能力发现、请求校验和实际执行使用同一集合。显式列表不自动补齐其他档位,并跳过硬件推荐;依赖预检仍照常执行。
-| api-server 启动配置 | `/v1/tiers` | 请求未指定 tier 时 |
+| api-server 启动配置 | `/v1/tiers` | PDF/image 请求未指定 tier 时 |
|---------------------|-------------|--------------------|
-| `--tier flash` | `flash` | 返回 `quality_tier_unavailable`,除非请求显式传 `tier=flash` |
-| `--tier basic` | `flash`、`basic` | `basic` |
-| `--tier basic --no-flash` | `basic` | `basic` |
-| `--tier basic --no-advanced` | `flash`、`basic` | `basic` |
-| `--tier standard` 或未传 `--tier` | `flash`、`basic`、`standard`、`advanced` | `standard` |
-| `--tier standard --no-flash` | `basic`、`standard`、`advanced` | `standard` |
-| `--tier standard --no-advanced` | `flash`、`basic`、`standard` | `standard` |
-| `--tier standard --no-flash --no-advanced` | `basic`、`standard` | `standard` |
+| `--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` 启动裸 api-server,请求未指定 tier 时不应静默使用 `flash`。需要 `flash` 时调用方必须显式传 `tier=flash`;非 PDF/image 文件的批量归一规则见 [ADR-0024](../decisions/0024-file-type-tier-normalization.md)。
+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默认选择与文件作用范围)。
-`--no-flash` 会同时关闭 Flash 能力发现和执行。显式 Flash 请求以及 OFD/EPUB/Office/HTML/MHTML/CSV/TSV 等必须归一到 Flash 的输入都会被拒绝。`--tier flash --no-flash` 因为没有可用能力而启动失败。
+### 自动推荐
-`--no-advanced` 会同时关闭 Advanced 能力发现和执行:`GET /v1/tiers` 不再发布 `advanced`,显式 Advanced 请求返回该 tier 不可用。Advanced 不是启动 tier,因此它与 `--tier flash` 或 `--tier basic` 组合时不会改变原有能力;Standard 仍保留自身所需的共享模型。
+省略 `--tiers` 等价于 `--tiers auto`:
-如果不同启动能力需要不同硬件、并发或生命周期策略,应启动多个 api-server 进程并由 doclib 或上层配置分别管理 URL。Doclib managed server 固定使用 `--no-flash`,因为 Flash 在 doclib 进程内执行。
+| 硬件条件 | 推荐开放集合 |
+|----------|--------------|
+| 进程可用 CPU 数不足 4,且无达标 GPU | `flash` |
+| 进程可用 CPU 数至少 4,且无达标 GPU | `flash,basic,standard` |
+| 有可用独显、OCR 校准达标的集显,或 Metal 可用的 Apple Silicon | 全部四档 |
+
+CPU 数按逻辑 CPU 计算,并考虑进程亲和性和 Linux cgroup 配额。集显沿用现有 OCR 校准的有效性及 GPU 时间不高于 CPU 时间 0.8 倍的判定。Apple Silicon 的 Metal 集显按已知能力直接推荐。探测失败或设备身份不明确时按 CPU 条件推荐。
+
+推荐阶段只探测设备并读取已有校准记录,不下载模型、不执行 OCR/VLM 性能测试、不写配置,也不增加内存分级门槛。模型的正常惰性加载和显式 `--preload-models` 行为独立于推荐阶段。
+
+真实 OCR 校准会在当前配置文件旁保存 `<配置文件路径>.onnx-calibration.json`。只有设备身份、后端版本和 CPU 配置匹配、输出一致且结果稳定的记录可用于集显推荐。旧的 `model.onnx_device=cpu/gpu` 偏好及手动 GPU 设置不作为校准证据。记录缺失、损坏或失效时集显不自动开放 advanced,用户仍可通过显式列表启用。新校准结果在下次启动时生效,运行中的服务不会动态增减档位。
+
+远程 VLM 配置不自动扩大推荐集合;部署者可显式指定所需列表。服务开放 advanced 不代表请求默认使用 advanced。
+
+### 旧命令迁移
+
+旧启动参数 `--tier`、`--no-flash`、`--no-advanced` 已移除,传入直接报错。等价迁移如下:
+
+| 旧参数 | 新参数 |
+|--------|--------|
+| `--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` 顺序发布。
+
+Doclib、WebUI 和 Router 保留现有托管配置语义,启动子进程时转换成等价列表。Doclib 的 basic/standard 分别传入 `basic`、`basic,standard,advanced`,Flash 仍由 Doclib 进程内执行;WebUI 和 Router 继续展开原有 flash/basic/standard 预设。
## 4. self-hosted 与 managed
@@ -73,19 +101,18 @@ managed 是生命周期管理方式,不是用户直接执行的命令模式。
## 5. Usage
-api-server 启动时可使用单个 `--tier` 指定能力上限:
+api-server 可自动推荐,也可显式指定精确集合:
```bash
-mineru-kit api-server --tier basic --port 16580
-mineru-kit api-server --tier standard --port 15982
-mineru-kit api-server --tier standard --no-flash --port 8000
-mineru-kit api-server --tier standard --no-advanced --port 8000
-mineru-kit api-server --tier standard --no-flash --no-advanced --port 8000
-mineru-kit api-server --tier standard --preload-models
-mineru-kit api-server --tier standard --disable-image-analysis
+mineru-kit api-server
+mineru-kit api-server --tiers auto
+mineru-kit api-server --tiers flash,standard --port 8000
+mineru-kit api-server --tiers advanced --preload-models
+mineru-api --tiers flash,basic,standard,advanced
+python -m mineru.parser.api_server --tiers flash
```
-未传 `--tier` 时暴露 `flash`、`basic`、`standard`、`advanced`;PDF/image 请求未指定 tier 时默认 `standard`。
+显式集合包含 standard 或 advanced 时,依赖检查与预加载合并使用现有 Standard 模型配置;只有 basic 时使用 Basic 配置。共享模型只加载一次,发布集合仍严格等于指定列表。
OCR 模式通过每次 `POST /v1/tasks` 请求的 `ocr_mode` 设置,可选 `auto`、`txt`、`ocr`,省略时为 `auto`。启动参数 `--ocr-mode` 已移除,传入会报错;Python `create_app()` 同样不再接受该参数。
@@ -116,7 +143,7 @@ HTTP 访问日志刷屏。连接外部服务时,其日志级别由服务部署
### 使用远程 MinerU VLM 服务
```bash
-mineru-kit api-server --tier standard --vlm-server-url http://127.0.0.1:30000/v1
+mineru-kit api-server --tiers flash,standard --vlm-server-url http://127.0.0.1:30000/v1
mineru-api --vlm-server-url https://vlm.example.com/proxy/v1 --vlm-model mineru-model --preload-models
```
diff --git a/docs/next/cli/mineru-kit-parse.md b/docs/next/cli/mineru-kit-parse.md
index 8c139ae9..3a5b15f1 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` 一致;`--tier` 值域更宽(`mineru-kit parse` 接受 `flash/basic/standard/advanced`,`api-server` 只接受 `flash/basic/standard` 作为能力上限)。`--language` OCR 语言参数已从全部命令移除,传入会报错。
+local 模式的 `ocr-mode`、`disable-image-analysis` 与 `mineru-kit api-server` 一致;`mineru-kit parse --tier` 选择单次解析档位,`api-server --tiers` 则配置四个档位中的任意非空集合,或通过 auto 推荐。`--language` OCR 语言参数已从全部命令移除,传入会报错。
完整决策背景见 [ADR-0016](../decisions/0016-mineru-kit-parse-command.md)。
diff --git a/docs/next/cli/mineru-kit-webui.md b/docs/next/cli/mineru-kit-webui.md
index a964b35d..529d7456 100644
--- a/docs/next/cli/mineru-kit-webui.md
+++ b/docs/next/cli/mineru-kit-webui.md
@@ -67,7 +67,7 @@ mineru-kit webui \
| `--enable-example` | 显示当前工作目录 `examples/` 中的示例文件。 |
| `--enable-api` | 暴露 Gradio 转换事件 API。 |
-Gradio 不接受 `--api-server-no-flash`、`--no-flash`、`--api-server-no-advanced`、`--no-advanced`;传入会报错。独立 API 启动命令仍保留 `--no-flash` 和 `--no-advanced`。
+Gradio 不接受 `--api-server-no-flash`、`--no-flash`、`--api-server-no-advanced`、`--no-advanced`;传入会报错。独立 API 启动命令使用 `--tiers` 精确列表;WebUI 的既有单值托管配置会转换为等价列表。
指定外部 `--api-url` 时,Gradio 先校验 `/v1/health` 和 `/v1/tiers`。远程已提供 Flash 时,全部请求使用远程;远程缺少 Flash 时,在运行 Gradio 的机器上自动启动仅提供 Flash 的 loopback V1 API,并完成能力发现后启动界面。Flash 请求只上传至本地服务,其他档位继续使用远程;远程未提供的 Advanced 不会补充。
diff --git a/docs/next/cli/mineru-kit.md b/docs/next/cli/mineru-kit.md
index eaffc4f1..0c0ab9db 100644
--- a/docs/next/cli/mineru-kit.md
+++ b/docs/next/cli/mineru-kit.md
@@ -42,7 +42,7 @@
```bash
mineru-openai-server --engine vllm --host 127.0.0.1 --port 30000
mineru-models-download --tier standard --source modelscope
-mineru-api --host 127.0.0.1 --port 8000 --tier standard
+mineru-api --host 127.0.0.1 --port 8000 --tiers flash,standard
```
`mineru-openai-server` 保留向底层引擎透传额外参数的能力。`mineru-models-download` 后直接填写模型仓库名或 `--tier` 等下载参数,不需要再输入 `download`。
diff --git a/docs/next/decisions/0017-mineru-kit-api-server-command.md b/docs/next/decisions/0017-mineru-kit-api-server-command.md
index a3b1465d..2c37a4fe 100644
--- a/docs/next/decisions/0017-mineru-kit-api-server-command.md
+++ b/docs/next/decisions/0017-mineru-kit-api-server-command.md
@@ -44,26 +44,15 @@ managed 是生命周期管理方式,不是用户直接操作的独立命令产
### 3. 单进程 tier 规则
-一个 `mineru-kit api-server` 进程使用单个 `--tier` 表示启动能力上限。
+一个 API 服务进程使用 `--tiers` 配置精确开放集合,接受 `flash/basic/standard/advanced` 的逗号分隔列表,省略等价于 `auto`。旧 `--tier`、`--no-flash`、`--no-advanced` 参数直接移除。
-支持的启动 tier:
+自动推荐规则:所有设备推荐 flash;进程可用逻辑 CPU 至少 4 时增加 basic、standard;可用独显、有效 OCR 校准判定更优的集显,或 Metal 可用的 Apple Silicon,推荐全部四档。设备探测失败或校准记录不可用时按 CPU 条件推荐。推荐不加载模型或运行性能测试,不增加内存门槛。
-- `flash`
-- `basic`
-- `standard`
+显式列表精确决定能力集合,可以覆盖推荐;依赖预检和可选模型预加载仍执行。Standard 与 Advanced 共用模型配置,模型需求合并不扩展公开档位。空集合、未知值、空项和 auto 混用均报错。
-Advanced 仍是公开请求 tier,但不是启动 tier;Standard 的依赖和模型同时覆盖 Advanced。
+开放集合在启动时固定。Tasks 请求的单数 `tier` 保持可选,默认顺序为 `standard -> basic -> flash`,advanced 仅显式使用;原生文档始终要求 flash 能力。
-规则:
-
-1. `--tier flash` 暴露 `flash`
-2. `--tier basic` 暴露 `flash`、`basic`
-3. `--tier standard` 暴露 `flash`、`basic`、`standard`、`advanced`
-4. 未传 `--tier` 等价于 `--tier standard`
-5. `--no-flash` 从能力中移除 Flash,并禁止该进程执行 Flash backend
-6. `--tier flash --no-flash` 启动失败
-7. `--no-advanced` 从能力中移除 Advanced,并禁止该进程接受 Advanced 请求
-8. `--no-flash --no-advanced` 可组合使用;Standard server 此时只发布 Basic 与 Standard
+Python 工厂改为 `create_app(tiers=...)`,None 自动推荐。Doclib、WebUI 和 Router 的托管配置保持原有语义,只把子进程参数转换为等价列表。详细规则及旧命令迁移见 [API 启动文档](../cli/mineru-kit-api-server.md)。
### 4. backend 的公开边界
@@ -84,9 +73,7 @@ backend 不是普通 API 协议层字段。
- `--host`
- `--port`
-- `--tier`
-- `--no-flash`
-- `--no-advanced`
+- `--tiers`
- `--api-key`
#### 稳定解析参数
diff --git a/docs/next/decisions/0024-file-type-tier-normalization.md b/docs/next/decisions/0024-file-type-tier-normalization.md
index 4dd2c155..27c7c783 100644
--- a/docs/next/decisions/0024-file-type-tier-normalization.md
+++ b/docs/next/decisions/0024-file-type-tier-normalization.md
@@ -2,6 +2,7 @@
状态: Accepted,已实现
日期: 2026-07-09
+Tasks 语义更新: 2026-10-27
相关文档: ../tiers.md, ../cli/mineru-parse.md, ../cli/mineru-kit-parse.md, ../api/tasks.md, 0022-doclib-file-type-tier-remote-semantics.md, 0028-csv-structured-flash-parsing.md
## 背景
@@ -38,7 +39,7 @@ EPUB、Office、HTML 和 CSV 即使通过高层接口传入了 `basic`、`standa
- `mineru parse <single-file>` 经 doclib 解析。
- `DoclibClient.ensure_parse(ParseRequest(...))`。
-- SDK 直接解析单个文件。
+- 本地 SDK 直接解析单个文件(HTTP `MinerUApiParser` 遵循下述 Tasks 规则)。
- `mineru-kit parse` 展开后只有一个输入文件。
规则:
@@ -55,7 +56,7 @@ EPUB、Office、HTML 和 CSV 即使通过高层接口传入了 `basic`、`standa
批量操作包括:
-- API Server v1 parse job。
+- API Server / Router 的 V1 Tasks,包括单文件请求及 HTTP SDK、file_parse 的提交。
- `mineru-kit parse` 展开后包含多个输入文件,或输入目录。
- parsing-rule 触发的后台解析。
@@ -71,7 +72,10 @@ EPUB、Office、HTML 和 CSV 即使通过高层接口传入了 `basic`、`standa
批量操作中,EPUB/Office/HTML/CSV 的实际 parse row、缓存目录、locator 和 metadata 必须记录 `flash`,不能记录用户传入的质量 tier。其它 text 不得生成这些解析产物。
-API Server 当前只有 job 级 `tier` 字段,暂不扩展 file-level effective tier 字段。因此 API job 响应中的 job tier 可以表示请求 tier;但内部执行 EPUB/Office/HTML/CSV 文件时,应按 `flash` 语义处理,不产生伪质量缓存。其它 text 不进入 API parse job。
+Tasks 的顶层请求 `tier` 可选,只对 PDF/image 生效。省略或 JSON `null` 时,接单服务按 `standard -> basic -> flash` 选择支持的档位;advanced 必须显式指定,仅有 advanced 时省略 tier 返回 `503 quality_tier_unavailable`。
+显式档位不受支持且批次包含 PDF/image 时,整个创建请求返回 `400 invalid_request`,不自动升降档。纯原生文档忽略合法的显式 tier,固定使用 flash;非法枚举或空字符串仍报参数错误,flash 被禁用时不能解析原生文档。
+选档在接单时保存,后续逐文件执行和 Router 转发使用有效档位,不随 worker 默认值变化。成功结果通过 `files[].parse.tier` 返回真实执行档位,不在顶层回显请求 tier,也不产生伪质量缓存。其它 text 不进入 Tasks 解析。
+Tasks 默认选择独立于 Doclib 主动操作的默认质量策略,不改变后者必须显式选择 flash 的规则。
### 4. Parsing-Rule 语义
@@ -99,7 +103,7 @@ remote 的含义取决于入口:
|------|----------------------|---------------|
| doclib / `mineru parse` 单文件主动解析 | 报 `remote_unsupported_for_file_type` | 报 `parse_not_required` |
| parsing-rule | 忽略 remote,按 `flash` | 只入库和索引 |
-| API Server job | 不适用;API Server 自身就是解析服务 | 不接受 text 作为解析输入 |
+| API Server / Router Tasks | 不适用;HTTP 请求明确发往配置的解析服务 | 不接受 text 作为解析输入 |
| `mineru-kit parse` | 允许,作为低层工具特例 | 不接受 text 作为解析输入 |
doclib 单文件主动解析中,`remote=true` 表示用户显式要求把该文件交给 remote parse-server。因为 remote parse-server 只支持 PDF/image,该组合必须报错,不能静默改成本地 `flash`,否则会改变用户显式选择的执行路径和隐私语义。
@@ -126,17 +130,11 @@ doclib 单文件主动解析中,`remote=true` 表示用户显式要求把该
- 批量任务经常包含混合文件类型。
- parsing-rule 是后台批量策略,不应因为 EPUB/Office/HTML/CSV 携带无效质量 tier 而阻断整个目录处理。
-- API Server v1 parse job 当前是多文件接口,也应支持异构输入。
+- API Server V1 Tasks 是多文件接口,也应支持异构输入。
### 方案 C: 为 API Server 增加 file-level effective tier 字段
-暂不采用。
-
-原因:
-
-- 当前目标是先统一行为,不扩展 API response schema。
-- API job 的 job-level tier 可以继续表达请求 tier。
-- 如未来需要精确暴露每个文件的实际 tier,可另行设计 file-level effective tier 字段。
+原先暂缓的响应设计已由 Tasks 的 `files[].parse.tier` 实现。该字段来自成功产物的实际元数据,不以请求档位代替;不再使用 job-level tier 表示整批实际执行档位。
## 影响
@@ -149,15 +147,15 @@ doclib 单文件主动解析中,`remote=true` 表示用户显式要求把该
### 对 SDK 和 mineru-kit
-- SDK 单文件解析应按单对象主动操作语义处理,并排除 text 解析输入。
+- 本地 SDK 单文件解析按单对象主动操作语义处理,并排除 text 解析输入;HTTP `MinerUApiParser` 遵循 Tasks 语义。
- `mineru-kit parse` 需要根据展开后的输入数量区分单对象和批量。
- `mineru-kit parse --remote` 对 EPUB/Office/HTML/CSV 是允许的低层工具特例;其它 text 不作为解析输入。
### 对 API Server
-- API Server job 按批量操作语义处理。
-- EPUB/Office/HTML/CSV 即使 job tier 是质量 tier,执行时也按 `flash` 语义;其它 text 不进入 parse job。
-- 暂不新增 file-level effective tier 字段。
+- API Server 和 Router Tasks 按批量操作语义处理,包括单文件提交。
+- EPUB/Office/HTML/CSV 即使请求 tier 是质量 tier,执行时也按 `flash` 语义;其它 text 不进入 Tasks 解析。
+- 成功文件的实际档位通过 `files[].parse.tier` 返回,默认选档及错误规则见上文。
### 对缓存和 locator
diff --git a/docs/next/glossary.md b/docs/next/glossary.md
index 7feaf6a3..0f890872 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` 使用单值 `--tier flash|basic|standard` 表示能力上限;启动后的 HTTP API 通过 `/v1/tiers` 发布展开后的请求 tier。
+- `mineru-kit api-server` 使用 `--tiers` 指定精确开放集合或 auto 硬件推荐;启动后的 HTTP API 通过 `/v1/tiers` 发布实际开放档位。
- Middle JSON schema 2.0 不记录 `_meta.backend`;产物 metadata 不包含 backend 字段,用户可见语义只记录 `tier`。
- `backend` 不应承担隐私语义;隐私由 `privacy` / `remote` / `via` 描述。
diff --git a/docs/next/open-questions.md b/docs/next/open-questions.md
index 813bfed1..fc2607d7 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 --tier` 是单值能力上限,只接受 `flash`、`basic`、`standard`;未传时按 `standard` 暴露四个请求 tier。 |
+| api-server tier | `mineru-kit api-server --tiers` 配置精确集合;省略等价于 auto,按硬件和已有 OCR 校准推荐,HTTP 请求默认仍优先 standard。 |
| managed 生命周期 | managed 模式下,模型下载、预热、重试和退避由 `mineru-kit api-server` 负责。 |
| 本地 api-server 安全 | 本地 api-server 默认监听 loopback;可通过 `--api-key` 设置固定 API Key,默认不设置。 |
| P0 主链路 | P0 包含完整 watch、rules、search,不再把它们标为可选主链路。 |
diff --git a/docs/next/sdk/api-parser.md b/docs/next/sdk/api-parser.md
index ff49ce4f..2ccbee32 100644
--- a/docs/next/sdk/api-parser.md
+++ b/docs/next/sdk/api-parser.md
@@ -13,6 +13,9 @@ 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 必须显式指定。
+显式 tier 原样发送,服务不支持该 PDF/图片档位时返回错误,不自动升降档。
+Office、HTML 等已支持的原生文档始终使用 flash,忽略合法的显式 tier;单文件 HTTP 调用也遵循 [Tasks 规则](../api/tasks.md#tier默认选择与文件作用范围),与直接本地解析及 Doclib 的选档策略独立。
`parse()` 和 `parse_async()` 均接收 `page_range/status_callback/duration_callback`。
## 请求与结果
diff --git a/docs/next/tiers.md b/docs/next/tiers.md
index 69853630..8c9489f2 100644
--- a/docs/next/tiers.md
+++ b/docs/next/tiers.md
@@ -16,10 +16,10 @@ MinerU 当前定义四个公开 tier。文档中使用面向用户的显示名
|--------|--------|------|------------|
| Flash | `flash` | 快速发现与索引 | 随 MinerU 默认安装,最快、质量最低,用于大量文件的低成本预处理 |
| Basic | `basic` | 基础解析 | 需要额外依赖,CPU 可运行,GPU 可加速,质量和资源消耗折中 |
-| Standard | `standard` | 标准解析 | 需要 VLM 相关依赖和支持的本地加速器,也是 MinerU 线上 API 提供的档位 |
+| Standard | `standard` | 标准解析 | 使用少量 VLM 工作,CPU 可运行、GPU 可加速,也是 MinerU 线上 API 提供的档位 |
| Advanced | `advanced` | 高级解析 | 与 Standard 硬件要求相同,但消耗更多算力和时间,困难文档质量更高 |
-`auto` 不再作为公开 tier 值。CLI 中不传 `--tier`、HTTP API 中省略 `tier` 或传 JSON `null`、Python SDK 中传 `None`,都表示使用当前入口的默认选择策略。
+`auto` 不是解析请求的公开 tier 值;API 启动参数 `--tiers auto` 专门表示硬件推荐开放集合。CLI 中不传 `--tier`、HTTP API 中省略 `tier` 或传 JSON `null`、Python SDK 中传 `None`,都表示使用当前入口的默认选择策略。
核心原则:
@@ -28,7 +28,7 @@ MinerU 当前定义四个公开 tier。文档中使用面向用户的显示名
- 默认选择策略在 PDF/image 质量解析语境下不会等价于 `flash`;OFD/EPUB/Office/HTML/MHTML/CSV/TSV 这类仅支持 flash tier 的输入按 [ADR-0024](decisions/0024-file-type-tier-normalization.md) 与 [ADR-0028](decisions/0028-csv-structured-flash-parsing.md) 归一为 `flash` 语义;其它 text 直接读取。
- `standard` 是高质量 tier,也是 `mineru.net/api` 对外提供的解析层级。
- `advanced` 是当前公开 tier 中质量和成本最高的档位。
-- 本地运行 `standard` 和 `advanced` 是正式支持能力,不是实验能力;它们依赖 VLM 相关依赖、支持的本地加速器和足够的显存或统一内存。
+- 本地运行 `standard` 和 `advanced` 是正式支持能力,不是实验能力;它们需要所选 VLM 后端的运行时依赖;standard 支持 CPU,advanced 因 VLM 工作更多而优先推荐 GPU。
- `mineru.net/api` 在相当长时间内只提供 `standard`,不暴露低成本远端 `basic`。
- 不使用 `--remote` 时,MinerU 不会把文档发送到 `mineru.net/api`。
@@ -54,19 +54,18 @@ MinerU 当前定义四个公开 tier。文档中使用面向用户的显示名
### 3.1 无能力列表的场景
-启动服务或直接解析时,如果当前入口没有可用 tier 列表可参考,默认 tier 是 `standard`。
+直接本地解析时,如果当前入口没有可用 tier 列表可参考,默认 tier 是 `standard`。API 服务启动的开放集合独立按 `--tiers` 配置或硬件推荐确定。
典型场景:
-- `mineru-kit api-server` 未传 `--tier`。
- `mineru-kit parse` local 模式未传 `--tier`。
- Tool SDK 直接本地解析且无法做能力发现。
-这类场景的默认值不是 `advanced`。`advanced` 消耗更多算力和时间,需要用户显式指定,或由具备能力发现上下文的调用方在没有 `standard` 时选择。
+这类场景的默认值不是 `advanced`。`advanced` 消耗更多算力和时间,需要用户显式指定。
-### 3.2 有能力发现上下文的场景
+### 3.2 Doclib 主动解析的能力发现
-当调用某个 parse-server,或有等价的可用 tier 上下文时,默认选择策略基于当前可发现能力选择实体 tier。MinerU 有 local parse-server,也有 remote parse-server。无论 local 还是 remote,parse-server 都应支持通过 API 发现当前 server 提供了哪些解析 tier。当前代码支持发现 `basic`、`standard`、`advanced` 等质量 tier。
+Doclib 主动解析调用某个 parse-server,或有等价的可用 tier 上下文时,默认选择策略基于当前可发现能力选择实体 tier。MinerU 有 local parse-server,也有 remote parse-server。无论 local 还是 remote,parse-server 都应支持通过 API 发现当前 server 提供了哪些解析 tier。当前代码支持发现 `basic`、`standard`、`advanced` 等质量 tier。
这类场景的默认选择顺序是:
@@ -74,25 +73,37 @@ MinerU 当前定义四个公开 tier。文档中使用面向用户的显示名
standard -> basic -> 报错
```
-也就是说,`standard` 是默认优先档位;没有 `standard` 时回退到 `basic`。`advanced` 必须由用户显式指定,不参与默认选择。按照当前服务能力契约,提供 `advanced` 的服务一定同时提供 `standard`。
+也就是说,`standard` 是默认优先档位;没有 `standard` 时回退到 `basic`。`advanced` 必须由用户显式指定,不参与默认选择。API 服务可以显式只开放 `advanced`;Doclib 既有 Standard 托管预设仍同时开放 standard 和 advanced。
| 可发现能力 | 默认解析结果 |
|------------|-----------------|
| 只支持 `basic` | `basic` |
| 只支持 `standard` | `standard` |
-| 只支持 `advanced` | 非法能力组合,不选择默认 tier |
+| 只支持 `advanced` | 无可用默认档位,报错 |
| 同时支持 `basic` 和 `standard` | `standard` |
| 同时支持 `standard` 和 `advanced` | `standard` |
| 同时支持 `basic` 和 `advanced`,不支持 `standard` | `basic` |
| 同时支持 `basic`、`standard` 和 `advanced` | `standard` |
| 只支持 `flash` 或没有可用能力 | 报错 |
-PDF/image 默认选择策略不会解析为 `flash`。如果系统找不到 `basic` 或 `standard`,应返回 `quality_tier_unavailable` 或等价结构化错误,而不是自动选择 `advanced` 或用 `flash` 内容替代。错误码见 [错误码体系](errors.md)。
+Doclib 主动解析 PDF/image 的默认选择策略不会解析为 `flash`。如果系统找不到 `basic` 或 `standard`,应返回 `quality_tier_unavailable` 或等价结构化错误,而不是自动选择 `advanced` 或用 `flash` 内容替代。错误码见 [错误码体系](errors.md)。
默认选择策略是请求时的选择逻辑,不是长期缓存语义。任务入队、缓存命中、产物目录和结果 metadata 应使用实际选择的实体 tier(例如 `basic`、`standard` 或 `advanced`),避免默认选择与实体 tier 产生重复缓存。
读取已有缓存时不使用这套解析默认顺序。`mineru read doc:{short_id}` 不带 `/tier:{tier}` 时不会创建新解析,应在已缓存的非 `flash` 结果中选择最高质量 tier,顺序为 `advanced` -> `standard` -> `basic`;没有非 `flash` 缓存时返回错误。
+### 3.3 HTTP Tasks 的默认选择
+
+Tasks(包括 HTTP `MinerUApiParser` 和 file_parse)省略 tier 时,由接单服务按 `standard -> basic -> flash` 选择支持的档位。JSON Tasks 的 `null` 也表示省略;file_parse 使用 multipart,应直接省略表单字段。
+advanced 只接受显式选择:只有 advanced 时没有默认档位,返回结构化错误。显式指定的 PDF/image 档位不受支持时拒绝请求,不自动升降档。
+已支持的原生文档固定使用 flash,忽略合法的显式 tier。任务受理后固定选档,实际结果逐文件记录在 `files[].parse.tier`。该策略不改变 Doclib 的主动阅读和缓存选择规则,详见 [Tasks](api/tasks.md#tier默认选择与文件作用范围)。
+
+### 3.4 API 服务启动推荐
+
+`--tiers 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)。
+
## 4. Flash
`flash` 随 MinerU 默认安装,面向没有额外 runtime 依赖、GPU 或加速器硬件的用户。它的质量通常最低,但必须足够快。
@@ -101,9 +112,9 @@ PDF/image 默认选择策略不会解析为 `flash`。如果系统找不到 `bas
P0 不做基于启发式的自动提示或自动排队升级。watch 使用 `flash` 后,如果需要在后台自动解析到 `basic`、`standard` 或 `advanced`,必须来自用户显式配置的 parsing-rules;系统不根据文件名、内容特征、搜索命中或“高价值文档”判断自行升级。
-`flash` 不应被当成 PDF/image 默认阅读质量。当 Agent 或用户决定真正读取 PDF/image 文档时,需求已经从“发现它”变成“尽可能准确地理解它”,此时未指定 tier 应使用默认选择策略,并解析到可用的非 `flash` 质量 tier。OFD/EPUB/Office/HTML/MHTML/CSV/TSV 这类仅支持 flash tier 的输入没有质量 tier 分层,按 `flash` 语义处理。其它 text 直接读取。
+在 Doclib 主动阅读中,`flash` 不应被当成 PDF/image 默认阅读质量。当 Agent 或用户决定真正读取 PDF/image 文档时,需求已经从“发现它”变成“尽可能准确地理解它”,此时未指定 tier 应使用默认选择策略,并解析到可用的非 `flash` 质量 tier。OFD/EPUB/Office/HTML/MHTML/CSV/TSV 这类仅支持 flash tier 的输入没有质量 tier 分层,按 `flash` 语义处理。其它 text 直接读取。
-只有在用户明确指定 `flash` 时,才返回 `flash` 的解析内容作为最终阅读结果。
+Doclib 只有在用户明确指定 `flash` 时,才返回 `flash` 的解析内容作为最终阅读结果;HTTP Tasks 可按其独立默认策略选择 flash。
## 5. Basic
@@ -156,7 +167,7 @@ MinerU 的 tier 策略同时遵守隐私优先和质量优先。
### 8.2 质量优先
-用户或 Agent 主动读取 PDF/image 文档时,默认应解析到可用的非 `flash` 质量 tier。
+用户或 Agent 通过 Doclib 主动读取 PDF/image 文档时,默认应解析到可用的非 `flash` 质量 tier。HTTP Tasks 的独立默认策略见第 3.3 节。
如果 `basic`、`standard` 和 `advanced` 都不可用,且远端也不可用,系统应报错,而不是擅自把 `flash` 结果作为最终阅读结果返回。
@@ -167,11 +178,12 @@ MinerU 的 tier 策略同时遵守隐私优先和质量优先。
| 请求 | 默认执行路径 |
|------|--------------|
| watch 自动发现文件 | 本地 `flash` |
-| `mineru-kit api-server` 未传 `--tier` | 以 `standard` 作为服务默认 tier |
+| `mineru-kit api-server` 未传 `--tiers` | 硬件推荐开放集合;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 只入库和索引 |
-| 用户主动 parse,未指定 tier;HTTP API 传 JSON `null`;Python SDK 传 `None` | PDF/image 有能力发现上下文时按 `standard` -> `basic` 选择;OFD/EPUB/Office/HTML/MHTML/CSV/TSV 按 [ADR-0024](decisions/0024-file-type-tier-normalization.md) 与 [ADR-0028](decisions/0028-csv-structured-flash-parsing.md) 归一为 `flash`;其它 text 不进入解析 |
+| Doclib 用户主动 parse,未指定 tier | PDF/image 有能力发现上下文时按 `standard` -> `basic` 选择;OFD/EPUB/Office/HTML/MHTML/CSV/TSV 按 [ADR-0024](decisions/0024-file-type-tier-normalization.md) 与 [ADR-0028](decisions/0028-csv-structured-flash-parsing.md) 归一为 `flash`;其它 text 不进入解析 |
+| HTTP Tasks 省略 tier 或传 JSON `null`;HTTP SDK 传 `None`;file_parse 省略 tier | PDF/image 按 `standard` -> `basic` -> `flash` 选择;已支持的原生文档固定 flash;advanced 必须显式指定 |
| 用户主动指定 `--tier flash` | 本地 `flash` |
| 用户主动指定 `--tier basic` | 本地 basic;不可用时报错 |
| 用户主动指定 `--tier standard` | 本地 standard;显式 remote 时使用 `mineru.net/api` standard |
@@ -188,9 +200,9 @@ CLI、API 和 SDK 暴露 tier 时,应遵守同一语义:
- 公开 tier 取值包括 `flash`、`basic`、`standard`、`advanced`。
- CLI 不传 `--tier`、HTTP API 省略 `tier` 或传 JSON `null`、Python SDK 传 `None`,表示使用当前入口按文件类型定义的默认选择策略。
- 没有能力列表的启动服务或直接解析场景默认使用 `standard`。
-- PDF/image 有能力发现上下文时,默认选择策略按 `standard` -> `basic` 解析为非 `flash` 质量 tier。
-- PDF/image 默认阅读质量不能静默降级到 `flash`。
-- 当更高 tier 不可用时,应返回结构化错误和修复建议。
+- Doclib 主动解析 PDF/image 时按 `standard` -> `basic` 选择,默认阅读质量不能静默降级到 `flash`。
+- HTTP Tasks 及其客户端默认按 `standard` -> `basic` -> `flash` 选择,不自动选择 advanced。
+- 显式请求的 PDF/image tier 不可用时,应返回结构化错误,不自动升降档。
- 当用户显式选择 `flash` 时,可以返回 `flash` 内容。
- `--remote` 或等价字段必须是显式选择。
diff --git a/mineru/doclib/background/parse_server_health.py b/mineru/doclib/background/parse_server_health.py
index beff0ebd..90d6e288 100644
--- a/mineru/doclib/background/parse_server_health.py
+++ b/mineru/doclib/background/parse_server_health.py
@@ -17,7 +17,7 @@ import httpx
from ...config import LogConfig, ManagedParseServerConfig, get_config
from ...parser.api_client import should_trust_env_for_url
-from ...types import DEPLOYMENT_TIERS, TIERS, DeploymentTier, Tier
+from ...types import TIERS_BY_SERVER_TIER, DEPLOYMENT_TIERS, TIERS, DeploymentTier, Tier
from ...parser.process_control import ManagedProcessControl
from ...utils.stdio import utf8_subprocess_env
from ..config_defaults import CONFIG_DEFAULTS
@@ -59,20 +59,14 @@ async def get_managed_parse_server_tier(config_svc: "ConfigService") -> Deployme
def api_server_args_for_tier(tier: DeploymentTier, *, host: str, port: int) -> list[str]:
- """Return managed api-server process args for a doclib tier.
-
- Managed doclib startup uses ``--tier`` so the api-server resolves its own
- backend. Backend remains an api-server implementation detail and must not
- leak into runtime doclib parse requests.
- """
+ """把既有 Doclib 托管配置转换为等价的显式档位集合,继续排除 Flash。"""
return [
- "--tier",
- tier,
+ "--tiers",
+ ",".join(item for item in TIERS_BY_SERVER_TIER[tier] if item != "flash"),
"--host",
host,
"--port",
str(port),
- "--no-flash",
"--preload-models",
"--log-level",
"warning",
diff --git a/mineru/kit/commands/api_server.py b/mineru/kit/commands/api_server.py
index 2067d31b..aeda3e21 100644
--- a/mineru/kit/commands/api_server.py
+++ b/mineru/kit/commands/api_server.py
@@ -1,46 +1,22 @@
from __future__ import annotations
-from typing import cast
-
import click
import typer
from ...parser import api_server as parser_api_server
-from ...types import SERVER_TIERS, ServerTier
from ...utils.i18n import t
from ...utils.logger import configure_global_log_level
from ...utils.stdio import configure_standard_streams
from ..errors import exit_with_message
-def _normalize_tier_option(tier: str | None) -> ServerTier | None:
- """规范化 mineru-kit 传入的单个 server tier。"""
- if tier is None:
- return None
- if tier not in SERVER_TIERS:
- exit_with_message(
- "invalid_request",
- t(
- "Unsupported server tier '{tier}'. Supported server tiers: {tiers}",
- tier=tier,
- tiers=", ".join(SERVER_TIERS),
- ),
- "tier",
- )
- return cast(ServerTier, tier)
-
-
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")),
- tier: str | None = typer.Option(
- None,
- "--tier",
- help=t("Server capability tier: flash, basic, or standard"),
+ tiers: str = typer.Option(
+ "auto", "--tiers", help=t("Exact tiers: flash,basic,standard,advanced; or auto for hardware recommendations")
),
- no_flash: bool = typer.Option(False, "--no-flash", help=t("Disable Flash tier advertisement and execution")),
- no_advanced: bool = typer.Option(False, "--no-advanced", help=t("Disable Advanced tier advertisement and execution")),
retention_seconds: int | None = typer.Option(
None,
"--retention-seconds",
@@ -78,8 +54,6 @@ def api_server_cmd(
),
) -> None:
"""转发显式启动参数,启动 self-hosted MinerU 解析 API 服务。"""
- tier_value = _normalize_tier_option(tier)
- tier_args = ["--tier", tier_value] if tier_value is not None else []
vlm_args: list[str] = []
for option, value in (
("--vlm-server-url", vlm_server_url),
@@ -103,10 +77,9 @@ def api_server_cmd(
str(concurrency),
"--url-timeout",
str(url_timeout),
- *tier_args,
+ "--tiers",
+ tiers,
*vlm_args,
- *(["--no-flash"] if no_flash else []),
- *(["--no-advanced"] if no_advanced else []),
*(["--allow-http-source"] if allow_http_source else []),
*(["--upload-dir", upload_dir] if upload_dir else []),
*(["--disable-image-analysis"] if disable_image_analysis else []),
diff --git a/mineru/kit/file_parse/app.py b/mineru/kit/file_parse/app.py
index b5e0784c..2bacba07 100644
--- a/mineru/kit/file_parse/app.py
+++ b/mineru/kit/file_parse/app.py
@@ -23,6 +23,7 @@ from starlette.requests import ClientDisconnect
from starlette.types import ASGIApp, Receive, Scope, Send
from ...task_types import TASK_OUTPUT_FORMATS
+from ...types import TIERS
from .models import GatewayError, ParseOptions, Record
from .service import FileParseService
from .settings import FileParseSettings
@@ -96,6 +97,16 @@ def _request_schema() -> dict[str, Any]:
"wait_timeout": {"type": "integer", "minimum": 0, "maximum": 3600, "default": 3600},
}
)
+ properties["tier"] = {
+ "title": "Tier",
+ "type": "string",
+ "enum": list(TIERS),
+ "description": (
+ "Optional PDF/image tier. Omit this multipart field to let the server choose standard, basic, then flash; "
+ "advanced requires an explicit request. Explicit unsupported PDF/image tiers are rejected. "
+ "Supported native documents always use flash. Empty strings and the literal string 'null' are invalid."
+ ),
+ }
properties["output_formats"] = {
"type": "array",
"items": {"type": "string", "enum": list(TASK_OUTPUT_FORMATS)},
diff --git a/mineru/kit/file_parse/client.py b/mineru/kit/file_parse/client.py
index e4df7241..24ba7c4e 100644
--- a/mineru/kit/file_parse/client.py
+++ b/mineru/kit/file_parse/client.py
@@ -15,6 +15,7 @@ import httpx
from pydantic import ValidationError
from ...task_types import task_status_url
+from ...tasks.contracts import ErrorResponse
from .models import GatewayError, Record, RemoteCreatedTask, RemoteFile, RemoteTask
from .settings import FileParseSettings, origin
@@ -24,6 +25,17 @@ RETRYABLE_HTTP = frozenset({408, 429, 500, 502, 503, 504})
REDIRECTS = frozenset({301, 302, 303, 307, 308})
+def _is_task_creation_rejected(status: int, body: bytes) -> bool:
+ """仅识别 Tasks 明确未接单的档位错误,畸形或混入任务字段的响应仍视为未知。"""
+ if status != 503:
+ return False
+ try:
+ response = ErrorResponse.model_validate_json(body)
+ except ValidationError:
+ return False
+ return response.error.code == "quality_tier_unavailable"
+
+
async def file_chunks(path: Path) -> AsyncIterator[bytes]:
"""从磁盘分块读取上传内容,不在事件循环中执行大块文件 I/O。"""
with path.open("rb") as source:
@@ -178,7 +190,11 @@ class TaskClient:
body = await self._read_metadata(response)
if response.status_code not in ({202} if method == "POST" else {200}):
error = self._http_error(response.status_code, body)
- if method == "POST" and (response.status_code >= 500 or response.status_code == 408):
+ if (
+ method == "POST"
+ and (response.status_code >= 500 or response.status_code == 408)
+ and not _is_task_creation_rejected(response.status_code, body)
+ ):
raise GatewayError("submission_unknown", "Task creation outcome is unknown; not resubmitting")
raise error
if method == "POST":
diff --git a/mineru/kit/gradio/client.py b/mineru/kit/gradio/client.py
index a8acc7ae..e4a65097 100644
--- a/mineru/kit/gradio/client.py
+++ b/mineru/kit/gradio/client.py
@@ -20,7 +20,7 @@ from ...parser.api_client import ApiTaskStatus, MinerUApiParser, should_trust_en
from ...parser.base import ParseResult
from ...parser.page_range import normalize_page_range_input
from ...parser.process_control import ManagedProcessControl
-from ...types import SERVER_TIERS, TIERS, ServerTier, Tier
+from ...types import TIERS_BY_SERVER_TIER, SERVER_TIERS, TIERS, ServerTier, Tier
from ...utils.stdio import utf8_subprocess_env
from .status import (
STATUS_CHECKING_SERVER,
@@ -428,8 +428,8 @@ class ManagedLocalApiServer:
str(port),
"--upload-dir",
str(upload_dir),
- "--tier",
- self.tier,
+ "--tiers",
+ ",".join(TIERS_BY_SERVER_TIER[self.tier]),
"--concurrency",
str(self.concurrency),
"--log-level",
diff --git a/mineru/kit/router/tasks.py b/mineru/kit/router/tasks.py
index 25aa25af..b23f11d6 100644
--- a/mineru/kit/router/tasks.py
+++ b/mineru/kit/router/tasks.py
@@ -18,7 +18,7 @@ from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import ValidationError
-from ...filetypes import is_flash_only_parse_extension
+from ...filetypes import batch_effective_parse_tier, is_flash_only_parse_extension
from ...tasks.contracts import (
CancelTaskResponse,
CreateTaskResponse,
@@ -32,7 +32,6 @@ from ...tasks.contracts import (
from ...tasks.errors import ApiServerError, raise_api_error
from ...tasks.execution import TaskExecution, TaskInputMetadata, TaskUpload
from ...tasks.service import TERMINAL_TASK_STATUSES, file_chunks, resolve_task_tier
-from ...types import select_default_quality_tier
from ...utils.async_utils import drain_future
from .proxy import (
RouterProxyError,
@@ -290,11 +289,11 @@ class RouterTaskBackend:
async def validate(self, options: UploadTaskOptions, inputs: list[TaskFileInput]) -> None:
"""能力预检不推进轮询游标,也不为尚未上传的任务预占 worker。"""
tiers = self.pool.available_tiers()
- options.tier = resolve_task_tier(options, inputs, tiers, select_default_quality_tier(tiers))
+ options.tier = resolve_task_tier(options, inputs, tiers)
checked_workers: set[str] = set()
for item in inputs:
lightweight = is_flash_only_parse_extension(item.file_name)
- selection_tier = "flash" if lightweight else options.tier
+ selection_tier = batch_effective_parse_tier(options.tier, item.file_name)
candidates = self.pool.capable_workers(
tier=selection_tier,
required_sources={"url" if item.url is not None else "upload"},
@@ -387,8 +386,10 @@ class RouterTaskBackend:
self, execution_id: str, options: UploadTaskOptions, item: TaskFileItem, upload: TaskUpload | None
) -> TaskExecution:
"""为单文件预占 worker,并把公开文件身份与下游身份一一关联。"""
+ if options.tier is None:
+ raise ValueError("Task tier must be resolved before execution")
lightweight = is_flash_only_parse_extension(item.file_name)
- tier = "flash" if lightweight else options.tier
+ tier = batch_effective_parse_tier(options.tier, item.file_name)
reservation = self.pool.reserve_job(
tier=tier,
required_sources={"url" if item.url is not None else "upload"},
@@ -417,7 +418,7 @@ class RouterTaskBackend:
request=self.request,
json_body={
"files": [worker_input],
- "tier": options.tier,
+ "tier": tier,
"ocr_mode": options.ocr_mode,
"output_formats": options.output_formats,
},
diff --git a/mineru/kit/router/workers.py b/mineru/kit/router/workers.py
index 00717b42..36f7d13e 100644
--- a/mineru/kit/router/workers.py
+++ b/mineru/kit/router/workers.py
@@ -21,7 +21,7 @@ from loguru import logger
from ...model.runtime.device import get_device
from ...parser.process_control import ManagedProcessControl
-from ...types import SERVER_TIERS, ServerTier, Tier
+from ...types import TIERS_BY_SERVER_TIER, SERVER_TIERS, ServerTier, Tier
from ...utils.stdio import utf8_subprocess_env
from ...utils.retention import resolve_retention_seconds
@@ -205,8 +205,8 @@ class ManagedLocalWorker:
str(port),
"--upload-dir",
str(upload_dir),
- "--tier",
- self.settings.worker_tier,
+ "--tiers",
+ ",".join(TIERS_BY_SERVER_TIER[self.settings.worker_tier]),
"--concurrency",
str(self.settings.worker_concurrency),
"--retention-seconds",
diff --git a/mineru/model/runtime/onnx_calibration.py b/mineru/model/runtime/onnx_calibration.py
index 66e863bb..4bc826b5 100644
--- a/mineru/model/runtime/onnx_calibration.py
+++ b/mineru/model/runtime/onnx_calibration.py
@@ -292,6 +292,9 @@ def run_calibration(
threshold: float | None = None,
) -> dict[str, Any]:
"""Run a fresh, hidden worker and kill it on timeout; failed measurements are never decisions."""
+ from .onnx_calibration_cache import invalidate_calibration_record, save_calibration_record
+
+ invalidate_calibration_record()
# Build/hash the derived graph outside the bounded inference worker, like model download.
threshold = _threshold(adapter, threshold)
prepare_rec_model(model_path)
@@ -338,6 +341,8 @@ def run_calibration(
raise ValueError(f"Calibration worker did not confirm valid {provider} results")
_validate_sampling(result)
result["worker_wall_s"] = time.perf_counter() - started
+ # 保存实际校准证据供下次服务启动读取,不将手动 cpu/gpu 偏好视为性能结论。
+ save_calibration_record(adapter, result)
return result
diff --git a/mineru/model/runtime/onnx_calibration_cache.py b/mineru/model/runtime/onnx_calibration_cache.py
new file mode 100644
index 00000000..28e91293
--- /dev/null
+++ b/mineru/model/runtime/onnx_calibration_cache.py
@@ -0,0 +1,142 @@
+"""保存可验证的 OCR 校准证据,供服务启动时只读推荐档位。"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from importlib.metadata import PackageNotFoundError, version
+import json
+import os
+from pathlib import Path
+import platform
+import tempfile
+from typing import Any, Literal
+
+from loguru import logger
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from .cpu_threads import effective_cpu_count
+from .webgpu import WebGPUDevice
+from .windows_gpu import GpuAdapter
+
+
+class CalibrationRecord(BaseModel):
+ """区分真实校准结果与手动设备偏好,并限制损坏记录的读取范围。"""
+
+ model_config = ConfigDict(extra="forbid", strict=True, allow_inf_nan=False)
+
+ schema_version: Literal[1] = 1
+ fingerprint: dict[str, Any]
+ cpu_elapsed: float = Field(gt=0)
+ gpu_elapsed: float = Field(gt=0)
+ threshold: float = Field(gt=0, lt=1)
+ outputs_match: Literal[True]
+ decision_valid: bool
+ model_sha256: str
+
+
+def calibration_record_path() -> Path:
+ """记录随当前配置文件隔离,读取时不创建目录或锁文件。"""
+ from ...config import get_config_file_path
+
+ return Path(f"{get_config_file_path()}.onnx-calibration.json")
+
+
+def _runtime_version(distribution: str) -> str | None:
+ """仅查询安装元数据,不导入或初始化推理运行时。"""
+ try:
+ return version(distribution)
+ except PackageNotFoundError:
+ return None
+
+
+def _threads(configured: int, variable: str, default: int) -> int:
+ """镜像 ONNX 校准的线程优先级,避免读取记录时创建 ORT 会话。"""
+ if configured > 0:
+ return configured
+ try:
+ value = int(os.getenv(variable, "0"))
+ except ValueError:
+ value = 0
+ return value if value > 0 else default
+
+
+def _fingerprint(
+ adapter: GpuAdapter | WebGPUDevice, intra_op_num_threads: int = 0, inter_op_num_threads: int = 0
+) -> dict[str, Any]:
+ """绑定物理设备、后端版本及 CPU 配置;忽略进程内设备序号和排序。"""
+ identity = asdict(adapter)
+ identity.pop("index", None)
+ identity.pop("preference", None)
+ backend = "webgpu" if isinstance(adapter, WebGPUDevice) else "dml"
+ # JSON 往返统一 metadata 等元组,确保读写指纹完全一致。
+ return json.loads(
+ json.dumps(
+ {
+ "adapter": identity,
+ "backend": backend,
+ "runtime": _runtime_version("onnxruntime" if backend == "webgpu" else "onnxruntime-directml"),
+ "ep": _runtime_version("onnxruntime-ep-webgpu") if backend == "webgpu" else None,
+ "system": platform.system(),
+ "release": platform.release(),
+ "machine": platform.machine(),
+ "processor": platform.processor(),
+ "cpu_count": effective_cpu_count(),
+ "intra_threads": _threads(intra_op_num_threads, "MINERU_INTRA_OP_NUM_THREADS", 4),
+ "inter_threads": _threads(inter_op_num_threads, "MINERU_INTER_OP_NUM_THREADS", 1),
+ }
+ )
+ )
+
+
+def save_calibration_record(adapter: GpuAdapter | WebGPUDevice, result: dict[str, Any]) -> None:
+ """只保存已由校准 worker 验证的结果,写入失败不改变实际设备选择。"""
+ temporary: str | None = None
+ try:
+ record = CalibrationRecord(
+ fingerprint=_fingerprint(adapter, result["intra_threads"], result["inter_threads"]),
+ cpu_elapsed=result["cpu_elapsed"],
+ gpu_elapsed=result["gpu_elapsed"],
+ threshold=result["decision_threshold"],
+ outputs_match=result["outputs_match"],
+ decision_valid=result["decision_valid"],
+ model_sha256=result["model_sha256"],
+ )
+ path = calibration_record_path()
+ path.parent.mkdir(parents=True, exist_ok=True)
+ descriptor, temporary = tempfile.mkstemp(prefix=".onnx-calibration.", dir=path.parent)
+ with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+ stream.write(record.model_dump_json())
+ os.replace(temporary, path)
+ except (OSError, ValueError, KeyError, TypeError) as error:
+ logger.warning("Cannot save ONNX calibration evidence: {}", error)
+ finally:
+ if temporary is not None:
+ try:
+ Path(temporary).unlink(missing_ok=True)
+ except OSError as error:
+ logger.warning("Cannot remove temporary ONNX calibration evidence: {}", error)
+
+
+def invalidate_calibration_record() -> None:
+ """新一轮实际校准开始时撤销旧证据,失败结果不能继续沿用旧的 GPU 胜出结论。"""
+ try:
+ calibration_record_path().unlink(missing_ok=True)
+ except OSError as error:
+ logger.warning("Cannot invalidate ONNX calibration evidence: {}", error)
+
+
+def calibrated_gpu_is_faster(adapter: GpuAdapter | WebGPUDevice, threshold: float) -> bool:
+ """仅接受当前设备和运行环境匹配、输出一致且稳定的真实校准记录。"""
+ try:
+ record = CalibrationRecord.model_validate_json(calibration_record_path().read_text(encoding="utf-8"))
+ return (
+ record.fingerprint == _fingerprint(adapter)
+ and record.threshold == threshold
+ and record.decision_valid
+ and record.gpu_elapsed / record.cpu_elapsed <= threshold
+ )
+ except (OSError, ValueError, TypeError, ValidationError):
+ return False
+
+
+__all__ = ["calibrated_gpu_is_faster", "calibration_record_path", "invalidate_calibration_record", "save_calibration_record"]
diff --git a/mineru/model/runtime/tier_recommendation.py b/mineru/model/runtime/tier_recommendation.py
new file mode 100644
index 00000000..6a50c8ff
--- /dev/null
+++ b/mineru/model/runtime/tier_recommendation.py
@@ -0,0 +1,116 @@
+"""通过静态设备事实与已有 OCR 校准,推荐 API 服务开放的档位集合。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+import sys
+
+from loguru import logger
+
+from ...types import TIERS, Tier
+from .cpu_threads import effective_cpu_count
+
+
+@dataclass(frozen=True)
+class TierHardware:
+ """与设备探测隔离的推荐依据,便于完整覆盖各类硬件组合。"""
+
+ cpu_count: int
+ advanced_gpu: bool = False
+ reason: str = "cpu"
+
+
+def tiers_for_hardware(hardware: TierHardware) -> frozenset[Tier]:
+ """按已确定的工程阈值计算集合,达标 GPU 同时开放所有较低档位。"""
+ if hardware.advanced_gpu:
+ return frozenset(TIERS)
+ if hardware.cpu_count >= 4:
+ return frozenset(("flash", "basic", "standard"))
+ return frozenset(("flash",))
+
+
+def _apple_metal_available() -> bool:
+ """仅在 Apple Silicon 探测时惰性查询 Metal,不加载推理模型。"""
+ from .platform import is_apple_silicon_cpu
+
+ if not is_apple_silicon_cpu():
+ return False
+ import torch
+
+ return torch.backends.mps.is_available()
+
+
+def _advanced_gpu_reason() -> str | None:
+ """复用可见设备及兼容策略,集显只读取证据而不触发自动校准。"""
+ backend = os.getenv("MINERU_LLAMA_CPP_BACKEND", "auto")
+ if backend == "cpu":
+ return None
+ if sys.platform == "darwin":
+ # ggml 的 Metal GPU 类型不能区分独显与集显,只采用已确认的 Apple Silicon 规则。
+ return "apple_silicon_metal" if backend in {"auto", "metal"} and _apple_metal_available() else None
+ if sys.platform not in {"linux", "win32"}:
+ return None
+
+ from .llama_device import discover_llama_devices
+
+ devices = tuple(d for d in discover_llama_devices() if backend == "auto" or d.backend == backend)
+ if any(not device.integrated for device in devices):
+ return "discrete_gpu"
+ if not devices:
+ return None
+
+ from .onnx_calibration_cache import calibrated_gpu_is_faster
+ from .onnx_device import ONNX_GPU_TIME_RATIO_THRESHOLDS
+
+ if sys.platform == "win32":
+ from .windows_gpu import discover_gpus, preferred_gpu
+
+ adapter = preferred_gpu(discover_gpus())
+ threshold = ONNX_GPU_TIME_RATIO_THRESHOLDS["dml"]
+ else:
+ from .webgpu import discover_webgpu_devices, select_webgpu_device
+
+ adapter = select_webgpu_device(discover_webgpu_devices())
+ threshold = ONNX_GPU_TIME_RATIO_THRESHOLDS["webgpu"]
+ if adapter is None or threshold is None:
+ return None
+ matches = [d for d in devices if (d.vendor_id, d.device_id) == (adapter.vendor_id, adapter.device_id)]
+ if len(matches) != 1:
+ logger.info("GPU tier recommendation uses CPU rules: OCR adapter identity is not uniquely matched")
+ return None
+ if calibrated_gpu_is_faster(adapter, threshold):
+ return "ocr_calibrated_gpu"
+ logger.info("GPU tier recommendation uses CPU rules: no matching valid OCR evidence of a faster GPU")
+ return None
+
+
+def detect_tier_hardware() -> TierHardware:
+ """探测失败时保守使用 CPU 条件,推荐过程不下载模型或保存配置。"""
+ try:
+ count = effective_cpu_count()
+ except OSError as error:
+ logger.warning("CPU availability discovery failed: {}", error)
+ count = 1
+ try:
+ reason = _advanced_gpu_reason()
+ except Exception as error:
+ logger.warning("GPU tier recommendation unavailable; using CPU rules: {}", error)
+ return TierHardware(count, reason="gpu_discovery_unavailable")
+ return TierHardware(count, bool(reason), reason or "cpu")
+
+
+def recommend_tiers() -> frozenset[Tier]:
+ """每次调用读取当前硬件事实;API 服务只在启动阶段调用一次。"""
+ hardware = detect_tier_hardware()
+ tiers = tiers_for_hardware(hardware)
+ logger.info(
+ "Recommended API tiers: {} (available CPUs: {}, reason: {})",
+ ",".join(tier for tier in TIERS if tier in tiers),
+ hardware.cpu_count,
+ hardware.reason,
+ )
+ return tiers
+
+
+__all__ = ["TierHardware", "detect_tier_hardware", "recommend_tiers", "tiers_for_hardware"]
diff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.py
index 86bbe3dd..8cfd24c3 100644
--- a/mineru/parser/api_server.py
+++ b/mineru/parser/api_server.py
@@ -16,6 +16,7 @@ import shutil
import tempfile
import threading
import time
+from collections.abc import Collection
from contextlib import asynccontextmanager
from copy import deepcopy
from dataclasses import dataclass, field
@@ -49,7 +50,7 @@ from ..filetypes import (
file_type_for_extension,
is_flash_only_parse_extension,
)
-from ..types import SERVER_TIERS, TIERS_BY_SERVER_TIER, DeploymentTier, PageInfo, ServerTier, Tier, select_default_quality_tier
+from ..types import DeploymentTier, PageInfo, Tier
from ..utils.async_utils import drain_future, run_sync
from ..model.runtime.ownership import RuntimeOwner, runtime_owner
from ..model.vlm.errors import is_fatal_engine_error
@@ -68,10 +69,10 @@ 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 .tier import (
ParserRuntimeOptions,
TierDependencyError,
- effort_for_tier,
ensure_tier_runtime_dependencies,
runtime_options_for_tier,
)
@@ -82,7 +83,6 @@ from ..tasks.execution import TaskExecution, TaskInputMetadata, execution_timest
from ..tasks.http import build_task_router
from ..tasks.service import TaskStore
-_DEFAULT_API_SERVER_TIER: ServerTier = "standard"
_MAX_URL_BYTES_DEFAULT = 209715200
logger = logging.getLogger("mineru.parser.api_server")
@@ -1653,30 +1653,8 @@ def _build_v1_router() -> APIRouter:
return _router
-def _normalize_server_tier(tier: str | None) -> ServerTier:
- """规范化 API server 的单个启动能力档位。"""
- if tier is not None and not isinstance(tier, str):
- raise ValueError("Server tier must be a single value: flash, basic, or standard")
- normalized = (tier or _DEFAULT_API_SERVER_TIER).strip().lower()
- if normalized in SERVER_TIERS:
- return normalized # type: ignore[return-value]
- supported = ", ".join(SERVER_TIERS)
- raise ValueError(f"Unsupported server tier '{tier}'. Supported server tiers: {supported}")
-
-
-def _request_tiers_for_server_tier(tier: ServerTier, *, no_flash: bool, no_advanced: bool = False) -> list[Tier]:
- """将单个启动档位展开为该进程可接受的请求 tier。"""
- if tier == "flash" and no_flash:
- raise ValueError("--tier flash cannot be combined with --no-flash")
- return [
- request_tier
- for request_tier in TIERS_BY_SERVER_TIER[tier]
- if (not no_flash or request_tier != "flash") and (not no_advanced or request_tier != "advanced")
- ]
-
-
-def _runtime_options_for_server_tiers(tiers: list[Tier]) -> dict[Tier, ParserRuntimeOptions]:
- """为展开后的请求 tier 生成独立 runtime,API server 只允许 tier 决定 backend/effort。"""
+def _runtime_options_for_server_tiers(tiers: Collection[Tier]) -> dict[Tier, ParserRuntimeOptions]:
+ """为明确开放的请求 tier 生成独立 runtime,执行 effort 仍由 tier 决定。"""
return {tier: runtime_options_for_tier(tier) for tier in tiers}
@@ -1716,14 +1694,14 @@ def _tiers_for_server_tier(tier: Tier) -> list[TierInfoData]:
]
-def _tiers_for_server_tiers(tiers: list[Tier]) -> list[TierInfoData]:
- """展开后的请求 tier metadata。"""
+def _tiers_for_server_tiers(tiers: Collection[Tier]) -> list[TierInfoData]:
+ """按精确集合发布请求 tier metadata。"""
return [tier_info for tier in tiers for tier_info in _tiers_for_server_tier(tier)]
-def _preflight_tier_dependencies(tier: ServerTier, vlm_config: VlmConfig | None = None) -> None:
+def _preflight_tier_dependencies(tier: DeploymentTier | None, vlm_config: VlmConfig | None = None) -> None:
"""远程 VLM 仅预检本地 Hybrid 依赖,避免要求安装本地 VLM serving 引擎。"""
- if tier == "flash":
+ if tier is None:
return
settings = vlm_config if vlm_config is not None else get_config().model.vlm
if tier == "standard":
@@ -1823,9 +1801,7 @@ def _start_force_exit_timer(
def create_app(
*,
upload_dir: str = "",
- tier: ServerTier | None = None,
- no_flash: bool = False,
- no_advanced: bool = False,
+ tiers: Collection[Tier] | None = None,
concurrency: int = 1,
url_timeout: int = 60,
max_url_bytes: int = _MAX_URL_BYTES_DEFAULT,
@@ -1842,13 +1818,9 @@ def create_app(
----------
upload_dir:
Directory for uploaded files and parse artifacts.
- tier:
- Server capability ceiling. ``"flash"`` exposes Flash, ``"basic"``
- exposes Flash and Basic, and ``"standard"`` exposes all request tiers.
- no_flash:
- Disable Flash advertisement and execution. Invalid with ``tier="flash"``.
- no_advanced:
- Disable Advanced advertisement and execution.
+ tiers:
+ Exact non-empty set of advertised request tiers. ``None`` recommends
+ tiers from available hardware and existing OCR calibration evidence.
concurrency:
Maximum concurrent parse jobs (default 1).
url_timeout:
@@ -1870,13 +1842,12 @@ def create_app(
"""
retention_seconds = resolve_retention_seconds(retention_seconds)
upload_dir = upload_dir or ""
- tier = _normalize_server_tier(tier)
- server_tiers = _request_tiers_for_server_tier(tier, no_flash=no_flash, no_advanced=no_advanced)
+ server_tiers = resolve_server_tiers(tiers)
+ model_tier = model_tier_for_server_tiers(server_tiers)
tier_runtime_options = _runtime_options_for_server_tiers(server_tiers)
- default_tier = select_default_quality_tier(tier_runtime_options)
- effort = effort_for_tier(tier)
+ default_tier = next((tier for tier in ("standard", "basic", "flash") if tier in server_tiers), None)
vlm_config = (vlm_config if vlm_config is not None else get_config().model.vlm).model_copy(deep=True)
- _preflight_tier_dependencies(tier, vlm_config)
+ _preflight_tier_dependencies(model_tier, vlm_config)
_api_key: str | None = api_key or None
_upload_dir = pathlib.Path(upload_dir) if upload_dir else pathlib.Path(tempfile.mkdtemp(prefix="mineru_"))
_upload_dir.mkdir(parents=True, exist_ok=True)
@@ -1885,16 +1856,15 @@ def create_app(
_tiers = _tiers_for_server_tiers(server_tiers)
_model_registered_at = int(time.time())
- _preload_tier: DeploymentTier | None = None
- if preload_models and tier != "flash":
- _preload_tier = tier
+ _preload_tier = model_tier if preload_models else None
@asynccontextmanager
async def _lifespan(application: FastAPI) -> AsyncIterator[None]:
application.state.upload_dir = _upload_dir
- application.state.tier = tier
+ application.state.server_tiers = server_tiers
+ application.state.model_tier = model_tier
application.state.default_tier = default_tier
- application.state.flash_enabled = not no_flash
+ application.state.flash_enabled = "flash" in server_tiers
application.state.tier_runtime_options = tier_runtime_options
application.state.model_ids = [_VIRTUAL_MODEL_ID]
application.state.model_registered_at = _model_registered_at
@@ -1904,7 +1874,6 @@ def create_app(
application.state.max_url_bytes = max_url_bytes
application.state.allow_http_source = allow_http_source
application.state.api_key = _api_key
- application.state.effort = effort
application.state.image_analysis = image_analysis
application.state.preload_models = preload_models
application.state.vlm_config = vlm_config
@@ -2021,9 +1990,10 @@ def create_app(
return get_swagger_ui_oauth2_redirect_html()
application.state.upload_dir = _upload_dir
- application.state.tier = tier
+ application.state.server_tiers = server_tiers
+ application.state.model_tier = model_tier
application.state.default_tier = default_tier
- application.state.flash_enabled = not no_flash
+ application.state.flash_enabled = "flash" in server_tiers
application.state.tier_runtime_options = tier_runtime_options
application.state.model_ids = [_VIRTUAL_MODEL_ID]
application.state.model_registered_at = _model_registered_at
@@ -2033,7 +2003,6 @@ def create_app(
application.state.max_url_bytes = max_url_bytes
application.state.allow_http_source = allow_http_source
application.state.api_key = _api_key
- application.state.effort = effort
application.state.image_analysis = image_analysis
application.state.preload_models = preload_models
application.state.vlm_config = vlm_config
@@ -2151,23 +2120,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(
- "--tier",
- default=None,
- type=click.Choice(list(SERVER_TIERS)),
- help=(
- "Server capability tier: flash, basic, or standard. "
- "Defaults to standard, which accepts flash, basic, standard, and advanced requests."
- ),
-)
- "--no-flash",
- is_flag=True,
- help="Disable Flash tier advertisement and execution.",
-)
- "--no-advanced",
- is_flag=True,
- help="Disable Advanced tier advertisement and execution.",
+ "--tiers",
+ default="auto",
+ type=str,
+ help="Exact comma-separated tiers (flash,basic,standard,advanced), or auto for hardware recommendations (default).",
)
@click.option(
"--concurrency",
@@ -2221,9 +2177,7 @@ def main(
host: str,
port: int,
upload_dir: str,
- tier: ServerTier | None,
- no_flash: bool,
- no_advanced: bool,
+ tiers: str,
concurrency: int,
url_timeout: int,
max_url_bytes: int,
@@ -2277,9 +2231,7 @@ def main(
)
application = create_app(
upload_dir=upload_dir,
- tier=tier,
- no_flash=no_flash,
- no_advanced=no_advanced,
+ tiers=parse_server_tiers(tiers),
concurrency=concurrency,
url_timeout=url_timeout,
max_url_bytes=max_url_bytes,
diff --git a/mineru/parser/server_tiers.py b/mineru/parser/server_tiers.py
new file mode 100644
index 00000000..478c5386
--- /dev/null
+++ b/mineru/parser/server_tiers.py
@@ -0,0 +1,45 @@
+"""API 服务的精确档位集合、CLI 参数解析与共享模型配置。"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+
+from ..types import TIERS, DeploymentTier, Tier, validate_tier
+
+
+def normalize_server_tiers(tiers: Collection[Tier]) -> tuple[Tier, ...]:
+ """校验非空显式集合,去重并按公共档位顺序稳定输出。"""
+ if not isinstance(tiers, Collection) or isinstance(tiers, (str, bytes)) or not tiers:
+ raise ValueError("Server tiers must be a non-empty collection of flash, basic, standard, advanced")
+ if any(not isinstance(tier, str) for tier in tiers):
+ raise ValueError("Server tiers must contain tier names")
+ selected = {validate_tier(tier) for tier in tiers}
+ return tuple(tier for tier in TIERS if tier in selected)
+
+
+def parse_server_tiers(value: str) -> tuple[Tier, ...] | None:
+ """解析 auto 或逗号分隔列表;空项及 auto 混用均明确报错。"""
+ if value.strip().lower() == "auto":
+ return None
+ return normalize_server_tiers(value.split(",")) # type: ignore[arg-type]
+
+
+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()
+ return normalize_server_tiers(tiers)
+
+
+def model_tier_for_server_tiers(tiers: Collection[Tier]) -> DeploymentTier | None:
+ """合并共享模型需求;advanced 复用 Standard 配置但不增加发布档位。"""
+ if "standard" in tiers or "advanced" in tiers:
+ return "standard"
+ if "basic" in tiers:
+ return "basic"
+ return None
+
+
+__all__ = ["model_tier_for_server_tiers", "normalize_server_tiers", "parse_server_tiers", "resolve_server_tiers"]
diff --git a/mineru/parser/task_backend.py b/mineru/parser/task_backend.py
index 53b41c03..8fa75cfe 100644
--- a/mineru/parser/task_backend.py
+++ b/mineru/parser/task_backend.py
@@ -7,6 +7,7 @@ from dataclasses import replace
from fastapi import Request
+from ..filetypes import batch_effective_parse_tier
from ..tasks.contracts import TaskFileInput, TaskFileItem, UploadTaskOptions
from ..tasks.errors import invalid_task_request
from ..tasks.execution import TaskExecution, TaskUpload
@@ -71,7 +72,7 @@ class ApiTaskBackend:
)
except ValueError as exc:
invalid_task_request(str(exc), param=f"files.{index}.url")
- options.tier = resolve_task_tier(options, inputs, set(state.tier_runtime_options), state.default_tier)
+ options.tier = resolve_task_tier(options, inputs, set(state.tier_runtime_options))
async def find_upload(self, sha256sum: str, filename: str) -> TaskUpload | None:
"""原子查找并取得缓存租约,准备阶段不会因原文件视图到期丢失字节。"""
@@ -112,6 +113,9 @@ class ApiTaskBackend:
self, execution_id: str, options: UploadTaskOptions, item: TaskFileItem, upload: TaskUpload | None
) -> TaskExecution:
"""提交唯一文件并保留公开结果身份,源文件视图只用于内部读取和租约。"""
+ if options.tier is None:
+ raise ValueError("Task tier must be resolved before execution")
+ tier = batch_effective_parse_tier(options.tier, item.file_name)
if upload is not None:
await run_sync(
self.files.register_source_file, upload.filename, upload.path, upload.sha256sum, upload.file_id, keep_alive=True
@@ -129,7 +133,7 @@ class ApiTaskBackend:
bytes=item.bytes,
sha256sum=item.sha256sum,
page_range=item.page_range or None,
- tier=options.tier,
+ tier=tier,
ocr_mode=options.ocr_mode,
output_formats=options.output_formats,
)
diff --git a/mineru/tasks/contracts.py b/mineru/tasks/contracts.py
index 506fd7cd..2306e4b5 100644
--- a/mineru/tasks/contracts.py
+++ b/mineru/tasks/contracts.py
@@ -80,7 +80,14 @@ class UploadTaskOptions(BaseModel):
"""解析选项仅来自 JSON 主体,文件元数据独立保存在 files 中。"""
model_config = ConfigDict(extra="forbid")
- tier: Tier | None = None
+ tier: Tier | None = Field(
+ default=None,
+ description=(
+ "PDF/image tier only. Omitted or null selects the highest supported tier in the order "
+ "standard, basic, flash; advanced requires an explicit request. Explicit unsupported tiers are rejected. "
+ "Supported native document formats always use flash, ignoring any valid tier value."
+ ),
+ )
ocr_mode: Literal["auto", "txt", "ocr"] = "auto"
page_range: str = ""
output_formats: list[TaskOutputFormat] = Field(default_factory=lambda: ["default"], min_length=1)
diff --git a/mineru/tasks/service.py b/mineru/tasks/service.py
index 61b30ee5..866721ca 100644
--- a/mineru/tasks/service.py
+++ b/mineru/tasks/service.py
@@ -23,24 +23,29 @@ from .execution import TaskBackend, TaskExecution, TaskUpload, execution_timesta
TASK_UPLOAD_TTL = 3600
TERMINAL_TASK_STATUSES = frozenset({"completed", "partial", "failed", "canceled"})
+_DEFAULT_TASK_TIER_SELECTION_ORDER: tuple[Tier, ...] = ("standard", "basic", "flash")
logger = logging.getLogger(__name__)
-def resolve_task_tier(options: UploadTaskOptions, inputs: list[TaskFileInput], tiers: set[Tier], default: Tier | None) -> Tier:
- """按现有轻量格式回退规则解析 tier,不触发 worker 选择或模型执行。"""
+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")
- tier = options.tier or default
- if tier is None and all(lightweight) and "flash" in tiers:
- tier = "flash"
- if tier is None:
- invalid_task_request(
- "No default quality tier is available; pass tier explicitly", code="quality_tier_unavailable", status_code=503
- )
- if tier not in tiers and not (all(lightweight) and "flash" in tiers):
- invalid_task_request(f"Tier '{tier}' is not available", param="tier")
- return tier
+ if all(lightweight):
+ return "flash"
+ if options.tier is not None:
+ if options.tier not in tiers:
+ invalid_task_request(f"Tier '{options.tier}' is not available", param="tier")
+ return options.tier
+ for tier in _DEFAULT_TASK_TIER_SELECTION_ORDER:
+ if tier in tiers:
+ return tier
+ invalid_task_request(
+ "No default tier is available (standard, basic, or flash); pass tier explicitly",
+ code="quality_tier_unavailable",
+ status_code=503,
+ )
async def file_chunks(path: Path) -> AsyncIterator[bytes]:
diff --git a/tests/unittest/test_api_model_ownership.py b/tests/unittest/test_api_model_ownership.py
index e17be767..8a4c7fa7 100644
--- a/tests/unittest/test_api_model_ownership.py
+++ b/tests/unittest/test_api_model_ownership.py
@@ -93,8 +93,8 @@ def test_api_apps_share_native_sessions_until_last_owner_closes(tmp_path: Path,
monkeypatch.setattr(hybrid, "atom_model_init", create_session)
monkeypatch.setattr(api_server, "parse_async", parse_with_shared_models)
- with TestClient(api_server.create_app(upload_dir=str(tmp_path / "second"), tier="flash")) as second:
- with TestClient(api_server.create_app(upload_dir=str(tmp_path / "first"), tier="flash")) as first:
+ with TestClient(api_server.create_app(upload_dir=str(tmp_path / "second"), tiers=("flash",))) as second:
+ with TestClient(api_server.create_app(upload_dir=str(tmp_path / "first"), tiers=("flash",))) as first:
_parse_task(first, b"<p>first</p>")
_parse_task(second, b"<p>second</p>")
assert len(sessions) == 3 # OCR、Layout 与惰性 MFR 只创建一份。
@@ -105,7 +105,7 @@ def test_api_apps_share_native_sessions_until_last_owner_closes(tmp_path: Path,
gc.collect()
assert all(reference() is None for reference in sessions)
- with TestClient(api_server.create_app(upload_dir=str(tmp_path / "replacement"), tier="flash")) as replacement:
+ with TestClient(api_server.create_app(upload_dir=str(tmp_path / "replacement"), tiers=("flash",))) as replacement:
_parse_task(replacement, b"<p>replacement</p>")
assert len(sessions) == 6
gc.collect()
diff --git a/tests/unittest/test_api_offline_docs.py b/tests/unittest/test_api_offline_docs.py
index 041e66e2..d38426b5 100644
--- a/tests/unittest/test_api_offline_docs.py
+++ b/tests/unittest/test_api_offline_docs.py
@@ -12,7 +12,7 @@ from mineru.parser import api_server
def test_offline_docs_resources_and_proxy_paths(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, root: str) -> None:
"""断言 Swagger/ReDoc 全部使用本地资源,授权回调遵守代理前缀。"""
monkeypatch.setattr(api_server, "_preflight_tier_dependencies", lambda *args: None)
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash", api_key="secret")
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",), api_key="secret")
with TestClient(app, root_path=root) as client:
for page in ("/docs", "/redoc"):
response = client.get(root + page)
@@ -43,7 +43,7 @@ def test_disabled_docs_mount_no_resources(tmp_path: Path, monkeypatch: pytest.Mo
"""关闭文档时不挂载静态资源,三个既有文档入口全部不可访问。"""
monkeypatch.setattr(api_server, "_preflight_tier_dependencies", lambda *args: None)
monkeypatch.setenv("MINERU_API_ENABLE_FASTAPI_DOCS", "false")
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",))
with TestClient(app) as client:
for path in ("/docs", "/redoc", "/openapi.json", "/docs/assets/vendor/favicon.png"):
assert client.get(path).status_code == 404
diff --git a/tests/unittest/test_doclib_cache_semantics.py b/tests/unittest/test_doclib_cache_semantics.py
index 327b4832..b5e682a3 100644
--- a/tests/unittest/test_doclib_cache_semantics.py
+++ b/tests/unittest/test_doclib_cache_semantics.py
@@ -336,25 +336,23 @@ def test_load_pages_from_done_batches_keeps_newest_page_idx(tmp_path: Path) -> N
def test_managed_api_server_args_use_tier_and_selected_port_for_process_start() -> None:
assert api_server_args_for_tier("standard", host="127.0.0.1", port=16580) == [
- "--tier",
- "standard",
+ "--tiers",
+ "basic,standard,advanced",
"--host",
"127.0.0.1",
"--port",
"16580",
- "--no-flash",
"--preload-models",
"--log-level",
"warning",
]
assert api_server_args_for_tier("basic", host="127.0.0.2", port=16581) == [
- "--tier",
+ "--tiers",
"basic",
"--host",
"127.0.0.2",
"--port",
"16581",
- "--no-flash",
"--preload-models",
"--log-level",
"warning",
@@ -620,8 +618,8 @@ def test_start_managed_parse_server_selects_port_and_writes_logs(monkeypatch: py
def _popen(*args: Any, **kwargs: Any) -> _Proc:
popen_calls.append({"args": args, "kwargs": kwargs})
cmd = args[0]
- assert "--tier" in cmd
- assert cmd[cmd.index("--tier") + 1] == "standard"
+ assert "--tiers" in cmd
+ assert cmd[cmd.index("--tiers") + 1] == "basic,standard,advanced"
assert "--host" in cmd
assert cmd[cmd.index("--host") + 1] == "127.0.0.2"
assert "--port" in cmd
@@ -806,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 "--tier" in cmd
- assert cmd[cmd.index("--tier") + 1] == "standard"
+ assert "--tiers" in cmd
+ assert cmd[cmd.index("--tiers") + 1] == "basic,standard,advanced"
events.append("start")
return _Proc()
diff --git a/tests/unittest/test_engine_dead_lifecycle.py b/tests/unittest/test_engine_dead_lifecycle.py
index 8b423026..21d84fe3 100644
--- a/tests/unittest/test_engine_dead_lifecycle.py
+++ b/tests/unittest/test_engine_dead_lifecycle.py
@@ -52,7 +52,7 @@ def test_api_engine_failure_drains_running_and_queued_jobs(tmp_path: Path, monke
cleanup.append(name)
monkeypatch.setattr(api_server, "parse_async", infer)
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash", concurrency=2)
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",), concurrency=2)
with TestClient(app) as client:
async def make_gate() -> None:
diff --git a/tests/unittest/test_file_parse.py b/tests/unittest/test_file_parse.py
index b03a146f..21dfc173 100644
--- a/tests/unittest/test_file_parse.py
+++ b/tests/unittest/test_file_parse.py
@@ -30,6 +30,7 @@ from mineru.kit.file_parse.client import TaskClient
from mineru.kit.file_parse.models import ParseOptions, Record, fingerprint
from mineru.kit.file_parse.settings import origin
from mineru.kit.file_parse.store import RecordStore
+from mineru.types import Tier
def artifact_bytes(formats: list[str]) -> bytes:
@@ -127,6 +128,8 @@ class Upstream:
}
if self.create_failure == "lost":
raise httpx.ReadError("creation response lost")
+ if self.create_failure == "timeout":
+ raise httpx.ReadTimeout("creation response timed out")
payload = self.payload(task_id)
if self.create_failure == "malformed":
payload["task_id"] = None
@@ -218,6 +221,20 @@ FORMATS = [
]
[email protected]("tier", [None, "flash", "basic", "standard", "advanced"])
+def test_file_parse_forwards_tier_only_when_provided(tmp_path: Path, tier: str | None) -> None:
+ """同步包装层不猜测上游默认档位,显式值原样进入 Tasks 请求。"""
+ upstream = Upstream()
+ with TestClient(application(tmp_path, upstream)) as client:
+ response = submit(client, **({"tier": tier} if tier is not None else {}))
+ assert response.status_code == 200, response.text
+ options = upstream.tasks["task_1"]["options"]
+ if tier is None:
+ assert "tier" not in options
+ else:
+ assert options["tier"] == tier
+
+
@pytest.mark.parametrize("formats", FORMATS)
def test_formats_are_returned_unchanged(tmp_path: Path, formats: list[str]) -> None:
"""覆盖全部十五种格式组合及附件字节、文件名、MIME 和临时文件释放。"""
@@ -297,7 +314,7 @@ def test_wait_budget_excludes_storage_notification_delay(tmp_path: Path) -> None
assert upstream.uploads == 1
[email protected]("failure", ["lost", "malformed"])
[email protected]("failure", ["lost", "timeout", "malformed"])
def test_unknown_creation_is_never_replayed(tmp_path: Path, failure: str) -> None:
"""上游创建成功但响应丢失或身份缺失时,重试和重启都不能再次 POST。"""
upstream = Upstream()
@@ -314,6 +331,94 @@ def test_unknown_creation_is_never_replayed(tmp_path: Path, failure: str) -> Non
assert len(upstream.tasks) == 1
[email protected]("deployment", ["api", "router"])
+ "tiers,tier,code,upstream_status",
+ [
+ (("advanced",), None, "quality_tier_unavailable", 503),
+ (("flash",), "basic", "invalid_request", 400),
+ ],
+)
+def test_real_task_tier_rejection_is_failed_and_not_replayed(
+ tmp_path: Path, deployment: str, tiers: tuple[Tier, ...], tier: Tier | None, code: str, upstream_status: int
+) -> None:
+ """真实 Tasks 拒单保留错误原因,包装层重复提交和重启都不能再次创建任务。"""
+ from test_task_tiers import _deployment
+
+ async def scenario() -> None:
+ """同一事件循环驱动真实 API、Router 和包装服务,观察上游提交次数与持久状态。"""
+ async with _deployment(tmp_path / "upstream", deployment, {"worker": tiers}) as (_client, upstream, apps, _calls):
+ transport = httpx.ASGITransport(app=upstream)
+ submitted: list[httpx.Request] = []
+
+ async def handle(request: httpx.Request) -> httpx.Response:
+ """记录包装层实际发送的请求,错误正文仍由真实 Tasks 生成。"""
+ submitted.append(request)
+ return await transport.handle_async_request(request)
+
+ fields = [("file", ("report.pdf", b"source")), ("request_id", (None, "rejected"))]
+ if tier is not None:
+ fields.append(("tier", (None, tier)))
+ settings = FileParseSettings("http://upstream", state_dir=tmp_path / "wrapper", poll_interval=0.01)
+ for _restart in range(2):
+ app = create_app(settings, transport=httpx.MockTransport(handle))
+ async with app.router.lifespan_context(app):
+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://wrapper") as client:
+ for _repeat in range(2):
+ response = await client.post("/v1/file_parse", files=fields)
+ assert response.status_code == 502, response.text
+ payload = response.json()
+ assert payload["status"] == "failed" and payload["task_id"] is None
+ assert payload["error"]["code"] == code
+ assert payload["error"]["upstream_status"] == upstream_status
+ assert payload["error"]["message"] != "Task creation outcome is unknown; not resubmitting"
+ response = await client.get("/v1/file_parse/rejected")
+ assert response.status_code == 200
+ assert response.json()["status"] == "failed"
+ assert response.json()["error"]["code"] == code
+ assert not list(app.state.service.store.sources.iterdir())
+ assert len(submitted) == 1 and submitted[0].method == "POST"
+ assert all(not app.state.task_store._records for app in apps)
+
+ asyncio.run(scenario())
+
+
+ "status,payload",
+ [
+ (503, b"<html>Service unavailable</html>"),
+ (503, {"error": {"type": "api_error", "code": "temporary", "message": "Try later"}}),
+ (503, {"error": {"code": "quality_tier_unavailable", "message": "Missing required error type"}}),
+ (
+ 503,
+ {"task_id": "maybe-created", "error": {"type": "api_error", "code": "quality_tier_unavailable", "message": "x"}},
+ ),
+ (500, {"error": {"type": "api_error", "code": "quality_tier_unavailable", "message": "Unexpected status"}}),
+ (408, {"error": {"type": "api_error", "code": "quality_tier_unavailable", "message": "Timed out"}}),
+ ],
+)
+def test_ambiguous_creation_errors_remain_unknown(tmp_path: Path, status: int, payload: bytes | dict[str, Any]) -> None:
+ """未列为明确拒单的状态或畸形错误信封保持未知,不能靠错误码字符串判断已拒绝。"""
+ calls: list[httpx.Request] = []
+
+ def handle(request: httpx.Request) -> httpx.Response:
+ """模拟代理错误或矛盾响应,记录是否发生意外重放。"""
+ calls.append(request)
+ assert request.method == "POST"
+ return httpx.Response(status, content=payload) if isinstance(payload, bytes) else httpx.Response(status, json=payload)
+
+ for _restart in range(2):
+ app = create_app(FileParseSettings("https://api.test", state_dir=tmp_path), transport=httpx.MockTransport(handle))
+ with TestClient(app) as client:
+ for _repeat in range(2):
+ response = submit(client)
+ assert response.status_code == 502
+ assert response.json()["status"] == "submission_unknown"
+ assert response.json()["error"]["code"] == "submission_unknown"
+ assert client.get("/v1/file_parse/request_1").json()["status"] == "submission_unknown"
+ assert len(calls) == 1
+
+
def test_auth_failure_cleans_source_without_retry(tmp_path: Path) -> None:
"""上游认证错误是配置错误,不向无认证的包装入口伪报 401。"""
upstream = Upstream()
@@ -651,6 +756,8 @@ def test_late_query_cannot_replace_reused_request_id(tmp_path: Path) -> None:
{"output_formats": ["markdown"]},
{"output_formats": [""]},
{"tier": "wrong"},
+ {"tier": ""},
+ {"tier": "null"},
{"ocr_mode": "wrong"},
{"api_url": "https://different.test"},
],
@@ -691,6 +798,11 @@ def test_openapi_and_light_imports(tmp_path: Path) -> None:
request = post["requestBody"]["content"]["multipart/form-data"]["schema"]
assert request["properties"]["wait_timeout"]["maximum"] == 3600
assert request["properties"]["output_formats"]["items"]["enum"] == ["default", "docx", "html", "latex"]
+ assert "tier" not in request["required"]
+ tier = request["properties"]["tier"]
+ assert tier["type"] == "string" and tier["enum"] == ["flash", "basic", "standard", "advanced"]
+ assert {"anyOf", "nullable", "default"}.isdisjoint(tier)
+ assert "Omit this multipart field" in tier["description"]
assert "application/zip" in post["responses"]["200"]["content"]
result = subprocess.run(
[
diff --git a/tests/unittest/test_flash_html.py b/tests/unittest/test_flash_html.py
index 88252ccb..3edd7789 100644
--- a/tests/unittest/test_flash_html.py
+++ b/tests/unittest/test_flash_html.py
@@ -199,7 +199,7 @@ def test_html_parse_server_flash_only_admits_extensionless_url(
"""跳过后台解析,仅验证 admission 已选择 Flash tier。"""
monkeypatch.setattr(api_server, "_run_execution", fake_run_job)
- app = api_server.create_app(upload_dir=str(tmp_path / "api"), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path / "api"), tiers=("flash",))
with TestClient(app) as client:
response = client.post(
diff --git a/tests/unittest/test_http_api_example_script.py b/tests/unittest/test_http_api_example_script.py
index 52b6e90e..e402f945 100644
--- a/tests/unittest/test_http_api_example_script.py
+++ b/tests/unittest/test_http_api_example_script.py
@@ -43,7 +43,7 @@ def test_http_example_delegates_to_tasks(tmp_path: Path) -> None:
"""原脚本入口执行同一 Tasks 客户端并保留退出码,不残留旧 HTTP 流程。"""
from mineru.parser.api_server import create_app
- server = _Server(create_app(upload_dir=str(tmp_path / "api"), tier="flash"))
+ server = _Server(create_app(upload_dir=str(tmp_path / "api"), tiers=("flash",)))
source = tmp_path / "source.html"
source.write_text("<h1>Unified HTTP example</h1>")
server.start()
diff --git a/tests/unittest/test_kit_commands.py b/tests/unittest/test_kit_commands.py
index b8e0ed05..b31e97a3 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", "--tier", "--no-flash", "--no-advanced", "--preload-models"),
+ ("--host", "--port", "--tiers", "--preload-models"),
),
],
)
@@ -207,10 +207,8 @@ def test_standalone_command_help(
"0.0.0.0",
"--port",
"18000",
- "--tier",
+ "--tiers",
"basic",
- "--no-flash",
- "--no-advanced",
"--preload-models",
],
],
@@ -320,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"], 1),
+ ("mineru-api", api_server.main, ["--tier", "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),
@@ -370,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", "--tier", "--no-flash", "--no-advanced", "--preload-models")),
+ ("api-server", ("--host", "--port", "--tiers", "--preload-models")),
("vlm-server", ("--engine",)),
("router", ("--host", "--upstream-url", "--local-gpus")),
("version", ("--json",)),
@@ -649,7 +647,8 @@ def test_kit_commands_do_not_expose_formula_table_switches() -> None:
assert _REMOVED_DISABLE_FORMULA_OPTION not in output
-def test_api_server_forwards_single_tier_and_disabled_tiers(monkeypatch: Any) -> None:
+def test_api_server_forwards_explicit_tier_list(monkeypatch: Any) -> None:
+ """精确列表原样转发,不再构造旧的禁用开关。"""
seen: dict[str, Any] = {}
def _fake_main(*, args: list[str], prog_name: str, standalone_mode: bool) -> None:
@@ -662,24 +661,25 @@ def test_api_server_forwards_single_tier_and_disabled_tiers(monkeypatch: Any) ->
result = runner.invoke(
app,
- ["api-server", "--tier", "standard", "--no-flash", "--no-advanced", "--preload-models"],
+ ["api-server", "--tiers", "standard", "--preload-models"],
)
assert result.exit_code == 0
assert seen["prog_name"] == "mineru-kit api-server"
assert seen["standalone_mode"] is False
- assert [seen["args"][index + 1] for index, item in enumerate(seen["args"]) if item == "--tier"] == ["standard"]
- assert "--no-flash" in seen["args"]
- assert "--no-advanced" in seen["args"]
+ assert [seen["args"][index + 1] for index, item in enumerate(seen["args"]) if item == "--tiers"] == ["standard"]
+ assert "--no-flash" not in seen["args"]
+ assert "--no-advanced" not in seen["args"]
assert "--preload-models" in seen["args"]
assert "--ocr-mode" not in seen["args"]
-def test_api_server_without_tier_lets_parser_api_apply_standard_default(monkeypatch: Any) -> None:
+def test_api_server_without_tiers_forwards_auto(monkeypatch: Any) -> None:
+ """省略启动集合时转发 auto,交由服务进行硬件推荐。"""
seen: dict[str, Any] = {}
def _fake_main(*, args: list[str], prog_name: str, standalone_mode: bool) -> None:
- """记录 mineru-kit api-server 默认参数,由底层应用 Standard 能力默认值。"""
+ """记录 mineru-kit api-server 默认参数,由底层应用硬件推荐集合。"""
seen["args"] = args
seen["prog_name"] = prog_name
seen["standalone_mode"] = standalone_mode
@@ -691,24 +691,27 @@ def test_api_server_without_tier_lets_parser_api_apply_standard_default(monkeypa
assert result.exit_code == 0
assert seen["prog_name"] == "mineru-kit api-server"
assert seen["standalone_mode"] is False
+ assert seen["args"][seen["args"].index("--tiers") + 1] == "auto"
assert "--tier" not in seen["args"]
assert "--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_advanced_startup_tier() -> None:
+def test_api_server_rejects_removed_tier_option() -> None:
+ """旧单值 API 启动参数明确报错。"""
result = runner.invoke(app, ["api-server", "--tier", "advanced"])
- assert result.exit_code == 1
- assert "Unsupported server tier 'advanced'" in result.output
+ assert result.exit_code == 2
+ assert "No such option" in result.output
-def test_api_server_rejects_flash_no_flash_conflict() -> None:
+def test_api_server_rejects_removed_disable_options() -> None:
+ """旧禁用参数不再构成可接受的 API 启动配置。"""
result = runner.invoke(app, ["api-server", "--tier", "flash", "--no-flash"])
- assert result.exit_code == 1
- assert "--tier flash cannot be combined with --no-flash" in result.output
+ assert result.exit_code == 2
+ assert "No such option" in result.output
def test_api_server_rejects_removed_language_option() -> None:
diff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.py
index 024ec304..49845d6d 100644
--- a/tests/unittest/test_kit_gradio.py
+++ b/tests/unittest/test_kit_gradio.py
@@ -321,8 +321,8 @@ def test_v1_client_discovers_api_server_without_advanced(
monkeypatch.setattr(parser_api_server, "_preflight_tier_dependencies", Mock())
api = parser_api_server.create_app(
upload_dir=str(tmp_path / "api"),
- tier="standard",
- no_advanced=True,
+ tiers=("flash", "basic", "standard"),
+
)
request_log: list[tuple[str, str, str | None]] = []
@@ -439,7 +439,7 @@ def test_v1_client_full_asgi_upload_job_poll_and_zip(
monkeypatch.setattr(task_outputs, "build_task_output", export)
api = parser_api_server.create_app(
upload_dir=str(tmp_path / "api"),
- tier="flash",
+ tiers=("flash",),
api_key="secret",
)
request_log: list[tuple[str, str, str | None]] = []
@@ -479,9 +479,9 @@ def test_gradio_routes_real_v1_jobs_and_isolates_remote_auth(monkeypatch: pytest
monkeypatch.setattr(parser_api_server, "parse_async", fake_parse_async)
remote_api = parser_api_server.create_app(
- upload_dir=str(tmp_path / "remote"), tier="standard", no_flash=True, no_advanced=True, api_key="remote-secret"
+ upload_dir=str(tmp_path / "remote"), tiers=("basic", "standard"), api_key="remote-secret"
)
- local_api = parser_api_server.create_app(upload_dir=str(tmp_path / "local"), tier="flash")
+ local_api = parser_api_server.create_app(upload_dir=str(tmp_path / "local"), tiers=("flash",))
requests: list[tuple[str, str, str, str | None]] = []
with TestClient(remote_api, base_url="http://remote.test") as remote_http:
with TestClient(local_api, base_url="http://local.test") as local_http:
@@ -624,7 +624,7 @@ def test_gradio_ocr_reaches_analysis_through_real_v1_jobs(monkeypatch: pytest.Mo
return middle, model
monkeypatch.setattr(mineru_parser, "aio_doc_analyze", fake_analyze)
- api = parser_api_server.create_app(upload_dir=str(tmp_path / "api"), tier="flash")
+ api = parser_api_server.create_app(upload_dir=str(tmp_path / "api"), tiers=("flash",))
with TestClient(api, base_url="http://testserver") as test_client:
request_log: list[tuple[str, str, str | None]] = []
proxy = _httpx_proxy_for_test_client(test_client, request_log)
@@ -768,7 +768,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 "--tier" in command and command[command.index("--tier") + 1] == "standard"
+ assert "--tiers" in command and command[command.index("--tiers") + 1] == "flash,basic,standard,advanced"
assert "--no-flash" not in command
assert "--no-advanced" not in command
assert "--preload-models" in command
diff --git a/tests/unittest/test_model_backend_selection.py b/tests/unittest/test_model_backend_selection.py
index 7b16ad1e..0186fd51 100644
--- a/tests/unittest/test_model_backend_selection.py
+++ b/tests/unittest/test_model_backend_selection.py
@@ -191,7 +191,7 @@ def test_standard_dependency_errors_survive_startup_wrappers(
assert "mineru[full]" in message
with pytest.raises(api_server.ParseServerStartupError) as startup_error:
- api_server.create_app(upload_dir=str(tmp_path), tier="standard", vlm_config=settings)
+ api_server.create_app(upload_dir=str(tmp_path), tiers=("flash", "basic", "standard", "advanced"), vlm_config=settings)
assert str(startup_error.value) == message
with pytest.raises(InvalidRequestError) as doclib_error:
diff --git a/tests/unittest/test_onnx_calibration.py b/tests/unittest/test_onnx_calibration.py
index 0e01ae74..3d73bdef 100644
--- a/tests/unittest/test_onnx_calibration.py
+++ b/tests/unittest/test_onnx_calibration.py
@@ -24,8 +24,9 @@ def gpu() -> GpuAdapter:
@pytest.fixture(autouse=True)
-def fake_rec_preparation(monkeypatch: pytest.MonkeyPatch) -> None:
- """Protocol tests mock sessions; real graph conversion is covered separately."""
+def fake_rec_preparation(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+ """隔离模型准备和校准证据,避免协议测试触及用户配置。"""
+ monkeypatch.setattr("mineru.model.runtime.onnx_calibration_cache.calibration_record_path", lambda: tmp_path / "record.json")
monkeypatch.setattr(calibration, "prepare_rec_model", lambda path: CompactRecModel("compact.onnx", 4, "raw", "compact"))
@@ -256,7 +257,9 @@ def test_invalid_calibration_set_is_rejected(failure: str) -> None:
"threshold",
],
)
-def test_webgpu_worker_protocol(monkeypatch: pytest.MonkeyPatch, failure: str | None) -> None:
+def test_webgpu_worker_protocol(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, failure: str | None) -> None:
+ """新校准必须替换旧证据,协议或输出验证失败时不可保留旧结论。"""
+ (tmp_path / "record.json").write_text('{"old": true}', encoding="utf-8")
output = {
"schema_version": 5,
"backend": "webgpu",
@@ -269,6 +272,9 @@ def test_webgpu_worker_protocol(monkeypatch: pytest.MonkeyPatch, failure: str |
"gpu_elapsed": 0.4,
"ratio": 0.4,
"outputs_match": True,
+ "intra_threads": 4,
+ "inter_threads": 1,
+ "model_sha256": "compact-model",
"gpu": {"providers": [WEBGPU_PROVIDER, "CPUExecutionProvider"], "warmup_s": [2], "timed_s": [0.4] * 3, "median_s": 0.4},
"cpu": {"providers": ["CPUExecutionProvider"], "warmup_s": [2], "timed_s": [1] * 3, "median_s": 1},
}
@@ -298,8 +304,12 @@ def test_webgpu_worker_protocol(monkeypatch: pytest.MonkeyPatch, failure: str |
if failure:
with pytest.raises(ValueError):
calibration.run_calibration("rec.onnx", descriptor)
+ assert not (tmp_path / "record.json").exists()
else:
assert calibration.run_calibration("rec.onnx", descriptor)["backend"] == "webgpu"
+ saved = json.loads((tmp_path / "record.json").read_text(encoding="utf-8"))
+ assert saved["outputs_match"] is True and saved["decision_valid"] is True
+ assert saved["fingerprint"]["adapter"]["device_id"] == 2
request = json.loads(runner.call_args.kwargs["input"])
assert request["backend"] == "webgpu"
assert request["adapter"]["metadata"] == [["pci_bus_id", "test"]]
diff --git a/tests/unittest/test_parser_api_contract.py b/tests/unittest/test_parser_api_contract.py
index a8475ff1..d3532f38 100644
--- a/tests/unittest/test_parser_api_contract.py
+++ b/tests/unittest/test_parser_api_contract.py
@@ -45,7 +45,6 @@ from mineru.types import (
TIERS_BY_SERVER_TIER,
MiddleJson,
PageInfo,
- ServerTier,
Tier,
select_default_quality_tier,
select_parsing_rule_tier,
@@ -65,6 +64,12 @@ _REMOVED_TABLE_ENABLE_ENV = "MINERU_" + "TABLE" + "_ENABLE"
_REMOVED_FORMULA_ENABLE_ENV = "MINERU_" + "FORMULA" + "_ENABLE"
[email protected](autouse=True)
+def _stable_hardware_recommendation(monkeypatch: pytest.MonkeyPatch) -> None:
+ """固定服务契约测试的硬件推荐,设备组合由独立测试覆盖。"""
+ monkeypatch.setattr("mineru.model.runtime.tier_recommendation.recommend_tiers", lambda: frozenset(TIERS))
+
+
def _stub_api_server_dependency_preflight(monkeypatch: pytest.MonkeyPatch) -> None:
"""只跳过服务依赖预检,避免覆盖全局导入而破坏运行时的惰性加载。"""
monkeypatch.setattr(api_server, "ensure_tier_runtime_dependencies", lambda *_args, **_kwargs: None)
@@ -621,13 +626,13 @@ def test_create_app_does_not_read_runtime_settings_from_env(tmp_path: Path, monk
app = create_app(upload_dir=str(tmp_path))
- assert app.state.tier == "standard"
+ assert app.state.model_tier == "standard"
assert app.state.concurrency == 1
assert app.state.url_timeout == 60
assert app.state.allow_http_source is False
assert not hasattr(app.state, "ocr_mode")
assert not hasattr(app.state, "language")
- assert app.state.effort == "high"
+ assert app.state.tier_runtime_options["standard"].effort == "high"
assert app.state.image_analysis is True
assert not hasattr(app.state, _REMOVED_TABLE_ENABLE_PARAM)
assert not hasattr(app.state, _REMOVED_FORMULA_ENABLE_PARAM)
@@ -720,27 +725,28 @@ def test_health_response_rejects_nonstandard_version_fields(field: str) -> None:
def test_api_server_tier_selects_compatible_backend(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
_stub_api_server_dependency_preflight(monkeypatch)
- flash_app = create_app(upload_dir=str(tmp_path / "flash"), tier="flash")
- basic_app = create_app(upload_dir=str(tmp_path / "basic"), tier="basic")
- standard_app = create_app(upload_dir=str(tmp_path / "standard"), tier="standard")
+ flash_app = create_app(upload_dir=str(tmp_path / "flash"), tiers=("flash",))
+ basic_app = create_app(upload_dir=str(tmp_path / "basic"), tiers=("flash", "basic"))
+ standard_app = create_app(upload_dir=str(tmp_path / "standard"), tiers=("flash", "basic", "standard", "advanced"))
- assert flash_app.state.tier == "flash"
+ assert flash_app.state.model_tier is None
assert [tier["id"] for tier in flash_app.state.tiers] == ["flash"]
- assert basic_app.state.tier == "basic"
- assert basic_app.state.effort == "medium"
+ assert basic_app.state.model_tier == "basic"
+ assert basic_app.state.tier_runtime_options["basic"].effort == "medium"
assert [tier["id"] for tier in basic_app.state.tiers] == ["flash", "basic"]
- assert standard_app.state.tier == "standard"
- assert standard_app.state.effort == "high"
+ assert standard_app.state.model_tier == "standard"
+ assert standard_app.state.tier_runtime_options["standard"].effort == "high"
assert [tier["id"] for tier in standard_app.state.tiers] == ["flash", "basic", "standard", "advanced"]
-def test_api_server_defaults_to_all_quality_tiers(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+def test_api_server_defaults_to_hardware_recommendation(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """默认使用推荐集合,模型配置与逐档执行参数保持一致。"""
_stub_api_server_dependency_preflight(monkeypatch)
app = create_app(upload_dir=str(tmp_path))
- assert app.state.tier == "standard"
+ assert app.state.model_tier == "standard"
assert app.state.default_tier == "standard"
- assert app.state.effort == "high"
+ assert app.state.tier_runtime_options["standard"].effort == "high"
assert [tier["id"] for tier in app.state.tiers] == ["flash", "basic", "standard", "advanced"]
assert app.state.tier_runtime_options["flash"].effort == "flash"
assert app.state.tier_runtime_options["basic"].effort == "medium"
@@ -751,11 +757,11 @@ def test_api_server_defaults_to_all_quality_tiers(tmp_path: Path, monkeypatch: p
def test_api_server_standard_no_flash_state_and_metadata(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""校验 Standard 能力上限发布三个模型档位,并可严格禁用 Flash。"""
_stub_api_server_dependency_preflight(monkeypatch)
- app = create_app(upload_dir=str(tmp_path), tier="standard", no_flash=True)
+ app = create_app(upload_dir=str(tmp_path), tiers=("basic", "standard", "advanced"))
- assert app.state.tier == "standard"
+ assert app.state.model_tier == "standard"
assert app.state.default_tier == "standard"
- assert app.state.effort == "high"
+ assert app.state.tier_runtime_options["standard"].effort == "high"
assert app.state.flash_enabled is False
assert [tier["id"] for tier in app.state.tiers] == ["basic", "standard", "advanced"]
assert app.state.model_ids == [api_server._VIRTUAL_MODEL_ID]
@@ -766,40 +772,25 @@ def test_api_server_standard_no_flash_state_and_metadata(tmp_path: Path, monkeyp
@pytest.mark.parametrize(
- ("tier", "no_flash", "expected_tiers", "expected_default_tier"),
- [
- ("standard", False, ("flash", "basic", "standard"), "standard"),
- ("standard", True, ("basic", "standard"), "standard"),
- ("basic", False, ("flash", "basic"), "basic"),
- ("flash", False, ("flash",), None),
- ],
+ ("tiers", "default"),
+ [(('flash', 'standard'), 'standard'), (('standard',), 'standard'),
+ (('basic',), 'basic'), (('flash',), 'flash'), (('advanced',), None)],
)
-def test_api_server_no_advanced_capability_matrix(
- tmp_path: Path,
- monkeypatch: pytest.MonkeyPatch,
- tier: ServerTier,
- no_flash: bool,
- expected_tiers: tuple[str, ...],
- expected_default_tier: str | None,
+def test_api_server_explicit_capability_matrix(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, tiers: tuple[Tier, ...], default: Tier | None
) -> None:
- """验证禁用 Advanced 可与 server tier 和禁用 Flash 组合,且不改变其它档位。"""
+ """精确集合独立控制能力发现、执行 runtime 与请求默认档位。"""
_stub_api_server_dependency_preflight(monkeypatch)
- app = create_app(
- upload_dir=str(tmp_path / f"{tier}-{no_flash}"),
- tier=tier,
- no_flash=no_flash,
- no_advanced=True,
- )
-
- assert tuple(tier_info["id"] for tier_info in app.state.tiers) == expected_tiers
- assert tuple(app.state.tier_runtime_options) == expected_tiers
- assert app.state.default_tier == expected_default_tier
+ app = create_app(upload_dir=str(tmp_path), tiers=tiers)
+ assert tuple(tier_info["id"] for tier_info in app.state.tiers) == tiers
+ assert tuple(app.state.tier_runtime_options) == tiers
+ assert app.state.default_tier == default
def test_api_server_standard_http_metadata(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""校验 /v1/tiers 与 /v1/models 返回 Standard 上限展开后的全部能力。"""
_stub_api_server_dependency_preflight(monkeypatch)
- app = create_app(upload_dir=str(tmp_path), tier="standard")
+ app = create_app(upload_dir=str(tmp_path), tiers=("flash", "basic", "standard", "advanced"))
with TestClient(app) as client:
health_response = client.get("/v1/health")
@@ -829,7 +820,7 @@ def test_api_server_models_created_is_stable_across_requests(
) -> None:
"""回归:created 是部署注册时间,两次请求之间不随墙钟跳动。"""
_stub_api_server_dependency_preflight(monkeypatch)
- app = create_app(upload_dir=str(tmp_path), tier="standard")
+ app = create_app(upload_dir=str(tmp_path), tiers=("flash", "basic", "standard", "advanced"))
with TestClient(app) as client:
first = client.get("/v1/models").json()["data"][0]["created"]
@@ -841,7 +832,7 @@ def test_api_server_models_created_is_stable_across_requests(
def test_api_server_model_detail_rejects_unknown_id(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""非虚拟模型 id 一律 404,包括历史上的引擎品牌名。"""
_stub_api_server_dependency_preflight(monkeypatch)
- app = create_app(upload_dir=str(tmp_path), tier="standard")
+ app = create_app(upload_dir=str(tmp_path), tiers=("flash", "basic", "standard", "advanced"))
with TestClient(app) as client:
response = client.get("/v1/models/MinerU2.5-Pro-2605-1.2B")
@@ -856,7 +847,7 @@ def test_api_server_no_advanced_http_metadata_keeps_shared_models(
) -> None:
"""验证能力接口隐藏 Advanced;虚拟模型 id 不随档位开关变化。"""
_stub_api_server_dependency_preflight(monkeypatch)
- app = create_app(upload_dir=str(tmp_path), tier="standard", no_advanced=True)
+ app = create_app(upload_dir=str(tmp_path), tiers=("flash", "basic", "standard"))
with TestClient(app) as client:
tiers_response = client.get("/v1/tiers")
@@ -878,7 +869,7 @@ def test_api_server_model_preload_failure_keeps_health_diagnostics_and_rejects_c
raise ValueError("CUDA is not available.")
monkeypatch.setattr(api_server, "_preload_server_models", _fail_preload)
- app = create_app(upload_dir=str(tmp_path), tier="standard", preload_models=True)
+ app = create_app(upload_dir=str(tmp_path), tiers=("flash", "basic", "standard", "advanced"), preload_models=True)
with TestClient(app) as client:
health_response = client.get("/v1/health")
@@ -905,11 +896,13 @@ def test_api_server_model_preload_is_opt_in_and_ignored_for_flash(tmp_path: Path
monkeypatch.setattr(api_server, "_preload_server_models", _preload)
- with TestClient(create_app(upload_dir=str(tmp_path / "lazy"), tier="basic")) as lazy_client:
+ with TestClient(create_app(upload_dir=str(tmp_path / "lazy"), tiers=("flash", "basic"))) as lazy_client:
assert lazy_client.get("/v1/health").status_code == 200
- with TestClient(create_app(upload_dir=str(tmp_path / "preload"), tier="basic", preload_models=True)) as preload_client:
+ with TestClient(
+ create_app(upload_dir=str(tmp_path / "preload"), tiers=("flash", "basic"), preload_models=True)
+ ) as preload_client:
assert preload_client.get("/v1/health").status_code == 200
- with TestClient(create_app(upload_dir=str(tmp_path / "flash"), tier="flash", preload_models=True)) as flash_client:
+ with TestClient(create_app(upload_dir=str(tmp_path / "flash"), tiers=("flash",), preload_models=True)) as flash_client:
assert flash_client.get("/v1/health").status_code == 200
assert calls == ["basic"]
@@ -930,7 +923,7 @@ def test_api_server_standard_jobs_use_requested_tier(tmp_path: Path, monkeypatch
monkeypatch.setattr("mineru.parser.api_server.parse_async", fake_parse_async)
source = tmp_path / "demo.pdf"
source.write_bytes(b"%PDF-1.7\n")
- app = create_app(upload_dir=str(tmp_path / "api"), tier="standard")
+ app = create_app(upload_dir=str(tmp_path / "api"), tiers=("flash", "basic", "standard", "advanced"))
file_store = FileStore(tmp_path / "api-files")
execution_store = api_server.ExecutionStore()
@@ -960,7 +953,7 @@ def test_api_server_basic_rejects_advanced_request(tmp_path: Path, monkeypatch:
_stub_api_server_dependency_preflight(monkeypatch)
source = tmp_path / "demo.pdf"
source.write_bytes(b"%PDF-1.7\n")
- app = create_app(upload_dir=str(tmp_path / "api"), tier="basic")
+ app = create_app(upload_dir=str(tmp_path / "api"), tiers=("flash", "basic"))
with TestClient(app) as client:
response = client.post(
@@ -982,8 +975,8 @@ def test_api_server_no_advanced_rejects_advanced_request(tmp_path: Path, monkeyp
source.write_bytes(b"%PDF-1.7\n")
app = create_app(
upload_dir=str(tmp_path / "api"),
- tier="standard",
- no_advanced=True,
+ tiers=("flash", "basic", "standard"),
+
)
with TestClient(app) as client:
@@ -1005,8 +998,8 @@ def test_api_server_no_flash_rejects_flash_request(tmp_path: Path, monkeypatch:
source.write_bytes(b"%PDF-1.7\n")
app = create_app(
upload_dir=str(tmp_path / "api"),
- tier="standard",
- no_flash=True,
+ tiers=("basic", "standard", "advanced"),
+
)
response = TestClient(app).post(
@@ -1022,14 +1015,15 @@ def test_api_server_no_flash_rejects_flash_request(tmp_path: Path, monkeypatch:
def test_api_server_rejects_invalid_startup_tier_configuration(tmp_path: Path) -> None:
- with pytest.raises(ValueError, match="Unsupported server tier 'advanced'"):
- create_app(upload_dir=str(tmp_path / "advanced"), tier="advanced") # type: ignore[arg-type]
-
- with pytest.raises(ValueError, match="must be a single value"):
- create_app(upload_dir=str(tmp_path / "multiple"), tier=["basic", "standard"]) # type: ignore[arg-type]
-
- with pytest.raises(ValueError, match="--tier flash cannot be combined with --no-flash"):
- create_app(upload_dir=str(tmp_path / "empty"), tier="flash", no_flash=True)
+ """拒绝非法集合与已移除的旧启动参数。"""
+ with pytest.raises(ValueError, match="Unsupported tier"):
+ create_app(upload_dir=str(tmp_path / "invalid"), tiers=("ultra",)) # type: ignore[arg-type]
+ with pytest.raises(ValueError, match="non-empty collection"):
+ create_app(upload_dir=str(tmp_path / "string"), tiers="standard") # type: ignore[arg-type]
+ with pytest.raises(ValueError, match="non-empty collection"):
+ create_app(upload_dir=str(tmp_path / "empty"), tiers=())
+ with pytest.raises(TypeError, match="unexpected keyword argument"):
+ create_app(tier="standard") # type: ignore[call-arg]
def test_api_server_skips_dependency_preflight_for_flash(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
@@ -1038,7 +1032,7 @@ def test_api_server_skips_dependency_preflight_for_flash(monkeypatch: pytest.Mon
monkeypatch.setattr(importlib, "import_module", fail_import_module)
- create_app(upload_dir=str(tmp_path), tier="flash")
+ create_app(upload_dir=str(tmp_path), tiers=("flash",))
def test_api_server_preflights_basic_tier_dependencies(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
@@ -1052,7 +1046,7 @@ def test_api_server_preflights_basic_tier_dependencies(monkeypatch: pytest.Monke
monkeypatch.setattr(api_server.get_config().model, "small_backend", "torch")
monkeypatch.setattr(api_server.get_config().model.vlm, "engine", "llama-cpp")
- create_app(upload_dir=str(tmp_path), tier="basic")
+ create_app(upload_dir=str(tmp_path), tiers=("flash", "basic"))
assert imported_modules == [
"onnxruntime",
@@ -1075,7 +1069,7 @@ def test_api_server_preflights_standard_tier_dependencies_for_platform(monkeypat
monkeypatch.setattr(api_server.get_config().model, "small_backend", "torch")
monkeypatch.setattr(api_server.get_config().model.vlm, "engine", "llama-cpp")
- create_app(upload_dir=str(tmp_path), tier="standard")
+ create_app(upload_dir=str(tmp_path), tiers=("flash", "basic", "standard", "advanced"))
assert imported_modules == [
"onnxruntime",
@@ -1101,7 +1095,7 @@ def test_api_server_preflights_standard_tier_dependencies_skip_mlx_on_intel_maco
monkeypatch.setattr(api_server.get_config().model, "small_backend", "torch")
monkeypatch.setattr(api_server.get_config().model.vlm, "engine", "llama-cpp")
- create_app(upload_dir=str(tmp_path), tier="standard")
+ create_app(upload_dir=str(tmp_path), tiers=("flash", "basic", "standard", "advanced"))
assert imported_modules == [
"onnxruntime",
@@ -1125,7 +1119,7 @@ def test_api_server_preflight_rejects_missing_tier_dependency(monkeypatch: pytes
monkeypatch.setattr(parser_tier.importlib_metadata, "packages_distributions", lambda: {"mineru": ["mineru"]})
with pytest.raises(api_server.ParseServerStartupError, match="tier 'basic'.*torch.*mineru\\[torch\\]"):
- create_app(upload_dir=str(tmp_path), tier="basic")
+ create_app(upload_dir=str(tmp_path), tiers=("flash", "basic"))
def test_api_server_create_app_rejects_backend_and_effort_parameters(tmp_path: Path) -> None:
@@ -1143,13 +1137,13 @@ def test_api_server_stores_parser_runtime_options(tmp_path: Path, monkeypatch: p
_stub_api_server_dependency_preflight(monkeypatch)
app = create_app(
upload_dir=str(tmp_path),
- tier="basic",
+ tiers=("flash", "basic"),
image_analysis=False,
)
assert not hasattr(app.state, "ocr_mode")
assert not hasattr(app.state, "language")
- assert app.state.effort == "medium"
+ assert app.state.tier_runtime_options["basic"].effort == "medium"
assert app.state.image_analysis is False
assert not hasattr(app.state, _REMOVED_TABLE_ENABLE_PARAM)
assert not hasattr(app.state, _REMOVED_FORMULA_ENABLE_PARAM)
@@ -1158,7 +1152,8 @@ def test_api_server_stores_parser_runtime_options(tmp_path: Path, monkeypatch: p
def test_api_server_cli_exposes_parser_runtime_options() -> None:
option_names = {name for param in main.params for name in param.opts}
- assert "--tier" in option_names
+ assert "--tiers" in option_names
+ assert "--tier" not in option_names
assert "--backend" not in option_names
assert "--language" not in option_names
assert "--ocr-mode" not in option_names
@@ -1184,11 +1179,12 @@ def test_api_server_cli_rejects_backend_and_effort_options() -> None:
assert "--effort" in effort_result.output
-def test_api_server_cli_defaults_to_all_quality_tiers(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_api_server_cli_defaults_to_hardware_recommendation(monkeypatch: pytest.MonkeyPatch) -> None:
+ """CLI 省略集合时使用推荐结果,默认请求仍选择 standard。"""
seen: dict[str, object] = {}
def _fake_run(server: Any) -> None:
- """记录无 --tier 启动后的默认 API server 能力,不启动真实服务。"""
+ """记录无 --tiers 启动后的自动推荐能力,不启动真实服务。"""
seen["tiers"] = [tier["id"] for tier in server.config.app.state.tiers]
seen["default_tier"] = server.config.app.state.default_tier
seen["effort_by_tier"] = {
@@ -1207,11 +1203,12 @@ def test_api_server_cli_defaults_to_all_quality_tiers(monkeypatch: pytest.Monkey
}
-def test_api_server_cli_accepts_single_tier_and_no_flash(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_api_server_cli_accepts_quality_tier_list(monkeypatch: pytest.MonkeyPatch) -> None:
+ """显式质量档位列表无需禁用开关即可排除 Flash。"""
seen: dict[str, object] = {}
def _fake_run(server: Any) -> None:
- """记录单个 --tier 与 --no-flash 启动后的 API server 能力列表。"""
+ """记录显式质量档位集合及其默认请求档位。"""
seen["tiers"] = [tier["id"] for tier in server.config.app.state.tiers]
seen["default_tier"] = server.config.app.state.default_tier
seen["effort_by_tier"] = {
@@ -1220,7 +1217,7 @@ def test_api_server_cli_accepts_single_tier_and_no_flash(monkeypatch: pytest.Mon
monkeypatch.setattr("uvicorn.Server.run", _fake_run)
- result = runner.invoke(main, ["--tier", "standard", "--no-flash", "--host", "0.0.0.0", "--port", "15984"])
+ result = runner.invoke(main, ["--tiers", "basic,standard,advanced", "--host", "0.0.0.0", "--port", "15984"])
assert result.exit_code == 0
assert seen == {
@@ -1230,8 +1227,8 @@ def test_api_server_cli_accepts_single_tier_and_no_flash(monkeypatch: pytest.Mon
}
-def test_api_server_cli_accepts_no_advanced(monkeypatch: pytest.MonkeyPatch) -> None:
- """验证底层 Click 入口将 --no-advanced 应用于能力发布与 runtime。"""
+def test_api_server_cli_accepts_list_without_advanced(monkeypatch: pytest.MonkeyPatch) -> None:
+ """验证精确列表同时约束能力发布与执行 runtime。"""
seen: dict[str, object] = {}
def _fake_run(server: Any) -> None:
@@ -1244,7 +1241,7 @@ def test_api_server_cli_accepts_no_advanced(monkeypatch: pytest.MonkeyPatch) ->
monkeypatch.setattr("uvicorn.Server.run", _fake_run)
- result = runner.invoke(main, ["--tier", "standard", "--no-advanced", "--host", "0.0.0.0", "--port", "15984"])
+ result = runner.invoke(main, ["--tiers", "flash,basic,standard", "--host", "0.0.0.0", "--port", "15984"])
assert result.exit_code == 0
assert seen == {
@@ -1262,24 +1259,25 @@ def test_api_server_cli_enables_model_preload(monkeypatch: pytest.MonkeyPatch) -
monkeypatch.setattr("uvicorn.Server.run", _fake_run)
- result = runner.invoke(main, ["--tier", "basic", "--preload-models"])
+ result = runner.invoke(main, ["--tiers", "flash,basic", "--preload-models"])
assert result.exit_code == 0
assert seen == {"preload_models": True}
def test_api_server_cli_rejects_invalid_tier_names() -> None:
- result = runner.invoke(main, ["--tier", "ultra"])
+ result = runner.invoke(main, ["--tiers", "ultra"])
assert result.exit_code != 0
- assert "Invalid value for '--tier'" in result.output
+ assert "Unsupported tier 'ultra'" in result.output
-def test_api_server_cli_rejects_flash_no_flash_conflict() -> None:
+def test_api_server_cli_rejects_old_options() -> None:
+ """旧单值与禁用参数均被 CLI 拒绝。"""
result = runner.invoke(main, ["--tier", "flash", "--no-flash"])
assert result.exit_code != 0
- assert "--tier flash cannot be combined with --no-flash" in result.output
+ assert "No such option" in result.output
def test_api_server_cli_rejects_removed_language_option() -> None:
@@ -1295,12 +1293,13 @@ def test_api_server_cli_help_exposes_tier_only_runtime_selection() -> None:
normalized_output = result.output.replace("-\n ", "-")
assert result.exit_code == 0
- assert "--tier" in normalized_output
+ assert "--tiers" in normalized_output
assert "flash" in normalized_output
assert "basic" in normalized_output
assert "standard" in normalized_output
assert "advanced" in normalized_output
- assert "--no-advanced" in normalized_output
+ assert "--no-advanced" not in normalized_output
+ assert "--no-flash" not in normalized_output
assert "--backend" not in normalized_output
assert "--effort" not in normalized_output
assert "hybrid-engine" not in normalized_output
diff --git a/tests/unittest/test_parser_api_ocr.py b/tests/unittest/test_parser_api_ocr.py
index 3098cfae..beecdc7a 100644
--- a/tests/unittest/test_parser_api_ocr.py
+++ b/tests/unittest/test_parser_api_ocr.py
@@ -89,7 +89,7 @@ def test_api_parser_rejects_invalid_ocr_mode(value: object) -> None:
@pytest.mark.parametrize("value", [None, "", "forced", True, 1, {}])
def test_api_server_rejects_invalid_request_ocr_mode(tmp_path: Path, value: object) -> None:
"""非法模式统一返回带参数定位的 HTTP 400,且不会创建任务。"""
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",))
with TestClient(app) as client:
response = client.post(
"/v1/tasks",
@@ -108,7 +108,7 @@ def test_api_server_ocr_defaults_to_request_auto_without_startup_configuration(t
"""请求缺省值固定为 auto,应用生命周期不保存全局 OCR 模式。"""
request = CreateTaskRequest.model_validate({"files": [{"file_name": "demo.pdf", "bytes": 9}]})
assert request.ocr_mode == "auto"
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",))
assert not hasattr(app.state, "ocr_mode")
with TestClient(app):
assert not hasattr(app.state, "ocr_mode")
diff --git a/tests/unittest/test_pdf_page_id.py b/tests/unittest/test_pdf_page_id.py
index b3a9ae4f..27c4f61e 100644
--- a/tests/unittest/test_pdf_page_id.py
+++ b/tests/unittest/test_pdf_page_id.py
@@ -174,7 +174,7 @@ def test_remote_clients_validate_before_network(tmp_path: Path, monkeypatch: pyt
def test_api_rejects_bad_ranges_before_creating_jobs(tmp_path: Path) -> None:
"""直接 HTTP 请求校验共享语法,错误定位到批量请求的具体文件。"""
- app = api_server.create_app(upload_dir=str(tmp_path / "api"), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path / "api"), tiers=("flash",))
with TestClient(app) as client:
for raw in INVALID_RANGES:
response = client.post(
@@ -262,7 +262,7 @@ def test_async_job_resolves_relative_ranges_and_reports_file_errors(tmp_path: Pa
source = tmp_path / "numbered.pdf"
_numbered_pdf(source)
data = source.read_bytes()
- app = api_server.create_app(upload_dir=str(tmp_path / "api-files"), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path / "api-files"), tiers=("flash",))
with TestClient(app) as client:
response = client.post(
"/v1/tasks",
diff --git a/tests/unittest/test_pdf_text_styles.py b/tests/unittest/test_pdf_text_styles.py
index 7c5ae8a1..72a63c10 100644
--- a/tests/unittest/test_pdf_text_styles.py
+++ b/tests/unittest/test_pdf_text_styles.py
@@ -266,11 +266,13 @@ def test_hybrid_txt_efforts_apply_dehyphenated_links(
@pytest.mark.parametrize("effort", ["medium", "high", "xhigh"])
[email protected]("script_case", ["single", "fragment-conflict", "ambiguous-source"])
def test_hybrid_txt_efforts_apply_shared_script_sidecar(
monkeypatch: pytest.MonkeyPatch,
effort: str,
+ script_case: str,
) -> None:
- """验证 Medium、High 与 XHigh 的 TXT 文本统一应用整行脚本 sidecar。"""
+ """验证各档位通过共享 sidecar 保留单一样式,并裁决 VLM 正文上的上下标冲突。"""
page_geometry = PDFPageTextGeometry([], {}, {})
script_line = PDFTextScriptLine(
@@ -280,7 +282,47 @@ def test_hybrid_txt_efforts_apply_shared_script_sidecar(
source_index=0,
angle=0,
)
- build_evidence = MagicMock(return_value=PDFTextEvidence((100.0, 100.0), page_geometry, scripts=(script_line,)))
+ script_lines = [script_line]
+ content = "x2"
+ expected = [
+ {"type": "text", "content": "x"},
+ {"type": "text", "content": "2", "styles": ["superscript"]},
+ ]
+ if script_case == "ambiguous-source":
+ script_lines.append(
+ PDFTextScriptLine(
+ bbox=(10.0, 30.0, 90.0, 40.0),
+ text="x2",
+ script_ranges=(PDFTextScriptRange(1, 2, "subscript", (20.0, 30.0, 25.0, 35.0), 1, False),),
+ source_index=1,
+ angle=0,
+ )
+ )
+ expected = [{"type": "text", "content": "x2"}]
+ elif script_case == "fragment-conflict":
+ content = "new123text"
+ script_lines = [
+ PDFTextScriptLine(
+ bbox=(10.0, 10.0, 90.0, 20.0),
+ text="old123text",
+ script_ranges=(PDFTextScriptRange(3, 6, "superscript", (20.0, 10.0, 30.0, 15.0), 1, False),),
+ source_index=0,
+ angle=0,
+ ),
+ PDFTextScriptLine(
+ bbox=(10.0, 30.0, 90.0, 40.0),
+ text="new123text",
+ script_ranges=(PDFTextScriptRange(3, 6, "subscript", (20.0, 30.0, 30.0, 35.0), 1, False),),
+ source_index=1,
+ angle=0,
+ ),
+ ]
+ expected = [
+ {"type": "text", "content": "new"},
+ {"type": "text", "content": "123", "styles": ["subscript"]},
+ {"type": "text", "content": "text"},
+ ]
+ build_evidence = MagicMock(return_value=PDFTextEvidence((100.0, 100.0), page_geometry, scripts=tuple(script_lines)))
monkeypatch.setattr(text_content, "prepare_text_evidence", build_evidence)
monkeypatch.setattr(text_content, "_build_page_text_formula_spans", lambda *_args: [])
@@ -306,7 +348,10 @@ def test_hybrid_txt_efforts_apply_shared_script_sidecar(
monkeypatch.setattr(text_content, "_apply_window_post_ocr", lambda *_args: None)
pdf_page = MagicMock(size=(100.0, 100.0))
pdf_page.get_char_count.return_value = 2
- model_list = [[{"type": BlockType.TEXT, "bbox": [0.1, 0.1, 0.3, 0.2], "content": ""}]]
+ # 冲突场景保留非空 VLM 正文,由真实回填调用消费共享证据;普通场景继续覆盖空正文回填。
+ model_list = [
+ [{"type": BlockType.TEXT, "bbox": [0.1, 0.1, 0.9, 0.4], "content": "" if script_case == "single" else content}]
+ ]
text_content._fill_window_block_content_and_lines(
[{"img_pil": object(), "scale": 1.0}],
@@ -320,10 +365,7 @@ def test_hybrid_txt_efforts_apply_shared_script_sidecar(
MagicMock(),
)
- assert model_list[0][0]["content"] == [
- {"type": "text", "content": "x"},
- {"type": "text", "content": "2", "styles": ["superscript"]},
- ]
+ assert model_list[0][0]["content"] == expected
def test_ocr_path_does_not_collect_or_apply_pdf_styles(
diff --git a/tests/unittest/test_resource_retention.py b/tests/unittest/test_resource_retention.py
index 01f7936d..ddb594c5 100644
--- a/tests/unittest/test_resource_retention.py
+++ b/tests/unittest/test_resource_retention.py
@@ -156,14 +156,14 @@ def test_startup_orphan_cleanup_and_directory_ownership(
unknown = root / "blobs/unknown.txt"
unknown.write_text("keep")
monkeypatch.setattr(api_server, "_preflight_tier_dependencies", lambda *args: None)
- app = api_server.create_app(upload_dir=str(root), tier="flash", retention_seconds=10)
+ app = api_server.create_app(upload_dir=str(root), tiers=("flash",), retention_seconds=10)
with TestClient(app):
assert not orphan_store._blob_abs(sha).exists() and unknown.exists()
- other = api_server.create_app(upload_dir=str(root), tier="flash", retention_seconds=10)
+ other = api_server.create_app(upload_dir=str(root), tiers=("flash",), retention_seconds=10)
with pytest.raises(RuntimeError, match="already owned"):
with TestClient(other):
pass
- with TestClient(api_server.create_app(upload_dir=str(root), tier="flash", retention_seconds=10)):
+ with TestClient(api_server.create_app(upload_dir=str(root), tiers=("flash",), retention_seconds=10)):
pass
@@ -239,7 +239,7 @@ def test_queued_cancel_releases_input_before_execution(tmp_path: Path, clock: li
def test_hash_preflight_rejection_releases_request_lease(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""清单 hash 命中后的声明大小校验失败不会泄漏准备阶段的 blob 引用。"""
monkeypatch.setattr(api_server, "_preflight_tier_dependencies", lambda *args: None)
- app = api_server.create_app(upload_dir=str(tmp_path / "files"), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path / "files"), tiers=("flash",))
with TestClient(app) as client:
_, sha = _source(app.state.file_store, tmp_path)
response = client.post(
@@ -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", "--tier", "flash", "--retention-seconds", "0"], env={"MINERU_API_RETENTION_SECONDS": "7200"}
+ app, ["api-server", "--tiers", "flash", "--retention-seconds", "0"], env={"MINERU_API_RETENTION_SECONDS": "7200"}
)
assert response.exit_code == 0, response.output
args = forwarded.call_args.kwargs["args"]
diff --git a/tests/unittest/test_router_balancing.py b/tests/unittest/test_router_balancing.py
index 51940c0d..66911249 100644
--- a/tests/unittest/test_router_balancing.py
+++ b/tests/unittest/test_router_balancing.py
@@ -31,7 +31,7 @@ def test_output_format_validation_precedes_worker_selection(formats: Any, tmp_pa
upstream = _FakeV1Upstream("worker-a", ("flash",))
app, _ = _make_router(upstream)
body = {**BODY, "tier": "flash", "output_formats": formats}
- with TestClient(create_api_app(upload_dir=str(tmp_path / "files"), tier="flash")) as direct:
+ with TestClient(create_api_app(upload_dir=str(tmp_path / "files"), tiers=("flash",))) as direct:
expected = direct.post("/v1/tasks", json=body)
with TestClient(app, raise_server_exceptions=False) as client:
response = client.post("/v1/tasks", json=body)
@@ -109,7 +109,9 @@ def test_cached_tasks_still_balance(tmp_path: Path, monkeypatch: pytest.MonkeyPa
return await original(*args, **kwargs)
monkeypatch.setattr(api_server, "parse_async", delayed)
- workers = {host: api_server.create_app(upload_dir=str(tmp_path / host), tier="flash") for host in ("worker-a", "worker-b")}
+ workers = {
+ host: api_server.create_app(upload_dir=str(tmp_path / host), tiers=("flash",)) for host in ("worker-a", "worker-b")
+ }
transport = _WorkerTransport(workers)
app = create_app(
RouterSettings(
@@ -169,7 +171,7 @@ def test_task_submission_failure_and_replacement_release_only_owned_load(
) -> None:
"""新 tasks 的网络失败和迟到响应释放自身预占,不能扣除新 generation 的任务。"""
for replacement in (False, True):
- worker_app = api_server.create_app(upload_dir=str(tmp_path / str(replacement)), tier="flash")
+ worker_app = api_server.create_app(upload_dir=str(tmp_path / str(replacement)), tiers=("flash",))
transport = _WorkerTransport({"worker-a": worker_app})
app = create_app(
RouterSettings(upstream_urls=("http://worker-a",), local_gpus="none", worker_refresh_interval_seconds=0),
diff --git a/tests/unittest/test_router_cascade.py b/tests/unittest/test_router_cascade.py
index 2fe017b7..fb275bba 100644
--- a/tests/unittest/test_router_cascade.py
+++ b/tests/unittest/test_router_cascade.py
@@ -54,7 +54,7 @@ async def _cascade(
tmp_path: Path, *, block_submission: bool = False
) -> AsyncIterator[tuple[httpx.AsyncClient, FastAPI, FastAPI, FastAPI, _WorkerTransport]]:
"""在同一事件循环启动外层、内层 Router 与实际解析 API。"""
- worker = api_server.create_app(upload_dir=str(tmp_path / "worker"), tier="flash", retention_seconds=1)
+ worker = api_server.create_app(upload_dir=str(tmp_path / "worker"), tiers=("flash",), retention_seconds=1)
transport = _WorkerTransport(worker, block_submission=block_submission)
inner = create_app(
RouterSettings(
diff --git a/tests/unittest/test_router_source_cache.py b/tests/unittest/test_router_source_cache.py
index 9c57ecae..a6f8bfe1 100644
--- a/tests/unittest/test_router_source_cache.py
+++ b/tests/unittest/test_router_source_cache.py
@@ -74,7 +74,7 @@ def test_private_cache_disabled_retention_and_rollback(monkeypatch: pytest.Monke
def test_parent_cleanup_releases_sources_after_worker_route_disappears(tmp_path: Path) -> None:
"""执行路由已移除时,父任务仍须结束私有源引用并允许独立缓存回收。"""
- worker = api_server.create_app(upload_dir=str(tmp_path / "worker"), tier="flash")
+ worker = api_server.create_app(upload_dir=str(tmp_path / "worker"), tiers=("flash",))
app = create_app(
RouterSettings(upstream_urls=("http://worker",), local_gpus="none", worker_refresh_interval_seconds=0),
transport=_WorkerTransport({"worker": worker}),
diff --git a/tests/unittest/test_task_api.py b/tests/unittest/test_task_api.py
index cfa53465..e0fc7c0f 100644
--- a/tests/unittest/test_task_api.py
+++ b/tests/unittest/test_task_api.py
@@ -113,10 +113,10 @@ class _WorkerTransport(httpx.AsyncBaseTransport):
def service(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[tuple[TestClient, FastAPI]]:
"""对本地服务与双 worker Router 执行同一份共同协议验收。"""
if request.param == "api":
- app = api_server.create_app(upload_dir=str(tmp_path / "direct"), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path / "direct"), tiers=("flash",))
else:
workers = {
- host: api_server.create_app(upload_dir=str(tmp_path / host), tier="flash") for host in ("worker-a", "worker-b")
+ host: api_server.create_app(upload_dir=str(tmp_path / host), tiers=("flash",)) for host in ("worker-a", "worker-b")
}
transport = _WorkerTransport(workers)
app = create_router(
@@ -902,7 +902,7 @@ def test_cancel_url_download_closes_stream_and_releases_worker(
def test_router_private_hash_cache_and_task_scope(tmp_path: Path) -> None:
"""Router 的缓存、任务与文件地址均隔离调用方,不能仅凭已知 hash 使用他人输入。"""
- workers = {"worker-a": api_server.create_app(upload_dir=str(tmp_path / "worker"), tier="flash")}
+ workers = {"worker-a": api_server.create_app(upload_dir=str(tmp_path / "worker"), tiers=("flash",))}
app = create_router(
RouterSettings(upstream_urls=("http://worker-a",), local_gpus="none", worker_refresh_interval_seconds=0),
transport=_WorkerTransport(workers),
@@ -925,7 +925,7 @@ def test_router_private_hash_cache_and_task_scope(tmp_path: Path) -> None:
@pytest.mark.parametrize("root", ["", "/mineru"])
def test_task_links_respect_proxy_root(tmp_path: Path, root: str) -> None:
"""固定查询路由保留客户端部署前缀,上传和结果仍使用服务返回的链接。"""
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash", api_key="secret")
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",), api_key="secret")
with TestClient(
app, base_url="http://testserver" + root, root_path=root, headers={"Authorization": "Bearer secret"}
) as client:
@@ -1038,7 +1038,9 @@ def test_completed_child_retention_starts_after_parent_finishes(service: tuple[T
def test_router_batch_uses_independent_workers_and_task_capabilities(tmp_path: Path) -> None:
"""单个父任务的文件按负载分发,旧 worker 即使声明 zip 也不能接新 Tasks。"""
- workers = {host: api_server.create_app(upload_dir=str(tmp_path / host), tier="flash") for host in ("worker-a", "worker-b")}
+ workers = {
+ host: api_server.create_app(upload_dir=str(tmp_path / host), tiers=("flash",)) for host in ("worker-a", "worker-b")
+ }
app = create_router(
RouterSettings(
upstream_urls=("http://worker-a", "http://worker-b"), local_gpus="none", worker_refresh_interval_seconds=0
@@ -1062,7 +1064,7 @@ def test_router_batch_uses_independent_workers_and_task_capabilities(tmp_path: P
def test_worker_upload_renews_result_lease_after_long_transfer(tmp_path: Path) -> None:
"""Router 转传超过内部租约长度时,上传完成会保护刚生成的子结果。"""
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash")
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",))
with TestClient(app) as client:
task = _submit(client, [("a.html", HTML)], hashes=False)
record = app.state.task_store._records[task["task_id"]]
@@ -1096,7 +1098,7 @@ def test_router_ends_local_result_lease_even_if_worker_rejects_release(tmp_path:
"""保留期结束后 worker 拒绝释放请求也不能永久保留过期的本地路由。"""
from mineru.kit.router.tasks import maintain_task_result_leases
- worker = api_server.create_app(upload_dir=str(tmp_path), tier="flash")
+ worker = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",))
transport = _WorkerTransport({"worker-a": worker})
app = create_router(
RouterSettings(upstream_urls=("http://worker-a",), local_gpus="none", worker_refresh_interval_seconds=0),
@@ -1206,7 +1208,7 @@ def test_router_lease_timeout_does_not_expire_other_worker_results(tmp_path: Pat
from mineru.kit.router import tasks as router_tasks
workers = {
- host: api_server.create_app(upload_dir=str(tmp_path / host), tier="flash", retention_seconds=1)
+ host: api_server.create_app(upload_dir=str(tmp_path / host), tiers=("flash",), retention_seconds=1)
for host in ("worker-a", "worker-b")
}
transport = _WorkerTransport(workers)
diff --git a/tests/unittest/test_task_file_states.py b/tests/unittest/test_task_file_states.py
index 70e7218a..7003ab9c 100644
--- a/tests/unittest/test_task_file_states.py
+++ b/tests/unittest/test_task_file_states.py
@@ -65,7 +65,7 @@ def test_url_preparation_does_not_block_ready_files_or_use_upload_expiry(
closed.set()
_install_downloads(monkeypatch, lambda _: httpx.Response(200, stream=Source()))
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash", concurrency=1)
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",), concurrency=1)
try:
with TestClient(app) as client:
remote = _url_task(client)
@@ -116,7 +116,7 @@ def test_ready_url_inputs_wait_in_pending_with_bounded_preparation(
monkeypatch.setattr(api_server, "parse_async", infer)
_install_downloads(monkeypatch, download)
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash", concurrency=1)
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",), concurrency=1)
try:
with TestClient(app) as client:
blocking = [("blocker.html", b"<html><body>blocker</body></html>")]
@@ -167,7 +167,7 @@ def test_file_duration_includes_preparation_but_excludes_queue_wait(tmp_path: Pa
_install_downloads(monkeypatch, download)
monkeypatch.setattr(api_server, "parse_async", infer)
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash", concurrency=1)
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",), concurrency=1)
with TestClient(app) as client:
client.portal.call(app.state.execution_store._semaphore.acquire)
task = _url_task(client)
diff --git a/tests/unittest/test_task_http.py b/tests/unittest/test_task_http.py
index e17b6272..a9130472 100644
--- a/tests/unittest/test_task_http.py
+++ b/tests/unittest/test_task_http.py
@@ -97,12 +97,12 @@ def live_service(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[_Li
execution_apps: list[FastAPI] = []
try:
if request.param == "api":
- app = api_server.create_app(upload_dir=str(tmp_path / "api"), tier="flash", api_key="test-key")
+ app = api_server.create_app(upload_dir=str(tmp_path / "api"), tiers=("flash",), api_key="test-key")
execution_apps.append(app)
else:
for index in range(2):
worker_app = api_server.create_app(
- upload_dir=str(tmp_path / f"worker-{index}"), tier="flash", api_key="test-key"
+ upload_dir=str(tmp_path / f"worker-{index}"), tiers=("flash",), api_key="test-key"
)
execution_apps.append(worker_app)
worker = _Server(worker_app)
@@ -223,7 +223,7 @@ def test_pdf_without_file_id_keeps_metadata_and_cached_results(live_service: _Li
def test_router_keeps_tls_proxy_headers_on_the_public_hop_only(tmp_path: Path) -> None:
"""TLS 终止代理后的上传、hash 复用及下载保持可用,worker 不继承客户端来源头。"""
calls: list[tuple[str, str, dict[str, str]]] = []
- worker_app = api_server.create_app(upload_dir=str(tmp_path / "worker"), tier="flash", api_key="test-key")
+ worker_app = api_server.create_app(upload_dir=str(tmp_path / "worker"), tiers=("flash",), api_key="test-key")
worker_app.add_middleware(_WorkerRequests, calls=calls)
worker = _Server(worker_app)
servers = [worker]
@@ -720,6 +720,7 @@ def _cloud_apps(state: _CloudState) -> tuple[FastAPI, FastAPI]:
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,
"files": manifest,
"ready": {item["file_id"] for item in manifest if item.get("sha256sum") in state.cache},
"upload_version": 0,
@@ -819,6 +820,25 @@ def cloud() -> Iterator[_CloudState]:
storage_server.stop()
[email protected]("tier", [None, "basic", "advanced"])
+def test_example_script_forwards_optional_tier(cloud: _CloudState, tmp_path: Path, tier: str | None) -> None:
+ """执行真实示例脚本,验证缺省不发送 tier、显式选档不由客户端替换。"""
+ source = tmp_path / "input.pdf"
+ source.write_bytes(b"%PDF-script-protocol")
+ env = _script_env(tmp_path, cloud.gateway_url)
+ if tier is None:
+ env.pop("MINERU_TIER")
+ else:
+ env["MINERU_TIER"] = tier
+ result = _run_script(env, source)
+ assert result.returncode == 0, result.stdout + result.stderr
+ body = cloud.tasks["cloud_1"]["request"]
+ if tier is None:
+ assert "tier" not in body
+ else:
+ assert body["tier"] == tier
+
+
@pytest.mark.parametrize("cache_mode", ["none", "mixed", "all", "no_hash"])
def test_same_client_works_with_saas_and_oss(cloud: _CloudState, tmp_path: Path, cache_mode: str) -> None:
"""通用客户端只向网关发送清单,文件和 ZIP 都直接走对象存储。"""
diff --git a/tests/unittest/test_task_outputs.py b/tests/unittest/test_task_outputs.py
index 41561a85..ceee88e8 100644
--- a/tests/unittest/test_task_outputs.py
+++ b/tests/unittest/test_task_outputs.py
@@ -171,7 +171,7 @@ def test_all_task_output_combinations(
@pytest.mark.parametrize("formats", [["docx"], ["html"], ["default"], ["latex"]])
def test_task_formats_use_only_service_authentication(tmp_path: Path, formats: list[str]) -> None:
"""启用 Key 时四种格式都需要服务认证,通过认证后都可执行。"""
- app = api_server.create_app(upload_dir=str(tmp_path), tier="flash", api_key="secret")
+ app = api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",), api_key="secret")
with TestClient(app) as client:
body = {"files": [{"file_name": "a.html", "bytes": len(HTML)}], "output_formats": formats}
assert client.post("/v1/tasks", json=body).status_code == 401
diff --git a/tests/unittest/test_task_response_contract.py b/tests/unittest/test_task_response_contract.py
index 9398f185..eadcff91 100644
--- a/tests/unittest/test_task_response_contract.py
+++ b/tests/unittest/test_task_response_contract.py
@@ -45,9 +45,10 @@ def _mixed_inputs() -> list[tuple[str, bytes]]:
def _service(tmp_path: Path, deployment: str) -> FastAPI:
"""创建完整本地或双 worker Router 服务,复用真实上传和后台执行流程。"""
if deployment == "api":
- return api_server.create_app(upload_dir=str(tmp_path / "api"), tier="standard")
+ return api_server.create_app(upload_dir=str(tmp_path / "api"), tiers=("flash", "basic", "standard", "advanced"))
workers = {
- name: api_server.create_app(upload_dir=str(tmp_path / name), tier="standard") for name in ("worker-a", "worker-b")
+ name: api_server.create_app(upload_dir=str(tmp_path / name), tiers=("flash", "basic", "standard", "advanced"))
+ for name in ("worker-a", "worker-b")
}
return create_router(
RouterSettings(
@@ -126,7 +127,7 @@ def test_missing_actual_metadata_does_not_fabricate_requested_tier(tmp_path: Pat
)
monkeypatch.setattr(api_server, "parse_async", infer)
- with TestClient(api_server.create_app(upload_dir=str(tmp_path), tier="flash")) as client:
+ with TestClient(api_server.create_app(upload_dir=str(tmp_path), tiers=("flash",))) as client:
inputs = [("input.html", b"<p>missing metadata</p>")]
task = _submit(client, inputs)
_upload(client, task, inputs)
diff --git a/tests/unittest/test_task_tiers.py b/tests/unittest/test_task_tiers.py
new file mode 100644
index 00000000..b458dd45
--- /dev/null
+++ b/tests/unittest/test_task_tiers.py
@@ -0,0 +1,353 @@
+"""Tasks 默认选档、原生格式归一化和逐跳档位固定的跨部署回归。"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+import zipfile
+from collections.abc import AsyncIterator
+from contextlib import AsyncExitStack, asynccontextmanager
+from pathlib import Path
+from typing import Any
+from unittest.mock import patch
+
+import httpx
+import pytest
+from fastapi import FastAPI
+from test_task_response_contract import _mixed_inputs
+
+from mineru.integrations.docvortex import build_metadata
+from mineru.kit.router import RouterSettings, create_app as create_router
+from mineru.parser import api_server
+from mineru.parser.base import ParseResult
+from mineru.parser.tier import runtime_options_for_tier
+from mineru.tasks.contracts import TaskFileInput, UploadTaskOptions
+from mineru.tasks.errors import ApiServerError
+from mineru.tasks.service import TERMINAL_TASK_STATUSES, resolve_task_tier
+from mineru.types import TIERS, MiddleJson, PageInfo, Tier, select_default_quality_tier
+
+
+class _RecordingTransport(httpx.AsyncBaseTransport):
+ """使用真实 ASGI 服务,并记录 Router 在每一跳发送的文件档位。"""
+
+ def __init__(self, apps: dict[str, FastAPI], submissions: list[tuple[str, dict[str, Any]]]) -> None:
+ """共享提交记录,应用生命周期由测试统一管理。"""
+ self.transports = {name: httpx.ASGITransport(app=app) for name, app in apps.items()}
+ self.submissions = submissions
+
+ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+ """按主机转发真实协议,保留请求正文供逐文件断言使用。"""
+ if request.method == "POST" and request.url.path == "/v1/tasks":
+ self.submissions.append((request.url.host, json.loads(await request.aread())))
+ return await self.transports[request.url.host].handle_async_request(request)
+
+
+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
+async def _deployment(
+ tmp_path: Path, deployment: str, capabilities: dict[str, tuple[Tier, ...]]
+) -> AsyncIterator[tuple[httpx.AsyncClient, FastAPI, list[FastAPI], list[tuple[str, dict[str, Any]]]]]:
+ """在同一事件循环启动本地、Router 或级联服务,确保任务完整关闭。"""
+ submissions: list[tuple[str, dict[str, Any]]] = []
+ apps: list[FastAPI] = []
+ async with AsyncExitStack() as stack:
+ workers: dict[str, FastAPI] = {}
+ for name, tiers in capabilities.items():
+ with patch.object(api_server, "ensure_tier_runtime_dependencies"):
+ worker = api_server.create_app(upload_dir=str(tmp_path / name), tiers=tiers)
+ await stack.enter_async_context(worker.router.lifespan_context(worker))
+ workers[name] = worker
+ apps.append(worker)
+ app = next(iter(workers.values()))
+ if deployment != "api":
+ app = create_router(
+ RouterSettings(
+ upstream_urls=tuple(f"http://{name}" for name in workers),
+ local_gpus="none",
+ worker_refresh_interval_seconds=0,
+ ),
+ transport=_RecordingTransport(workers, submissions),
+ )
+ await stack.enter_async_context(app.router.lifespan_context(app))
+ apps.append(app)
+ if deployment == "cascade":
+ app = create_router(
+ RouterSettings(upstream_urls=("http://inner",), local_gpus="none", worker_refresh_interval_seconds=0),
+ transport=_RecordingTransport({"inner": app}, submissions),
+ )
+ await stack.enter_async_context(app.router.lifespan_context(app))
+ apps.append(app)
+ client = await stack.enter_async_context(
+ httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://entry")
+ )
+ yield client, app, apps, submissions
+
+
+def _request_body(inputs: list[tuple[str, bytes]], options: dict[str, Any]) -> dict[str, Any]:
+ """保留 tier 缺省与 null 的区别,避免通用测试助手自动补上 flash。"""
+ return {"files": [{"file_name": name, "bytes": len(data)} for name, data in inputs], **options}
+
+
+async def _complete(client: httpx.AsyncClient, task: dict[str, Any], inputs: list[tuple[str, bytes]]) -> dict[str, Any]:
+ """上传真实源文件并等待终态,执行和结果获取均经过公共接口。"""
+ for item, (_name, data) in zip(task["files"], inputs):
+ response = await client.put(item["upload"]["url"], content=data, headers=item["upload"]["headers"])
+ assert response.status_code == 200, response.text
+ async with asyncio.timeout(20):
+ while True:
+ response = await client.get(f"/v1/tasks/{task['task_id']}")
+ assert response.status_code == 200, response.text
+ result = response.json()
+ if result["status"] in TERMINAL_TASK_STATUSES:
+ return result
+ await asyncio.sleep(0.01)
+
+
+async def _archive(client: httpx.AsyncClient, item: dict[str, Any]) -> dict[str, bytes]:
+ """下载并读取真实产物,用元数据和文本验证最终执行路径。"""
+ response = await client.get(item["result_url"])
+ assert response.status_code == 200, response.text
+ with zipfile.ZipFile(io.BytesIO(response.content)) as archive:
+ return {name: archive.read(name) for name in archive.namelist()}
+
+
+def _stub_inference(monkeypatch: pytest.MonkeyPatch) -> list[tuple[str, Tier]]:
+ """仅替代 PDF/图片推理,原生文档继续使用真实解析和导出。"""
+ original = api_server.parse_async
+ calls: list[tuple[str, Tier]] = []
+
+ async def infer(path: str, **kwargs: Any) -> ParseResult:
+ """记录实际入参并生成对应档位结果,不将请求值填入响应层。"""
+ suffix = Path(path).suffix
+ tier: Tier = kwargs["tier"]
+ calls.append((suffix, tier))
+ if suffix not in {".pdf", ".png"}:
+ return await original(path, **kwargs)
+ effort = {"flash": "flash", "basic": "medium", "standard": "high", "advanced": "xhigh"}[tier]
+ return ParseResult(
+ MiddleJson(
+ pages=[PageInfo(page_idx=0)],
+ is_full_document=True,
+ metadata={"file_suffix": "pdf", "producer": {"name": "mineru", "version": "test"}},
+ extensions=build_metadata(effort=effort, parse_mode="txt"),
+ )
+ )
+
+ monkeypatch.setattr(api_server, "parse_async", infer)
+ return calls
+
+
+ "tiers,expected",
+ [
+ (TIERS, "standard"),
+ (("standard",), "standard"),
+ (("basic", "standard"), "standard"),
+ (("basic", "advanced"), "basic"),
+ (("flash", "basic"), "basic"),
+ (("flash",), "flash"),
+ (("flash", "advanced"), "flash"),
+ (("advanced",), None),
+ ((), None),
+ ],
+)
+def test_task_default_tier_matrix(tiers: tuple[Tier, ...], expected: Tier | None) -> None:
+ """覆盖非连续能力集合,Tasks 默认值包含 flash 且永远不自动选 advanced。"""
+ inputs = [TaskFileInput(file_name="input.pdf", bytes=1)]
+ if expected is None:
+ with pytest.raises(ApiServerError) as error:
+ resolve_task_tier(UploadTaskOptions(), inputs, set(tiers))
+ assert error.value.status_code == 503
+ assert error.value.error.code == "quality_tier_unavailable"
+ assert "pass tier explicitly" in str(error.value)
+ else:
+ assert resolve_task_tier(UploadTaskOptions(), inputs, set(tiers)) == expected
+
+
[email protected]("tier", TIERS)
+def test_task_explicit_tier_is_not_upgraded_or_downgraded(tier: Tier) -> None:
+ """显式档位只校验是否存在,原生文档则固定归一为 flash。"""
+ inputs = [TaskFileInput(file_name="input.pdf", bytes=1)]
+ assert resolve_task_tier(UploadTaskOptions(tier=tier), inputs, set(TIERS)) == tier
+ assert resolve_task_tier(UploadTaskOptions(tier=tier), inputs, {tier}) == tier
+ with pytest.raises(ApiServerError) as error:
+ resolve_task_tier(UploadTaskOptions(tier=tier), inputs, set(TIERS) - {tier})
+ assert error.value.status_code == 400 and error.value.error.param == "tier"
+ native = [TaskFileInput(file_name="input.docx", bytes=1)]
+ assert resolve_task_tier(UploadTaskOptions(tier=tier), native, {"flash"}) == "flash"
+
+
[email protected]("deployment", ["api", "router"])
+ "tiers,options,names,status,param",
+ [
+ (("flash",), {}, ["input.pdf", "input.docx"], 202, None),
+ (("flash",), {"tier": None}, ["input.pdf"], 202, None),
+ (("flash",), {"tier": "advanced"}, ["input.pdf", "input.docx"], 400, "tier"),
+ (("flash",), {"tier": ""}, ["input.docx"], 400, "tier"),
+ (("flash",), {"tier": "unknown"}, ["input.docx"], 400, "tier"),
+ (("advanced",), {}, ["input.pdf"], 503, None),
+ (("standard",), {}, ["input.pdf", "input.docx"], 400, "files"),
+ ],
+)
+def test_task_tier_preflight_and_schema(
+ tmp_path: Path,
+ deployment: str,
+ tiers: tuple[Tier, ...],
+ options: dict[str, Any],
+ names: list[str],
+ status: int,
+ param: str | None,
+) -> None:
+ """真实创建接口在分配任务和上传链接前拒绝非法或不可执行的请求。"""
+
+ async def scenario() -> None:
+ """同时检查运行时行为和 OpenAPI 的可选字段描述。"""
+ async with _deployment(tmp_path, deployment, {"worker": tiers}) as (client, app, apps, submissions):
+ schema = (await client.get("/openapi.json")).json()
+ request = schema["paths"]["/v1/tasks"]["post"]["requestBody"]["content"]["application/json"]["schema"]
+ assert "tier" not in request["required"]
+ assert "standard, basic, flash" in request["properties"]["tier"]["description"]
+ response = await client.post("/v1/tasks", json=_request_body([(name, b"x") for name in names], options))
+ assert response.status_code == status, response.text
+ if status == 202:
+ record = app.state.task_store._records[response.json()["task_id"]]
+ assert record.options.tier == "flash"
+ else:
+ assert response.json()["error"]["param"] == param
+ assert response.json()["error"]["code"] == ("quality_tier_unavailable" if status == 503 else "invalid_request")
+ assert all(not service.state.task_store._records for service in apps)
+ assert not submissions
+ assert "files" not in response.json()
+
+ asyncio.run(scenario())
+
+
[email protected]("deployment", ["api", "router", "cascade"])
+ "options,expected", [({}, "standard"), ({"tier": None}, "standard"), ({"tier": "advanced"}, "advanced")]
+)
+def test_mixed_task_tiers_across_deployments(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, deployment: str, options: dict[str, Any], expected: Tier
+) -> None:
+ """异构 worker 和级联 Router 对混合文件保留同一选档,原生产物执行真实解析。"""
+ calls = _stub_inference(monkeypatch)
+
+ async def scenario() -> None:
+ """检查接单记录、各跳请求、推理参数和最终产物中的档位。"""
+ capabilities = (
+ {"worker": TIERS} if deployment == "api" else {"quality": ("basic", "standard", "advanced"), "native": ("flash",)}
+ )
+ async with _deployment(tmp_path, deployment, capabilities) as (client, app, apps, submissions):
+ inputs = _mixed_inputs()
+ response = await client.post("/v1/tasks", json=_request_body(inputs, options))
+ assert response.status_code == 202, response.text
+ task = response.json()
+ assert app.state.task_store._records[task["task_id"]].options.tier == expected
+ result = await _complete(client, task, inputs)
+ assert result["status"] == "completed", result
+ assert "tier" not in result
+ assert dict(calls) == {".pdf": expected, ".png": expected, ".html": "flash", ".docx": "flash"}
+ assert [item["parse"]["tier"] for item in result["files"]] == [expected, "flash", "flash", expected]
+ for index, item in enumerate(result["files"]):
+ archive = await _archive(client, item)
+ middle = json.loads(archive["middle_json.json"])
+ assert middle["extensions"]["mineru"]["tier"] == item["parse"]["tier"]
+ if index in {1, 2}:
+ assert (b"Mixed task HTML" if index == 1 else b"Mixed task DOCX") in archive["markdown.md"]
+ 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")
+ for service in apps:
+ if hasattr(service.state, "execution_store"):
+ for execution in service.state.execution_store._executions.values():
+ native = Path(execution.request.file_name).suffix in {".html", ".docx"}
+ assert execution.request.tier == ("flash" if native else expected)
+
+ asyncio.run(scenario())
+
+
[email protected]("deployment", ["api", "router", "cascade"])
+def test_native_only_task_ignores_unavailable_explicit_tier(tmp_path: Path, deployment: str) -> None:
+ """纯原生文档携带未开放的 advanced 时仍按 flash 完成,并保存归一化选项。"""
+
+ async def scenario() -> None:
+ """使用真实 HTML 和 DOCX 验证单一 flash 部署的参数作用域。"""
+ async with _deployment(tmp_path, deployment, {"native": ("flash",)}) 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
+ task = response.json()
+ assert app.state.task_store._records[task["task_id"]].options.tier == "flash"
+ result = await _complete(client, task, inputs)
+ assert result["status"] == "completed", result
+ assert all(item["parse"]["tier"] == "flash" for item in result["files"])
+ assert all(body["tier"] == "flash" for _host, body in submissions)
+
+ asyncio.run(scenario())
+
+
[email protected]("deployment", ["api", "router", "cascade"])
[email protected]("remove_selected", [False, True])
+def test_accepted_task_keeps_tier_when_capabilities_change(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, deployment: str, remove_selected: bool
+) -> None:
+ """接单后的能力变化不重新选档;原档位失效时按文件失败而不自动切换。"""
+ calls = _stub_inference(monkeypatch)
+
+ async def scenario() -> None:
+ """在等待上传期间增加 standard 或移除 basic,复现后续转发的选择边界。"""
+ async with _deployment(tmp_path, deployment, {"worker": ("flash", "basic")}) as (client, app, apps, _submissions):
+ inputs = [_mixed_inputs()[0]]
+ response = await client.post("/v1/tasks", json=_request_body(inputs, {}))
+ assert response.status_code == 202, response.text
+ task = response.json()
+ record = app.state.task_store._records[task["task_id"]]
+ assert record.options.tier == "basic"
+ changed: tuple[Tier, ...] = ("flash", "standard") if remove_selected else ("flash", "basic", "standard")
+ for service in apps:
+ if hasattr(service.state, "execution_store"):
+ _set_tiers(service, changed)
+ else:
+ await service.state.worker_pool.refresh_all()
+ result = await _complete(client, task, inputs)
+ assert record.options.tier == "basic"
+ assert result["status"] == ("failed" if remove_selected else "completed"), result
+ if remove_selected:
+ assert not calls and "parse" not in result["files"][0]
+ else:
+ assert calls == [(".pdf", "basic")]
+ assert result["files"][0]["parse"]["tier"] == "basic"
+
+ asyncio.run(scenario())
+
+
[email protected]("deployment", ["api", "router"])
+def test_flash_only_server_parses_real_pdf_without_tier(tmp_path: Path, deployment: str) -> None:
+ """真实文本 PDF 不指定 tier 即可完成 flash 解析、轮询和产物下载。"""
+
+ async def scenario() -> None:
+ """检查下载后的正文和产品元数据,不替换 PDF 解析入口。"""
+ async with _deployment(tmp_path, deployment, {"worker": ("flash",)}) as (client, _app, _apps, _submissions):
+ inputs = [_mixed_inputs()[0]]
+ response = await client.post("/v1/tasks", json=_request_body(inputs, {"ocr_mode": "txt"}))
+ assert response.status_code == 202, response.text
+ result = await _complete(client, response.json(), inputs)
+ assert result["status"] == "completed", result
+ item = result["files"][0]
+ assert item["parse"]["tier"] == "flash"
+ archive = await _archive(client, item)
+ assert b"Mixed task PDF" in archive["markdown.md"]
+ assert json.loads(archive["middle_json.json"])["extensions"]["mineru"]["tier"] == "flash"
+
+ asyncio.run(scenario())
diff --git a/tests/unittest/test_tasks_sdk.py b/tests/unittest/test_tasks_sdk.py
index d9d0d63b..13bdcb0a 100644
--- a/tests/unittest/test_tasks_sdk.py
+++ b/tests/unittest/test_tasks_sdk.py
@@ -19,7 +19,7 @@ from mineru.parser import api_client
from mineru.tasks.contracts import CreateTaskRequest
from mineru.parser.task_outputs import build_task_output
from mineru.parser.base import ParseResult
-from mineru.types import MiddleJson, PageInfo
+from mineru.types import MiddleJson, PageInfo, Tier
from mineru.integrations.docvortex import build_metadata
from docvortex.schema import Producer
@@ -87,8 +87,9 @@ def parse(parser: MinerUApiParser, source: Path, asynchronous: bool, **kwargs: A
@pytest.mark.parametrize("asynchronous", [False, True])
@pytest.mark.parametrize("prefix", ["", "/gateway/api"])
[email protected]("tier", [None, "basic", "advanced"])
def test_task_query_uses_configured_prefix_without_status_url(
- tmp_path: Path, monkeypatch: pytest.MonkeyPatch, asynchronous: bool, prefix: str
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, asynchronous: bool, prefix: str, tier: Tier | None
) -> None:
"""响应不含查询链接时仍能轮询,代理前缀和编码后的任务 ID 均不丢失。"""
source = tmp_path / "file.pdf"
@@ -103,6 +104,11 @@ def test_task_query_uses_configured_prefix_without_status_url(
assert request.headers.get("authorization") == "Bearer secret"
if request.method == "POST":
assert request.url.path == prefix + "/v1/tasks"
+ body = json.loads(request.content)
+ if tier is None:
+ assert "tier" not in body
+ else:
+ assert body["tier"] == tier
snapshot = task_snapshot("pending")
else:
queries.append(request.url.raw_path.decode())
@@ -113,7 +119,7 @@ def test_task_query_uses_configured_prefix_without_status_url(
return httpx.Response(200, json=snapshot)
bind_transport(monkeypatch, handle)
- result = parse(MinerUApiParser(api_url="https://api.test" + prefix, api_key="secret"), source, asynchronous)
+ result = parse(MinerUApiParser(api_url="https://api.test" + prefix, api_key="secret", tier=tier), source, asynchronous)
assert len(result.pages) == 1 and len(queries) == 1
diff --git a/tests/unittest/test_v1_router.py b/tests/unittest/test_v1_router.py
index fc886131..8330a4f8 100644
--- a/tests/unittest/test_v1_router.py
+++ b/tests/unittest/test_v1_router.py
@@ -120,7 +120,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 ["--tier", "basic"] == command[command.index("--tier") : command.index("--tier") + 2]
+ assert ["--tiers", "flash,basic"] == command[command.index("--tiers") : command.index("--tiers") + 2]
assert ["--concurrency", "3"] == command[command.index("--concurrency") : command.index("--concurrency") + 2]
assert "--preload-models" in command
diff --git a/tests/unittest/test_vlm_config.py b/tests/unittest/test_vlm_config.py
index cae39514..285185b1 100644
--- a/tests/unittest/test_vlm_config.py
+++ b/tests/unittest/test_vlm_config.py
@@ -160,7 +160,7 @@ def test_vlm_app_and_parser_snapshot_configuration(tmp_path: Path, monkeypatch:
monkeypatch.setattr(api_server, "ensure_tier_runtime_dependencies", lambda tier, **kwargs: None)
settings = VlmConfig(server_url="http://remote.test", model="alias")
monkeypatch.setattr(api_server.get_config().model, "vlm", settings)
- app = api_server.create_app(upload_dir=str(tmp_path))
+ app = api_server.create_app(tiers=("flash", "basic", "standard", "advanced"), upload_dir=str(tmp_path))
parser = MinerUParser()
local_parser = MinerUParser(vlm_config=VlmConfig())
settings.model = "changed"
diff --git a/tests/unittest/test_vlm_remote.py b/tests/unittest/test_vlm_remote.py
index 6e0c95c8..29252f53 100644
--- a/tests/unittest/test_vlm_remote.py
+++ b/tests/unittest/test_vlm_remote.py
@@ -221,11 +221,18 @@ def test_remote_preload_failure_is_reported(
"""预加载认证失败通过现有健康和能力错误暴露,未预加载时保持懒连接。"""
monkeypatch.setattr(api_server, "ensure_tier_runtime_dependencies", lambda tier, **kwargs: None)
settings = _settings(openai_server, api_key="wrong-key")
- lazy = api_server.create_app(upload_dir=str(tmp_path / "lazy"), vlm_config=settings)
+ lazy = api_server.create_app(
+ tiers=("flash", "basic", "standard", "advanced"), upload_dir=str(tmp_path / "lazy"), vlm_config=settings
+ )
with TestClient(lazy) as client:
assert client.get("/v1/health").status_code == 200
assert openai_server.requests == []
- preloaded = api_server.create_app(upload_dir=str(tmp_path / "preload"), vlm_config=settings, preload_models=True)
+ preloaded = api_server.create_app(
+ tiers=("flash", "basic", "standard", "advanced"),
+ upload_dir=str(tmp_path / "preload"),
+ vlm_config=settings,
+ preload_models=True,
+ )
with TestClient(preloaded) as client:
for endpoint in ("health", "tiers", "models"):
response = client.get(f"/v1/{endpoint}")
@@ -330,7 +337,7 @@ def test_api_job_through_http_vlm_to_middle_json(
app = api_server.create_app(
upload_dir=str(tmp_path / "api"),
api_key="inbound-key",
- no_flash=True,
+ tiers=("basic", "standard", "advanced"),
vlm_config=_settings(openai_server),
)
with TestClient(app, headers={"Authorization": "Bearer inbound-key"}) as client: