Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
feat(hardware): improve runtime probe summaries and device reporting
myhloli8718ab949cb1
diff --git a/docs/next/cli/mineru-kit-hardware.md b/docs/next/cli/mineru-kit-hardware.mdindex 3c732efe..5b1ea35c 100644--- a/docs/next/cli/mineru-kit-hardware.md+++ b/docs/next/cli/mineru-kit-hardware.md@@ -49,9 +49,13 @@ JSON 报告保持 `schema_version=1`,包含 `ceiling`、`pdf_image_tiers`、`d- 系统可探测到的全部独显、集显和虚拟 GPU,以及当前进程运行时可用设备。保留名称、身份、驱动及可获得的显存/共享内存信息。- GPU 的 `kind` 与选型共用同一套分类;`kind_source` 标识分类来源,`source` 保留硬件资料的采集来源,`unified_memory` 单独记录已知的统一内存属性。- 已安装的软件包版本:MinerU、DocVortex、mineru-llama-cpp、mineru-vl-utils、torch、transformers、ONNX Runtime及EP、vLLM、LMDeploy、mlx-vlm、pypdfium2。JSON 额外保留安装位置,未安装的包不列入软件版本列表。-- Torch 导入、编译使用的 CUDA/ROCm 版本和后端可用性;ORT provider 与相关引擎的探测结果。+- 运行时摘要:实际小模型后端与 VLM 引擎、各运行时状态和版本;Torch 只展示选中设备及其型号/容量,ONNX 展示可用 provider 和选中候选,llama.cpp 展示可见设备名称。- 后端、设备、线程及可见设备限制的有效配置与来源;OCR 校准记录的存在状态、环境匹配、稳定性、耗时和阈值。+运行时文本不直接展开内部 `selection`、`backends` 或适配器字典。Torch 的 CUDA/ROCm 构建版本仅在选中相应设备且版本已知时展示;CPU、MPS 及 NPU/GCU/MUSA/MLU/SDAA 等扩展设备直接显示实际设备名,不列出其他不可用后端,也不套用无关构建字段。这些构建版本来自 Torch 自身,不代表系统驱动或另行安装的工具链版本。++Windows DXGI 和 Linux Vulkan 的原生库存用于补充“系统显卡”,不在运行时文本中重复展开;macOS 使用系统工具采集,不执行 DXGI/Vulkan 这两项库存探测。采集错误仍进入提示,完整后端矩阵、所有适配器及 LUID/PCI/厂商标识等诊断字段继续保留在 `--json` 中。+“设备选择与校准”展示当前小模型后端、设备及选择依据。Torch 直接使用运行时的设备检查结果,并说明不适用 ONNX OCR 校准;ONNX 复用实际选型的候选规则,解释显式 CPU/GPU、独显免校准、不可用或待校准的情况。只读检查不会初始化 GPU 推理会话;需要测速时,设备显示“待校准”(JSON `selected_device.device` 为 `null`),不预先声称 CPU 或 GPU 胜出。存在有效校准记录时展开详细信息;没有详细记录时仅展示设备选择与原因,不列出空的测速字段。损坏或不可读的记录保留路径及错误。当前为 Torch 时,已有 ONNX 记录明确标注为不参与当前选择。JSON 的原始 `calibration` 对象仍保留全部字段。diff --git a/mineru/kit/commands/hardware.py b/mineru/kit/commands/hardware.pyindex f3712dc9..53b76360 100644--- a/mineru/kit/commands/hardware.py+++ b/mineru/kit/commands/hardware.py@@ -55,20 +55,97 @@ def _memory(value: int | None) -> str:return "未知" if value is None else f"{value / 1024**3:.3f} GiB"-def _runtime_value(value: Any) -> str:- """递归隐藏运行时模块路径并格式化容量,不修改原始探测数据。"""- if isinstance(value, dict):- fields = []- for key, item in value.items():- if key == "module_path":- continue- label = key.removesuffix("_bytes")- rendered = _memory(item) if key.endswith("_bytes") else _runtime_value(item)- fields.append(f"{label}: {rendered}")- return "{" + ", ".join(fields) + "}"- if isinstance(value, (list, tuple)):- return "[" + ", ".join(_runtime_value(item) for item in value) + "]"- return _value(value)+def _torch_device_summary(data: dict[str, Any]) -> str:+ """仅展示选中的 Torch 设备及其型号、容量,严格匹配设备索引而不猜测其他卡。"""+ device = (data.get("selected_device") or {}).get("device")+ if not device:+ return "未知"+ kind, _, index_text = device.partition(":")+ try:+ index = int(index_text) if index_text else 0+ except ValueError:+ return device+ rows = data.get("backends", {}).get(kind, {}).get("devices", [])+ selected = next((row for row in rows if row.get("index") == index), None)+ if selected is None:+ return device+ details = [selected["name"]] if selected.get("name") else []+ if selected.get("total_memory_bytes") is not None:+ details.append(_memory(selected["total_memory_bytes"]))+ label = f"{kind}:{index}"+ return f"{label}({','.join(details)})" if details else label+++def _render_runtime_probe(probe: dict[str, Any]) -> list[str]:+ """将各运行时转成重点摘要,完整适配器身份和原生库存只保留在 JSON 中。"""+ name, status, data = probe["name"], probe["status"], probe["data"]+ if name in {"dxgi", "vulkan"}:+ # 原生库存已合并进系统显卡;采集失败由报告末尾的 warnings 保留。+ return []+ if name == "selection" and status == "ok":+ return [f" 小模型后端:{_value(data.get('small_backend'))};VLM 引擎:{_value(data.get('vlm_engine'))}"]+ labels = {+ "selection": "后端选择",+ "torch": "Torch",+ "onnx": "ONNX Runtime",+ "llama-cpp": "llama.cpp",+ "vllm": "vLLM",+ "lmdeploy": "LMDeploy",+ "mlx-vlm": "MLX-VLM",+ }+ states = {"ok": "正常", "not_installed": "未安装", "error": "失败", "timeout": "超时"}+ version = f"{data['version']}," if data.get("version") else ""+ lines = [f" {labels.get(name, name)}:{version}{states.get(status, status)}"]+ if probe["error"]:+ lines.append(f" {probe['error']}")+ if status != "ok":+ return lines+ if name == "torch":+ lines.append(f" 当前设备:{_torch_device_summary(data)}")+ selected = data.get("selected_device") or {}+ if (selected.get("device") or "").split(":", 1)[0] == "cuda":+ if data.get("rocm_build"):+ lines.append(f" ROCm 构建版本:{data['rocm_build']}")+ elif data.get("cuda_build"):+ lines.append(f" CUDA 构建版本:{data['cuda_build']}")+ if selected.get("warning"):+ lines.append(f" 提示:{selected['warning']}")+ lines.extend(+ f" 提示:{backend} 探测失败:{details['error']}"+ for backend, details in data.get("backends", {}).items()+ if details.get("error")+ )+ elif name == "onnx":+ providers = [+ {"DmlExecutionProvider": "DirectML", "WebGpuExecutionProvider": "WebGPU"}.get(+ provider, provider.removesuffix("ExecutionProvider")+ )+ for provider in data.get("providers", [])+ ]+ if providers:+ lines.append(f" 可用 Provider:{', '.join(providers)}")+ selected = data.get("selected_device") or {}+ device = selected.get("device")+ adapter = selected.get("adapter") or data.get("selected_adapter") or {}+ if selected.get("reason") in {"calibration_required", "calibration_pending"}:+ lines.append(" 设备选择:待校准")+ if adapter.get("name"):+ lines.append(f" 候选设备:{adapter['name']}")+ elif device == "gpu":+ label = f"{selected.get('backend') or data.get('backend')}:gpu"+ detail = f"({adapter['name']})" if adapter.get("name") else ""+ lines.append(f" 设备选择:{label}{detail}")+ else:+ lines.append(f" 设备选择:{_value(device)}")+ if data.get("adapter_error"):+ lines.append(f" 提示:{data['adapter_error']}")+ elif name == "llama-cpp" and "devices" in data:+ lines.append(" 可见设备:" if data["devices"] else " 未发现可见 GPU")+ for device in data["devices"]:+ label = device.get("name") or device.get("backend") or "GPU"+ detail = f":{device['description']}" if device.get("description") else ""+ lines.append(f" {label}{detail}")+ return linesdef _render_device_selection(data: dict[str, Any]) -> list[str]:@@ -179,15 +256,9 @@ def _render_info_section(section: HardwareInfoSection, data: dict[str, Any]) ->)return "\n".join(lines)if section == "runtimes":- lines = ["当前进程运行时探测:"] if data.get("runtime_header", True) else []+ lines = ["运行时:"] if data.get("runtime_header", True) else []for probe in data["runtimes"]:- lines.append(f" {probe['name']}: {probe['status']}")- if probe["error"]:- lines.append(f" {probe['error']}")- for key, value in probe["data"].items():- if key != "module_path":- rendered = _memory(value) if key.endswith("_bytes") else _runtime_value(value)- lines.append(f" {key.removesuffix('_bytes')}: {rendered}")+ lines.extend(_render_runtime_probe(probe))return "\n".join(lines)lines = ["有效配置:"]lines.extend(f" {key}: {_value(value)}" for key, value in data["effective_config"].items())@@ -204,7 +275,9 @@ def render_info(data: dict[str, Any]) -> str:def _emit_info_section(section: HardwareInfoSection, data: dict[str, Any]) -> None:"""每节完成后立即刷新 stdout,管道重定向时也能读取到早期结果。"""- print(_render_info_section(section, data), file=sys.stdout, flush=True)+ rendered = _render_info_section(section, data)+ if rendered:+ print(rendered, file=sys.stdout, flush=True)def _info_data(*, stream: bool = False) -> dict[str, Any] | None:diff --git a/tests/unittest/test_hardware_info.py b/tests/unittest/test_hardware_info.pyindex d19c9ac3..4fa38ffc 100644--- a/tests/unittest/test_hardware_info.py+++ b/tests/unittest/test_hardware_info.py@@ -375,7 +375,8 @@ def test_info_memory_and_runtime_paths(amount: int | None, expected: str) -> Non"error": None,"data": {"module_path": "/runtime/torch.py",- "backends": {"cuda": {"devices": [{"total_memory_bytes": amount, "module_path": "/nested/path"}]}},+ "selected_device": {"device": "cuda", "reason": "torch_accelerator"},+ "backends": {"cuda": {"devices": [{"index": 0, "total_memory_bytes": amount, "module_path": "/nested/path"}]}},},}]@@ -383,7 +384,10 @@ def test_info_memory_and_runtime_paths(amount: int | None, expected: str) -> Nonrendered = command.render_info(data)assert f"总量 {expected}" in renderedassert f"共享内存 {expected}" in rendered- assert f"total_memory: {expected}" in rendered+ if amount is None:+ assert "当前设备:cuda:0\n" in rendered+ else:+ assert f"当前设备:cuda:0({expected})" in renderedassert "独立显存 未知," in rendered and "未知 bytes" not in renderedassert "module_path" not in rendered and "/runtime" not in rendered and "/nested" not in renderedassert "/env" not in rendered and "/source" not in rendered@@ -479,7 +483,7 @@ def test_info_parallel_probes_stream_in_order(monkeypatch: pytest.MonkeyPatch) -gpu_section = next(data for section, data in sections if section == "gpus")assert gpu_section["gpus"][0]["kind"] == "discrete"assert gpu_section["gpus"][0]["dedicated_memory_bytes"] == 8 * 1024**3- streamed = "\n".join(command._render_info_section(section, data) for section, data in sections)+ streamed = "\n".join(filter(None, (command._render_info_section(section, data) for section, data in sections)))assert streamed == command.render_info(asdict(report))diff --git a/tests/unittest/test_hardware_runtime_output.py b/tests/unittest/test_hardware_runtime_output.pynew file mode 100644index 00000000..bdf13a11--- /dev/null+++ b/tests/unittest/test_hardware_runtime_output.py@@ -0,0 +1,204 @@+"""默认硬件报告突出运行时选择,完整设备库存仅保留在 JSON 中。"""++from __future__ import annotations++from dataclasses import asdict+import json+from typing import Any++import pytest++from mineru.kit.commands import hardware as command+from mineru.model.runtime.hardware_types import RuntimeProbe+++def windows_runtimes() -> dict[str, Any]:+ """复现双显卡 Windows 报告中的重复适配器、Torch 后端矩阵和原生身份字段。"""+ adapters = [+ {"name": "NVIDIA GeForce RTX 3060 Ti", "luid": "00000000:0000f514", "index": 0, "kind": "unknown"},+ {"name": "Intel(R) UHD Graphics 770", "luid": "00000000:00010445", "index": 1, "kind": "unknown"},+ {"name": "NVIDIA GeForce RTX 3060 Ti", "luid": "00000000:0001e2fd", "index": 2, "kind": "unknown"},+ ]+ probes = [+ RuntimeProbe("selection", "ok", {"small_backend": "torch", "vlm_engine": "lmdeploy"}),+ RuntimeProbe(+ "torch",+ "ok",+ {+ "version": "2.12.1+cu126",+ "cuda_build": "12.6",+ "rocm_build": None,+ "backends": {+ "cuda": {+ "available": True,+ "devices": [+ {"index": 0, "name": "NVIDIA GeForce RTX 3060 Ti", "total_memory_bytes": 8 * 1024**3},+ ],+ },+ "mps": {"available": False},+ "xpu": {"available": False, "devices": []},+ },+ "selected_device": {"device": "cuda", "reason": "torch_accelerator", "warning": None},+ },+ ),+ RuntimeProbe(+ "onnx",+ "ok",+ {+ "version": "1.24.4",+ "providers": ["DmlExecutionProvider", "CPUExecutionProvider"],+ "backend": "dml",+ "adapters": adapters,+ "selected_adapter": adapters[0],+ "selected_device": {"device": "gpu", "backend": "dml", "reason": "configured_gpu", "adapter": adapters[0]},+ },+ ),+ RuntimeProbe(+ "llama-cpp",+ "ok",+ {+ "devices": [+ {"name": "Vulkan0", "description": "NVIDIA GeForce RTX 3060 Ti", "backend": "vulkan", "kind": "discrete"},+ {"name": "Vulkan1", "description": "Intel(R) UHD Graphics 770", "backend": "vulkan", "kind": "integrated"},+ ]+ },+ ),+ RuntimeProbe("lmdeploy", "ok", {"version": "0.17.0", "module_path": "/lmdeploy/__init__.py"}),+ RuntimeProbe("dxgi", "ok", {"devices": [{**adapter, "vendor_id": 4318, "pci_error": None} for adapter in adapters]}),+ ]+ return {"runtimes": [asdict(probe) for probe in probes]}+++def test_windows_runtime_summary_preserves_raw_diagnostics(windows_runtimes: dict[str, Any]) -> None:+ """用户提供的繁杂报告缩为关键信息,JSON 原始字段和重复适配器不被改写。"""+ before = json.dumps(windows_runtimes)+ rendered = command._render_info_section("runtimes", windows_runtimes)+ assert rendered == "\n".join(+ [+ "运行时:",+ " 小模型后端:torch;VLM 引擎:lmdeploy",+ " Torch:2.12.1+cu126,正常",+ " 当前设备:cuda:0(NVIDIA GeForce RTX 3060 Ti,8.000 GiB)",+ " CUDA 构建版本:12.6",+ " ONNX Runtime:1.24.4,正常",+ " 可用 Provider:DirectML, CPU",+ " 设备选择:dml:gpu(NVIDIA GeForce RTX 3060 Ti)",+ " llama.cpp:正常",+ " 可见设备:",+ " Vulkan0:NVIDIA GeForce RTX 3060 Ti",+ " Vulkan1:Intel(R) UHD Graphics 770",+ " LMDeploy:0.17.0,正常",+ ]+ )+ assert json.dumps(windows_runtimes) == before++[email protected]("backend", ["cuda", "npu", "xpu", "gcu", "musa", "mlu", "sdaa"])+def test_torch_summary_selects_actual_device_index(backend: str) -> None:+ """多卡和第三方后端只显示选中索引,扩展设备不展示无关 CUDA 构建字段。"""+ probe = asdict(+ RuntimeProbe(+ "torch",+ "ok",+ {+ "cuda_build": "12.6",+ "rocm_build": None,+ "selected_device": {"device": f"{backend}:1"},+ "backends": {+ backend: {+ "available": True,+ "devices": [+ {"index": 0, "name": "other GPU", "total_memory_bytes": 4 * 1024**3},+ {"index": 1, "name": "selected GPU", "total_memory_bytes": 16 * 1024**3},+ ],+ }+ },+ },+ )+ )+ rendered = "\n".join(command._render_runtime_probe(probe))+ assert f"当前设备:{backend}:1(selected GPU,16.000 GiB)" in rendered+ assert "other GPU" not in rendered+ assert ("CUDA 构建版本" in rendered) == (backend == "cuda")+ assert "ROCm" not in rendered++[email protected]("device", ["cpu", "mps", "cuda:2"])+def test_torch_summary_does_not_guess_missing_device(device: str) -> None:+ """CPU、MPS 和缺失索引不能误用第一张卡的型号或容量。"""+ probe = asdict(+ RuntimeProbe(+ "torch",+ "ok",+ {+ "selected_device": {"device": device},+ "backends": {"cuda": {"devices": [{"index": 0, "name": "wrong GPU", "total_memory_bytes": 8 * 1024**3}]}},+ },+ )+ )+ rendered = "\n".join(command._render_runtime_probe(probe))+ assert f"当前设备:{device}" in rendered+ assert "wrong GPU" not in rendered and "8.000 GiB" not in rendered+++def test_torch_summary_displays_rocm_build_when_applicable() -> None:+ """ROCm 构建沿用实际 cuda 设备接口,只展示存在的 ROCm 构建版本。"""+ probe = asdict(+ RuntimeProbe(+ "torch",+ "ok",+ {+ "selected_device": {"device": "cuda"},+ "cuda_build": None,+ "rocm_build": "6.3",+ },+ )+ )+ rendered = "\n".join(command._render_runtime_probe(probe))+ assert "ROCm 构建版本:6.3" in rendered and "CUDA 构建版本" not in rendered++[email protected]("device, reason", [("cpu", "configured_cpu"), (None, "calibration_required")])+def test_onnx_summary_distinguishes_candidate_from_selected_gpu(device: str | None, reason: str) -> None:+ """显式 CPU 不展示 GPU 为当前设备,待校准只将适配器标为候选。"""+ probe = asdict(+ RuntimeProbe(+ "onnx",+ "ok",+ {+ "selected_device": {"device": device, "reason": reason},+ "selected_adapter": {"name": "candidate GPU"},+ },+ )+ )+ rendered = "\n".join(command._render_runtime_probe(probe))+ if device == "cpu":+ assert "设备选择:cpu" in rendered and "candidate GPU" not in rendered+ else:+ assert "设备选择:待校准" in rendered and "候选设备:candidate GPU" in rendered++[email protected]("name", ["dxgi", "vulkan"])+def test_native_inventory_does_not_create_empty_output(name: str, capsys: pytest.CaptureFixture[str]) -> None:+ """原生库存不重复展示,分阶段渲染也不会额外写出空行。"""+ command._emit_info_section("runtimes", {"runtime_header": False, "runtimes": [asdict(RuntimeProbe(name, "ok"))]})+ assert capsys.readouterr().out == ""+++def test_runtime_summary_keeps_actionable_errors() -> None:+ """简化展示仍保留运行时导入错误和局部设备探测错误。"""+ failed = asdict(RuntimeProbe("onnx", "error", error="driver unavailable"))+ torch = asdict(+ RuntimeProbe(+ "torch",+ "ok",+ {+ "selected_device": {"device": "cpu", "warning": "configured GPU unavailable"},+ "backends": {"cuda": {"available": None, "error": "driver failure"}},+ },+ )+ )+ rendered = command._render_info_section("runtimes", {"runtimes": [failed, torch]})+ assert "ONNX Runtime:失败" in rendered and "driver unavailable" in rendered+ assert "configured GPU unavailable" in rendered and "cuda 探测失败:driver failure" in rendered