PDF zu Markdown in Python konvertieren

Warum Markdown — und warum das schwerer ist, als es aussieht

LLMs verarbeiten Markdown außergewöhnlich gut: Überschriften markieren Abschnittsgrenzen, Pipe-Tabellen halten tabellarische Daten ausgerichtet, und Listen bleiben Listen. Roh aus der PDF extrahierter Text verliert all das — und die PDF-Binärdatei direkt einzuspeisen ist für die meisten Pipelines keine Option. Deshalb konvertiert praktisch jeder ernsthafte RAG-Stack Dokumente vor dem Chunking und Embedding zu Markdown.

Der schwierige Teil: PDFs enthalten keine Struktur, sondern Zeichen an x/y-Koordinaten. Ein Konverter muss zurückrechnen, welche Zeilen Überschriften sind (aus der Schriftgröße), welche Wörter eine Tabelle bilden (aus der Ausrichtung) und wie die Lesereihenfolge lautet (aus der Layout-Analyse). Wie gut Bibliotheken das können, unterscheidet sich enorm — genau deshalb ist die Wahl wichtig.

Eine zweite Komplikation: Gescannte PDFs enthalten überhaupt keinen Text, nur Bilder von Seiten. Nur einige der folgenden Optionen kommen damit klar — per OCR.

Option 1: PyMuPDF4LLM — schnell und leichtgewichtig

PyMuPDF4LLM ist eine dünne Schicht über PyMuPDF (fitz), gebaut speziell für LLM-Pipelines: pip install pymupdf4llm, dann md = pymupdf4llm.to_markdown("doc.pdf") — eine Zeile, und sehr schnell: Die meisten Dokumente sind in deutlich unter einer Sekunde verarbeitet.

Die Bibliothek erkennt Überschriften an Schriftgrößen, rendert Tabellen als Pipe-Tabellen und kann Seiten-Chunks mit Metadaten ausgeben — direkt bereit für LlamaIndex oder LangChain. Für digital erzeugte PDFs mit unkomplizierten Layouts — Berichte, Dokumentation, Papers ohne exotische Formatierung — ist sie ein exzellenter Default.

Grenzen: kein OCR, gescannte Seiten kommen also leer zurück. Komplexe mehrspaltige Layouts und verschachtelte Tabellen können durcheinandergeraten, weil die zugrunde liegenden Heuristiken Geschwindigkeit über tiefe Layout-Analyse stellen. Lizenzhinweis: PyMuPDF steht unter AGPL — für interne Tools unproblematisch, aber vor dem Einbau in ein kommerzielles Produkt mit der Rechtsabteilung klären.

Option 2: Marker — höchste Qualität, braucht eine GPU

Marker nutzt eine Pipeline aus Deep-Learning-Modellen für Layout-Erkennung, Lesereihenfolge und Tabellenstruktur und produziert das treueste Markdown aller Open-Source-Optionen — mehrspaltige wissenschaftliche Papers, komplexe Tabellen und sogar Formeln funktionieren.

Der Preis ist Infrastruktur: mehrere Gigabyte Modellgewichte, eine GPU für vernünftige Geschwindigkeit (CPU geht, ist aber langsam — oft Dutzende Sekunden pro Dokument) und ein schwerer Dependency-Baum, dessen Deployment in Produktions- oder Serverless-Umgebungen echten Aufwand bedeutet.

Marker ist die richtige Wahl, wenn Ausgabequalität bei schwierigen Dokumenten oberste Priorität hat und die Hardware da ist — ein wissenschaftliches Korpus auf einer GPU-Maschine massenzukonvertieren ist sein Sweet Spot. Für einen leichtgewichtigen Service oder eine Serverless-Funktion scheidet er wegen des operativen Gewichts meist aus.

Option 3: MarkItDown — Microsofts Alles-Konverter

MarkItDown ist Microsofts Open-Source-Bibliothek für alles-zu-Markdown: pip install markitdown, dann MarkItDown().convert("doc.pdf").text_content. Ihre Stärke ist die Breite — dieselbe API konvertiert PDF, DOCX, PPTX, XLSX, HTML und mehr, weshalb sie für LLM-Datenaufbereitung viral ging.

Speziell bei PDFs ist die Extraktion simpler als bei den dedizierten Optionen: Sie stützt sich auf einfache Textextraktion, sodass Überschriften-Erkennung und Tabellentreue hinter PyMuPDF4LLM und Marker zurückbleiben — und gescannte PDFs brauchen ein zusätzliches OCR-Setup.

MarkItDown ist die richtige Wahl, wenn eine einzige Dependency viele Dateitypen bei moderater Qualität abdecken soll — etwa ein internes Ingestion-Skript, das akzeptieren muss, "was auch immer die Leute hochladen" — und nicht die bestmögliche PDF-Ausgabe zählt.

Option 4: Eine gehostete API — ganz ohne Dependencies

Die vierte Option: die Konvertierung gar nicht lokal laufen lassen, sondern die PDF per POST an eine Parsing-API schicken und Markdown zurückbekommen. Mit ParseJet: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — das "text"-Feld der JSON-Antwort ist das Markdown.

Dieser Weg hat OCR für gescannte Seiten eingebaut, braucht keine Modellgewichte oder nativen Bibliotheken und funktioniert identisch in einer Serverless-Funktion, einem Container oder einem Notebook. Die AGPL-Frage umgeht er gleich mit. Der Trade-off: ein Netzwerk-Roundtrip und Kosten pro Dokument nach dem Free-Tier (300 Credits/Monat kostenlos; eine PDF kostet 3 Credits).

Die API ist die richtige Wahl, wenn die Pipeline heute laufen soll, wenn Scans unter den PDFs sind oder wenn das Deployment-Ziel schwere Dependencies bestraft — Lambda, Cloud Run, Vercel.

Welche Option ist die richtige?

Digital erzeugte PDFs, einfache bis mittlere Layouts, Geschwindigkeit zählt: PyMuPDF4LLM. Das beste Aufwand-zu-Qualität-Verhältnis in reinem Python.

Schwierige Dokumente (mehrspaltige Papers, komplexe Tabellen) und eine GPU vorhanden: Marker. Nichts Open-Source schlägt seine Ausgabequalität.

Viele verschiedene Dateitypen durch eine Bibliothek, moderate Qualität reicht: MarkItDown.

Gescannte PDFs im Mix, Serverless-Deployment oder null Lust auf Dependency-Management: die gehostete API. Ein HTTP-Aufruf, OCR inklusive, dasselbe Ausgabeschema für jedes Dokument.

Komplettes Beispiel: PDF-Ordner zu Markdown-Dateien

Egal welcher Weg — die Pipeline hat immer dieselbe Form: iterieren, konvertieren, schreiben. Hier mit der API (für die lokale Variante den inneren Aufruf durch pymupdf4llm.to_markdown() ersetzen):

import httpx; from pathlib import Path — dann für jede pdf in Path("pdfs/").glob("*.pdf"): resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": pdf.read_bytes()}); Path("md/", pdf.stem + ".md").write_text(resp.json()["text"], encoding="utf-8").

Für die RAG-Ingestion das Markdown entlang der Überschriften chunken statt nach fixen Zeichenzahlen — überschriften-bewusste Chunks halten Abschnitte zusammen und retrieven dramatisch besser. Genau diese strukturelle Treue ist der Grund, warum sich der sorgfältige Konvertierungsschritt gelohnt hat.