MinerU API Configuration#

Overview#

mineru-api uses a two-layer configuration model: service-level config (how the server runs) is fixed at startup, while model-level config (how documents are parsed) starts from CLI-supplied defaults but can be overridden per request via form fields. This separation is enforced at startup by split_service_and_model_config() and carried into every parse job by merging app.state.config with the validated ParseRequestOptions.

Service vs. Model Config Split#

At startup, main() calls arg_parse(ctx) to normalize any unknown CLI flags into a dict, then immediately passes the result to split_service_and_model_config(). This function:

1. Extracts service keys (currently only enable_vlm_preload) from the raw dict, applying defaults from SERVICE_CONFIG_DEFAULTS 1.
2. Returns the remainder as model kwargs — arbitrary key/value pairs forwarded to model constructors (e.g., vLLM arguments).

The results are stored on app.state 2:

app.state.service_config = service_config # controls VLM preload
app.state.config = model_config # forwarded as **config to every parse job

At startup, maybe_preload_vlm_model() reads service_config["enable_vlm_preload"] to decide whether to warm up the VLM model 3. The model_config dict is not consulted at startup — it is passed as **config into run_parse_job() on every request.

Per-Request Configuration via ParseRequestOptions#

Every request (sync POST /file_parse and async POST /tasks) goes through the parse_request_form FastAPI dependency, which validates multipart form fields and returns a ParseRequestOptions dataclass.

Key per-request parameters and their defaults:

Available backends are defined in backend_options.py: pipeline, vlm-engine, hybrid-engine, vlm-http-client, hybrid-http-client. Legacy aliases (vlm-auto-engine, hybrid-auto-engine) are normalized by normalize_backend().

How CLI Defaults Flow Into Requests#

The model_config dict (arbitrary extra CLI kwargs, e.g. --gpu-memory-utilization 0.8) is spread as **config at the end of run_parse_job()'s parse_kwargs dict 6. This means:

• Any key in model_config that matches a do_parse / aio_do_parse parameter acts as a server-wide default.
• Per-request form fields (formula_enable, table_enable, etc.) are set explicitly before the **config spread and thus take precedence over any conflicting keys in model_config.

Unknown CLI args are parsed by parse_unknown_args(), which normalizes dashes to underscores and coerces values to bool | int | float | str. This allows passing arbitrary vLLM constructor args (e.g. --enable-prefix-caching false) directly on the command line.

Configuration Flow Diagram#

mineru-api [CLI flags] [--extra-model-arg value ...]
         │
         ├─ arg_parse() → raw_config dict
         │
         └─ split_service_and_model_config()
               │
               ├─ service_config → app.state.service_config
               │ └─ enable_vlm_preload → maybe_preload_vlm_model() (startup only)
               │
               └─ model_config → app.state.config
                                             │
                         ┌───────────────────┘
                         │ (on each request, spread as **config)
                         ▼
               run_parse_job(output_dir, ..., formula_enable, table_enable, ..., **config)
                         ▲
                         │ (explicit per-request fields take precedence over **config)
               ParseRequestOptions ← POST /file_parse or POST /tasks

Key Source Files#