Model Weight Management#

MinerU's model weight management system handles automatic download, local caching, path resolution, and configuration persistence for all pipeline and VLM model weights. The primary implementation lives in mineru/utils/models_download_utils.py, with a CLI entry point in mineru/cli/models_download.py and consumption in mineru/backend/pipeline/model_init.py.

Model Sources#

Three model sources are supported 1:

The resolved source is determined by resolve_model_source(), which checks (in order): the MINERU_MODEL_SOURCE environment variable → model-source in mineru.json → automatic detection via resolve_auto_model_source().

resolve_auto_model_source() is decorated with @lru_cache(maxsize=1), so reachability is only probed once per process 2. Once resolved from auto, the result is immediately persisted back to mineru.json to avoid repeating the probe on subsequent runs 3.

Model Paths (ModelPath)#

All model weight relative paths are centralised in the ModelPath class (mineru/utils/enum_class.py):

Two repo_mode values govern which root repo and path semantics to use: 'pipeline' (for all the models above) and 'vlm' 4.

Download & Cache Flow#

The central function is auto_download_and_get_model_root_path(relative_path, repo_mode='pipeline'). Its logic:

1. Local mode – returns the directory configured under models-dir[repo_mode] in mineru.json immediately 5.
2. Configured cache hit – calls get_existing_configured_model_root() to check if mineru.json already points to a directory that contains the requested model path. If so, returns the root path without any network call.
3. Remote download – calls _snapshot_download_cached(), which is @lru_cache(maxsize=None) — deduplicated per (model_source, repo_mode, repo, relative_path) key within the process. After a successful download, it calls persist_downloaded_model_config() to write the cache directory path into mineru.json.

The config file path defaults to ~/mineru.json but is overridable via the MINERU_TOOLS_CONFIG_JSON environment variable 6. If the file's config_version is below the current MINERU_CONFIG_VERSION (1.3.2), the template at https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/mineru.template.json is fetched and merged in, preserving user-set keys 7 8.

MFR Weight Resolution at Runtime#

MineruPipelineModel and MineruHybridModel in model_init.py resolve the MFR weight directory at instantiation time:

mfr_weight_dir = os.path.join(
    auto_download_and_get_model_root_path(mfr_model_path),
    mfr_model_path
)

The active MFR backend is selected by the MINERU_FORMULA_CH_SUPPORT environment variable: False (default) → unimernet_small; True → pp_formulanet_plus_m 9.

CLI: mineru-models-download#

The download_models Click command provides an interactive or flag-driven way to pre-download weights:

• -s / --source: auto | huggingface | modelscope
• -m / --model_type: pipeline | vlm | all

Pipeline download iterates over all ModelPath entries and calls auto_download_and_get_model_root_path for each 10. VLM download fetches the entire repo root 11. The source is temporarily injected via MINERU_MODEL_SOURCE using a context manager temporary_model_source() so it doesn't bleed into subsequent operations.

Key Files#