{"id":51462961,"url":"https://github.com/sergeyshmakov/mineru-runpod","last_synced_at":"2026-07-06T07:30:38.756Z","repository":{"id":358854339,"uuid":"1243320691","full_name":"sergeyshmakov/mineru-runpod","owner":"sergeyshmakov","description":"📄 Serverless MinerU 2.5 Pro PDF parser on RunPod. Scales to zero. PDF → Markdown + JSON.","archived":false,"fork":false,"pushed_at":"2026-06-09T07:45:25.000Z","size":1373,"stargazers_count":1,"open_issues_count":1,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T09:26:02.981Z","etag":null,"topics":["document-ai","mineru","ocr","pdf-extraction","pdf-md","pdf-ocr","pdf-parsing","pdf-to-markdown","python","rag","runpod","serverless","vllm","vlm"],"latest_commit_sha":null,"homepage":"https://sergeyshmakov.github.io/mineru-runpod/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sergeyshmakov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T08:31:20.000Z","updated_at":"2026-06-09T07:43:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sergeyshmakov/mineru-runpod","commit_stats":null,"previous_names":["sergeyshmakov/runpod-mineru","sergeyshmakov/mineru-runpod"],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/sergeyshmakov/mineru-runpod","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeyshmakov%2Fmineru-runpod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeyshmakov%2Fmineru-runpod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeyshmakov%2Fmineru-runpod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeyshmakov%2Fmineru-runpod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sergeyshmakov","download_url":"https://codeload.github.com/sergeyshmakov/mineru-runpod/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergeyshmakov%2Fmineru-runpod/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35182322,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document-ai","mineru","ocr","pdf-extraction","pdf-md","pdf-ocr","pdf-parsing","pdf-to-markdown","python","rag","runpod","serverless","vllm","vlm"],"created_at":"2026-07-06T07:30:37.790Z","updated_at":"2026-07-06T07:30:38.742Z","avatar_url":"https://github.com/sergeyshmakov.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mineru-runpod\n \n\u003c!-- badges: ci, license, python, runpod --\u003e\n[![CI](https://github.com/sergeyshmakov/mineru-runpod/actions/workflows/ci.yml/badge.svg)](https://github.com/sergeyshmakov/mineru-runpod/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](pyproject.toml)\n[![MinerU](https://img.shields.io/badge/MinerU-3.2-purple)](https://github.com/opendatalab/MinerU)\n[![Runpod](https://api.runpod.io/badge/sergeyshmakov/mineru-runpod)](https://console.runpod.io/hub/sergeyshmakov/mineru-runpod)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-fa6673.svg)](https://www.conventionalcommits.org/)\n\nServerless [MinerU](https://github.com/opendatalab/MinerU) PDF parser on [RunPod](https://runpod.io?ref=31jdfpnq). MinerU 3.2.x runtime with the `MinerU2.5-Pro-2605-1.2B` VLM. Scales to zero, ~$0.0003 per page on a 24 GB serverless RTX 4090, ten minutes from sign-up to first parse.\n\n**📚 [Docs](https://sergeyshmakov.github.io/mineru-runpod/)**  ·  **🚀 [Get started on RunPod](https://runpod.io?ref=31jdfpnq)**  ·  **📝 [Blog](https://sergeyshmakov.github.io/mineru-runpod/blog/)**\n\n## 30-second taste\n\nPick your method. Either of these works.\n\n**Python (`mineru_client`):**\n\n```python\nfrom mineru_client import MineruClient\n\nclient = MineruClient(endpoint_id=\"\u003cyour-endpoint-id\u003e\")\nresult = client.parse_document(file_url=\"https://example.com/report.pdf\", end_page=4)\nclient.save_tarball(result, \"./out/doc\")\n# → markdown + content_list + middle.json + images\n```\n\n**curl (no SDK):**\n\n```sh\ncurl -X POST \"https://api.runpod.ai/v2/\u003cendpoint-id\u003e/runsync\" \\\n  -H \"Authorization: Bearer $RUNPOD_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"input\":{\"file_url\":\"https://example.com/report.pdf\",\"end_page\":4,\"transport\":\"inline\"}}'\n```\n\nThe response wraps each parsed file as an entry inside `results: [...]`. For a single document, the markdown sits at `output.results[0].markdown` — pipe it straight to a file: `curl ... | jq -r '.output.results[0].markdown' \u003e report.md`.\n\nAccepts PDF, image (PNG/JPEG/GIF/BMP/TIFF/WebP), DOCX, PPTX, XLSX. Two orthogonal knobs control output — **transport** (`tarball_b64` / `inline` / `s3`) and **formats** — both covered in [Output modes](https://sergeyshmakov.github.io/mineru-runpod/guides/output-modes/).\n\n## Why this exists\n\n- **MinerU** is SOTA for PDF → structured Markdown/JSON: charts, tables, math, 109 languages. Apache 2.0 with explicit commercial thresholds. See the [paper](https://arxiv.org/abs/2604.04771), [repo](https://github.com/opendatalab/MinerU), and [model card](https://huggingface.co/opendatalab/MinerU2.5-Pro-2605-1.2B).\n- **RunPod Serverless** bills per-second and scales to zero. A 100-page document costs roughly $0.03 on a 24 GB serverless RTX 4090 instead of paying for an always-on GPU. See [RunPod pricing](https://www.runpod.io/pricing) for current rates.\n- **You don't have to wire any of that together yourself.** Deploy from the [RunPod Hub](https://runpod.io?ref=31jdfpnq) in one click, or fork this repo for full control.\n\n## Ways to integrate\n\n### A. Quick start with `MineruClient`\n\nA small Python wrapper that lives in this repo. Best for prototyping and single-user scripts — usage is the snippet above. Install it with:\n\n```powershell\n# pip\npip install \"mineru-client @ git+https://github.com/sergeyshmakov/mineru-runpod\"\n\n# or uv\nuv pip install \"mineru-client @ git+https://github.com/sergeyshmakov/mineru-runpod\"\n```\n\n### B. Production with RunPod SDK / HTTP\n\nFor high-throughput, async, or non-Python callers. Hit the endpoint directly using the documented [JSON payload contract](https://sergeyshmakov.github.io/mineru-runpod/reference/api/).\n\n```python\nimport runpod\nrunpod.api_key = \"...\"\nendpoint = runpod.Endpoint(\"\u003cendpoint-id\u003e\")\nresult = endpoint.run_sync({\"input\": {\"file_url\": \"https://example.com/report.pdf\"}})\n```\n\n### C. Migrating from the official MinerU API\n\nAlready calling the MinerU cloud API (`mineru.net/api/v4/...`)? `MineruApiClient` mirrors its `create_task` / `get_task` surface over your own endpoint, so you can evaluate or migrate with a near-identical code path. See [Migrate from the MinerU API](https://sergeyshmakov.github.io/mineru-runpod/getting-started/migrate-from-mineru-api/).\n\nPrototype with A; switch to B once you need async, retries, or multi-language callers. See [Clients](https://sergeyshmakov.github.io/mineru-runpod/getting-started/clients/) for the full comparison.\n\n## API at a glance\n\nSend `{\"input\": {...}}` to `/runsync` (or `/run`). The most-used fields:\n\n| Field | Required | Default | Notes |\n|---|---|---|---|\n| `file_url` / `file_b64` / `volume_path` | exactly one | — | Public URL, base64 bytes, or container path. Format auto-detected. |\n| `end_page` | no | `-1` | 0-based inclusive; `-1` = end of doc |\n| `backend` | no | `\"vlm-auto-engine\"` | `pipeline` / `vlm-auto-engine` / `hybrid-*` / `*-http-client` |\n| `transport` | no | `\"tarball_b64\"` | `tarball_b64` / `inline` / `s3` — how output ships back |\n| `formats` | no | all four | Subset of `markdown` / `content_list` / `middle` / `images` |\n\nResponses wrap each file in a `results: [...]` list alongside a top-level `debug` block; failures set `ok=false` with a top-level `error`. The full field list, per-transport response shapes, and validation rules live in the **[API reference](https://sergeyshmakov.github.io/mineru-runpod/reference/api/)** (mirrored from the docstring atop [`handler.py`](handler.py)).\n\n## How does it compare?\n\nParsing accuracy is MinerU's domain; their published [OmniDocBench](https://github.com/opendatalab/OmniDocBench) leaderboard puts the 1.2B VLM ahead of much larger general-purpose models:\n\n[![MinerU2.5-Pro-2605 vs other PDF parsers — OmniDocBench leaderboard](https://hotelll.github.io/MinerU2.5-Pro/leaderboard.png)](https://huggingface.co/opendatalab/MinerU2.5-Pro-2605-1.2B)\n\n\u003csub\u003eSource: [MinerU2.5-Pro-2605-1.2B model card](https://huggingface.co/opendatalab/MinerU2.5-Pro-2605-1.2B) and the [MinerU 2.5 technical report](https://arxiv.org/abs/2604.04771).\u003c/sub\u003e\n\n| | mineru-runpod (this) | Marker | GROBID | Nougat |\n|---|---|---|---|---|\n| Scale-to-zero | ✅ ready to use | ⚠️ possible, needs extra setup | ❌ (always-on) | ❌ |\n| GPU support | GPU only | CPU or GPU | CPU | GPU required |\n| Equations | ✅ LaTeX | ✅ LaTeX | ❌ | ✅ LaTeX |\n| Multi-lang | ✅ 109 langs (pipeline backend) | per upstream README | EN only | per upstream README |\n| Setup time | 5 min | 10 min | 30 min | 20 min |\n| License | Apache 2.0 + attribution\\* | **GPL-3.0 code + modified RAIL-M weights**\\*\\* | Apache 2.0 | MIT code + **CC-BY-NC 4.0 weights** |\n| Commercial SaaS | ✅ free below thresholds\\* | ⚠️ depends on RAIL-M competitor clause\\*\\* | ✅ free | ⚠️ subject to CC-BY-NC non-commercial clause |\n\n\u003csub\u003e\\*MinerU is Apache 2.0 with an addendum: free commercial use up to 100M MAU and $20M monthly revenue, with attribution required in UI/docs. See the [MinerU LICENSE](https://github.com/opendatalab/MinerU/blob/master/LICENSE.md).\u003c/sub\u003e\n\n\u003csub\u003e\\*\\*Marker's code is GPL-3.0; its OCR engine (Surya) ships under a modified RAIL-M licence whose §2(c) prohibits use by entities that \"provide … any product or service that competes with … Licensor.\" Datalab's own README says Marker is free for \"startups under $2M funding/revenue\" — that carveout doesn't appear in the literal licence text, so the two read differently. Verify the current licence against your own usage with counsel before depending on Marker for a competing service. Datalab ships [Chandra](https://github.com/datalab-to/chandra) (the model behind their hosted API) under the same modified RAIL-M licence. See [Surya MODEL_LICENSE](https://github.com/datalab-to/surya/blob/master/MODEL_LICENSE) and [Chandra MODEL_LICENSE](https://github.com/datalab-to/chandra/blob/master/MODEL_LICENSE).\u003c/sub\u003e\n\nThe license row matters most for production SaaS. Marker pairs GPL-3.0 code with modified RAIL-M weights whose competitor clause is at least ambiguous about commercial reach; Datalab's marketing and the literal license text say different things, so plan for legal review. Nougat's model weights are CC-BY-NC 4.0 — Creative Commons' definition of non-commercial use is fuzzy at the edges, and deploying Nougat as part of a paid service is plainly outside it. GROBID is cleanly Apache 2.0 but is English-only and equations-blind. MinerU is the only one of the four with both production-grade accuracy AND a license whose commercial reach is documented in clear, quantitative terms (100M MAU and $20M monthly revenue thresholds).\n\n## Documentation\n\nEverything below the surface lives on the docs site:\n\n- **[Overview](https://sergeyshmakov.github.io/mineru-runpod/getting-started/overview/)** — what it is, who it's for, architecture\n- **[Deploy](https://sergeyshmakov.github.io/mineru-runpod/getting-started/deploy/)** — Hub one-click, fork-and-build, or BYO image\n- **[Clients](https://sergeyshmakov.github.io/mineru-runpod/getting-started/clients/)** — Python `MineruClient` vs. direct RunPod SDK\n- **[Migrate from the MinerU API](https://sergeyshmakov.github.io/mineru-runpod/getting-started/migrate-from-mineru-api/)** — drop-in-shaped `MineruApiClient` for moving off the cloud API\n- **[Choosing a GPU](https://sergeyshmakov.github.io/mineru-runpod/guides/choosing-gpu/)** — workload-to-pool map, when to bump VRAM\n- **[API reference](https://sergeyshmakov.github.io/mineru-runpod/reference/api/)** — JSON payload contract, response shapes, validation rules\n- **[Blog](https://sergeyshmakov.github.io/mineru-runpod/blog/)** — launch posts and project notes\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Commits follow [Conventional Commits](https://www.conventionalcommits.org/); commitlint enforces this in CI and `CHANGELOG.md` is generated automatically by semantic-release on push to `main`.\n\n## Support this project\n\nIf this saves you time, the cheapest way to support development is to **[sign up for RunPod through this link](https://runpod.io?ref=31jdfpnq)**. Costs you nothing extra and lets the maintainer keep iterating.\n\n## License\n\n[MIT](LICENSE). The underlying [MinerU](https://github.com/opendatalab/MinerU) is Apache-2.0; the [RunPod SDK](https://github.com/runpod/runpod-python) is MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergeyshmakov%2Fmineru-runpod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsergeyshmakov%2Fmineru-runpod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergeyshmakov%2Fmineru-runpod/lists"}