Skip to content

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

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.md
index 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.py
index 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 lines
def _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.py
index 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) -> Non
rendered = command.render_info(data)
assert f"总量 {expected}" in rendered
assert 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 rendered
assert "独立显存 未知," in rendered and "未知 bytes" not in rendered
assert "module_path" not in rendered and "/runtime" not in rendered and "/nested" not in rendered
assert "/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.py
new file mode 100644
index 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