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(runtime): simplify automatic tier recommendations
myhlolid0440c1698bc
diff --git a/docs/en/usage/tiers.md b/docs/en/usage/tiers.mdindex bf591639..905dc26c 100644--- a/docs/en/usage/tiers.md+++ b/docs/en/usage/tiers.md@@ -66,6 +66,8 @@ mineru-kit hardware info --jsondetect shares API startup recommendations and may perform applicable ONNX calibration. info reads hardware, installed runtimes, effective configuration, and calibration records without benchmarking, downloading weights, or writing configuration.+Automatic API/WebUI tiers use the small-model backend’s device decision: GPU enables all four tiers; CPU with at least 10 available logical cores enables up to Standard, 4–9 cores up to Basic, and fewer than 4 cores only Flash. Recommendations do not query GPU memory capacity. Standard is the default request tier when available; CPU does not automatically enable Advanced. An explicit startup ceiling bypasses automatic recommendation.+## Resources and platform boundariesNative text parsing needs no inference models. Basic can run on CPU. Standard / Advanced speed and memory depend on the VLM engine, input size, and concurrency. Plan for at least 16 GB of system memory for higher-throughput local deployment. NVIDIA deployments also need an engine-supported GPU, driver, and sufficient free VRAM; 8 GB is only a planning starting point, not a guarantee for every workload.diff --git a/docs/next/api/changes.md b/docs/next/api/changes.mdindex 90f8b9d4..4d1c5cda 100644--- a/docs/next/api/changes.md+++ b/docs/next/api/changes.md@@ -8,7 +8,7 @@ API 启动改为 `--tier auto|flash|basic|standard|advanced`,移除 `--tiers`Python `create_app(tiers=...)` 保留精确 PDF/图片集合,模型依赖及预加载仍按实际需求合并。HTTP 请求默认、逐文件实际档位和产物协议保持原规则。-`--tier auto`(包括省略参数)按有效小模型后端分流。CPU 可用逻辑核至少 4 时默认开放到 Basic;GPU 经既有选型确认可用且对应显存/预算至少 5.5 GiB 时,才开放 Standard/Advanced,且不额外要求 4 核。Torch、Apple Metal 及符合既有绑定规则的独显免测速,其他 ONNX 候选仍要求有效校准胜出。Windows/Linux 在 CPU 达标或存在内存达标的兼容 GPU 候选时同步完成适用 ONNX 选型,最终 CPU 或失败结果不能凭静态库存重新升级。无需启用 `--preload-models`,首次校准可能准备或下载 OCR rec 模型。显式启动档位以及已保存的设备选择不强制测速;模型预加载与请求默认选档顺序保持原规则。+`--tier auto`(包括省略参数)直接消费小模型后端的设备结论,取消显存容量门槛。GPU 开放全部四档;CPU 可用逻辑核至少 10 开放到 Standard,4–9 核开放到 Basic,不足 4 核只开放 Flash。Torch 使用经过验证的加速设备可用性;ONNX 在所有核数下同步完成现有设备选型,复用缓存、显式配置、独显免校准和适用的 OCR 校准。推荐不额外扫描显卡库存或要求历史性能证据。无需启用 `--preload-models`,首次校准可能准备或下载 OCR rec 模型。显式启动档位跳过推荐,模型依赖预检、可选预加载及请求默认选档顺序保持原规则。新增 `mineru-kit hardware detect [--json]` 和 `hardware info [--json]`,分别用于同源推荐与只读问题反馈诊断。软件版本只展示指定清单内已安装的包;没有 `--quiet` 或 `auto-tier` 别名。diff --git a/docs/next/cli/mineru-kit-api-server.md b/docs/next/cli/mineru-kit-api-server.mdindex fe0374d3..29f7599f 100644--- a/docs/next/cli/mineru-kit-api-server.md+++ b/docs/next/cli/mineru-kit-api-server.md@@ -56,27 +56,26 @@ Tasks 的请求 `tier` 仍可选,只对 PDF/图片生效。省略或 JSON `nul省略 `--tier` 等价于 `--tier auto`。启动时取推荐集合的最高档作为上限并展开,运行中不重新选档:-| 硬件条件 | 启动上限 | PDF/图片公开集合 |-|----------|----------|------------------|-| 进程可用 CPU 数不足 4,且无达标 GPU | flash | `flash` |-| 进程可用 CPU 数至少 4,且无达标 GPU | basic | `flash,basic` |-| GPU 已确认可用,且选定设备显存/预算至少 5.5 GiB(CPU 核数不限) | advanced | 全部四档 |+| 设备结论 | 进程可用逻辑核数 | 启动上限 | PDF/图片公开集合 | 请求默认档位 |+|----------|------------------|----------|------------------|--------------|+| GPU | 不限 | advanced | 全部四档 | standard |+| CPU | 至少 10 | standard | `flash,basic,standard` | standard |+| CPU | 4–9 | basic | `flash,basic` | basic |+| CPU | 不足 4 | flash | `flash` | flash |-CPU 数按逻辑 CPU 计算,并考虑进程亲和性和 Linux cgroup 配额。集显沿用有效 OCR 校准的 GPU 时间不高于 CPU 时间 0.8 倍的判定。探测失败或设备身份不明确时按 CPU 条件推荐。显式上限可以覆盖推荐,随后仍执行正常依赖预检。+CPU 数沿用进程可用逻辑核数,考虑亲和性和 Linux cgroup 配额。计数失败回退 1 核并给出警告,不影响已确认的 GPU 结果。CPU 不自动开放 Advanced。显式上限可以覆盖推荐,随后仍执行正常依赖预检。-5.5 GiB 按 `5_905_580_032` 字节比较,不四舍五入、不累加多卡,也不使用 `MINERU_VIRTUAL_VRAM_SIZE`。独显读取专用显存总量;Apple 统一内存使用 Metal 推荐工作集,Windows/Linux 集显分别使用 DXGI 本地预算与 Vulkan `heapBudget`。预算比较使用上限,不减去当前用量;未知预算不以系统总内存替代。容量证据可通过 `mineru-kit hardware detect --json` 的 `gpu_memory` 查看。+自动推荐先解析有效小模型后端。Torch(包括 auto 最终选择 Torch)使用经过可用性验证的 CUDA/ROCm、MPS、XPU 等加速设备,开放全部四档;显式 CPU、设备不可用或探测失败时按 CPU 核数推荐。该分支不调用 ONNX 选型、不下载校准模型或改写其配置/记录。-GPU 类型与 OCR 和硬件诊断使用共享分类;小模型后端可见且原生身份确认的独显可以免测速,但仍须满足 5.5 GiB 内存门槛才能开放 Standard/Advanced。未知类型、虚拟 GPU 和无法唯一关联的设备不能直接获得独显免校准资格。推荐不查询 llama.cpp 库存,也不受其专用后端设置影响;llama 自动模式消费小模型的 CPU/GPU 结论,具体显卡由原生引擎选择。+ONNX 分支直接调用现有设备选择入口,不再进行显卡库存初选或显存检查。无论 CPU 核数多少,均在发布服务能力前完成适用选型:GPU 开放全部四档,CPU 按表中核数规则推荐。不受支持平台的 CPU 回退由 ONNX 入口处理,不额外探测 Apple Metal。显式 `--tier` 和 Python 精确集合跳过自动推荐。-自动推荐先解析有效小模型后端。Torch(包括 auto 最终选择 Torch)验证实际设备可用性及容量:选中 CUDA/MPS/XPU 等设备的显存/预算至少 5.5 GiB 时推荐 advanced;显式 CPU 或设备不可用时按 CPU 条件推荐,不下载 ONNX 校准模型或改写其配置/记录。Torch 推荐不依赖 llama.cpp 库存。--ONNX 分支先探测硬件并读取已有校准记录。如果 CPU 至少 4 核或存在内存达标的兼容 GPU 候选,Windows/Linux 会在发布服务能力前同步执行现有 ONNX 设备选择流程,再根据实际选择和容量确定最终上限。CPU 不足 4 核且无内存达标候选、macOS 及其他平台跳过这一步;显式 `--tier` 和 Python 精确集合也不触发这项启动校准。+推荐与 llama.cpp 自动模式复用相同的小模型设备选择入口,不读取 llama 专用参数,也不增加显卡匹配或独立测速。显存容量未知、偏小或查询失败均不参与推荐;`hardware detect --json` 为兼容保留 `gpu_memory: null`。启动选型继续遵守 `model.onnx_device`:`auto` 才按设备策略决定是否测速,显式或已保存的 `cpu/gpu` 不强制重新校准。Windows 确认的独显,以及 Linux 通过兼容检查、由 Vulkan 唯一识别并配置物理绑定的独显,均跳过 OCR 校准;首次真实 GPU 会话成功后才保存设备偏好。集显或类型无法确认的候选继续按 0.8 阈值测速。需要测速时会按正常模型生命周期准备或下载 OCR rec 权重,并复用已有进程缓存、文件锁、采样阈值及失败回退。下载和模型准备不计入 15 秒校准子进程超时。校准失败或结果不稳定不会阻止后续推荐,但不作为 GPU 胜出证据。-实际 OCR 校准把证据保存在 `<配置文件路径>.onnx-calibration.json`,仅复用设备、运行时版本与 CPU 配置匹配的有效结果;旧 cpu/gpu 偏好及手动 GPU 设置不视为校准证据。启动阶段产生的新证据在本次最终推荐中生效,之后 `/v1/tiers` 在服务生命周期内固定。+实际 OCR 校准把证据保存在 `<配置文件路径>.onnx-calibration.json`。自动推荐直接采用本次设备结论,历史记录只供诊断,不额外要求有效性能证据。显式或已保存的 `gpu` 只要实际选型为 GPU 就开放全部四档;本次 CPU 或失败结果不会被静态库存覆盖。之后 `/v1/tiers` 在服务生命周期内固定。-远程 VLM 配置不自动扩大推荐上限或放宽本机内存门槛,也不增加 VLM 性能测试。上述 OCR 选型不要求 `--preload-models`;该参数仍另外控制完整模型或 VLM 客户端的提前初始化。+远程 VLM 配置不自动扩大推荐上限,也不增加 VLM 性能测试。上述 OCR 选型不要求 `--preload-models`;该参数仍另外控制完整模型或 VLM 客户端的提前初始化。`mineru-kit hardware detect` 使用同一结构化推荐流程;`hardware info` 只读输出诊断报告,详见 [hardware 命令](mineru-kit-hardware.md)。API 工厂的 VLM 配置覆盖也参与推荐,避免与实际运行配置不一致。diff --git a/docs/next/cli/mineru-kit-hardware.md b/docs/next/cli/mineru-kit-hardware.mdindex 32f772c4..b8c973bd 100644--- a/docs/next/cli/mineru-kit-hardware.md+++ b/docs/next/cli/mineru-kit-hardware.md@@ -15,39 +15,28 @@ mineru-kit hardware info --json > hardware-info.json## 自动推荐-命令与 `api-server --tier auto` 共享结构化推荐结果。先解析有效小模型后端,再确定设备与上限:+命令与 API、WebUI 的自动启动共享结构化推荐结果。先解析有效小模型后端,再直接采用其 GPU/CPU 设备结论,不查询显存容量:-| 有效后端 | 行为 |-|----------|------|-| Torch + 可用 CUDA/MPS/XPU 等加速设备 | 跳过 OCR 测速;选定设备的显存/预算至少 5.5 GiB 时推荐 advanced,否则按 CPU 条件推荐 |-| Torch + 显式 CPU 或加速设备不可用 | 跳过测速,进程可用逻辑 CPU 至少 4 时推荐 basic,否则 flash |-| ONNX | CPU 至少 4 核或存在内存达标的兼容 GPU 候选时,在 Windows/Linux 同步完成现有设备选型;实际选中 GPU 且内存达标时开放全部四档,不再额外检查性能证据 |+| 设备结论 | 进程可用逻辑核数 | PDF/图片开放档位 | 请求默认档位 |+|----------|------------------|------------------|--------------|+| GPU | 不限 | flash、basic、standard、advanced | standard |+| CPU | 至少 10 | flash、basic、standard | standard |+| CPU | 4–9 | flash、basic | basic |+| CPU | 不足 4 | flash | flash |-自动推荐的 CPU 条件只开放 Basic:进程可用逻辑核数至少 4 时开放 `flash,basic`,默认请求 Basic,否则只开放 Flash。计数遵守进程亲和性和容器 CPU 配额。GPU 经现有选型确认可用且显存/预算至少 `5_905_580_032` 字节时,独立于 CPU 核数开放全部四档;默认请求仍为 Standard,Advanced 必须显式请求。+CPU 计数沿用进程亲和性和 Linux cgroup 配额限制。读取失败回退为 1 核并记录警告,不影响已确认的 GPU 结果。CPU 核数再多也不自动开放 Advanced。-内存检查只使用确认设备的原始字节值,不四舍五入、不累加多卡,也不读取 `MINERU_VIRTUAL_VRAM_SIZE`。独显按专用显存总量判断;Apple Metal 按推荐工作集预算,Windows 集显按 DXGI 本地预算,Linux 集显按 Vulkan `heapBudget` 判断。预算比较使用上限,不减去当前用量。不能唯一关联设备、容量未知、预算扩展不可用或查询失败时按 CPU 条件推荐;系统总内存和共享内存理论上限不能替代 GPU 预算。+Torch(包括 `small_backend=auto` 最终选择 Torch)使用经过可用性验证的加速设备结论,包括 CUDA/ROCm、MPS、XPU 等。显式 CPU、设备不可用或探测失败时按 CPU 规则推荐,并保留原因与警告。该分支不调用 ONNX 选型、不下载 OCR 校准权重,也不修改 ONNX 配置或校准记录。-Windows 原生查询不依赖 Torch。DXGI 库存通过系统 `D3DKMTOpenAdapterFromLuid` / `D3DKMTQueryAdapterInfo(KMTQAITYPE_ADAPTERADDRESS)` 补充物理 PCI 位置,内存仍来自该适配器的 DXGI 查询。ONNX 已选设备按 LUID 关联;可选 Torch/ROCm 后端的整数 PCI 字段作为部分坐标参与关联,不把 bus 编号当作完整 BDF,不猜测缺失的 domain/function。匹配优先采用 LUID 和已知 PCI 坐标,最后才使用唯一型号或名称;同名但无物理地址的条目不能覆盖明确的 PCI 匹配。无效地址、查询失败或多个同等匹配继续保留未知,不按容量大小或枚举顺序猜测。可用性和实际推理验证仍由各后端负责,读取预算成功不代表模型推理已验证。+ONNX 分支在所有 CPU 核数下调用现有 `resolve_onnx_device()`,复用进程缓存、兼容策略、显式配置和校准。Windows 确认的独显,以及 Linux 通过兼容检查、由 Vulkan 唯一识别并配置物理绑定的独显,保留免 OCR 校准路径。`onnx_device=auto` 下需要测速的候选沿用 0.8 阈值;首次可能准备或下载 OCR rec 模型。下载和派生图准备不计入 15 秒校准 worker 超时。校准失败、超时或不稳定时使用本次 CPU 结果推荐。-`small_backend=auto` 最终选择 Torch 时同样免校准。显式设备字符串必须经过实际可用性检查;检查失败会给出保守结果及原因,不修改设备配置。Torch 推荐不依赖 llama.cpp 库存,不下载 ONNX 校准权重,也不写入 `model.onnx_device` 或 OCR 校准记录。+`onnx_device=gpu` 无论来自用户配置还是先前自动选型,都不强制测速。实际选中 GPU 就开放全部四档;校准记录缺失、损坏、过期或记录 GPU 较慢均不额外阻止开放。此时推荐原因是 `configured_gpu`,校准状态为 `status=skipped, reason=configured_gpu`。记录摘要仅供诊断,读取失败附带警告,不改变设备和档位结论。`onnx_device=cpu` 及不受支持平台的 ONNX CPU 回退均遵循 CPU 规则;ONNX 分支不额外探测 Apple Metal。-ONNX 分支保留既有兼容策略、0.8 阈值和进程缓存。Windows 确认的独显,以及 Linux 通过兼容检查、由 Vulkan 唯一识别并配置物理绑定的独显,均免 OCR 校准,报告 `status=skipped, reason=discrete_gpu`;首次真实 GPU 会话成功后才保存 `gpu`,硬件推荐本身不生成校准记录。`onnx_device=auto` 时,集显或类型无法确认的候选继续沿用现有设备选型测速,首次可能下载 OCR rec 模型;下载和派生图准备不计入 15 秒校准 worker 超时。校准失败、超时或不稳定导致本次设备选型回退 CPU 时,按 CPU 条件推荐,并携带警告。+推荐与 llama.cpp 自动模式复用相同的小模型设备选择入口,不读取 llama 专用参数,也不额外探测 ggml 库存或匹配显卡身份。VLM 使用其他引擎或远程服务不会自动扩大推荐上限。-`onnx_device=gpu` 无论来自用户配置还是之前的自动选型,都不触发测速;实际选中兼容 GPU 后,仅检查该设备的显存/预算是否达到 5.5 GiB。校准记录缺失、损坏、过期或记录 GPU 较慢,均不阻止内存达标的 GPU 开放 Standard/Advanced。此时推荐原因是 `configured_gpu`,校准状态为 `status=skipped, reason=configured_gpu`。内存不足或未知时报告相应内存原因。记录摘要只供诊断,读取失败会附带警告,不改变设备和档位结论。`onnx_device=cpu` 仍遵循 CPU 规则。+JSON 报告保持 `schema_version=1`,包含 `ceiling`、`pdf_image_tiers`、`default_request_tier`、`reason`、`cpu_count`、`small_backend`、`vlm_engine`、`device`、`calibration` 和 `warnings`。兼容保留 `gpu_memory` 字段,固定为 `null`;文本不再展示内存门槛。Torch 校准状态为 `status=skipped, reason=torch_backend`,不将可用性标成性能实测通过。-llama.cpp 自动模式只复用小模型后端的 CPU/GPU 结论:Torch 使用加速可用性,ONNX 使用实际选型与缓存。-显式参数优先,具体显卡由原生引擎选择;MinerU 不在推荐或引擎构造时查询 ggml 库存、匹配身份、绑定或重映射设备。-自动推荐同样不读取 llama 专用后端设置;VLM 使用其他引擎或远程服务时不会因此探测 llama。-Linux Intel 串行提交仅在自动 ONNX 路径依据已有适配器信息补充,用户环境值优先;Torch 和手动路径不自动补充。--OCR、档位推荐与诊断保留共享 GPU 分类和双向唯一身份匹配,内存查询必须对应小模型后端选中的设备。-`hardware info` 可独立探测 llama 的真实可见设备,诊断失败不会影响自动推荐。--JSON 报告保留 `schema_version=1`,包含 `ceiling`、`pdf_image_tiers`、`default_request_tier`、`reason`、`cpu_count`、`small_backend`、`vlm_engine`、`device`、`calibration` 和 `warnings`,并增补 `gpu_memory`。内存证据包含 `device`、`identity`、`memory_bytes`、`kind`(`dedicated`/`budget`/`unknown`)、`source`、`warning`;没有候选设备时为 `null`。校准状态来自执行结果;Torch 使用 `status=skipped, reason=torch_backend`,不将可用性结论标成性能实测通过。--本次实际选型落在 CPU 或选型失败时,不会凭静态显卡库存重新开放高档位。性能判断归属 ONNX 自动设备选型,auto tier 不增加独立测速或历史性能证据门槛。设备容量信息不进入 OCR 校准指纹,每次启动读取当前选定设备的内存容量。每个服务在启动阶段形成一次最终开放集合,运行过程中不动态升降档位。--开放 Advanced 后,请求省略 tier 仍默认 Standard。推荐不代表模型已准备好,API 服务继续执行依赖预检;显式启动上限和 Python 精确集合不进入自动推荐。API 工厂的 VLM 配置覆盖参与共享推荐,远程 VLM 显示为 `http-client`,不自动扩大本机上限。+每个服务在启动阶段形成一次最终开放集合,运行中不动态升降档位。选型落在 CPU 或失败时按 CPU 核数推荐,不凭静态显卡库存升级。显式启动上限和 Python 精确集合跳过自动推荐;依赖预检、可选预加载和原生文档固定 Flash 的行为保持不变。开放全部四档时请求默认仍为 Standard。## 环境报告@@ -63,6 +52,8 @@ JSON 报告保留 `schema_version=1`,包含 `ceiling`、`pdf_image_tiers`、`d未知值为 JSON `null`,文本显示“未知”。例如 Apple Silicon 通常不报告可可靠读取的 CPU 主频,统一内存也不作为独立显存。系统或容器限制导致库存不完整时保留错误说明;不从型号名称猜测设备类型或频率。+独立显存采集能力和 Windows PCI 身份修复继续保留,其结果不参与自动 tier。Windows 原生查询不依赖 Torch:DXGI 库存通过 `D3DKMTOpenAdapterFromLuid` / `D3DKMTQueryAdapterInfo(KMTQAITYPE_ADAPTERADDRESS)` 补充物理 PCI 位置,内存仍由对应适配器的 DXGI 接口读取。身份匹配优先使用 LUID 和已知 PCI 坐标,不猜测缺失字段;查询失败或多个同等匹配保留未知。读取预算成功不代表模型推理已验证。+配置报告使用明确白名单,不输出认证信息、完整远程服务地址或整个环境变量集合。诊断报告中的本地路径用于确认解释器和实际加载位置。## 退出码diff --git a/docs/next/decisions/0017-mineru-kit-api-server-command.md b/docs/next/decisions/0017-mineru-kit-api-server-command.mdindex d34e9c2c..1e488139 100644--- a/docs/next/decisions/0017-mineru-kit-api-server-command.md+++ b/docs/next/decisions/0017-mineru-kit-api-server-command.md@@ -46,7 +46,7 @@ managed 是生命周期管理方式,不是用户直接操作的独立命令产一个 API 服务进程使用 `--tier auto|flash|basic|standard|advanced` 表示 PDF/图片的最高开放档位,上限包含自身及全部较低档位;省略等价于 auto,取硬件推荐集合的最高档。Standard 上限不再隐含 Advanced。`--tiers`、`--no-flash`、`--no-advanced` 均直接移除。-自动推荐先按有效小模型后端分流:CPU 可用逻辑核至少 4 时开放到 Basic,否则只开放 Flash。GPU 经既有选型确认可用且选定设备显存/预算至少 5.5 GiB 时,独立于 CPU 核数开放全部四档。Torch、Apple Metal 和符合既有绑定规则的独显保留免测速路径;其他 ONNX GPU 仍须校准胜出。CPU 至少 4 核或存在内存达标的兼容 GPU 候选时,Windows/Linux 在本次启动内完成适用选型;最终 CPU 回退不能被静态库存覆盖。显式启动上限跳过推荐。不引入新的采样阈值或 VLM 实测,依赖预检与可选预加载仍执行。Advanced 复用 Standard 模型配置,请求默认仍优先 Standard。`hardware detect` 与服务使用相同结构化推荐及设备内存证据。+自动推荐直接消费有效小模型后端的设备结论:GPU 开放全部四档;CPU 可用逻辑核至少 10 时开放到 Standard,4–9 核开放到 Basic,否则只开放 Flash。计数沿用亲和性和容器配额,失败回退 1 核,不影响已确认的 GPU 结果。Torch 验证加速设备可用性且不调用 ONNX;ONNX 在所有核数下完成现有选型,复用缓存、显式配置、独显免校准和适用的 OCR 校准。推荐不查询显存、不增加独立测速或历史性能证据门槛;最终 CPU 结果不能被静态库存覆盖。显式启动上限跳过推荐,依赖预检与可选预加载继续执行。Advanced 复用 Standard 模型配置,请求默认仍优先 Standard。`hardware detect` 共享结构化推荐,保持 `schema_version=1`,兼容保留 `gpu_memory: null`。`/v1/tiers` 仅发布 PDF/图片可选档位。所有服务都支持现有原生文档格式,固定使用 flash;原生支持不再从公开 flash 档位推断,不新增原生能力声明。Tasks 请求 tier 继续可选,PDF/图片按 `standard -> basic -> flash` 默认选择,advanced 仅显式使用。diff --git a/docs/next/onnx-device.md b/docs/next/onnx-device.mdindex 6acfaa66..297da0bf 100644--- a/docs/next/onnx-device.md+++ b/docs/next/onnx-device.md@@ -14,12 +14,12 @@ llama.cpp 自动模式复用这里的 CPU/GPU 结论。### 共享 GPU 分类与选型-OCR、auto tier 和硬件诊断共用 `discrete / integrated / virtual / unknown` 分类。+OCR 和硬件诊断共用 `discrete / integrated / virtual / unknown` 分类;auto tier 直接复用 OCR 设备选择的最终结果。Windows 的分类依据为 D3D12 UMA,Linux 为 Vulkan 原生设备类型,macOS 复用现有系统显示设备信息。统一内存属性单独保存,不将 Apple Silicon 的集显分类解释为低性能设备。ONNX 先应用显式配置、设备可见性及兼容限制,再按“确认独显 → 确认集显 → 虚拟 GPU → 类型未知”排序;-同类设备保留 Windows 高性能排序或 Vulkan 原生顺序。显存证据只取 ONNX 实际选中的设备。+同类设备保留 Windows 高性能排序或 Vulkan 原生顺序。自动 tier 不再查询显存容量。身份匹配优先使用 LUID、PCI 地址,再使用双方唯一的厂商/设备型号;名称只用于原生库存的唯一关联。重复库存或原生查询失败时保留未知类型,不据此授予独显免校准资格。@@ -99,7 +99,7 @@ MinerU 的 WebGPU 运行时锁覆盖过滤与会话初始化,后续每次会本机双卡及仅 Intel ICD 的验证见 [Intel 架构过滤报告](onnx-intel-architecture-policy-validation.md)。-通常在首次实际使用 ONNX 模型时选型。API 使用 `--tier auto`(或省略),有效小模型后端为 ONNX,且可用逻辑 CPU 至少 4 核或存在显存/预算达到 5.5 GiB 的兼容 GPU 候选时,Windows/Linux 会提前同步调用相同的设备选择流程,并直接采用本次设备选型结果,不依赖 `--preload-models`。实际选中 GPU 且内存达标时开放 Standard/Advanced;auto tier 不增加独立测速,也不额外检查历史校准是否胜出。`onnx_device=gpu` 无论来自用户偏好还是自动选型写入,均免测速,校准记录缺失、损坏、过期或 GPU 较慢不阻止内存达标的已选 GPU 开放高级档位。CPU 不足 4 核且无内存达标 GPU 候选、显式启动档位或 macOS 不增加这项启动选型。有效小模型后端为 Torch 时采用实际设备可用性和内存证据并跳过 OCR 校准,不修改 ONNX 设备偏好或证据;llama.cpp 自动模式也遵循这处分流,且不要求另一次显卡匹配。+通常在首次实际使用 ONNX 模型时选型。API/WebUI 使用自动 tier 且有效小模型后端为 ONNX 时,会在所有 CPU 核数下提前同步调用相同的设备选择流程,不依赖 `--preload-models`。选中 GPU 就开放全部四档;选中 CPU 时,可用逻辑核至少 10 开放到 Standard,4–9 核开放到 Basic,不足 4 核只开放 Flash。推荐不查询显存、不增加独立测速,也不额外要求历史校准证据。`onnx_device=gpu` 无论来自用户偏好还是自动选型写入,均不强制测速。显式启动档位和 Python 精确集合跳过推荐。有效小模型后端为 Torch 时采用已验证的加速设备结论,不调用 ONNX 或修改其配置/证据。llama.cpp 自动模式也复用相同的小模型设备选择入口。`mineru-kit hardware detect` 与 API 自动启动共享推荐逻辑;`hardware info` 只读报告环境与校准记录,不测速。界面启动本身、导入 SDK、查询配置和模型列表不会运行测速;界面托管的 API 服务仍遵循其启动参数。自动决策成功后原子更新有效配置文件中的 `model.onnx_device`,保留其余键;进程间通过文件锁协调。@@ -107,7 +107,7 @@ MinerU 的 WebGPU 运行时锁覆盖过滤与会话初始化,后续每次会实际设备或物理绑定改变后,诊断报告会显示旧记录不再匹配;这不会覆盖配置中的设备偏好,也不会单独限制已选 GPU 的档位。Windows/Linux 免校准独显都只在首次真实 GPU 会话成功后保存 `gpu`;仅运行硬件推荐时仍保留 `auto`,不下载校准权重、不生成性能校准记录。初始化错误或静默回退 CPU 不保存 GPU 偏好。-环境变量覆盖不写入文件;只读配置保留本进程选择。测速失败不保存为 CPU 性能优胜,同进程不重复尝试。写入 `onnx_device=gpu` 不要求达到 5.5 GiB,该内存门槛只用于 auto tier 开放 Standard/Advanced;较小的 GPU 仍可用于 ONNX 加速。+环境变量覆盖不写入文件;只读配置保留本进程选择。测速失败不保存为 CPU 性能优胜,同进程不重复尝试。设备偏好和自动 tier 均不设置显存容量门槛。Linux 插件缺失、没有可用设备、物理绑定失败、校准超时或输出不一致时保留 `auto`。通过环境变量强制 `auto` 时,每个新进程重新选择,并使用选择锁避免同时测速。显式或已保存的 `cpu` 不会因后来接入独显而改变。@@ -135,8 +135,8 @@ MinerU 才在初始化期间补充 `GGML_VK_SERIALIZE_SUBMISSIONS=1`。依据来临时环境设置使用互斥锁并在成功或异常后恢复;不生成 `GGML_VK_VISIBLE_DEVICES`。离线 server 仍禁止为自动选型下载校准模型,缺少本地权重时沿用现有 ONNX CPU 回退。-档位推荐只看小模型后端、其实际选型及显存预算,不受 llama 专用后端参数或诊断失败影响。-CPU 核数、5.5 GiB 显存门槛及默认 Standard 的规则保持不变。+档位推荐只消费小模型后端的 GPU/CPU 结论和进程可用逻辑核数,不受 llama 专用后端参数或诊断失败影响。+GPU 开放全部四档;CPU 至少 10 核开放到 Standard,至少 4 核开放到 Basic,否则只开放 Flash。存在 Standard 时请求默认仍为 Standard。## 模型预设diff --git a/docs/next/open-questions.md b/docs/next/open-questions.mdindex 0c22d1df..6785bf96 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` 配置最高开放档位;省略等价于 auto,CPU 至少 4 核默认开放 basic,GPU 确认可用且显存/预算至少 5.5 GiB 才开放更高档位;Torch 免校准,ONNX 在 CPU 或 GPU 候选达标时同步完成适用选型,HTTP 请求默认仍优先 standard;`hardware detect` 共享推荐逻辑。 |+| api-server tier | `mineru-kit api-server --tier` 配置最高开放档位;省略等价于 auto,直接消费小模型设备结论:GPU 开放四档,CPU 至少 10 核开放到 standard,4–9 核到 basic,不足 4 核到 flash。取消显存门槛;Torch 免校准,ONNX 在所有核数下完成现有选型。HTTP 请求默认仍优先 standard;`hardware detect` 共享推荐逻辑。 || 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/tiers.md b/docs/next/tiers.mdindex 68dbf31d..f891bfc1 100644--- a/docs/next/tiers.md+++ b/docs/next/tiers.md@@ -100,11 +100,11 @@ advanced 仅在它是服务唯一可用档位时自动选择。显式指定的 P### 3.4 API 服务启动推荐-`--tier auto` 或省略启动参数时,进程可用逻辑 CPU 至少 4 核默认开放 flash、basic,否则只开放 flash;计数遵守亲和性和容器配额。只有实际 GPU 已经确认可用,并且选中设备的专用显存总量或 GPU 内存预算至少 5.5 GiB,才开放 standard、advanced。GPU 达标不要求 CPU 同时达到 4 核;开放全部四档时请求默认仍为 standard。+`--tier auto` 或省略启动参数时,推荐直接采用小模型后端的 GPU/CPU 结论:GPU 开放全部四档,默认请求 Standard;CPU 可用逻辑核至少 10 时开放到 Standard,4–9 核开放到 Basic,不足 4 核只开放 Flash。CPU 默认请求该集合中的最高档位,不自动开放 Advanced。计数沿用亲和性和容器配额限制,读取失败回退 1 核并保留警告,不影响已确认的 GPU 结果。-自动推荐先解析有效小模型后端。Torch(包括 auto 最终选择 Torch)、Apple Metal 和符合既有确认与绑定规则的独显保留免 OCR 测速路径。CPU 至少 4 核或存在内存达标的兼容 GPU 候选时,Windows/Linux 在本次启动内完成现有 ONNX 设备选型:`onnx_device=auto` 保留适用的性能校准,`onnx_device=gpu` 无论来自手动配置还是先前自动选型都不测速。auto tier 直接采用实际选型结果,GPU 内存达标即开放全部四档,不再额外要求独显类型或校准胜出记录;历史记录缺失、损坏、过期或 GPU 较慢均不影响已选 GPU 的档位判断。最终选中 CPU、选型失败、设备身份不明确或内存未知时按 CPU 条件推荐,静态 GPU 库存不能覆盖最终结果。+Torch 使用已验证的加速设备可用性,包括 CUDA/ROCm、MPS、XPU 等,不调用 ONNX 校准。ONNX 在所有 CPU 核数下完成现有设备选型,复用缓存、显式配置和独显免校准策略;`onnx_device=auto` 保留适用的性能校准,显式或已保存的 `cpu/gpu` 不强制测速。推荐不增加独立测速或历史性能证据门槛。最终选中 CPU 或选型失败时按 CPU 核数推荐,静态 GPU 库存不能覆盖结果。-显存按原始字节比较,不取整、不累加多卡,不使用虚拟显存覆盖。统一/共享内存使用 Metal 推荐工作集、DXGI 本地预算或 Vulkan `heapBudget`,不以系统总内存替代。最终集合在启动时固定;`mineru-kit hardware detect` 共享推荐与内存证据,`hardware info` 只读收集环境信息。+自动推荐不查询显存容量或预算,不额外探测 Apple Metal;Torch/MPS 正常按加速设备处理。最终集合在启动时固定;`mineru-kit hardware detect` 共享推荐结果,JSON 保留 `schema_version=1` 和 `gpu_memory: null`。`hardware info` 继续只读收集环境信息,独立显存采集能力保留。`--tier standard` 等显式上限开放自身和全部较低档位,允许覆盖硬件推荐。`/v1/tiers` 只约束 PDF/图片,原生文档在任何正常可用服务上均固定使用 flash。请求默认仍优先 standard;仅开放 advanced 的精确集合以 advanced 为默认档位。详见 [启动配置与迁移说明](cli/mineru-kit-api-server.md)。diff --git a/docs/zh/usage/tiers.md b/docs/zh/usage/tiers.mdindex 51f5b2ac..e1cc2e43 100644--- a/docs/zh/usage/tiers.md+++ b/docs/zh/usage/tiers.md@@ -66,6 +66,8 @@ mineru-kit hardware info --jsondetect 与 API 自动启动共用推荐逻辑,可能执行适用的 ONNX 校准;info 只读采集硬件、已安装运行时、有效配置和校准记录,不测速、不下载权重、不写配置。+API/WebUI 的自动 tier 采用小模型后端的设备结论:GPU 开放全部四档;CPU 可用逻辑核至少 10 时开放到 Standard,4–9 核开放到 Basic,不足 4 核只开放 Flash。自动推荐不查询显存容量。开放 Standard 时默认请求 Standard,CPU 不自动开放 Advanced。显式启动上限跳过自动推荐。+## 资源与平台边界原生文本解析不需要推理模型。Basic 可在 CPU 运行;Standard / Advanced 的速度和内存占用取决于 VLM 引擎、输入规模和并发。高吞吐本地部署建议至少 16 GB 系统内存;NVIDIA 部署还需要所选引擎支持的显卡、驱动和足够可用显存,8 GB 仅作为规划起点,不是所有任务的保证。diff --git a/mineru/kit/commands/hardware.py b/mineru/kit/commands/hardware.pyindex fb4a05ca..40eb1032 100644--- a/mineru/kit/commands/hardware.py+++ b/mineru/kit/commands/hardware.py@@ -37,15 +37,6 @@ def render_detection(data: dict[str, Any]) -> str:f"实际设备:{data['device']}",f"校准状态:{calibration['status']} ({calibration['reason']})",]- memory = data.get("gpu_memory")- if memory is not None:- lines.extend(- [- f"GPU 内存设备:{memory['device']},身份:{_value(memory['identity'])}",- f"GPU 内存:{_value(memory['memory_bytes'])} bytes,口径:{memory['kind']},来源:{memory['source']}",- "Standard/Advanced 内存门槛:5.5 GiB (5905580032 bytes)",- ]- )lines.extend(f"提示:{warning}" for warning in data.get("warnings", []))return "\n".join(lines)diff --git a/mineru/model/runtime/tier_recommendation.py b/mineru/model/runtime/tier_recommendation.pyindex e8f1bd6f..0934d127 100644--- a/mineru/model/runtime/tier_recommendation.py+++ b/mineru/model/runtime/tier_recommendation.py@@ -1,10 +1,9 @@# Copyright (c) Opendatalab. All rights reserved.-"""通过现有设备选型与选定 GPU 的内存预算,确定 API 服务开放档位。"""+"""通过小模型后端的实际设备选择与可用 CPU 数确定 API 服务开放档位。"""from __future__ import annotations-import sys-from dataclasses import dataclass, replace+from dataclasses import dataclassfrom typing import TYPE_CHECKINGfrom loguru import logger@@ -12,13 +11,10 @@ from loguru import loggerfrom ...types import TIERS, Tier, select_default_task_tierfrom .cpu_threads import effective_cpu_countfrom .device import resolve_small_model_backend, resolve_torch_device-from .gpu import is_discrete_gpu-from .gpu_memory import GpuMemory, native_gpu_memory, torch_gpu_memoryfrom .onnx_calibration_cache import CalibrationInfo, inspect_calibration_recordif TYPE_CHECKING:from ...config import VlmConfig- from .onnx_device import OnnxSelection@dataclass(frozen=True)@@ -45,113 +41,32 @@ class TierRecommendation:calibration: CalibrationDecisionwarnings: tuple[str, ...] = ()schema_version: int = 1- gpu_memory: GpuMemory | None = None+ # 保留 JSON 字段兼容性;自动推荐不再查询或消费显存容量。+ gpu_memory: None = None@dataclass(frozen=True)class TierHardware:- """与设备探测隔离的推荐依据,便于完整覆盖各类硬件组合。"""+ """与设备选型隔离的推荐依据,便于覆盖 CPU 阈值和 GPU 结果。"""cpu_count: intadvanced_gpu: bool = Falsereason: str = "cpu"- gpu_memory: GpuMemory | None = Nonedef tiers_for_hardware(hardware: TierHardware) -> frozenset[Tier]:- """按已确定的工程阈值计算集合,达标 GPU 同时开放所有较低档位。"""- if hardware.advanced_gpu and hardware.gpu_memory is not None and hardware.gpu_memory.sufficient:+ """GPU 开放全部档位;CPU 至少 4 核开放 Basic,至少 10 核开放 Standard。"""+ if hardware.advanced_gpu:return frozenset(TIERS)+ if hardware.cpu_count >= 10:+ return frozenset(TIERS[:3])if hardware.cpu_count >= 4:- return frozenset(("flash", "basic"))+ return frozenset(TIERS[:2])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 _gpu_hardware(count: int, confirmed: bool, reason: str, memory: GpuMemory) -> TierHardware:- """把设备确认和容量阈值合并为一次可解释的推荐。"""- if confirmed and not memory.sufficient:- reason = "gpu_memory_unknown" if memory.memory_bytes is None else "gpu_memory_insufficient"- return TierHardware(count, confirmed and memory.sufficient, reason, memory)---def _onnx_gpu_hardware(count: int, choice: OnnxSelection | None = None) -> TierHardware:- """初选只读候选和旧证据;最终推荐严格采用本次选型,CPU 或失败不能被库存升级。"""- from ...config import get_config-- if choice is not None and (choice.device != "gpu" or choice.adapter is None):- return TierHardware(count, reason=choice.reason)- if sys.platform == "darwin":- if _apple_metal_available():- return _gpu_hardware(count, True, "apple_silicon_metal", torch_gpu_memory("mps"))- return TierHardware(count)- if sys.platform not in {"linux", "win32"}:- return TierHardware(count)- if choice is None and get_config().model.onnx_device == "cpu":- return TierHardware(count, reason="configured_cpu")-- if choice is not None:- adapter = choice.adapter- elif sys.platform == "win32":- from .windows_gpu import discover_gpus, preferred_gpu-- adapter = preferred_gpu(discover_gpus())- else:- from .webgpu import discover_webgpu_devices, select_webgpu_device-- adapter = select_webgpu_device(discover_webgpu_devices())- if adapter is None:- return TierHardware(count, reason="no_eligible_gpu")- memory = native_gpu_memory(adapter.identity, device=f"{choice.backend if choice else 'onnx'}:gpu")- if choice is not None:- # 性能判断属于 ONNX 自动选型;已选 GPU 仅需满足内存门槛,不再要求历史校准证据。- reason = "ocr_calibrated_gpu" if choice.reason == "rec_calibration" else choice.reason- return _gpu_hardware(count, True, reason, memory)- if get_config().model.onnx_device == "gpu":- # 初选保留内存候选,让低 CPU 配额也能进入实际设备选型,配置本身不确认设备可用。- return TierHardware(count, reason="configured_gpu", gpu_memory=memory)-- from .onnx_calibration_cache import calibrated_gpu_is_faster- from .onnx_device import ONNX_GPU_TIME_RATIO_THRESHOLDS- from .webgpu import WebGPUDevice-- threshold = ONNX_GPU_TIME_RATIO_THRESHOLDS["webgpu" if sys.platform == "linux" else "dml"]- if threshold is None:- return TierHardware(count, reason="no_eligible_gpu")- discrete = is_discrete_gpu(adapter) and (- not isinstance(adapter, WebGPUDevice) or adapter.vulkan_device == (adapter.vendor_id, adapter.device_id)- )- calibrated = calibrated_gpu_is_faster(adapter, threshold)- reason = "discrete_gpu" if discrete else "ocr_calibrated_gpu" if calibrated else "gpu_calibration_required"- return _gpu_hardware(count, discrete or calibrated, reason, memory)---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:- return _onnx_gpu_hardware(count)- except Exception as error:- logger.warning("GPU tier recommendation unavailable; using CPU rules: {}", error)- return TierHardware(count, reason="gpu_discovery_unavailable")--def recommend_tiers(*, vlm_config: VlmConfig | None = None) -> TierRecommendation:- """先分流实际小模型后端;Torch 免测速,ONNX 初选达标后同步完成既有选型。"""+ """复用小模型后端的实际设备结论,不额外探测 GPU 库存、显存或性能。"""from ...config import get_configfrom ..vlm.selector import resolve_vlm_engine@@ -160,41 +75,32 @@ def recommend_tiers(*, vlm_config: VlmConfig | None = None) -> TierRecommendatiosmall_backend = resolve_small_model_backend()vlm_engine = "http-client" if settings.server_url else resolve_vlm_engine(settings.engine)warnings: list[str] = []+ try:+ count = effective_cpu_count()+ except OSError as error:+ count = 1+ warnings.append(f"CPU availability discovery failed: {error}")+device = "cpu"- calibration = CalibrationDecision("skipped", "not_required")if small_backend == "torch":choice = resolve_torch_device()- try:- count = effective_cpu_count()- except OSError as error:- count = 1- warnings.append(f"CPU availability discovery failed: {error}")- hardware = (- _gpu_hardware(count, True, choice.reason, torch_gpu_memory(choice.device))- if choice.accelerated- else TierHardware(count, reason=choice.reason)- )+ hardware = TierHardware(count, choice.accelerated, choice.reason)device = choice.devicecalibration = CalibrationDecision("skipped", "torch_backend")if choice.warning:warnings.append(choice.warning)else:- hardware = detect_tier_hardware()- if hardware.gpu_memory is not None and hardware.gpu_memory.device == "mps":- device = "mps"- calibration = CalibrationDecision("skipped", "apple_silicon_metal")- tiers = tiers_for_hardware(hardware)- gpu_candidate = hardware.gpu_memory is not None and hardware.gpu_memory.sufficient- if small_backend == "onnx" and ("basic" in tiers or gpu_candidate) and sys.platform in {"win32", "linux"}:logger.info("Automatic API tier selection is resolving the ONNX device before finalizing tiers")try:from .onnx_device import cached_onnx_device, resolve_onnx_device- # 复用模型运行时的配置、锁和缓存;显式设备选择及不兼容 GPU 不强制测速。+ # 与 llama 自动模式复用相同入口;缓存、显式配置和免校准规则均由 ONNX 选型负责。cached = cached_onnx_device()onnx_choice = resolve_onnx_device()- device = f"{onnx_choice.backend}:gpu" if onnx_choice.device == "gpu" else "cpu"- hardware = _onnx_gpu_hardware(hardware.cpu_count, onnx_choice)+ accelerated = onnx_choice.device == "gpu"+ device = f"{onnx_choice.backend}:gpu" if accelerated else "cpu"+ reason = "ocr_calibrated_gpu" if accelerated and onnx_choice.reason == "rec_calibration" else onnx_choice.reason+ hardware = TierHardware(count, accelerated, reason)try:evidence = inspect_calibration_record((onnx_choice.adapter,) if onnx_choice.adapter is not None else None)except Exception as error:@@ -218,20 +124,16 @@ def recommend_tiers(*, vlm_config: VlmConfig | None = None) -> TierRecommendatiologger.warning("Startup ONNX selection unavailable; using CPU recommendation rules: {}", error)warnings.append(f"ONNX selection unavailable: {error}")calibration = CalibrationDecision("failed", "selection_unavailable")- hardware = replace(hardware, advanced_gpu=False, reason="selection_unavailable")- # 以实际选择形成最终结果,不能重新扫描库存覆盖本次 CPU 回退。- tiers = tiers_for_hardware(hardware)- if hardware.reason == "gpu_discovery_unavailable":- warnings.append("GPU discovery unavailable; using CPU recommendation rules")- if hardware.gpu_memory is not None and hardware.gpu_memory.warning:- warnings.append(hardware.gpu_memory.warning)+ hardware = TierHardware(count, reason="selection_unavailable")++ tiers = tiers_for_hardware(hardware)+ ordered = tuple(tier for tier in TIERS if tier in tiers)logger.info("Recommended API tiers: {} (available CPUs: {}, reason: {})",- ",".join(tier for tier in TIERS if tier in tiers),+ ",".join(ordered),hardware.cpu_count,hardware.reason,)- ordered = tuple(tier for tier in TIERS if tier in tiers)default = select_default_task_tier(tiers)assert default is not None # 硬件推荐始终包含 Flash,必定存在请求默认档位。return TierRecommendation(@@ -245,7 +147,6 @@ def recommend_tiers(*, vlm_config: VlmConfig | None = None) -> TierRecommendatiodevice,calibration,tuple(warnings),- gpu_memory=hardware.gpu_memory,)@@ -253,7 +154,6 @@ __all__ = ["CalibrationDecision","TierHardware","TierRecommendation",- "detect_tier_hardware","recommend_tiers","tiers_for_hardware",]diff --git a/tests/unittest/test_gpu_policy.py b/tests/unittest/test_gpu_policy.pyindex 56166ae9..c1233674 100644--- a/tests/unittest/test_gpu_policy.py+++ b/tests/unittest/test_gpu_policy.py@@ -12,8 +12,7 @@ from unittest.mock import Mockimport pytest-from mineru.model.runtime import hardware, llama_probe, tier_recommendation, vulkan, webgpu, windows_gpu-from mineru.model.runtime.gpu_memory import GpuMemory+from mineru.model.runtime import hardware, llama_probe, vulkan, webgpu, windows_gpufrom mineru.model.runtime.gpu import (GPU_KIND_ORDER,GpuClassification,@@ -45,20 +44,10 @@ from mineru.model.runtime.hardware_types import GpuInfo, RuntimeProbedef test_native_classification_agrees_across_runtime_and_report(monkeypatch: pytest.MonkeyPatch, platform: str, classification: GpuClassification) -> None:- """同一卡的 OCR、ggml 可见设备、档位推荐和硬件报告必须采用同一个分类来源。"""- from mineru.model.runtime import onnx_calibration_cache-- for module in (llama_probe, webgpu, tier_recommendation):+ """同一卡的 OCR、ggml 可见设备和硬件报告必须采用同一个分类来源。"""+ for module in (llama_probe, webgpu):monkeypatch.setattr(module, "sys", SimpleNamespace(platform=platform))monkeypatch.delenv("MINERU_LLAMA_CPP_BACKEND", raising=False)- monkeypatch.setattr(tier_recommendation, "effective_cpu_count", lambda: 4)- from mineru.config import get_config-- monkeypatch.setattr(get_config().model, "onnx_device", "auto")- monkeypatch.setattr(- tier_recommendation, "native_gpu_memory", lambda identity, *, device: GpuMemory(device, identity, 8 * 1024**3)- )- monkeypatch.setattr(onnx_calibration_cache, "calibrated_gpu_is_faster", lambda *args: False)native = vulkan.VulkanDevice(0x1002, 1, "GPU", 0)# Windows 故意提供相反的 Vulkan 类型,确认分类权威仍是 D3D12。native = with_gpu_classification(@@ -86,7 +75,6 @@ def test_native_classification_agrees_across_runtime_and_report(assert device.kind == classification.kindassert device.kind_source == classification.kind_sourceassert device.unified_memory == classification.unified_memory- assert tier_recommendation.detect_tier_hardware().advanced_gpu is (classification.kind == "discrete")@pytest.mark.parametrize("order", list(itertools.permutations(GPU_KIND_ORDER)))diff --git a/tests/unittest/test_hardware_recommendation.py b/tests/unittest/test_hardware_recommendation.pyindex 88f5bb03..4817f4cd 100644--- a/tests/unittest/test_hardware_recommendation.py+++ b/tests/unittest/test_hardware_recommendation.py@@ -17,7 +17,7 @@ from typer.testing import CliRunnerfrom mineru.config import VlmConfig, get_configfrom mineru.kit.commands import hardware as hardware_cmdfrom mineru.kit.main import app as kit_app-from mineru.model.runtime import device, llama_device, onnx_calibration_cache, onnx_device, tier_recommendation+from mineru.model.runtime import device, gpu_memory, llama_device, onnx_calibration_cache, onnx_device, tier_recommendationfrom mineru.parser import api_serverfrom mineru.types import TIERS@@ -34,7 +34,8 @@ def torch_environment(monkeypatch: pytest.MonkeyPatch) -> Mock:monkeypatch.setattr(onnx_device, "resolve_onnx_device", forbidden)monkeypatch.setattr(onnx_calibration_cache, "save_calibration_record", forbidden)monkeypatch.setattr(onnx_calibration_cache, "invalidate_calibration_record", forbidden)- monkeypatch.setattr(tier_recommendation, "_onnx_gpu_hardware", forbidden)+ monkeypatch.setattr(gpu_memory, "native_gpu_memory", forbidden)+ monkeypatch.setattr(gpu_memory, "torch_gpu_memory", forbidden)return forbidden@@ -43,12 +44,9 @@ def _fake_torch(monkeypatch: pytest.MonkeyPatch, kind: str, available: bool, couapi = SimpleNamespace(is_available=lambda: available,device_count=lambda: count,- current_device=lambda: 0,- get_device_properties=lambda index: SimpleNamespace(total_memory=8 * 1024**3, is_integrated_gpu=False),)unavailable = SimpleNamespace(is_available=lambda: False, device_count=lambda: 0)fake = SimpleNamespace(- mps=SimpleNamespace(recommended_max_memory=lambda: 8 * 1024**3),cuda=api if kind == "cuda" else unavailable,xpu=api if kind == "xpu" else unavailable,backends=SimpleNamespace(mps=api if kind == "mps" else unavailable),@@ -82,7 +80,7 @@ def test_torch_accelerator_skips_onnx_for_every_engine(("requested", "available", "expected_warning"),[("cpu", True, False), ("cuda", False, True), ("cuda:2", True, True), ("xpu:-1", True, True)],)[email protected]("cores", [3, 4])[email protected]("cores", [1, 3, 4, 9, 10, 32])def test_torch_cpu_and_invalid_explicit_device_are_conservative(torch_environment: Mock,monkeypatch: pytest.MonkeyPatch,@@ -96,7 +94,8 @@ def test_torch_cpu_and_invalid_explicit_device_are_conservative(monkeypatch.setattr(tier_recommendation, "effective_cpu_count", lambda: cores)_fake_torch(monkeypatch, requested.split(":")[0], available)report = tier_recommendation.recommend_tiers()- assert report.device == "cpu" and report.ceiling == ("basic" if cores == 4 else "flash")+ assert report.device == "cpu"+ assert report.ceiling == ("standard" if cores >= 10 else "basic" if cores >= 4 else "flash")assert bool(report.warnings) == expected_warningassert get_config().model.small_backend == "torch"assert os.environ["MINERU_DEVICE_MODE"] == requested@@ -112,54 +111,55 @@ def test_torch_probe_exception_keeps_warning(torch_environment: Mock, monkeypatctorch_environment.assert_not_called()[email protected]("cores", [3, 4])[email protected]("cores", [1, 10])@pytest.mark.parametrize("accelerator", ["cuda", "mps", "xpu"])[email protected]("amount", [None, 5_905_580_032 - 1, 5_905_580_032, 6 * 1024**3 - 1])-def test_torch_memory_gate_preserves_onnx_isolation(- torch_environment: Mock, monkeypatch: pytest.MonkeyPatch, cores: int, accelerator: str, amount: int | None[email protected]("amount", [None, 1024**3, "error"])+def test_torch_memory_does_not_affect_recommendation(+ torch_environment: Mock, monkeypatch: pytest.MonkeyPatch, cores: int, accelerator: str, amount: int | str | None) -> None:- """真实推荐链路检查精确容量边界,内存不足和未知均不触发 ONNX。"""+ """容量偏小、未知或读取异常均不影响设备结论,且无需任何显存查询。"""monkeypatch.setattr(tier_recommendation, "effective_cpu_count", lambda: cores)monkeypatch.setenv("MINERU_DEVICE_MODE", accelerator)_fake_torch(monkeypatch, accelerator, True)+ memory = Mock(return_value=amount, side_effect=RuntimeError("memory unavailable") if amount == "error" else None)fake = sys.modules["torch"]if accelerator == "mps":- fake.mps.recommended_max_memory = lambda: amount+ fake.mps = SimpleNamespace(recommended_max_memory=memory)else:- getattr(fake, accelerator).get_device_properties = lambda index: SimpleNamespace(- total_memory=amount, is_integrated_gpu=False- )+ getattr(fake, accelerator).get_device_properties = memoryreport = tier_recommendation.recommend_tiers()- expected = TIERS if amount is not None and amount >= 5_905_580_032 else TIERS[:2] if cores >= 4 else ("flash",)- assert report.pdf_image_tiers == expected- assert report.gpu_memory.memory_bytes == amount and report.calibration.reason == "torch_backend"- assert bool(report.warnings) is (amount is None)+ assert report.pdf_image_tiers == TIERS and report.default_request_tier == "standard"+ assert report.gpu_memory is None and report.calibration.reason == "torch_backend"+ assert not report.warnings+ memory.assert_not_called()torch_environment.assert_not_called()-def test_auto_basic_api_defaults_and_rejects_higher_tiers(- torch_environment: Mock, monkeypatch: pytest.MonkeyPatch, tmp_path: Path[email protected](("cores", "expected"), [(4, TIERS[:2]), (10, TIERS[:3])])+def test_auto_cpu_api_defaults_and_rejects_higher_tiers(+ torch_environment: Mock, monkeypatch: pytest.MonkeyPatch, tmp_path: Path, cores: int, expected: tuple[str, ...]) -> None:- """经过真实推荐形成 Basic 服务,文本/JSON、能力列表和接单错误保持一致。"""- monkeypatch.setenv("MINERU_DEVICE_MODE", "cuda")- _fake_torch(monkeypatch, "cuda", True)- sys.modules["torch"].cuda.get_device_properties = lambda index: SimpleNamespace(total_memory=5_905_580_032 - 1)+ """真实 CPU 推荐驱动文本/JSON、API 能力、默认请求以及显式请求的上下界。"""+ monkeypatch.setenv("MINERU_DEVICE_MODE", "cpu")+ monkeypatch.setattr(tier_recommendation, "effective_cpu_count", lambda: cores)monkeypatch.setattr(api_server, "ensure_tier_runtime_dependencies", Mock())report = tier_recommendation.recommend_tiers()monkeypatch.setattr(hardware_cmd, "_detect_data", lambda: asdict(report))output = CliRunner().invoke(kit_app, ["hardware", "detect", "--json"])+ assert output.exit_code == 0, output.outputdata = json.loads(output.stdout)- assert data["schema_version"] == 1 and data["gpu_memory"]["memory_bytes"] == 5_905_580_032 - 1+ assert data["schema_version"] == 1 and data["gpu_memory"] is Nonerendered = hardware_cmd.render_detection(data)- assert "gpu_memory_insufficient" in rendered and "5905580031 bytes" in rendered and "torch.cuda.total_memory" in rendered+ assert f"推荐启动上限:{expected[-1]}" in rendered+ assert "5.5" not in rendered and "GPU 内存" not in renderedapp = api_server.create_app(upload_dir=str(tmp_path))with TestClient(app) as client:- assert tuple(row["id"] for row in client.get("/v1/tiers").json()["data"]) == ("flash", "basic")- for options in ({}, {"tier": None}):+ assert tuple(row["id"] for row in client.get("/v1/tiers").json()["data"]) == expected+ for options in ({}, {"tier": None}, {"tier": expected[-1]}):response = client.post("/v1/tasks", json={"files": [{"file_name": "test.pdf", "bytes": 1}], **options})assert response.status_code == 202- assert app.state.task_store._records[response.json()["task_id"]].options.tier == "basic"- for tier in ("standard", "advanced"):+ assert app.state.task_store._records[response.json()["task_id"]].options.tier == expected[-1]+ for tier in TIERS[len(expected) :]:response = client.post("/v1/tasks", json={"files": [{"file_name": "test.pdf", "bytes": 1}], "tier": tier})assert response.status_code == 400 and response.json()["error"]["code"] == "invalid_request"assert response.json()["error"]["param"] == "tier"@@ -204,4 +204,19 @@ def test_torch_llama_integrated_route_does_not_return_to_onnx(result = llama_device.resolve_llama_device()assert result.device == ("gpu" if accelerated else "cpu")assert result.environment == ()+ assert tier_recommendation.recommend_tiers().ceiling == ("advanced" if accelerated else "basic")+ torch_environment.assert_not_called()++[email protected]("accelerated", [False, True])+def test_torch_cpu_count_failure_preserves_device_result(+ torch_environment: Mock, monkeypatch: pytest.MonkeyPatch, accelerated: bool+) -> None:+ """CPU 计数异常回退一核,已验证的 Torch 加速设备仍开放全部档位。"""+ monkeypatch.setattr(tier_recommendation, "effective_cpu_count", Mock(side_effect=OSError("affinity")))+ monkeypatch.setenv("MINERU_DEVICE_MODE", "cuda" if accelerated else "cpu")+ _fake_torch(monkeypatch, "cuda", accelerated)+ report = tier_recommendation.recommend_tiers()+ assert report.cpu_count == 1 and report.pdf_image_tiers == (TIERS if accelerated else TIERS[:1])+ assert any("affinity" in warning for warning in report.warnings)torch_environment.assert_not_called()diff --git a/tests/unittest/test_tier_recommendation.py b/tests/unittest/test_tier_recommendation.pyindex 40d23325..e267a0c2 100644--- a/tests/unittest/test_tier_recommendation.py+++ b/tests/unittest/test_tier_recommendation.py@@ -4,6 +4,8 @@ from __future__ import annotationsimport importlibimport json+import sys+from collections.abc import Iteratorfrom dataclasses import asdict, replacefrom pathlib import Pathfrom types import SimpleNamespace@@ -15,17 +17,16 @@ import yamlfrom mineru.model.runtime import onnx_calibration_cache as cachefrom mineru.model.runtime import tier_recommendation as recommendation-from mineru.model.runtime.gpu import GpuIdentity, classify_d3d12_gpu, classify_vulkan_gpu, with_gpu_classification-from mineru.model.runtime.gpu_memory import GpuMemory+from mineru.model.runtime.gpu import classify_d3d12_gpu, classify_vulkan_gpu, with_gpu_classificationfrom mineru.model.runtime.webgpu import WebGPUDevicefrom mineru.model.runtime.windows_gpu import GpuAdapterfrom mineru.types import TIERS@pytest.fixture(autouse=True)-def onnx_recommendation_backend(monkeypatch: pytest.MonkeyPatch) -> None:+def onnx_recommendation_backend(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:"""本文件验证 ONNX 既有推荐规则,隔离宿主可能自动选择的 Torch 后端。"""- from mineru.model.runtime import llama_probe+ from mineru.model.runtime import gpu_memory, llama_probe, onnx_deviceimport subprocessforbidden = Mock(side_effect=AssertionError("recommendation must not probe llama devices"))@@ -42,50 +43,54 @@ def onnx_recommendation_backend(monkeypatch: pytest.MonkeyPatch) -> None:from mineru.config import get_configmonkeypatch.setattr(get_config().model, "onnx_device", "auto")- monkeypatch.setattr(- recommendation,- "native_gpu_memory",- lambda identity, *, device: GpuMemory(device, identity, 8 * 1024**3, "budget", "test"),- )+ monkeypatch.setattr(get_config().model.vlm, "engine", "llama-cpp")+ monkeypatch.setattr(onnx_device, "_selections", {})+ memory_probe = Mock(side_effect=AssertionError("recommendation must not query GPU memory"))+ monkeypatch.setattr(gpu_memory, "native_gpu_memory", memory_probe)+ monkeypatch.setattr(gpu_memory, "torch_gpu_memory", memory_probe)+ yield+ memory_probe.assert_not_called()+ forbidden.assert_not_called()- ("cores", "gpu", "expected"),- [- (1, False, {"flash"}),- (3, False, {"flash"}),- (4, False, set(TIERS[:2])),- (32, False, set(TIERS[:2])),- (1, True, set(TIERS)),- (4, True, set(TIERS)),- ],-)-def test_recommendation_matrix(cores: int, gpu: bool, expected: set[str]) -> None:[email protected]("cores", [1, 3, 4, 9, 10, 32])[email protected]("gpu", [False, True])+def test_recommendation_matrix(cores: int, gpu: bool) -> None:"""验证 CPU 边界及 GPU 对全部档位的开放规则。"""- assert (- recommendation.tiers_for_hardware(- recommendation.TierHardware(cores, gpu, gpu_memory=GpuMemory("gpu", GpuIdentity(), 8 * 1024**3))- )- == expected- )+ expected = TIERS if gpu else TIERS[:3] if cores >= 10 else TIERS[:2] if cores >= 4 else TIERS[:1]+ assert recommendation.tiers_for_hardware(recommendation.TierHardware(cores, gpu)) == frozenset(expected)@pytest.mark.parametrize(- ("affinity", "quota", "expected"), [(2, "max 100000", 2), (8, "300000 100000", 3), (8, "400000 100000", 4)]+ ("affinity", "quota", "expected"),+ [+ (2, "max 100000", 2),+ (8, "300000 100000", 3),+ (8, "400000 100000", 4),+ (16, "900000 100000", 9),+ (16, "1000000 100000", 10),+ ],)def test_recommendation_respects_affinity_and_quota(monkeypatch: pytest.MonkeyPatch, affinity: int, quota: str, expected: int) -> None:"""使用真实有效 CPU 计数逻辑,保证亲和性与容器配额限制进入推荐。"""- from mineru.model.runtime import cpu_threads+ from mineru.model.runtime import cpu_threads, onnx_devicemonkeypatch.setattr(cpu_threads.os, "cpu_count", lambda: 16)monkeypatch.setattr(cpu_threads.os, "sched_getaffinity", lambda pid: set(range(affinity)), raising=False)- monkeypatch.setattr(cpu_threads.Path, "read_text", lambda path: quota if path.name == "cpu.max" else "-1")- monkeypatch.setattr(recommendation, "_onnx_gpu_hardware", lambda count: recommendation.TierHardware(count))- hardware = recommendation.detect_tier_hardware()- assert hardware.cpu_count == expected- assert recommendation.tiers_for_hardware(hardware) == frozenset(TIERS[:2] if expected >= 4 else ("flash",))+ read_text = Path.read_text++ def read_quota(path: Path, *args: Any, **kwargs: Any) -> str:+ if path.as_posix().startswith("/sys/fs/cgroup/"):+ return quota if path.name == "cpu.max" else "-1"+ return read_text(path, *args, **kwargs)++ monkeypatch.setattr(cpu_threads.Path, "read_text", read_quota)+ monkeypatch.setattr(onnx_device, "resolve_onnx_device", lambda: onnx_device.OnnxSelection())+ report = recommendation.recommend_tiers()+ assert report.cpu_count == expected+ assert report.pdf_image_tiers == (TIERS[:3] if expected >= 10 else TIERS[:2] if expected >= 4 else TIERS[:1])@pytest.fixture@@ -174,51 +179,21 @@ def test_unwritable_record_does_not_break_calibration(evidence_path: Path, monkeassert not list(evidence_path.parent.iterdir())[email protected](("platform", "metal"), [("darwin", True), ("darwin", False), ("other", False)])-def test_apple_metal_recommendation(monkeypatch: pytest.MonkeyPatch, platform: str, metal: bool) -> None:- """Apple Silicon 按 Metal 可用性推荐,不要求 Windows/Linux 校准记录。"""[email protected]("platform", ["darwin", "other"])+def test_onnx_unsupported_platform_uses_cpu_without_torch(+ monkeypatch: pytest.MonkeyPatch, evidence_path: Path, platform: str+) -> None:+ """ONNX 的平台回退由选型入口负责,不通过额外 Torch/Metal 探测升级。"""from mineru.model.runtime import onnx_devicemonkeypatch.delenv("MINERU_LLAMA_CPP_BACKEND", raising=False)- monkeypatch.setattr(recommendation, "sys", SimpleNamespace(platform=platform))- monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: 4)- monkeypatch.setattr(recommendation, "_apple_metal_available", lambda: metal)- monkeypatch.setattr(- recommendation, "torch_gpu_memory", lambda device: GpuMemory(device, GpuIdentity(), 8 * 1024**3, "budget", "test")- )- selection = Mock(side_effect=AssertionError("unsupported platform must not select ONNX device"))- monkeypatch.setattr(onnx_device, "resolve_onnx_device", selection)- assert frozenset(recommendation.recommend_tiers().pdf_image_tiers) == frozenset(TIERS if metal else TIERS[:2])- selection.assert_not_called()--[email protected]("platform", ["win32", "linux"])[email protected]("kind", ["discrete", "calibrated", "slow", "unknown", "hidden", "failure"])-def test_gpu_discovery_uses_only_existing_onnx_evidence(- evidence_path: Path, monkeypatch: pytest.MonkeyPatch, platform: str, kind: str-) -> None:- """初选仅查询 ONNX 候选和旧证据,不提前校准或依赖 llama 库存。"""- from mineru.model.runtime import onnx_device, webgpu, windows_gpu-- monkeypatch.setattr(recommendation, "sys", SimpleNamespace(platform=platform))- monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: 4)- monkeypatch.setattr(onnx_device, "resolve_onnx_device", Mock(side_effect=AssertionError("must not calibrate")))- adapter = _adapter() if platform == "win32" else WebGPUDevice(0x8086, 0x7D51, vulkan_device=(0x8086, 0x7D51))- if kind == "discrete":- adapter = replace(adapter, kind="discrete")- discover = Mock(- return_value=() if kind == "hidden" else (adapter,), side_effect=RuntimeError("driver") if kind == "failure" else None- )- monkeypatch.setattr(windows_gpu, "discover_gpus", discover)- monkeypatch.setattr(webgpu, "discover_webgpu_devices", discover)- monkeypatch.setattr(webgpu, "select_webgpu_device", lambda devices: devices[0] if devices else None)- if kind != "unknown":- cache.save_calibration_record(adapter, _measurement(gpu_elapsed=3.0 if kind == "slow" else 1.0))- before = evidence_path.read_bytes() if evidence_path.exists() else None- hardware = recommendation.detect_tier_hardware()- assert recommendation.tiers_for_hardware(hardware) == frozenset(TIERS if kind in {"discrete", "calibrated"} else TIERS[:2])- assert (evidence_path.read_bytes() if evidence_path.exists() else None) == before- onnx_device.resolve_onnx_device.assert_not_called()+ monkeypatch.setattr(onnx_device, "sys", SimpleNamespace(platform=platform))+ monkeypatch.setattr(onnx_device, "_selections", {})+ monkeypatch.setitem(sys.modules, "torch", None)+ monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: 10)+ report = recommendation.recommend_tiers()+ assert report.device == "cpu" and report.pdf_image_tiers == TIERS[:3]+ assert report.reason == "unsupported_platform"def test_explicit_cpu_and_discovery_failure(monkeypatch: pytest.MonkeyPatch) -> None:@@ -247,7 +222,7 @@ def startup_calibration(monkeypatch.setattr(settings, "get_config_file_path", lambda: str(config_file))monkeypatch.setattr(settings, "get_config_source", lambda key: "file")monkeypatch.delenv("MINERU_LLAMA_CPP_BACKEND", raising=False)- for module in (recommendation, onnx_device, webgpu):+ for module in (onnx_device, webgpu):monkeypatch.setattr(module, "sys", SimpleNamespace(platform=request.param))monkeypatch.setattr(vulkan,@@ -334,23 +309,36 @@ def test_auto_startup_calibrates_before_publishing(}-def test_flash_without_sufficient_gpu_skips_calibration(- startup_calibration: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch[email protected]("gpu_wins", [False, True])[email protected]("cores", [1, 3, 4, 9, 10, 32])+def test_startup_calibrates_at_every_cpu_threshold(+ startup_calibration: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch, gpu_wins: bool, cores: int) -> None:- """可用 CPU 不足四且无已有 GPU 证据时,只开放 Flash 并跳过启动选型。"""- from mineru.model.runtime import onnx_device+ """所有核数均进入真实 ONNX 选型,并按本次校准的 GPU/CPU 结论开放档位。"""+ from mineru.model.runtime import llama_device, onnx_device- monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: 3)- monkeypatch.setattr(recommendation, "native_gpu_memory", lambda identity, *, device: GpuMemory(device, identity))- assert recommendation.recommend_tiers().pdf_image_tiers == ("flash",)- startup_calibration[1].assert_not_called()- assert not onnx_device._selections+ monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: cores)+ monkeypatch.setattr(llama_device, "sys", SimpleNamespace(platform=onnx_device.sys.platform))+ from mineru.config import get_config++ monkeypatch.setattr(get_config().model, "small_backend", "onnx")+ startup_calibration[1].return_value = _measurement(gpu_elapsed=1.0 if gpu_wins else 3.0)+ report = recommendation.recommend_tiers()+ expected = TIERS if gpu_wins else TIERS[:3] if cores >= 10 else TIERS[:2] if cores >= 4 else TIERS[:1]+ assert report.pdf_image_tiers == expected+ assert report.default_request_tier == ("standard" if "standard" in expected else expected[-1])+ assert report.calibration.status == "completed"+ assert report.gpu_memory is None+ assert llama_device.resolve_llama_device().device == ("gpu" if gpu_wins else "cpu")+ startup_calibration[1].assert_called_once()+ assert recommendation.recommend_tiers().calibration.status == "reused"+ startup_calibration[1].assert_called_once()def test_low_cpu_advanced_recommendation_still_selects_device(startup_calibration: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch) -> None:- """门槛按初选档位判断,低 CPU 配额的独显设备仍按平台规则提前选型。"""+ """低 CPU 配额的独显设备仍按平台规则提前选型,且复用独显免校准路径。"""from mineru.model.runtime import onnx_device, vulkanmonkeypatch.setattr(recommendation, "effective_cpu_count", lambda: 2)@@ -389,7 +377,7 @@ def test_explicit_ceiling_skips_startup_selection(startup_calibration: tuple[Patdef test_startup_preserves_explicit_device_without_performance_evidence(startup_calibration: tuple[Path, Mock], requested: str) -> None:- """显式设备不触发测速,实际选中的达标 GPU 无需校准证据即可开放四档。"""+ """显式设备不触发测速,实际选中的 GPU 无需校准证据即可开放四档。"""settings = importlib.import_module("mineru.config")config_file, measurement = startup_calibrationsettings.get_config().model.onnx_device = requested@@ -404,7 +392,7 @@ def test_startup_preserves_explicit_device_without_performance_evidence(@pytest.mark.parametrize("remove_evidence", [False, True])def test_next_startup_reuses_saved_device(startup_calibration: tuple[Path, Mock], remove_evidence: bool) -> None:- """自动校准保存 GPU 后,即使记录丢失也直接采用 GPU 与当前内存预算。"""+ """自动校准保存 GPU 后,即使记录丢失也直接采用已保存的 GPU 设备选择。"""from mineru.model.runtime import onnx_deviceassert frozenset(recommendation.recommend_tiers().pdf_image_tiers) == frozenset(TIERS)@@ -465,41 +453,10 @@ def test_configured_gpu_does_not_require_performance_evidence(writes.assert_not_called()[email protected]("cores", [3, 4])[email protected]("amount", [None, 5_905_580_032 - 1, 5_905_580_032, 6 * 1024**3 - 1])-def test_configured_gpu_memory_threshold(- configured_gpu: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch, cores: int, amount: int | None-) -> None:- """配置 GPU 仍遵守精确内存门槛,内存不足时按 CPU 核数降级且不测速。"""- config_file, measurement = configured_gpu- before = config_file.read_bytes()- monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: cores)- monkeypatch.setattr(- recommendation, "native_gpu_memory", lambda identity, *, device: GpuMemory(device, identity, amount, "budget", "test")- )-- report = recommendation.recommend_tiers()-- enough = amount is not None and amount >= 5_905_580_032- expected = TIERS if enough else TIERS[:2] if cores >= 4 else ("flash",)- assert report.pdf_image_tiers == expected- assert report.default_request_tier == ("standard" if enough else expected[-1])- assert report.gpu_memory.memory_bytes == amount- if cores >= 4 or enough:- assert report.device.endswith(":gpu")- assert report.calibration.status == "skipped" and report.calibration.reason == "configured_gpu"- assert report.reason == (- "configured_gpu" if enough else "gpu_memory_unknown" if amount is None else "gpu_memory_insufficient"- )- measurement.assert_not_called()- assert config_file.read_bytes() == before- assert not cache.calibration_record_path().exists()--def test_configured_gpu_does_not_require_calibration_threshold(configured_gpu: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch) -> None:- """性能阈值仅约束自动测速,不能阻断已选 GPU 的内存判定。"""+ """性能阈值仅约束自动测速,不能阻断已选 GPU 开放全部档位。"""from mineru.model.runtime import onnx_devicemonkeypatch.setitem(onnx_device.ONNX_GPU_TIME_RATIO_THRESHOLDS, "dml", None)@@ -564,62 +521,69 @@ def test_failed_recalibration_revokes_previous_fast_evidence(startup_calibrationassert not cache.calibration_record_path().exists()[email protected]("cores", [3, 4])[email protected]("amount", [None, 5_905_580_032 - 1, 5_905_580_032, 6 * 1024**3 - 1, 8 * 1024**3])-def test_startup_gpu_memory_threshold_and_low_cpu_calibration(- startup_calibration: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch, cores: int, amount: int | None-) -> None:- """低核数的达标 GPU 仍能完成首次校准;四核小显存 GPU 只加速 Basic。"""- monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: cores)- monkeypatch.setattr(- recommendation, "native_gpu_memory", lambda identity, *, device: GpuMemory(device, identity, amount, "budget", "test")- )- enough = amount is not None and amount >= 5_905_580_032- expected = TIERS if enough else ("flash", "basic") if cores >= 4 else ("flash",)- report = recommendation.recommend_tiers()- assert report.pdf_image_tiers == expected- assert report.default_request_tier == ("standard" if enough else expected[-1])- assert startup_calibration[1].call_count == int(cores >= 4 or enough)- assert report.gpu_memory.memory_bytes == amount- if cores >= 4 and not enough:- assert report.device.endswith(":gpu") and report.calibration.status == "completed"- assert report.reason == ("gpu_memory_unknown" if amount is None else "gpu_memory_insufficient")--[email protected]("cores", [3, 4, 10])@pytest.mark.parametrize("failure", ["configured_cpu", "selection_failed", "no_hardware_gpu", "webgpu_architecture_policy", "raise"])def test_final_cpu_result_cannot_be_upgraded_by_discrete_inventory(- startup_calibration: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch, failure: str+ startup_calibration: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch, failure: str, cores: int) -> None:- """即使初选发现达标独显,最终 CPU 或选型异常也必须撤销高级能力。"""- from mineru.model.runtime import onnx_device+ """最终 CPU 或选型异常按 CPU 阈值推荐,不再额外扫描显卡库存。"""+ from mineru.model.runtime import onnx_device, webgpu, windows_gpu- candidate = recommendation.TierHardware(4, True, "discrete_gpu", GpuMemory("gpu", GpuIdentity(), 24 * 1024**3))- monkeypatch.setattr(recommendation, "detect_tier_hardware", lambda: candidate)+ monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: cores)+ discovery = Mock(side_effect=AssertionError("tier recommendation must not rescan GPU inventory"))+ monkeypatch.setattr(windows_gpu, "discover_gpus", discovery)+ monkeypatch.setattr(webgpu, "discover_webgpu_devices", discovery)selection = Mock(return_value=onnx_device.OnnxSelection(reason=failure),side_effect=RuntimeError("driver") if failure == "raise" else None,)monkeypatch.setattr(onnx_device, "resolve_onnx_device", selection)report = recommendation.recommend_tiers()- assert report.pdf_image_tiers == ("flash", "basic") and report.default_request_tier == "basic"+ expected = TIERS[:3] if cores >= 10 else TIERS[:2] if cores >= 4 else TIERS[:1]+ assert report.pdf_image_tiers == expected and report.default_request_tier == expected[-1]+ assert report.device == "cpu"+ if failure in {"raise", "selection_failed"}:+ assert report.calibration.status == "failed" and report.warningsselection.assert_called_once()+ discovery.assert_not_called()[email protected]("amount", [None, 5_905_580_032 - 1, 5_905_580_032, 6 * 1024**3 - 1])-def test_apple_onnx_path_also_requires_budget(monkeypatch: pytest.MonkeyPatch, amount: int | None) -> None:- """ONNX 小模型配合 Apple Metal 的旧免测速路径同样受预算门槛约束。"""- monkeypatch.delenv("MINERU_LLAMA_CPP_BACKEND", raising=False)- monkeypatch.setattr(recommendation, "sys", SimpleNamespace(platform="darwin"))- monkeypatch.setattr(recommendation, "effective_cpu_count", lambda: 4)- monkeypatch.setattr(recommendation, "_apple_metal_available", lambda: True)- monkeypatch.setattr(- recommendation, "torch_gpu_memory", lambda device: GpuMemory(device, GpuIdentity(), amount, "budget", "metal")- )+def test_cpu_count_failure_does_not_disable_selected_gpu(+ configured_gpu: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch+) -> None:+ """CPU 计数回退至一核,不改变 ONNX 已确认的 GPU 结果。"""+ monkeypatch.setattr(recommendation, "effective_cpu_count", Mock(side_effect=OSError("affinity")))report = recommendation.recommend_tiers()- assert report.pdf_image_tiers == (TIERS if amount is not None and amount >= 5_905_580_032 else TIERS[:2])- assert report.device == "mps" and report.calibration.reason == "apple_silicon_metal"+ assert report.cpu_count == 1 and report.pdf_image_tiers == TIERS+ assert any("affinity" in warning for warning in report.warnings)+ configured_gpu[1].assert_not_called()++[email protected]("amount", [None, 1024**3, "error"])+def test_onnx_recommendation_without_torch_or_memory_queries(+ configured_gpu: tuple[Path, Mock], monkeypatch: pytest.MonkeyPatch, amount: int | str | None+) -> None:+ """未安装 Torch 时自动选择 ONNX,显存偏小、未知或查询异常均不参与推荐。"""+ from mineru.config import get_config+ from mineru.model.runtime import device, gpu_memory++ monkeypatch.setattr(get_config().model, "small_backend", "auto")+ monkeypatch.setattr(recommendation, "resolve_small_model_backend", device.resolve_small_model_backend)+ monkeypatch.setitem(sys.modules, "torch", None)+ monkeypatch.setitem(sys.modules, "torchvision", None)+ torch_probe = Mock(side_effect=AssertionError("ONNX recommendation must not probe Torch"))+ monkeypatch.setattr(recommendation, "resolve_torch_device", torch_probe)+ memory = Mock(return_value=amount, side_effect=RuntimeError("memory unavailable") if amount == "error" else None)+ monkeypatch.setattr(gpu_memory, "native_gpu_memory", memory)+ report = recommendation.recommend_tiers()+ assert report.small_backend == "onnx" and report.device.endswith(":gpu")+ assert report.pdf_image_tiers == TIERS and report.gpu_memory is None+ assert not report.warnings+ memory.assert_not_called()+ torch_probe.assert_not_called()+ configured_gpu[1].assert_not_called()@pytest.mark.parametrize("backend", ["dml", "webgpu"])