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(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.mdindex 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.0diff --git a/docs/zh/reference/changelog.md b/docs/zh/reference/changelog.mdindex 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.0diff --git a/mineru/backend/postprocess/legacy_middle_json.py b/mineru/backend/postprocess/legacy_middle_json.pyindex 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__.pyindex a96ee388..f3fd0447 100644--- a/mineru/parser/__init__.py+++ b/mineru/parser/__init__.py@@ -12,11 +12,9 @@ from ..types import Tierfrom .api_client import ApiJobStatus, MinerUApiParserfrom .base import MIDDLE_JSON_SCHEMA_VERSION, DocumentParser, ParseResultfrom .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.pyindex 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.backendeffort = 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 = tierapplication.state.default_tier = default_tierapplication.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_optionsapplication.state.model_ids = _model_idsapplication.state.tiers = _tiersapplication.state.concurrency = concurrency@@ -2376,7 +2373,6 @@ def create_app(application.state.tier = tierapplication.state.default_tier = default_tierapplication.state.flash_enabled = not no_flash- application.state.backend = backendapplication.state.tier_runtime_options = tier_runtime_optionsapplication.state.model_ids = _model_idsapplication.state.tiers = _tiersdiff --git a/mineru/parser/tier.py b/mineru/parser/tier.pyindex 78486430..ff53481b 100644--- a/mineru/parser/tier.py+++ b/mineru/parser/tier.py@@ -9,63 +9,23 @@ from typing import Finalfrom ..config import VlmConfigfrom ..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: streffort: 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: VlmConmissing_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.pyindex 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 SearchServicefrom mineru.doclib.types import DocContentExportRequest, FileInfo, InvalidateRequest, ParseResponse, WatchRequestfrom mineru.errors import InvalidRequestError, MineruError, NotFoundErrorfrom mineru.filetypes import file_type_for_extension-from mineru.parser import backend_for_tierfrom mineru.parser.api_client import _APITransportError, _V1APIErrorfrom mineru.parser.base import ParseResultfrom 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) -> Nassert 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.pyindex 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, monkapp = create_app(upload_dir=str(tmp_path))assert app.state.tier == "standard"- assert app.state.backend == "hybrid-engine"assert app.state.concurrency == 1assert app.state.url_timeout == 60assert 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: passert 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, monkeypassert 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 Falseassert [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(