paperless-gpt: LLM-OCR und automatische Metadaten für paperless-ngx

Welches Problem paperless-gpt überhaupt löst

paperless-ngx archiviert Dokumente und vergibt Titel, Tags und Korrespondenten. Diese Metadaten entstehen entweder aus der Texterkennung oder aus manueller Arbeit. Bei sauberen digitalen PDFs funktioniert das ausreichend. Bei eingescannten Rechnungen, Faxen oder mehrfach kopierten Belegen liefert die klassische OCR Zeichenfolgen, die zwar technisch Text sind, aber kaum als Titel oder Tag taugen. Genau dort setzt paperless-gpt an: Das Projekt kombiniert laut README die LLM-gestützte Texterkennung mit der automatischen Erzeugung von Titel, Tags, Korrespondent und Custom Fields. Die Zielgruppe sind also nicht Menschen, die mit der Digitalisierung beginnen, sondern Betreiber einer bereits laufenden paperless-ngx-Instanz, deren Eingangskorb regelmäßig schlecht lesbare Scans enthält. Wer ausschließlich digitale Dokumente ablegt, bekommt von dem Projekt wenig, weil die klassische Textextraktion dort bereits brauchbare Ergebnisse liefert.

Wie die Verarbeitung abläuft

Der Dienst läuft neben paperless-ngx und nutzt dessen API. Für die Texterkennung stehen mehrere Wege zur Verfügung: LLM-OCR über OpenAI oder Ollama, Google Document AI, Azure Document Intelligence und ein selbst gehosteter Docling Server. Beim LLM-Weg gibt es drei Betriebsarten. Im Image Mode wird jede Seite als Bild an das Modell gegeben, im PDF Mode werden Seiten als PDF-Ausschnitte übergeben, im Whole PDF Mode das gesamte Dokument in einem Aufruf. Die Dokumentation enthält eine Kompatibilitätstabelle, die angibt, welcher Anbieter welche Betriebsart unterstützt. Zusätzlich existiert eine Erkennung bereits vorhandener OCR: Liegt für ein Dokument schon Text vor, kann die Verarbeitung übersprungen werden. Für die Metadaten laufen getrennte Abfragen für Titel, Tags, Korrespondent und Custom Fields. Das Ergebnis landet zunächst als Vorschlag in der Web-Oberfläche und wird entweder manuell bestätigt oder im Auto-Modus direkt übernommen. Die Prompts für diese Abfragen liegen im Verzeichnis prompts, während default_prompts als unveränderte Vorlage dient. Anpassungen über die Weboberfläche bleiben dadurch über Updates hinweg erhalten.

Installation mit Docker Compose

Der vorgesehene Weg ist Docker Compose neben einer bestehenden paperless-ngx-Instanz. Das README nennt als Voraussetzungen eine erreichbare paperless-ngx-Instanz sowie einen API-Token, außerdem einen LLM-Anbieter. Die Konfiguration erfolgt über Umgebungsvariablen. Für die Metadatenerzeugung sind unter anderem der paperless-ngx-Endpunkt und das zugehörige Token nötig, für die OCR der gewählte Anbieter samt Zugangsdaten. Wer Ollama lokal betreibt, gibt dessen Adresse an und wählt ein Modell; das README empfiehlt für diesen Zweck ausdrücklich ein Reasoning-Modell wie qwen3:8b. Die Custom-Field-Funktion ist nicht automatisch aktiv: Sie muss in den Einstellungen eingeschaltet und mindestens ein Zielfeld ausgewählt werden. Für die Ausgabe der OCR gibt es Optionen, das erzeugte PDF lokal zu speichern oder an paperless-ngx hochzuladen. Ein manueller Betrieb ist ebenfalls dokumentiert, der Docker-Weg ist aber der beschriebene Standard.

Drei Schreibmodi für Custom Fields

Die Custom-Field-Unterstützung kennt drei Modi, und die Wahl hat spürbare Folgen. Append ergänzt nur Felder, die auf dem Dokument noch nicht existieren, und überschreibt nie einen vorhandenen Wert, auch keinen leeren. Update ergänzt neue Felder und überschreibt bestehende mit dem neuen Vorschlag, lässt aber Felder unberührt, für die es keinen Vorschlag gibt. Replace entfernt alle vorhandenen Custom Fields und ersetzt sie vollständig durch die vorgeschlagenen Werte. Replace ist damit der einzige Modus, in dem manuell gepflegte Werte verloren gehen können, wenn das Modell für ein Feld keinen Vorschlag liefert. Das README bezeichnet Append selbst als die sicherste Option. Wer Custom Fields bereits manuell pflegt, sollte deshalb bei Append bleiben oder Replace nur auf Dokumente anwenden, deren Felder ausschließlich maschinell erzeugt wurden.

Durchsuchbare PDFs und ihre Nebenwirkungen

paperless-gpt kann PDFs mit einer transparenten Textebene erzeugen, die über den Wörtern des Originalbildes liegt. Das Dokument bleibt dadurch optisch unverändert, wird aber durchsuchbar und selektierbar. Der Haken steckt in den Metadaten: Das README führt einen eigenen Abschnitt zu den Grenzen beim Kopieren von Metadaten. Wer OCR-PDFs an paperless-ngx hochlädt, sollte also nicht davon ausgehen, dass alle Eigenschaften des Ausgangsdokuments unverändert übernommen werden. Für die Textebene gilt zusätzlich: Die Positionierung hängt von der Qualität der Worterkennung ab, und die Dokumentation beschreibt Sicherheitsvorkehrungen für den Fall, dass die Verarbeitung fehlschlägt. Ein LLM liefert außerdem kein deterministisches Ergebnis. Derselbe Scan kann bei zwei Durchläufen unterschiedliche Titel oder Tags ergeben. Wer reproduzierbare Metadaten braucht, ist mit regelbasierten Verfahren besser bedient.

Wann ein anderes Werkzeug die bessere Wahl ist

Der naheliegende Vergleich ist Tesseract, das in paperless-ngx selbst zum Einsatz kommt. Der Unterschied liegt im Ansatz: Tesseract erkennt Zeichen auf Basis eines trainierten Modells und liefert Text ohne Kontextwissen. paperless-gpt schickt Seitenbilder oder PDF-Ausschnitte an ein Sprachmodell, das den Inhalt einordnet und daraus Titel und Tags ableitet. Das erklärt, warum das Projekt bei verrauschten Scans Vorteile reklamiert, und ebenso, warum es pro Dokument Rechenzeit und bei gehosteten Anbietern Geld kostet. Für saubere, digital erzeugte PDFs ist Tesseract schneller, günstiger und deterministisch. Wer bereits Google Document AI oder Azure Document Intelligence lizenziert hat, kann diese Dienste in paperless-gpt als OCR-Anbieter eintragen, statt ein LLM für die Texterkennung zu verwenden. Der Austausch betrifft nur die OCR-Stufe, die Metadatenerzeugung läuft weiterhin über das LLM.

Wartung, Lizenz und Betriebsaufwand

paperless-gpt steht unter der MIT-Lizenz, die Nutzung, Veränderung und Weitergabe erlaubt, solange der Lizenztext erhalten bleibt. Das Projekt wird aktiv gepflegt: Die letzten Releases v0.27.0, v0.26.1 und v0.26.0 stammen aus Juli 2026, der letzte Push auf den main-Branch aus September 2026. Die Versionsnummern liegen noch im 0.x-Bereich, und die Release-Titel deuten auf funktionale Erweiterungen statt auf reine Fehlerbehebungen hin. Der eigentliche Aufwand liegt nicht im Container, sondern in der Umgebung: ein LLM-Endpunkt, sei es lokal über Ollama oder gehostet, muss erreichbar, aktuell und ausreichend dimensioniert sein. Dazu kommen die laufenden Kosten pro Dokument bei gehosteten Anbietern. Weil Prompts im Verzeichnis prompts liegen und default_prompts als Vorlage dient, überleben eigene Anpassungen ein Update. Die Struktur der Umgebungsvariablen kann sich zwischen Minor-Versionen dennoch ändern, weshalb ein Blick in die Release Notes vor dem Aktualisieren sinnvoll ist.

Wer einsteigen sollte und wer nicht

Für Betreiber mit laufender paperless-ngx-Instanz und einem Bestand schwer lesbarer Scans ist paperless-gpt eine naheliegende Ergänzung, besonders wenn Ollama bereits lokal läuft und die Dokumente das Haus nicht verlassen sollen. Wer dagegen ausschließlich digitale PDFs archiviert, ersetzt eine schnelle, deterministische Texterkennung durch einen langsameren, nicht reproduzierbaren Prozess. Vor dem ersten produktiven Lauf sollten drei Dinge geklärt sein: der Schreibmodus für Custom Fields, die Einstellung zur Erkennung bestehender OCR und die Frage, welche Metadaten beim Upload des OCR-PDFs tatsächlich erhalten bleiben. Wer die Custom-Field-Funktion nicht ausdrücklich aktiviert und mindestens ein Zielfeld auswählt, wird sie nie in Aktion sehen, weil sie standardmäßig inaktiv ist.

Redaktionelles Fazit

Sinnvoll ist paperless-gpt für Betreiber einer bestehenden paperless-ngx-Instanz mit vielen schwer lesbaren Scans und der Bereitschaft, einen LLM-Endpunkt zu betreiben oder zu bezahlen. Wer saubere, digitale PDFs archiviert, gewinnt wenig und trägt nur Betriebsaufwand. Vor dem Produktiveinsatz zu prüfen sind der Schreibmodus für Custom Fields, die Einstellung für die bestehende OCR-Erkennung und die Frage, ob die Metadaten des Originaldokuments beim Upload vollständig übernommen werden.

Offizielle Quellen

1. icereed/paperless-gpt on GitHub
2. Issues
3. License: MIT
4. README
5. Releases