MinerU Gradio Interface#

Overview#

The Gradio web UI (mineru/cli/gradio_app.py) is the primary interactive frontend for MinerU. It accepts PDF, image, and Office files (DOCX, PPTX, XLSX), dispatches document-parsing jobs to a backend API server (local or remote), and streams real-time status updates back to the user while they wait. Output is delivered as a downloadable ZIP archive alongside rendered Markdown and JSON tabs.

Entry point: mineru/cli/gradio_app.py — invoked via the main() Click command 1.

Architecture: Local API Server + Gradio Frontend#

The UI does not call the document-parsing libraries directly. Instead, it delegates to a FastAPI backend via HTTP:

• By default, Gradio starts a reusable local mineru-api process managed by ReusableLocalAPIServer in api_client.py. The singleton is held at module level as _gradio_local_api_server 2.
• A remote API URL can be supplied via --api-url, in which case the local process is never started 3.
• VLM model preloading on startup is gated by --enable-vlm-preload 4.

The local server is launched as a subprocess (or a multiprocessing spawn process on Ascend/Linux) and shut down via atexit 5.

File I/O and Output Layout#

Each conversion creates an isolated run directory under ./output/gradio/<run_id>/:

./output/gradio/<timestamp>_<uuid>_<stem>/
├── result/ ← extracted parse output (images, MD, JSON)
└── <stem>.zip ← downloadable archive of result/

This directory structure is built by create_gradio_run_paths() and run_root.mkdir() 6.

The ZIP archive is created by compress_directory_to_zip(), which recursively walks the parse output directory. After extraction, the temporary result ZIP downloaded from the API server is deleted 7.

Allowed Paths and HTTP File Serving#

Gradio only serves files over HTTP from explicitly allowed directories. The build_gradio_allowed_paths() function:

1. Reads a comma-separated GRADIO_ALLOWED_PATHS environment variable.
2. Always appends the resolved ./output directory (the default output root).
3. Passes the final list to demo.launch(allowed_paths=...) 8.

This is the prerequisite for image preview. After parsing, embedded image paths in the Markdown are rewritten from local filesystem paths to /gradio_api/file=<abs_path> HTTP URLs by replace_image_with_gradio_file_urls(). This rewriting only affects the in-memory preview string sent to gr.Markdown — the exported .md file retains its original relative paths 9.

Supported preview image extensions: .jpg, .jpeg, .png, .gif, .webp, .svg 10.

For Office file preview, the Gradio file is exposed at a public URL via build_gradio_file_public_url(), which respects x-forwarded-host and x-forwarded-proto headers for reverse-proxy environments, and is passed to Microsoft Office Online's embedding endpoint 11.

Async Streaming Pattern for Real-Time Status#

The conversion is driven by stream_to_markdown(), an async generator that runs the actual job as a background asyncio.Task and streams UI updates via yield 12.

Key design points:

• Job task: _run_to_markdown_job() runs as an asyncio.Task; all its status messages are pushed through a thread-safe asyncio.Queue via loop.call_soon_threadsafe() 13.
• Event loop: The main while True: loop uses asyncio.wait(..., return_when=FIRST_COMPLETED) across three competing tasks: queue_get_task, timer_task, and the main job_task 14.
• Status panel state: A StatusPanelState dataclass accumulates log lines and tracks animated "processing" and "queue" states with elapsed timers. Updates are only yielded when state actually changes.
• Concurrency limiting: Before dispatching, the request acquires a slot from GradioRequestConcurrencyLimiter (backed by asyncio.Semaphore). While waiting, it emits a "Queued locally: N ahead" message 15.
• Timer interval: Status ticks fire every STATUS_TIMER_INTERVAL_SECONDS = 0.1s during processing and every STATUS_QUEUE_ANIMATION_INTERVAL_SECONDS = 1.0s during queue animation 16.

The full pipeline of status messages emitted during a job:
Preparing request → Checking server → Submitting task → Queued on server / Processing on server → Downloading result → Preparing outputs → Completed 17.

Key CLI Options#

18

Gradio 5 / 6 Compatibility#

The file detects the installed Gradio major version at import time and selects the appropriate kwarg names for API visibility, CSS injection, and footer links 19. The IS_GRADIO_6 flag gates several blocks throughout the file.