Skip to content

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

refactor(parser): drop dead backend_for_tier chain and Hybrid-era locks

jinzhenjdd20bf0052e2
diff --git a/docs/en/reference/changelog.md b/docs/en/reference/changelog.md
index 258b4434..80bfda51 100644
--- a/docs/en/reference/changelog.md
+++ b/docs/en/reference/changelog.md
@@ -5,7 +5,7 @@ This document records the release history of MinerU, including major capability
## Unreleased
- Breaking change: removed the `--backend` option from `mineru-kit parse` (introduced during the 4.0 alphas). The option only inferred a tier and had no independent effect, so use `--tier` instead: `pipeline` → `--tier basic`; `vlm-engine`, `vlm-auto-engine`, and `vlm-http-client` → `--tier advanced`; `hybrid-engine` and `hybrid-auto-engine` → `--tier standard` (or omit the option); `flash` → `--tier flash`. Parsing with a remote VLM service is configured through the VLM server settings and is unrelated to this option.
-- Breaking change: removed the `PARSER_BACKENDS` constant from the `mineru.parser` exports (present in the 4.0 release). Backends are derived from tiers and are no longer a public choice; call `mineru.parser.backend_for_tier(tier)` if you need a tier's implementation name.
+- Breaking change: removed the `PARSER_BACKENDS` constant from the `mineru.parser` exports (present in the 4.0 release). Backends are derived from tiers and are no longer a public choice or a public symbol; configure engines through `model.small_backend` and `model.vlm.engine` instead.
## 4.0
diff --git a/docs/zh/reference/changelog.md b/docs/zh/reference/changelog.md
index 5e9a74f0..85c31ad6 100644
--- a/docs/zh/reference/changelog.md
+++ b/docs/zh/reference/changelog.md
@@ -5,7 +5,7 @@
## 未发布
- 破坏性变更:移除 `mineru-kit parse` 的 `--backend` 参数(该参数在 4.0 alpha 阶段引入)。它仅用于推断 tier,没有独立作用,请改用 `--tier`:`pipeline` → `--tier basic`;`vlm-engine`、`vlm-auto-engine`、`vlm-http-client` → `--tier advanced`;`hybrid-engine`、`hybrid-auto-engine` → `--tier standard`(或省略该参数);`flash` → `--tier flash`。使用远程 VLM 服务由 VLM 服务配置表达,与该参数无关。
-- 破坏性变更:移除 `mineru.parser` 公开导出中的 `PARSER_BACKENDS` 常量(4.0 正式版包含该导出)。backend 由 tier 派生,不再作为公开选择;如需某 tier 的实现名称,请调用 `mineru.parser.backend_for_tier(tier)`。
+- 破坏性变更:移除 `mineru.parser` 公开导出中的 `PARSER_BACKENDS` 常量(4.0 正式版包含该导出)。backend 由 tier 派生,不再是公开选择或公开符号;请通过 `model.small_backend` 与 `model.vlm.engine` 配置引擎。
## 4.0
diff --git a/mineru/backend/postprocess/legacy_middle_json.py b/mineru/backend/postprocess/legacy_middle_json.py
index 5074f42f..d92d0a82 100644
--- a/mineru/backend/postprocess/legacy_middle_json.py
+++ b/mineru/backend/postprocess/legacy_middle_json.py
@@ -127,4 +127,4 @@ def read_legacy_middle_json(payload: dict[str, Any]) -> MiddleJson:
return document
-__all__ = ["read_legacy_middle_json"]
\ No newline at end of file
+__all__ = ["read_legacy_middle_json"]
diff --git a/mineru/parser/__init__.py b/mineru/parser/__init__.py
index a96ee388..f3fd0447 100644
--- a/mineru/parser/__init__.py
+++ b/mineru/parser/__init__.py
@@ -12,11 +12,9 @@ from ..types import Tier
from .api_client import ApiJobStatus, MinerUApiParser
from .base import MIDDLE_JSON_SCHEMA_VERSION, DocumentParser, ParseResult
from .mineru_parser import MinerUParser
-from .tier import backend_for_tier
__all__ = [
"ApiJobStatus",
- "backend_for_tier",
"DocumentParser",
"MinerUApiParser",
"MinerUParser",
diff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.py
index 0b757018..b9f2a16f 100644
--- a/mineru/parser/api_server.py
+++ b/mineru/parser/api_server.py
@@ -2289,8 +2289,6 @@ def create_app(
server_tiers = _request_tiers_for_server_tier(tier, no_flash=no_flash, no_advanced=no_advanced)
tier_runtime_options = _runtime_options_for_server_tiers(server_tiers)
default_tier = select_default_quality_tier(tier_runtime_options)
- startup_runtime = runtime_options_for_tier(tier)
- backend = startup_runtime.backend
effort = effort_for_tier(tier)
vlm_config = (vlm_config if vlm_config is not None else mineru_config.model.vlm).model_copy(deep=True)
_preflight_tier_dependencies(tier, vlm_config)
@@ -2313,8 +2311,7 @@ def create_app(
application.state.tier = tier
application.state.default_tier = default_tier
application.state.flash_enabled = not no_flash
- application.state.backend = backend
- application.state.tier_runtime_options = tier_runtime_options
+ application.state.tier_runtime_options = tier_runtime_options
application.state.model_ids = _model_ids
application.state.tiers = _tiers
application.state.concurrency = concurrency
@@ -2376,7 +2373,6 @@ def create_app(
application.state.tier = tier
application.state.default_tier = default_tier
application.state.flash_enabled = not no_flash
- application.state.backend = backend
application.state.tier_runtime_options = tier_runtime_options
application.state.model_ids = _model_ids
application.state.tiers = _tiers
diff --git a/mineru/parser/tier.py b/mineru/parser/tier.py
index 78486430..ff53481b 100644
--- a/mineru/parser/tier.py
+++ b/mineru/parser/tier.py
@@ -9,63 +9,23 @@ from typing import Final
from ..config import VlmConfig
from ..types import DEPLOYMENT_TIERS, DeploymentTier, Tier, validate_tier
-CANONICAL_HYBRID_ENGINE: Final = "hybrid-engine"
-LOCAL_HYBRID_EFFORT: Final = "medium"
-LAYOUT_HYBRID_EFFORT: Final = "high"
-MAX_HYBRID_EFFORT: Final = "xhigh"
-DEFAULT_HYBRID_EFFORT: Final = LAYOUT_HYBRID_EFFORT
-DEFAULT_EFFORT: Final = DEFAULT_HYBRID_EFFORT
-HYBRID_EFFORT_HELP: Final = "Higher effort improves parsing quality but may be slower; medium is the fastest local Hybrid mode."
-HYBRID_EFFORT_CHOICES: Final[tuple[str, ...]] = (LOCAL_HYBRID_EFFORT, LAYOUT_HYBRID_EFFORT, MAX_HYBRID_EFFORT)
-HYBRID_EFFORT_BY_TIER: Final[dict[str, str]] = {
+_EFFORT_BY_TIER: Final[dict[str, str]] = {
"flash": "flash",
- "basic": LOCAL_HYBRID_EFFORT,
- "standard": LAYOUT_HYBRID_EFFORT,
- "advanced": MAX_HYBRID_EFFORT,
+ "basic": "medium",
+ "standard": "high",
+ "advanced": "xhigh",
}
-HYBRID_EFFORT_SCHEMA_EXTRA: Final[dict[str, list[str]]] = {"enum": list(HYBRID_EFFORT_CHOICES)}
-SUPPORTED_EFFORTS: Final[tuple[str, ...]] = HYBRID_EFFORT_CHOICES
-
-
-def validate_effort(effort: str | None) -> str:
- """校验 Hybrid effort 只使用 medium、high 或 xhigh。"""
- normalized = (effort or DEFAULT_EFFORT).strip().lower()
- if normalized in HYBRID_EFFORT_CHOICES:
- return normalized
- raise ValueError(f"Unsupported effort '{effort}'. Supported efforts: {', '.join(HYBRID_EFFORT_CHOICES)}")
def effort_for_tier(tier: str | None) -> str:
"""将公开 tier 映射为对应的 Hybrid effort。"""
normalized = (tier or "").strip().lower()
- if normalized in HYBRID_EFFORT_BY_TIER:
- return HYBRID_EFFORT_BY_TIER[normalized]
- supported_tiers = ", ".join(HYBRID_EFFORT_BY_TIER)
+ if normalized in _EFFORT_BY_TIER:
+ return _EFFORT_BY_TIER[normalized]
+ supported_tiers = ", ".join(_EFFORT_BY_TIER)
raise ValueError(f"Unsupported tier '{tier}'. Supported hybrid tiers: {supported_tiers}")
-__all__ = [
- "CANONICAL_HYBRID_ENGINE",
- "DEFAULT_EFFORT",
- "DEFAULT_HYBRID_EFFORT",
- "HYBRID_EFFORT_CHOICES",
- "HYBRID_EFFORT_HELP",
- "HYBRID_EFFORT_SCHEMA_EXTRA",
- "ParserRuntimeOptions",
- "SUPPORTED_EFFORTS",
- "TierDependencyError",
- "backend_for_tier",
- "effort_for_tier",
- "ensure_tier_runtime_dependencies",
- "installed_distribution_name",
- "missing_modules_for_tier",
- "required_modules_for_tier",
- "resolve_runtime_options",
- "runtime_options_for_tier",
- "validate_effort",
-]
-
-
class TierDependencyError(RuntimeError):
def __init__(self, tier: DeploymentTier, missing_modules: list[str]) -> None:
self.tier = tier
@@ -82,39 +42,17 @@ class TierDependencyError(RuntimeError):
@dataclass(frozen=True)
class ParserRuntimeOptions:
- """记录某个 tier 实际执行时使用的 backend 与 effort。"""
+ """记录某个 tier 实际执行时使用的 effort。"""
tier: Tier
- backend: str
effort: str
- def as_kwargs(self) -> dict[str, str]:
- """转换为 parser 调用可直接展开的关键参数,方便测试和调用端复用。"""
- return {
- "tier": self.tier,
- "backend": self.backend,
- "effort": self.effort,
- }
-
-
-def backend_for_tier(tier: Tier) -> str:
- """返回指定 tier 使用的 parser backend,tier 自身决定质量档位。"""
- tier = validate_tier(tier)
- mapping = {
- "flash": "flash",
- "basic": CANONICAL_HYBRID_ENGINE,
- "standard": CANONICAL_HYBRID_ENGINE,
- "advanced": CANONICAL_HYBRID_ENGINE,
- }
- return mapping[tier]
-
def resolve_runtime_options(tier: Tier | None = None) -> ParserRuntimeOptions:
- """统一解析 parser 运行所需的 runtime;backend 与 effort 均由 tier 派生。"""
+ """统一解析 parser 运行所需的 runtime;effort 由 tier 派生。"""
resolved_tier: Tier = validate_tier(tier) if tier is not None else "standard"
- resolved_backend = backend_for_tier(resolved_tier)
resolved_effort = "flash" if resolved_tier == "flash" else effort_for_tier(resolved_tier)
- return ParserRuntimeOptions(tier=resolved_tier, backend=resolved_backend, effort=resolved_effort)
+ return ParserRuntimeOptions(tier=resolved_tier, effort=resolved_effort)
def runtime_options_for_tier(tier: Tier) -> ParserRuntimeOptions:
@@ -165,3 +103,16 @@ def ensure_tier_runtime_dependencies(tier: DeploymentTier, *, vlm_config: VlmCon
missing_modules = missing_modules_for_tier(tier, vlm_config=vlm_config)
if missing_modules:
raise TierDependencyError(tier, missing_modules)
+
+
+__all__ = [
+ "ParserRuntimeOptions",
+ "TierDependencyError",
+ "effort_for_tier",
+ "ensure_tier_runtime_dependencies",
+ "installed_distribution_name",
+ "missing_modules_for_tier",
+ "required_modules_for_tier",
+ "resolve_runtime_options",
+ "runtime_options_for_tier",
+]
diff --git a/tests/unittest/test_doclib_cache_semantics.py b/tests/unittest/test_doclib_cache_semantics.py
index 691674cd..74a5b24d 100644
--- a/tests/unittest/test_doclib_cache_semantics.py
+++ b/tests/unittest/test_doclib_cache_semantics.py
@@ -66,7 +66,6 @@ from mineru.doclib.services.search_svc import SearchService
from mineru.doclib.types import DocContentExportRequest, FileInfo, InvalidateRequest, ParseResponse, WatchRequest
from mineru.errors import InvalidRequestError, MineruError, NotFoundError
from mineru.filetypes import file_type_for_extension
-from mineru.parser import backend_for_tier
from mineru.parser.api_client import _APITransportError, _V1APIError
from mineru.parser.base import ParseResult
from mineru.parser import MIDDLE_JSON_SCHEMA_VERSION
@@ -334,11 +333,6 @@ def test_load_pages_from_done_batches_keeps_newest_page_idx(tmp_path: Path) -> N
assert inline_text(pages[1].blocks[0].content) == "newer" # type: ignore[union-attr]
-def test_parser_tier_backend_mapping_is_parser_layer_only() -> None:
- assert backend_for_tier("flash") == "flash"
- assert backend_for_tier("basic") == "hybrid-engine"
- assert backend_for_tier("standard") == "hybrid-engine"
- assert backend_for_tier("advanced") == "hybrid-engine"
def test_managed_api_server_args_use_tier_and_selected_port_for_process_start() -> None:
diff --git a/tests/unittest/test_parser_api_contract.py b/tests/unittest/test_parser_api_contract.py
index 11cb5a42..f82fa749 100644
--- a/tests/unittest/test_parser_api_contract.py
+++ b/tests/unittest/test_parser_api_contract.py
@@ -370,48 +370,25 @@ print("ok")
assert result.stdout.strip() == "ok"
-def test_validate_effort_rejects_low() -> None:
- """校验 Hybrid effort 只接受 medium/high/xhigh 三档。"""
- from mineru.parser.tier import (
- HYBRID_EFFORT_CHOICES,
- effort_for_tier,
- validate_effort,
- )
+def test_effort_for_tier_rejects_unknown_tier() -> None:
+ """校验 effort 由 tier 派生,非法 tier 被拒绝。"""
+ from mineru.parser.tier import effort_for_tier
- assert HYBRID_EFFORT_CHOICES == ("medium", "high", "xhigh")
assert effort_for_tier("basic") == "medium"
assert effort_for_tier("standard") == "high"
assert effort_for_tier("advanced") == "xhigh"
- with pytest.raises(ValueError, match="Unsupported effort 'low'"):
- validate_effort("low")
with pytest.raises(ValueError, match="Unsupported tier 'ultra'"):
effort_for_tier("ultra")
def test_tier_runtime_options_map_hybrid_effort() -> None:
- """校验 tier 到 Hybrid runtime 参数的共享映射,避免 API/Gradio 分叉维护。"""
+ """校验 tier 到 effort 的共享映射,避免 API/Gradio 分叉维护。"""
from mineru.parser.tier import runtime_options_for_tier
- assert runtime_options_for_tier("flash").as_kwargs() == {
- "tier": "flash",
- "backend": "flash",
- "effort": "flash",
- }
- assert runtime_options_for_tier("basic").as_kwargs() == {
- "tier": "basic",
- "backend": "hybrid-engine",
- "effort": "medium",
- }
- assert runtime_options_for_tier("standard").as_kwargs() == {
- "tier": "standard",
- "backend": "hybrid-engine",
- "effort": "high",
- }
- assert runtime_options_for_tier("advanced").as_kwargs() == {
- "tier": "advanced",
- "backend": "hybrid-engine",
- "effort": "xhigh",
- }
+ assert runtime_options_for_tier("flash").effort == "flash"
+ assert runtime_options_for_tier("basic").effort == "medium"
+ assert runtime_options_for_tier("standard").effort == "high"
+ assert runtime_options_for_tier("advanced").effort == "xhigh"
@pytest.mark.parametrize("module_name", ["torch", "vllm", "lmdeploy", "mlx_vlm", "onnxruntime", "mineru_llama_cpp"])
@@ -1820,7 +1797,6 @@ def test_create_app_does_not_read_runtime_settings_from_env(tmp_path: Path, monk
app = create_app(upload_dir=str(tmp_path))
assert app.state.tier == "standard"
- assert app.state.backend == "hybrid-engine"
assert app.state.concurrency == 1
assert app.state.url_timeout == 60
assert app.state.allow_local_source is False
@@ -2486,14 +2462,11 @@ def test_api_server_tier_selects_compatible_backend(tmp_path: Path, monkeypatch:
standard_app = create_app(upload_dir=str(tmp_path / "standard"), tier="standard")
assert flash_app.state.tier == "flash"
- assert flash_app.state.backend == "flash"
assert [tier["id"] for tier in flash_app.state.tiers] == ["flash"]
assert basic_app.state.tier == "basic"
- assert basic_app.state.backend == "hybrid-engine"
assert basic_app.state.effort == "medium"
assert [tier["id"] for tier in basic_app.state.tiers] == ["flash", "basic"]
assert standard_app.state.tier == "standard"
- assert standard_app.state.backend == "hybrid-engine"
assert standard_app.state.effort == "high"
assert [tier["id"] for tier in standard_app.state.tiers] == ["flash", "basic", "standard", "advanced"]
@@ -2504,29 +2477,12 @@ def test_api_server_defaults_to_all_quality_tiers(tmp_path: Path, monkeypatch: p
assert app.state.tier == "standard"
assert app.state.default_tier == "standard"
- assert app.state.backend == "hybrid-engine"
assert app.state.effort == "high"
assert [tier["id"] for tier in app.state.tiers] == ["flash", "basic", "standard", "advanced"]
- assert app.state.tier_runtime_options["flash"].as_kwargs() == {
- "tier": "flash",
- "backend": "flash",
- "effort": "flash",
- }
- assert app.state.tier_runtime_options["basic"].as_kwargs() == {
- "tier": "basic",
- "backend": "hybrid-engine",
- "effort": "medium",
- }
- assert app.state.tier_runtime_options["standard"].as_kwargs() == {
- "tier": "standard",
- "backend": "hybrid-engine",
- "effort": "high",
- }
- assert app.state.tier_runtime_options["advanced"].as_kwargs() == {
- "tier": "advanced",
- "backend": "hybrid-engine",
- "effort": "xhigh",
- }
+ assert app.state.tier_runtime_options["flash"].effort == "flash"
+ assert app.state.tier_runtime_options["basic"].effort == "medium"
+ assert app.state.tier_runtime_options["standard"].effort == "high"
+ assert app.state.tier_runtime_options["advanced"].effort == "xhigh"
def test_api_server_standard_no_flash_state_and_metadata(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
@@ -2536,26 +2492,13 @@ def test_api_server_standard_no_flash_state_and_metadata(tmp_path: Path, monkeyp
assert app.state.tier == "standard"
assert app.state.default_tier == "standard"
- assert app.state.backend == "hybrid-engine"
assert app.state.effort == "high"
assert app.state.flash_enabled is False
assert [tier["id"] for tier in app.state.tiers] == ["basic", "standard", "advanced"]
assert app.state.model_ids == ["Hybrid-Basic", "MinerU-HTML", "MinerU2.5-Pro-2605-1.2B"]
- assert app.state.tier_runtime_options["basic"].as_kwargs() == {
- "tier": "basic",
- "backend": "hybrid-engine",
- "effort": "medium",
- }
- assert app.state.tier_runtime_options["standard"].as_kwargs() == {
- "tier": "standard",
- "backend": "hybrid-engine",
- "effort": "high",
- }
- assert app.state.tier_runtime_options["advanced"].as_kwargs() == {
- "tier": "advanced",
- "backend": "hybrid-engine",
- "effort": "xhigh",
- }
+ assert app.state.tier_runtime_options["basic"].effort == "medium"
+ assert app.state.tier_runtime_options["standard"].effort == "high"
+ assert app.state.tier_runtime_options["advanced"].effort == "xhigh"
@pytest.mark.parametrize(