Overview

mineru-runpod runs MinerU 3.4.x on RunPod Serverless, using the MinerU2.5-Pro-2605-1.2B VLM by default. It is a generic parsing endpoint rather than a hosted application: the repo contains the worker image, two Python client surfaces, and endpoint lifecycle scripts. A RAG pipeline, document indexer, or Office archive can call the same document → Markdown + structured JSON contract.

What's in the repo

• handler.py — the serverless worker. Accepts a PDF via URL, base64, or mounted-volume path; calls MinerU's async parse; returns Markdown + content_list + middle.json + images. The MinerU-specific parts live in worker/; input transport, response packaging, logging and diagnostics come from the harness below.
• runpod-doc-worker — a dependency, not a directory: the engine-agnostic half of this worker, extracted so the repo can be the engine and the entry point. It fetches the input from a URL, a base64 blob or a volume path, checks outbound targets, packs the result as a tarball, inline fields or an S3 object, emits one JSON log line per record, and answers a probe: true job. What this worker declares to it — env prefix, input roots, output manifest — is one file, worker/harness.py. See the harness docs.
• mineru_client/ — the dependency-light Python package. MineruClient exposes the native worker contract; MineruApiClient provides a temporary compatibility facade for evaluating a move from the MinerU cloud API.
• deploy.py / destroy.py — create and remove endpoints with CLI flags for identity, scaling, GPU, disk, and timeout settings. Configure environment variables, secrets, storage, and regions in RunPod.
• .runpod/hub.json — the active RunPod Hub listing and deploy form, including GPU pools and optional integration settings.
• examples/ — URL, base64, API-compatibility, and typed-adapter examples.

Who it's for

Why MinerU + serverless

• Published evaluation. The MinerU2.5-Pro-2605-1.2B model card reports OmniDocBench results for text, formulas, tables, and reading order. Review the model card, benchmark, and technical report for scope and limitations.
• Economics. Per-second billing on RunPod with FlashBoot means an idle worker costs nothing. ~$0.0003 per page on a 24 GB RTX 4090 (default) at current rates (see RunPod pricing; rates change).
• Licensing. MinerU uses an open-source license based on Apache 2.0 with additional terms, attribution requirements, and stated commercial thresholds. Review the upstream terms for your use case.

_{Source: MinerU2.5-Pro-2605-1.2B model card and the MinerU 2.5 technical report.}

How it compares

Marker uses Surya as its in-process OCR/layout engine; Surya's weights ship under a modified RAIL-M license. The license's §2(c) competitor clause does not include the $2M revenue carveout that §2(a) and §2(b) carry, while Marker's own README markets the model weights as free for "startups under $2M funding/revenue." The two read differently — get counsel before depending on Marker for a service that could be characterized as competitive. Datalab's Chandra model (what their hosted API runs) carries the same modified RAIL-M license.

See the project README for the fully source-cited version of this comparison.

What it accepts and what comes back

• Inputs: PDF, image (PNG/JPEG/GIF/BMP/TIFF/WebP), DOCX, PPTX, XLSX — auto-detected from bytes. Three sources: URL, base64, or a path on a mounted volume. See Input formats.
• Outputs: Markdown + content_list + middle.json + extracted images. Three transport modes: base64 tarball, inline fields, or presigned URL to an S3-compatible bucket. See Output modes.
• Backends: five MinerU backends — the VLM (model card tagged English + Chinese; empirically handles Cyrillic on the tested Pro model), the pipeline OCR with script-family language models, the hybrid auto-router, and two backends for an external VLM server. See Picking a backend.

Versions and compatibility

This template tracks MinerU 3.4.x, pinned as mineru[core,vllm]>=3.4.0,<3.5.0.

The major version moves only when MinerU has a major release. Breaking changes to the job contract or to installability ship on a minor and lead the release notes — see Versioning for what to read before upgrading.

Next steps

The Deploy guide covers all three supported paths:

1. Deploy the public RunPod Hub template for the shortest setup.
2. Fork the repository and let RunPod auto-build it when you need code or dependency changes.
3. Bring your own container image when you control the image pipeline.

After deployment, use Clients for the first request and OpenTelemetry when the endpoint needs production logs, traces, and metrics.