Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
refactor(api): 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.mdindex 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.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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/v1mineru-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.mdindex 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.mdindex 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.mdindex eaffc4f1..0c0ab9db 100644--- a/docs/next/cli/mineru-kit.md+++ b/docs/next/cli/mineru-kit.md@@ -42,7 +42,7 @@```bashmineru-openai-server --engine vllm --host 127.0.0.1 --port 30000mineru-models-download --tier standard --source modelscope-mineru-api --host 127.0.0.1 --port 8000 --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.mdindex 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.mdindex 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` 返回,默认选档及错误规则见上文。### 对缓存和 locatordiff --git a/docs/next/glossary.md b/docs/next/glossary.mdindex 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.mdindex 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.mdindex 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.mdindex 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`。如果系统找不到 `basP0 不做基于启发式的自动提示或自动排队升级。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.pyindex beff0ebd..90d6e288 100644--- a/mineru/doclib/background/parse_server_health.py+++ b/mineru/doclib/background/parse_server_health.py@@ -17,7 +17,7 @@ import httpxfrom ...config import LogConfig, ManagedParseServerConfig, get_configfrom ...parser.api_client import should_trust_env_for_url-from ...types import DEPLOYMENT_TIERS, TIERS, DeploymentTier, Tier+from ...types import TIERS_BY_SERVER_TIER, DEPLOYMENT_TIERS, TIERS, DeploymentTier, Tierfrom ...parser.process_control import ManagedProcessControlfrom ...utils.stdio import utf8_subprocess_envfrom ..config_defaults import CONFIG_DEFAULTS@@ -59,20 +59,14 @@ async def get_managed_parse_server_tier(config_svc: "ConfigService") -> Deploymedef 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.pyindex 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 clickimport typerfrom ...parser import api_server as parser_api_server-from ...types import SERVER_TIERS, ServerTierfrom ...utils.i18n import tfrom ...utils.logger import configure_global_log_levelfrom ...utils.stdio import configure_standard_streamsfrom ..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.pyindex 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 ClientDisconnectfrom starlette.types import ASGIApp, Receive, Scope, Sendfrom ...task_types import TASK_OUTPUT_FORMATS+from ...types import TIERSfrom .models import GatewayError, ParseOptions, Recordfrom .service import FileParseServicefrom .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.pyindex e4df7241..24ba7c4e 100644--- a/mineru/kit/file_parse/client.py+++ b/mineru/kit/file_parse/client.py@@ -15,6 +15,7 @@ import httpxfrom pydantic import ValidationErrorfrom ...task_types import task_status_url+from ...tasks.contracts import ErrorResponsefrom .models import GatewayError, Record, RemoteCreatedTask, RemoteFile, RemoteTaskfrom .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 errorif method == "POST":diff --git a/mineru/kit/gradio/client.py b/mineru/kit/gradio/client.pyindex 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_enfrom ...parser.base import ParseResultfrom ...parser.page_range import normalize_page_range_inputfrom ...parser.process_control import ManagedProcessControl-from ...types import SERVER_TIERS, TIERS, ServerTier, Tier+from ...types import TIERS_BY_SERVER_TIER, SERVER_TIERS, TIERS, ServerTier, Tierfrom ...utils.stdio import utf8_subprocess_envfrom .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.pyindex 25aa25af..b23f11d6 100644--- a/mineru/kit/router/tasks.py+++ b/mineru/kit/router/tasks.py@@ -18,7 +18,7 @@ from fastapi.exceptions import RequestValidationErrorfrom fastapi.responses import JSONResponsefrom pydantic import ValidationError-from ...filetypes import is_flash_only_parse_extension+from ...filetypes import batch_effective_parse_tier, is_flash_only_parse_extensionfrom ...tasks.contracts import (CancelTaskResponse,CreateTaskResponse,@@ -32,7 +32,6 @@ from ...tasks.contracts import (from ...tasks.errors import ApiServerError, raise_api_errorfrom ...tasks.execution import TaskExecution, TaskInputMetadata, TaskUploadfrom ...tasks.service import TERMINAL_TASK_STATUSES, file_chunks, resolve_task_tier-from ...types import select_default_quality_tierfrom ...utils.async_utils import drain_futurefrom .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.pyindex 00717b42..36f7d13e 100644--- a/mineru/kit/router/workers.py+++ b/mineru/kit/router/workers.py@@ -21,7 +21,7 @@ from loguru import loggerfrom ...model.runtime.device import get_devicefrom ...parser.process_control import ManagedProcessControl-from ...types import SERVER_TIERS, ServerTier, Tier+from ...types import TIERS_BY_SERVER_TIER, SERVER_TIERS, ServerTier, Tierfrom ...utils.stdio import utf8_subprocess_envfrom ...utils.retention import resolve_retention_seconds@@ -205,8 +205,8 @@ class ManagedLocalWorker:str(port),"--upload-dir",str(upload_dir),- "--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.pyindex 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 resultdiff --git a/mineru/model/runtime/onnx_calibration_cache.py b/mineru/model/runtime/onnx_calibration_cache.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 86bbe3dd..8cfd24c3 100644--- a/mineru/parser/api_server.py+++ b/mineru/parser/api_server.py@@ -16,6 +16,7 @@ import shutilimport tempfileimport threadingimport time+from collections.abc import Collectionfrom contextlib import asynccontextmanagerfrom copy import deepcopyfrom 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, Tierfrom ..utils.async_utils import drain_future, run_syncfrom ..model.runtime.ownership import RuntimeOwner, runtime_ownerfrom ..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_tiersfrom .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_timestfrom ..tasks.http import build_task_routerfrom ..tasks.service import TaskStore-_DEFAULT_API_SERVER_TIER: ServerTier = "standard"_MAX_URL_BYTES_DEFAULT = 209715200logger = 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:returnsettings = vlm_config if vlm_config is not None else get_config().model.vlmif 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@asynccontextmanagerasync 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_tierapplication.state.default_tier = default_tier- application.state.flash_enabled = not no_flash+ application.state.flash_enabled = "flash" in server_tiersapplication.state.tier_runtime_options = tier_runtime_optionsapplication.state.model_ids = [_VIRTUAL_MODEL_ID]application.state.model_registered_at = _model_registered_at@@ -1904,7 +1874,6 @@ def create_app(application.state.max_url_bytes = max_url_bytesapplication.state.allow_http_source = allow_http_sourceapplication.state.api_key = _api_key- application.state.effort = effortapplication.state.image_analysis = image_analysisapplication.state.preload_models = preload_modelsapplication.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_tierapplication.state.default_tier = default_tier- application.state.flash_enabled = not no_flash+ application.state.flash_enabled = "flash" in server_tiersapplication.state.tier_runtime_options = tier_runtime_optionsapplication.state.model_ids = [_VIRTUAL_MODEL_ID]application.state.model_registered_at = _model_registered_at@@ -2033,7 +2003,6 @@ def create_app(application.state.max_url_bytes = max_url_bytesapplication.state.allow_http_source = allow_http_sourceapplication.state.api_key = _api_key- application.state.effort = effortapplication.state.image_analysis = image_analysisapplication.state.preload_models = preload_modelsapplication.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.pynew file mode 100644index 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.pyindex 53b41c03..8fa75cfe 100644--- a/mineru/parser/task_backend.py+++ b/mineru/parser/task_backend.py@@ -7,6 +7,7 @@ from dataclasses import replacefrom fastapi import Request+from ..filetypes import batch_effective_parse_tierfrom ..tasks.contracts import TaskFileInput, TaskFileItem, UploadTaskOptionsfrom ..tasks.errors import invalid_task_requestfrom ..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.pyindex 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.pyindex 61b30ee5..866721ca 100644--- a/mineru/tasks/service.py+++ b/mineru/tasks/service.py@@ -23,24 +23,29 @@ from .execution import TaskBackend, TaskExecution, TaskUpload, execution_timestaTASK_UPLOAD_TTL = 3600TERMINAL_TASK_STATUSES = frozenset({"completed", "partial", "failed", "canceled"})+_DEFAULT_TASK_TIER_SELECTION_ORDER: tuple[Tier, ...] = ("standard", "basic", "flash")logger = logging.getLogger(__name__)-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.pyindex 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) == 6gc.collect()diff --git a/tests/unittest/test_api_offline_docs.py b/tests/unittest/test_api_offline_docs.pyindex 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_serverdef 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 == 404diff --git a/tests/unittest/test_doclib_cache_semantics.py b/tests/unittest/test_doclib_cache_semantics.pyindex 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) -> Ndef test_managed_api_server_args_use_tier_and_selected_port_for_process_start() -> None:assert api_server_args_for_tier("standard", host="127.0.0.1", port=16580) == [- "--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: pydef _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 cmdassert 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.pyindex 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, monkecleanup.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.pyindex 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 TaskClientfrom mineru.kit.file_parse.models import ParseOptions, Record, fingerprintfrom mineru.kit.file_parse.settings import originfrom mineru.kit.file_parse.store import RecordStore+from mineru.types import Tierdef 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) -> Noneassert 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) -> Nonassert 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"] == 3600assert 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.pyindex 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.pyindex 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.pyindex 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 == 0assert seen["prog_name"] == "mineru-kit api-server"assert seen["standalone_mode"] is False- assert [seen["args"][index + 1] for index, item in enumerate(seen["args"]) if item == "--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"] = argsseen["prog_name"] = prog_nameseen["standalone_mode"] = standalone_mode@@ -691,24 +691,27 @@ def test_api_server_without_tier_lets_parser_api_apply_standard_default(monkeypaassert result.exit_code == 0assert seen["prog_name"] == "mineru-kit api-server"assert seen["standalone_mode"] is False+ assert seen["args"][seen["args"].index("--tiers") + 1] == "auto"assert "--tier" not in seen["args"]assert "--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.outputdef test_api_server_rejects_removed_language_option() -> None:diff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.pyindex 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: pytestmonkeypatch.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.Moreturn middle, modelmonkeypatch.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 commandassert "--no-advanced" not in commandassert "--preload-models" in commanddiff --git a/tests/unittest/test_model_backend_selection.py b/tests/unittest/test_model_backend_selection.pyindex 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 messagewith 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) == messagewith pytest.raises(InvalidRequestError) as doclib_error:diff --git a/tests/unittest/test_onnx_calibration.py b/tests/unittest/test_onnx_calibration.pyindex 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"] == 2request = 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.pyindex 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, monkapp = create_app(upload_dir=str(tmp_path))- assert app.state.tier == "standard"+ assert app.state.model_tier == "standard"assert app.state.concurrency == 1assert app.state.url_timeout == 60assert app.state.allow_http_source is Falseassert 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 Trueassert 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 Noneassert [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: pdef 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 Falseassert [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 == defaultdef 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_craise 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: Pathmonkeypatch.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 == 200assert calls == ["basic"]@@ -930,7 +923,7 @@ def test_api_server_standard_jobs_use_requested_tier(tmp_path: Path, monkeypatchmonkeypatch.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, monkeypsource.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.Monmonkeypatch.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.Monkemonkeypatch.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(monkeypatmonkeypatch.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_macomonkeypatch.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: pytesmonkeypatch.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 Falseassert 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: pdef 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_namesassert "--backend" not in option_namesassert "--language" not in option_namesassert "--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_tierseen["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_tierseen["effort_by_tier"] = {@@ -1220,7 +1217,7 @@ def test_api_server_cli_accepts_single_tier_and_no_flash(monkeypatch: pytest.Monmonkeypatch.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 == 0assert 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 == 0assert 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 == 0assert 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.outputdef 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_outputassert "flash" in normalized_outputassert "basic" in normalized_outputassert "standard" in normalized_outputassert "advanced" in normalized_output- assert "--no-advanced" in normalized_output+ assert "--no-advanced" not in normalized_output+ assert "--no-flash" not in normalized_outputassert "--backend" not in normalized_outputassert "--effort" not in normalized_outputassert "hybrid-engine" not in normalized_outputdiff --git a/tests/unittest/test_parser_api_ocr.py b/tests/unittest/test_parser_api_ocr.pyindex 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.pyindex 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: pytdef 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: Pasource = 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.pyindex 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"] == expecteddef 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.pyindex 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: lidef 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.outputargs = forwarded.call_args.kwargs["args"]diff --git a/tests/unittest/test_router_balancing.py b/tests/unittest/test_router_balancing.pyindex 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_paupstream = _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.MonkeyPareturn 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.pyindex 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.pyindex 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.Monkedef 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.pyindex 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[Tdef 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: Pdef 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: Patfrom mineru.kit.router import tasks as router_tasksworkers = {- 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.pyindex 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.pyindex 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[_Liexecution_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: _Lidef 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.pyindex 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 == 401diff --git a/tests/unittest/test_task_response_contract.py b/tests/unittest/test_task_response_contract.pyindex 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.pynew file mode 100644index 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.pyindex 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_clientfrom mineru.tasks.contracts import CreateTaskRequestfrom mineru.parser.task_outputs import build_task_outputfrom mineru.parser.base import ParseResult-from mineru.types import MiddleJson, PageInfo+from mineru.types import MiddleJson, PageInfo, Tierfrom mineru.integrations.docvortex import build_metadatafrom 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"] == tiersnapshot = 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) == 1diff --git a/tests/unittest/test_v1_router.py b/tests/unittest/test_v1_router.pyindex 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 commanddiff --git a/tests/unittest/test_vlm_config.py b/tests/unittest/test_vlm_config.pyindex 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.pyindex 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 == 200assert 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: