Skip to content

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

Select table ONNX CUDA automatically when available

myhlolibf8a518d235e
diff --git a/docs/en/usage/tiers.md b/docs/en/usage/tiers.md
index 709be4f0..a7777a9e 100644
--- a/docs/en/usage/tiers.md
+++ b/docs/en/usage/tiers.md
@@ -28,7 +28,9 @@ PDF and images support all four tiers. Office, OpenDocument, RTF, EPUB, OFD, HTM
| Windows, accelerator and `full` | Torch | LMDeploy |
| CPU environment | ONNX / CPU | llama.cpp |
-Automatic selection uses installed dependencies and available devices. An explicit choice with missing dependencies fails instead of silently selecting another backend. ONNX small models run on CPU; VLM device selection is independent.
+Automatic selection uses installed dependencies and available devices. An explicit choice with missing dependencies fails instead of silently selecting another backend. ONNX Layout, OCR, and formula models run on CPU; VLM device selection is independent.
+
+Table classification, SLANet, and UNet use `MINERU_TABLE_DEVICE=auto` by default: the CPU `onnxruntime` package uses CPU; replacing it with a compatible `onnxruntime-gpu` package enables CUDA when its provider is available. CUDA initialization failures are logged and fall back to CPU. Do not install both ORT distributions together. Set `MINERU_TABLE_DEVICE=cpu` to force CPU or `cuda` to explicitly attempt CUDA. This option affects only table models, and logs report the actual providers.
Intel XPU is excluded from automatic LMDeploy selection. Linux prefers an installed XPU-compatible vLLM and otherwise falls back to llama.cpp; Windows uses llama.cpp.
diff --git a/docs/next/model-assets.md b/docs/next/model-assets.md
index 1a7a4b98..be5150a2 100644
--- a/docs/next/model-assets.md
+++ b/docs/next/model-assets.md
@@ -30,7 +30,11 @@ mineru-kit parse input.pdf --tier basic -o output.md
```
`MINERU_MODEL_BASE_DIR` 可指定独立模型根目录。`--small-backend`、`--vlm-engine` 只覆盖当前模型管理命令;解析和服务运行时读取环境变量或配置文件。
-所有 ONNX 会话固定使用 CPU,最低版本为 ONNX Runtime 1.20.1,支持资源包所需的 ONNX IR 10。
+Layout、OCR 和公式的 ONNX 会话固定使用 CPU,最低版本为 ONNX Runtime 1.20.1,支持资源包所需的 ONNX IR 10。
+
+表格分类、SLANet 和 UNet 共用独立的设备策略:`MINERU_TABLE_DEVICE=auto`(默认)根据 ONNX Runtime 的可用 provider 选择设备。安装 CPU 版 `onnxruntime` 时使用 CPU;替换为与 CUDA/cuDNN 环境兼容的 `onnxruntime-gpu` 后优先使用 CUDA,CUDA 会话初始化失败则记录原因并回退 CPU。不要同时安装两个发行包,它们共享同一个 Python 模块。日志中的实际 providers 表示最终加载结果。
+
+设置 `MINERU_TABLE_DEVICE=cpu` 可固定表格在 CPU 执行(ZeroGPU Space 默认采用此配置);设置 `cuda` 可显式尝试 CUDA,仍保留故障回退。该选项不影响 Layout、OCR 和公式的 ONNX 后端,也不影响 Torch 设备选择。所有表格会话均读取 `MINERU_INTRA_OP_NUM_THREADS` 和 `MINERU_INTER_OP_NUM_THREADS`,限制 CPU 算子及回退路径的线程数。
llama.cpp 的设备参数独立于 ONNX provider;Torch 和 VLM 仍沿用各自设备策略。
## 资源结构
diff --git a/docs/zh/usage/tiers.md b/docs/zh/usage/tiers.md
index d8fd5d95..3d200749 100644
--- a/docs/zh/usage/tiers.md
+++ b/docs/zh/usage/tiers.md
@@ -28,7 +28,9 @@ PDF 和图片可选四档。Office、OpenDocument、RTF、EPUB、OFD、HTML、CS
| Windows,有加速器并安装 `full` | Torch | LMDeploy |
| CPU 环境 | ONNX / CPU | llama.cpp |
-自动选择依据已安装依赖和可用设备;显式指定的后端缺依赖时会报错,不会静默改用另一种。ONNX 小模型在 CPU 上执行,VLM 的设备选择独立。
+自动选择依据已安装依赖和可用设备;显式指定的后端缺依赖时会报错,不会静默改用另一种。Layout、OCR 和公式的 ONNX 模型在 CPU 上执行,VLM 的设备选择独立。
+
+表格分类、SLANet 和 UNet 默认使用 `MINERU_TABLE_DEVICE=auto`:CPU 版 `onnxruntime` 使用 CPU;替换为兼容的 `onnxruntime-gpu` 后,有可用 CUDA provider 时优先使用 CUDA,初始化失败则记录原因并回退 CPU。两个 ORT 发行包不要同时安装。设置 `MINERU_TABLE_DEVICE=cpu` 可固定 CPU,设置 `cuda` 可显式尝试 CUDA;该选项仅影响表格模型。日志会记录实际使用的 providers。
Intel XPU 不会自动选择 LMDeploy。Linux 上安装了支持 XPU 的 vLLM 时优先使用 vLLM,否则回退 llama.cpp;Windows 上使用 llama.cpp。
diff --git a/mineru/model/runtime/onnx.py b/mineru/model/runtime/onnx.py
index 419d5d23..34d5c12e 100644
--- a/mineru/model/runtime/onnx.py
+++ b/mineru/model/runtime/onnx.py
@@ -1,5 +1,5 @@
# Copyright (c) Opendatalab. All rights reserved.
-"""ONNX Runtime CPU 会话与可选的表格 CUDA 会话。"""
+"""ONNX Runtime CPU 会话与自动选择设备的表格会话。"""
import os
import time
@@ -22,7 +22,7 @@ def get_op_num_threads(env_name: str) -> int:
def ort_providers(device: str | None = None) -> list[tuple[str, dict[str, object]]]:
- """所有 ONNX 模型固定使用 CPU,宿主 Torch 设备不参与 provider 选择。"""
+ """通用 ONNX 模型固定使用 CPU;表格工厂独立选择 CUDA provider。"""
return [("CPUExecutionProvider", {"arena_extend_strategy": "kSameAsRequested"})]
@@ -41,10 +41,10 @@ def ort_session(model_path: str, device: str | None = None, intra_op_num_threads
def table_ort_session(model_path: str, *, sess_options: ort.SessionOptions | None = None) -> ort.InferenceSession:
- """表格独立选择 CPU/CUDA;创建失败或 provider 静默降级时明确记录并保留 CPU 回退。"""
- device = os.getenv("MINERU_TABLE_DEVICE", "cpu").strip().lower()
- if device not in {"cpu", "cuda"}:
- raise ValueError("MINERU_TABLE_DEVICE must be 'cpu' or 'cuda'")
+ """表格默认按可用 provider 选择设备;支持固定 CPU/CUDA,并明确记录 CUDA 失败回退。"""
+ device = os.getenv("MINERU_TABLE_DEVICE", "auto").strip().lower()
+ if device not in {"auto", "cpu", "cuda"}:
+ raise ValueError("MINERU_TABLE_DEVICE must be 'auto', 'cpu' or 'cuda'")
opts = sess_options if sess_options is not None else ort.SessionOptions()
opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
opts.log_severity_level = 3
@@ -61,8 +61,10 @@ def table_ort_session(model_path: str, *, sess_options: ort.SessionOptions | Non
opts.enable_profiling = True
opts.profile_file_prefix = str(Path(profile_dir) / f"{Path(model_path).stem}-{os.getpid()}")
providers = ort_providers()
- if device == "cuda":
- if "CUDAExecutionProvider" in ort.get_available_providers():
+ use_cuda = False
+ if device != "cpu":
+ use_cuda = "CUDAExecutionProvider" in ort.get_available_providers()
+ if use_cuda:
providers = [
(
"CUDAExecutionProvider",
@@ -75,18 +77,18 @@ def table_ort_session(model_path: str, *, sess_options: ort.SessionOptions | Non
),
*providers,
]
- else:
+ elif device == "cuda":
logger.warning("Table CUDA unavailable; falling back to CPU: {}", model_path)
started = time.perf_counter()
try:
session = ort.InferenceSession(model_path, sess_options=opts, providers=providers)
except Exception as exc:
- if device != "cuda" or providers == ort_providers():
+ if not use_cuda:
raise
logger.warning("Table CUDA initialization failed; falling back to CPU: {}: {}", model_path, exc)
session = ort.InferenceSession(model_path, sess_options=opts, providers=ort_providers())
actual = session.get_providers()
- if device == "cuda" and "CUDAExecutionProvider" not in actual:
+ if use_cuda and "CUDAExecutionProvider" not in actual:
logger.warning("Table requested CUDA but actual providers are {}: {}", actual, model_path)
logger.info(
"Table ONNX ready: model={}, requested={}, providers={}, init_s={:.3f}, pid={}",
diff --git a/tests/unittest/test_table_onnx_runtime.py b/tests/unittest/test_table_onnx_runtime.py
index d7c8e30e..bd811e03 100644
--- a/tests/unittest/test_table_onnx_runtime.py
+++ b/tests/unittest/test_table_onnx_runtime.py
@@ -1,4 +1,4 @@
-"""表格 CUDA provider 的显式选择、回退与 CPU 模型边界。"""
+"""表格 CUDA provider 的自动选择、显式覆盖、回退与 CPU 模型边界。"""
from types import SimpleNamespace
from unittest.mock import Mock
@@ -9,10 +9,11 @@ import pytest
from mineru.model.runtime import onnx
-def test_table_default_is_cpu(monkeypatch: pytest.MonkeyPatch) -> None:
- """Torch 使用 CUDA 不应隐式改变表格模型设备。"""
+def test_table_default_uses_cpu_without_cuda_provider(monkeypatch: pytest.MonkeyPatch) -> None:
+ """CPU ORT 包保持 CPU 执行,Torch 设备不参与表格 provider 决策。"""
monkeypatch.delenv("MINERU_TABLE_DEVICE", raising=False)
monkeypatch.setenv("MINERU_DEVICE_MODE", "cuda")
+ monkeypatch.setattr(onnx.ort, "get_available_providers", lambda: ["CPUExecutionProvider"])
session = SimpleNamespace(get_providers=lambda: ["CPUExecutionProvider"])
factory = Mock(return_value=session)
monkeypatch.setattr(onnx.ort, "InferenceSession", factory)
@@ -20,9 +21,13 @@ def test_table_default_is_cpu(monkeypatch: pytest.MonkeyPatch) -> None:
assert factory.call_args.kwargs["providers"] == onnx.ort_providers()
-def test_cuda_is_explicit_and_other_onnx_models_stay_cpu(monkeypatch: pytest.MonkeyPatch) -> None:
- """表格 CUDA 使用低冷启动开销选项,OCR/Layout ONNX 仍保留 CPU 策略。"""
- monkeypatch.setenv("MINERU_TABLE_DEVICE", "cuda")
[email protected]("device", [None, "auto", "cuda"])
+def test_cuda_selection_and_other_onnx_models_stay_cpu(monkeypatch: pytest.MonkeyPatch, device: str | None) -> None:
+ """默认自动和显式 CUDA 都选择 GPU,但 OCR/Layout ONNX 仍保留 CPU 策略。"""
+ if device is None:
+ monkeypatch.delenv("MINERU_TABLE_DEVICE", raising=False)
+ else:
+ monkeypatch.setenv("MINERU_TABLE_DEVICE", device)
monkeypatch.setenv("MINERU_INTRA_OP_NUM_THREADS", "4")
monkeypatch.setenv("MINERU_INTER_OP_NUM_THREADS", "1")
monkeypatch.setattr(onnx.ort, "get_available_providers", lambda: ["CUDAExecutionProvider", "CPUExecutionProvider"])
@@ -38,10 +43,21 @@ def test_cuda_is_explicit_and_other_onnx_models_stay_cpu(monkeypatch: pytest.Mon
assert factory.call_args.kwargs["providers"] == onnx.ort_providers()
+def test_explicit_cpu_overrides_available_cuda_provider(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Space 的显式 CPU 配置不能因安装 GPU ORT 包而申请 CUDA 会话。"""
+ monkeypatch.setenv("MINERU_TABLE_DEVICE", "cpu")
+ monkeypatch.setattr(onnx.ort, "get_available_providers", lambda: ["CUDAExecutionProvider", "CPUExecutionProvider"])
+ factory = Mock(return_value=SimpleNamespace(get_providers=lambda: ["CPUExecutionProvider"]))
+ monkeypatch.setattr(onnx.ort, "InferenceSession", factory)
+ onnx.table_ort_session("table.onnx")
+ assert factory.call_args.kwargs["providers"] == onnx.ort_providers()
+
+
[email protected]("device", ["auto", "cuda"])
@pytest.mark.parametrize("mode", ["unavailable", "exception", "silent"])
-def test_cuda_failure_is_reported_and_cpu_remains_available(monkeypatch: pytest.MonkeyPatch, mode: str) -> None:
+def test_cuda_failure_is_reported_and_cpu_remains_available(monkeypatch: pytest.MonkeyPatch, mode: str, device: str) -> None:
"""覆盖未安装 CUDA、动态库失败以及 ORT 自动降级,不能把回退误报为 GPU。"""
- monkeypatch.setenv("MINERU_TABLE_DEVICE", "cuda")
+ monkeypatch.setenv("MINERU_TABLE_DEVICE", device)
monkeypatch.setattr(
onnx.ort,
"get_available_providers",
@@ -53,7 +69,7 @@ def test_cuda_failure_is_reported_and_cpu_remains_available(monkeypatch: pytest.
monkeypatch.setattr(onnx.ort, "InferenceSession", factory)
monkeypatch.setattr(onnx.logger, "warning", warning)
assert onnx.table_ort_session("table.onnx") is cpu
- assert warning.called
+ assert warning.called == (mode != "unavailable" or device == "cuda")
if mode in {"unavailable", "exception"}:
assert factory.call_args.kwargs["providers"] == onnx.ort_providers()