Wie OCR ein gescanntes PDF liest, und warum dieses Werkzeug Markdown liefert
Ein gescanntes PDF ist ein Bild von Text. Dieser OCR-Endpunkt liefert standardmäßig Markdown und auf Wunsch ein durchsuchbares PDF. Auto nutzt vorhandenen Text, Force OCR liest jede Seite neu.

Ein gescanntes PDF speichert Seiten als Rasterbilder, also als Fotografien von Text und nicht als markierbare Zeichen. OCR (Optical Character Recognition) betrachtet diese Pixel, schätzt, welche Formen Zeichen sind, und gibt echten Text aus. Auf PDF123 läuft das als kostenloses Browserwerkzeug und als POST /api/v1/misc/ocr-pdf; die Antwort ist standardmäßig Markdown oder auf Wunsch ein durchsuchbares PDF.
Der Scan bleibt ein Bild
OCR bereinigt, schärft oder ersetzt die Bitmap nicht. Ein scharfer Scan, den OCR falsch liest, sieht weiterhin scharf aus. Nicht das Bild war der Engpass bei der Qualität, sondern die Erkennung. Tauscht man bei denselben Scans nur die Erkennungs-Engine aus, kann die Genauigkeit stark schwanken, obwohl sich an den Pixeln selbst nichts ändert.
Klassisches PDF-OCR schreibt eine zweite, unsichtbare Textebene unter das Bild, damit Markieren und Suchen auf den richtigen Wörtern landen. Genau das zeigt das Diagramm, und so arbeiten bis heute viele Desktopwerkzeuge.
Was dieser Endpunkt tatsächlich liefert
Die Route OCR ruft /api/v1/misc/ocr-pdf auf, das auf einer eigenständigen Rust-Crate namens pdf-inspector läuft (gebaut mit ihrem ocr-Feature). Sie übergibt nicht das gesamte PDF an ein Erkennungsmodell. pdf-inspector klassifiziert zunächst jede Seite entweder als bereits mit extrahierbarem nativem Text oder als reine Bildseite. Seiten mit nativem Text behalten diesen Text unverändert und berühren das Erkennungsmodell nie; reine Bildseiten durchlaufen stattdessen die Erkennungspipeline: PDFium (derselbe Open-Source-Renderer, den Chrome intern verwendet) rastert die Seite, und ONNX Runtime führt das Modell PP-OCRv6 Small aus, um sie zu lesen. Beide Seitenarten werden anschließend der Reihe nach zu einem einzigen Markdown-Dokument zusammengefügt, weshalb die Antwort text/markdown ist und der Download mit .md endet.
Dieser Vertrag ist neu mit dieser Neufassung. Das Java/Spring-Boot-Backend, das dieses Projekt früher betrieben hat, rief OCRmyPDF auf, den klassischen Ansatz „Bild plus versteckte Textebene", und lieferte ein PDF zurück. Die Rust-Neufassung hat diesen Pfad vollständig durch das selektive OCR von pdf-inspector ersetzt, und die Ausgabe wechselte dabei von PDF zu Markdown. Das alte Java-Backend wurde inzwischen komplett aus dem Repository entfernt; es ist kein Schalter, den man zurücklegen kann.
Ein durchsuchbares PDF (Bild plus Textebene) ist eine eigene Ausgabe. Sende outputFormat=pdf, und derselbe Endpunkt rendert jede Seite mit 300 dpi, erkennt sie mit Tesseract in der angegebenen Sprache (Standard eng, bis zu vier, mit + verbunden) und liefert die Seiten mit versteckter Textebene zurück, bis zu 50 Seiten pro Anfrage. Dieser Pfad ist von allem oben Gesagten unabhängig: Die Aufteilung in Auto und Force, pdf-inspector und das Modell PP-OCRv6 gehören zur Markdown-Ausgabe, die keinen Sprachparameter hat.
Auto und Force OCR
Das Formular hat ein Feld ocrType:
- Normal (alles außer
force-ocr) entspricht Auto: vorhandenen Text dort nutzen, wo die Datei ihn bereits hat, und OCR nur auf reinen Bildseiten ausführen. Bei einem sauber erzeugten digitalen PDF lädt Auto die OCR-Laufzeit nicht. - Force OCR (
ocrType=force-ocr) führt die Erkennung auf jeder Seite erneut aus, auch auf Seiten mit vorhandener Textebene. Bei echten Bildseiten zahlst du mit Zeit und nicht mit zusätzlicher Genauigkeit; du bekommst einen Durchlauf, der eine beschädigte oder unvollständige Ebene ignoriert.
Die Voreinstellung im Portal ist Force OCR. Eine Sprachauswahl gibt es nicht: Übrig gebliebene tessdata-Codes aus dem alten Java-Pfad werden ignoriert.
Die Aufteilung zwischen Auto und Force passiert innerhalb der Anfrage selbst, und weder das Portal noch die Capability-Probe der API prüfen das vorab. GET /api/v1/settings/get-endpoints-status meldet ocr-pdf immer als aktiviert, ohne tatsächlich zu prüfen, ob PDFium, ONNX Runtime oder das PP-OCRv6-Modell installiert sind. Die eigentliche Prüfung erfolgt erst in dem Moment, in dem eine Anfrage die Erkennung auslöst: Fehlt eines davon, liefert der Endpunkt 503 zurück, statt still auf ein degradiertes Markdown mit nur nativem Text zurückzufallen. Das PP-OCRv6-Small-Modell selbst ist etwa 31 MB groß; sofern es beim Deployment nicht vorab in den lokalen Cache geladen wurde, lädt es sich beim ersten Mal, wenn eine Seite tatsächlich Erkennung braucht, über das Netzwerk herunter. Eine Maschine, die offline ist und kein vorab geladenes Modell hat, scheitert höchstwahrscheinlich genau dort bei ihrer ersten Force-Anfrage, statt nur langsamer zu laufen.
Erkennung ist probabilistisch
Die OCR-Engines gleichen Pixelmuster mit Modellen von Buchstaben und Wörtern ab. Sie sind gut bei sauberem, kontrastreichem Druck in Standardschrift und schlechter bei:
- Scans mit niedriger Auflösung oder geringem Kontrast (Faxqualität gegen ein 300-DPI-Original)
- Handschrift, Zierschriften und ungewöhnlichen Layouts (mehrspaltige Tabellen, gedrehter Text, dichte Formulare)
- Schrägen Seiten, die Glyphenformen gerade so weit verzerren, dass der Abgleich fehlschlägt
Ein unscharfes Fax lässt sich nicht so zuverlässig erkennen wie ein sauberer Scan, unabhängig davon, ob Auto oder Force aktiv ist. Das ist eine Grenze des Modells selbst, die kein Parameter beheben kann.
Was OCR nicht leistet
OCR liefert Text. Es baut keine Absätze, Überschriften, Tabellen oder ein umfließbares Word-Dokument wieder auf. Editierbares Layout ist ein Konvertierungsproblem, das auf Erkennungsfehlern aufsitzt, und damit eine andere Aufgabe als das Lesen eines Scans.
PDF per OCR lesen läuft serverseitig ohne Konto. Der Download ist standardmäßig Markdown; wähle durchsuchbares PDF für eine Textebene. Wirkt eine vorhandene Textebene falsch, nutze Force OCR, damit Auto dieser Ebene nicht vertraut; um zu prüfen, ob eine bestimmte Maschine PDFium und das Modell tatsächlich installiert hat, ist eine echte Anfrage verlässlicher als die Capability-Probe zu lesen, denn die Probe bestätigt nur, dass der Endpunkt existiert, nicht dass seine Laufzeitumgebung bereit ist. Für Automatisierungsschlüssel und OpenAPI siehe Entwickler.