
pdfmux
io.github.NameetP由 GitHub 账号 NameetP 发布v1.8.7更新于 Oct 25, 2026
PDF-to-Markdown extraction that audits its own output and flags any extractor's silent drops.
概览
本地 MCP 服务器,将 PDF 转换为 Markdown、JSON 或 RAG 分块,并审计自身输出、核查其他提取器是否静默丢页。
- 可以做什么
- 将 PDF 转换为 Markdown、JSON、CSV 或适合 RAG 的分块,按页在多个本地后端间路由并可选用 LLM 兜底,支持整目录批处理和长文档流式输出。分析与审计提取质量,返回每页置信度、覆盖率与被标记的页面,而不是静默丢弃。使用发票、收据、合同、简历、论文等内置模式提取结构化数据。读取 PDF 元数据,并可将其他引擎的输出与源 PDF 比对,报告被静默丢弃的页面。
- 适用场景
- 适合助手需要读取或索引 PDF 用于 RAG 流程时,尤其是包含扫描件、表格或复杂版式的混合批次;也适合需要置信度评分并明确标出失败页面而非留下静默缺口的场景。还可用于检查现有提取引擎是否漏页。
- 运行要求
- 以本地进程运行,通过 pip install pdfmux 安装(需 Python 3.11+);扫描页建议加装 OCR 扩展。可选的 GEMINI_API_KEY 启用付费 Gemini Flash 兜底,不设置则完全本地运行。仅在配置后才会把页面发送给第三方 LLM 提供商。
安装
在 SourceWeft 中
- 打开 控制台中的 pdfmux,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
pdfmux
[CI] [PyPI] [Python 3.11+] [License: MIT] [Downloads]
Self-healing PDF extraction that flags the pages it can't read instead of dropping them — and now certifies any extractor's output for silent drops. Open-source LlamaParse alternative for RAG pipelines, MCP server for Claude Desktop, LangChain + LlamaIndex loaders.
pdfmux extracts PDFs and checks its own work — and now certifies any extractor's, telling you which pages it silently dropped. Free, MIT. Patent-pending method.
pip install pdfmux.
Two jobs, one tool:
- Self-healing extraction. The only PDF extractor that audits its own output. Catches blank pages, scrambled columns, broken tables — re-extracts them with a stronger backend, and flags what it still can't read instead of silently dropping it. So your LLM gets clean data, not silent garbage. Routes each page to the best of 7 built-in extraction backends + BYOK LLM fallback (Gemini / Claude / GPT-4o / Ollama). One CLI. One API. Zero config.
- Certify Anything — new in v1.8.1.
pdfmux verifyaudits any extraction engine's output against the source PDF — Reducto, Mistral OCR, LlamaParse, Docling, your in-house parser — and tells you which pages it silently dropped. Free, MIT, patent-clean.
Install
That handles digital PDFs. For any real-world batch, install pdfmux[ocr] too — almost every directory of PDFs has at least one scan, and without OCR those pages return empty text:
Other backends, by document type:
Requires Python 3.11+.
Quick Start
CLI
Python
For batch processing, use batch_extract() — not a subprocess.run(['pdfmux', ...]) loop. Same pipeline, no per-file process spawn, handles non-ASCII filenames:
Don't wrap pdfmux with your own pypdf/pdfplumber fallback. pdfmux already routes per page through PyMuPDF → RapidOCR → vision LLM. PyMuPDF tolerates malformed PDFs that pypdf rejects ("Stream has ended unexpectedly"), so a downstream pypdf fallback turns recoverable PDFs into failures. Trust the router; check the confidence score on the result.
Certify Anything
pdfmux verify audits any extraction engine's output against the source PDF and tells you which pages it silently dropped — not just pdfmux's own extraction. Point it at the output of Reducto, Mistral OCR, LlamaParse, Docling, or your in-house parser and it re-derives the source text with pdfmux's own audit pass, aligns the extraction to it, and scores every page.
The failure it catches: a page where the source has real text but the engine returned nothing — while reporting success. That "silent drop" is the exact failure that poisons a RAG index without a single error in the logs.
Every run prints a PASS / REVIEW / FAIL verdict, overall confidence and coverage, and — when it finds them — the silently dropped pages by number:
Per page you get a verdict (pass / review / fail), confidence, coverage, alignment, hallucination-risk, and table/heading integrity. Batch mode rolls that up into a single "N pages silently dropped across M documents" line — the report you run on 100 of your own PDFs to find the silent failures already in your pipeline.
It works on any engine's output
--extracted accepts JSON, Markdown, or plain text (--extracted-format auto | json | markdown | text). When the extraction exposes real per-page structure, pdfmux compares page-by-page; when it's a single blob, it falls back to content-presence checks so it never fabricates a "silent drop" from a pagination mismatch.
Python API
Each manifest carries a tamper-evident SHA-256 content signature over its canonical body and an embedded, honest limitations list: the certifier is lexical, not linguistic — it detects missing and garbled content, not faithful paraphrase or translation.
MCP
verify_extraction is exposed as an MCP tool (the 7th — see MCP Server), so an agent can certify an engine's output in the same session it extracts.
Free, MIT, patent-clean
Certify Anything reuses only pdfmux's shipped MIT audit layer. It does not include, and does not require, the patent-pending decision-trace method — that stays in pdfmux Cloud/Pro. pip install pdfmux gives you the full verify command at no cost.
Full reference: docs/CERTIFY-ANYTHING.md.
When you need to prove it to someone else
A local install can audit an extraction, but it cannot attest to one — anything it signs, anyone could forge. pdfmux Cloud returns an Ed25519-signed manifest over the extraction: your auditor verifies it offline, against a published public key, without an account and without trusting pdfmux.
Verification is free and open forever; only generation is paid ($49/mo). That asymmetry is deliberate — you should never need our permission to check our work.
Free tool, no signup: app.pdfmux.com/audit — upload a PDF and see which pages your current extractor silently dropped. Measured accuracy (and its blind spots) published in pdfmux-bench.
Architecture
Key design decisions
- Router, not extractor. pdfmux does not compete with PyMuPDF or Docling. It picks the best one per page.
- Agentic multi-pass. Extract, audit confidence, re-extract failures with a stronger backend. Bad pages get retried automatically.
- Segment-level detection. Each page is classified by content type (text, tables, images, formulas, headers) before routing.
- 4-signal confidence. Dynamic quality scoring from character density, OCR noise ratio, table integrity, and heading structure. Not hardcoded thresholds.
- Document cache. Each PDF is opened once, not once per extractor. Shared across the full pipeline.
- Data flywheel. Local telemetry tracks which extractors win per document type. Routing improves with usage.
Features
CLI Reference
pdfmux convert
pdfmux serve
Start the MCP server for AI agent integration.
pdfmux doctor
pdfmux benchmark
pdfmux estimate
Predict spend (and which backends will run) before processing.
pdfmux stream
Emit NDJSON events as pages complete — useful for very long PDFs and live UIs.
pdfmux watch
Auto-convert any PDFs that land in a directory. Survives until Ctrl+C.
pdfmux diff
Side-by-side extraction comparison (quality, content, cost).
pdfmux profiles
Saved configs at ~/.config/pdfmux/profiles.yaml. Built-ins ship for the
common shapes; save your own for project defaults.
Python API
Text extraction
Structured extraction
RAG chunking
Schema-guided extraction
Streaming (bounded memory)
Types and errors
Framework Integrations
LangChain
LlamaIndex
MCP Server (AI Agents)
Listed on mcpservers.org. One-line setup:
Or via Claude Code:
Tools exposed: convert_pdf, analyze_pdf, extract_structured,
extract_streaming, get_pdf_metadata, batch_convert.
BYOK LLM Configuration
pdfmux supports any LLM via 5 lines of YAML. Bring your own keys -- nothing leaves your machine unless you configure it to.
Supported providers:
Every provider's extract_page() is wrapped in @with_retry(max_attempts=3, backoff_base=2.0), which honors Retry-After headers on 429s and skips
retries on auth failures so a bad key fails fast.
Arabic & RTL Support
pdfmux ships first-class support for Arabic, Persian, Urdu, and Hebrew. Out of the box, RTL detection runs on every PDF and PyMuPDF-extracted pages are passed through the Unicode Bidirectional Algorithm so glyphs that were stored in left-to-right order render in correct reading order.
What happens automatically:
pdfmux convertdetects Arabic content and routes pages with >5% Arabic characters through the Arabic-aware extractor chain.- PyMuPDF, RapidOCR, and Docling outputs are post-processed with the
Bidi algorithm — markdown headings (
#) and pipe-table rows preserve structure, only inner text is reordered. DocumentResult.has_arabicis set toTruewhenever any page contains Arabic script.
What requires opt-in:
- Vision LLM extraction. Set
--llm-provider gemma(or any vision provider) to route Arabic pages through Gemma instead of PyMuPDF. - Aggressive normalization (Tatweel removal, Alef/Yeh unification,
Tashkeel stripping) — call
pdfmux.arabic.normalize_arabic(text)on extracted strings if you need canonicalized output for search or embedding.
Proof: a real customer batch
We measured pdfmux on 433 real customer documents — technical and safety data sheets, mixed digital and scanned, some encoding-corrupted. Run the naive way first (an early pdfmux CLI in a subprocess, pypdf fallback, no OCR), the pipeline silently dropped 16 documents — 11 of them with no log line at all. That was our own tool failing at the exact thing it promises.
Rebuilt with the per-page audit + budgeted OCR cascade: 433 of 433 processed, zero silent failures. Every unrecoverable page is flagged, not dropped.
(A small internal confidence-calibration set also ships under eval/ — it's a regression guard on the confidence gate, not a competitive benchmark; see eval/README.md.)
Benchmark
On opendataloader-bench — 200 real-world PDFs (financial filings, academic papers, legal contracts, government reports) — pdfmux scores 0.903 overall — #2 of the 8 engines measured, behind opendataloader-hybrid (0.909). Re-run 2026-07-16 (reproduction below).
Full per-document scores: the 200-PDF head-to-head · methodology: best PDF extraction library, benchmarked.
Smart Result Cache
Re-running the same extraction is instant. pdfmux hashes every input PDF
(SHA-256) and keys results on (file_hash, quality, format, schema). Cache
files live under ~/.cache/pdfmux/results/, expire after 30 days, and are
LRU-evicted at 1 GB.
The cache also speeds up --profile, --schema, and --format switches —
each combination is keyed independently, so you can flip between Markdown
and JSON for the same document for free after the first extraction.
Confidence Scoring
Every result includes a 4-signal confidence score:
- 95-100% -- clean digital text, fully extractable
- 80-95% -- good extraction, minor OCR noise on some pages
- 50-80% -- partial extraction, some pages unrecoverable
- <50% -- significant content missing, warnings included
When confidence drops below 80%, pdfmux tells you exactly what went wrong and how to fix it:
Cost Modes
Set a hard budget cap: --budget 0.50 stops LLM calls when spend reaches $0.50 per document.
Why pdfmux?
pdfmux is not another PDF extractor. It is the orchestration layer that picks the right extractor per page, verifies the result, and retries failures.
Open source Reducto alternative: what costs $0.015/page elsewhere is free with pdfmux's rule-based backends, or ~$0.002/page average with BYOK LLM fallback.
Development
Contributing
- Fork the repo
- Create a branch (
git checkout -b feature/your-feature) - Write tests for new functionality
- Ensure
pytestandruff checkpass - Open a PR
License
The pdfmux library and MCP server in this repository are MIT licensed — free for any use, and every released version stays MIT.
The confidence-budgeted decision-trace method (the persisted per-page decision trace with retained rejected candidates, and the monotonic repair guard) is patent-pending (US Provisional App No. 64/106,302) and is reserved for pdfmux Cloud/Pro under a separate commercial license — it is not part of the MIT grant. See LICENSING.md and NOTICE.
来源:README.md,提交 3e6e88d
工具
0版本历史
1- v1.8.7最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分