Paperless-ngx mit KI: Von 602 Tags zurück zu 18

Kurz gesagt: Paperless-ngx ist ein Open-Source-Archiv, das Belege per Texterkennung durchsuchbar macht. In meinem standen zuletzt 602 Tags, viele davon von der KI-Erweiterung paperless-ai erfunden. Heute macht die KI nur noch Vorschläge. Ob ein Beleg privat, geschäftlich oder steuerlich relevant ist, entscheidet ein kleines Python-Skript mit festen Regeln.

Alle Texte im Video zum Nachlesen

1. Einstieg: „Jeder Beleg. Mit einer Suche.“ Im Suchfeld steht „Lohnsteuerbescheinigung“, genau dieser Beleg hebt sich aus dem Stapel.
2. Titel: „Paperless-ngx: mein Belegarchiv.“
3. Was ist Paperless-ngx? „Ein Archiv, das mitliest. Open Source, auf dem eigenen Server.“ Beleg (PDF, Scan oder Mail-Anhang), dann Texterkennung (OCR), dann Archiv mit Volltextsuche, Tags, Absender und Dokumenttyp.
4. Schritt 1, Eingang: „Belege kommen von selbst. Aus Postfach und NAS-Ordner.“
5. Schritt 2, Ordnung: „KI schlägt vor, Regeln entscheiden. Die KI läuft lokal. Unklares landet auf meiner Prüfliste.“ Beispiel: Für eine Rechnung von Hetzner schlägt die KI Absender, Typ Rechnung und Tag Gewerbe vor, das Regelwerk macht daraus verbindliche Angaben.
6. Schritt 3, Server: „Archiv und KI laufen im Haus. Eigener Server, keine Cloud-KI.“ Proxmox-Server mit Container 1 (Docker: Paperless-ngx, paperless-ai, Nginx Proxy Manager, Regelwerk stündlich) und Container 2 (Ollama, qwen2.5:3b, nur CPU, 4 Kerne, 6 GB), dazu ein Synology-NAS für Eingangsordner und Sicherungen.
7. Schritt 4, Sicherung: „Gesichert, 3× pro Woche. Alle Container, nachts aufs NAS im Haus.“ Montag, Mittwoch und Samstag um 2 Uhr.
8. Nutzen: „Belege schnell finden. Steuerbelege per Filter. Buchhaltung vorbereitet.“
9. Abspann: „SYFRT. Reduziert auf das, was wirkt.“ Sascha Seyfert, Digital-Handwerker, Rödertal, syfrt.de

Paperless-ngx: 602 Tags und kein Überblick

In meinem Paperless-ngx landen alle Belege: Rechnungen aus dem Mail-Postfach, Gehaltsabrechnungen, Bescheide, Verträge. Dazu läuft paperless-ai. Es liest jedes neue Dokument mit einem lokalen Sprachmodell und schlägt Titel, Absender, Dokumenttyp und Tags vor.

Mit der Zeit kamen 602 Tags und 33 Dokumenttypen zusammen, viele davon von paperless-ai erfunden. Zwei Tags waren besonders tückisch: „Steuern“ und „Gehalt & Lohn“ hingen per automatischer Zuordnung an jedem Dokument, in dem „Umsatzsteuer“ oder „Abrechnung“ vorkam, also an sehr vielen Rechnungen. Welche privaten Belege wirklich für die Steuererklärung zählen, war dagegen nicht zu erkennen. Am 21. Oktober 2026 habe ich aufgeräumt.

Mein Aufbau: Paperless-ngx, paperless-ai und Ollama

• Paperless-ngx und paperless-ai laufen in Docker auf einem Container meines Proxmox-Homelabs.
• Das Sprachmodell ist qwen2.5:3b über Ollama, auf einem Container ohne Grafikkarte mit vier Kernen und 6 GB Arbeitsspeicher. Mehr passt dort nicht.
• Mail-Regeln holen Rechnungen automatisch aus meinem Postfach bei Google, erkannt am Betreff (Rechnung, Invoice, Auftrag).
• Dazu kommt mein Synology-NAS: Eine Datei im Eingangsordner dort genügt, Paperless holt sie ab. Auch ein Netzwerkscanner wie der Brother ADS-4300N Werbung kann direkt in diesen Ordner scannen (selbst nicht getestet, Einordnung in der Liste am Ende).
• Proxmox sichert alle Container und virtuellen Maschinen dreimal pro Woche nachts auf dasselbe NAS. Eine Kopie außer Haus fehlt noch.

Archiv, Texterkennung und KI laufen damit auf eigener Hardware. Der Mail-Eingang läuft über Google, und die Geschäftsrechnungen wandern einmal im Monat zur Prüfung in meine Buchhaltung bei Lexware Office.

Meine Geräte sind ein paar Jahre alt. Welche aktuellen Modelle ich für einen Neuaufbau wählen würde, steht in der Box am Ende des Artikels.

Ein Hinweis vorab: paperless-ai wird laut Projektseite derzeit nicht gepflegt (Stand 01.11.2026). Seit Version 3 bringt Paperless-ngx selbst KI-Funktionen mit, laut Release-Notes unter anderem KI-Vorschläge und einen Chat über die Dokumente. Mein Setup läuft noch mit paperless-ai, ein Vergleich mit der eingebauten KI steht aus. Die verbindlichen Tags setzt ohnehin das Regelwerk weiter unten.

Paperless-ngx Tags neu geordnet: 18 Tags, 10 Dokumenttypen

Vor dem Umbau habe ich die Datenbank gesichert. Danach gilt diese Ordnung:

Gruppe	Tags
Bereich, genau einer je Rechnung	Gewerbe, Privat, Arbeitnehmer (Gehalt)
Steuer (privat)	Handwerker & Haushalt, Versicherung & Vorsorge, Kinderbetreuung, Krankheitskosten, Werbungskosten, Bescheide & Nachweise, Spenden
Personen	drei Tags, je eines pro Familienmitglied, dazu „Familie & Haus“
Sonstiges	Finanzen & Bank, Prüfen
System	pre-process (Eingang für paperless-ai), ai-processed

„Handwerker & Haushalt“ meint Rechnungen, die für die Steuerermäßigung nach § 35a EStG in Frage kommen, also Handwerkerleistungen und haushaltsnahe Dienste im Privathaushalt. Die Tags sortieren nur vor, die Steuerberatung ersetzen sie nicht.

Dazu zehn Dokumenttypen: Rechnung, Gehaltsabrechnung, Bescheid, Bescheinigung, Vertrag, Schreiben, Kontoauszug, Lieferschein, Ticket, Bericht.

Außerdem habe ich 49 Dubletten in den Papierkorb verschoben: Dokumente mit identischem Volltext, gleichem Absender und gleicher Seitenzahl.

paperless-ai begrenzen, das Regelwerk entscheiden lassen

1. paperless-ai bekommt engere Grenzen. Mit RESTRICT_TO_EXISTING_TAGS=yes soll es nur noch aus vorhandenen Tags wählen. Im Prompt steht zusätzlich: nur Personen-, Gewerbe- und Bank-Tags, keine Steuer-Tags, kein erfundenes Datum.

2. Ein Python-Skript setzt die verbindlichen Tags. regeln.py läuft stündlich per Cron in der Python-Konsole von Paperless, der sogenannten Django-Shell. Es ordnet zu:

• den Bereich nach Lieferant: Listen für Gewerbe und Arbeitgeber, jede andere Rechnung ist Privat,
• die Steuerkategorie nach Lieferant, Inhalt oder Titel,
• die Dokumenttypen, indem es Varianten zusammenführt, etwa jeden Typ, dessen Name „verdienst“ oder „entgelt“ enthält, zu „Gehaltsabrechnung“.

Die Regeln selbst sind einfache Listen und Suchmuster, sogenannte reguläre Ausdrücke (Auszug, Lieferantennamen teils ersetzt):

GEWERBE = {"Hetzner Online GmbH", "JetBrains s.r.o.", "Anthropic"}

STEUER_LIEFERANT = {
    "Steuer: Handwerker & Haushalt": {"Elektro Beispiel GmbH"},
    "Steuer: Versicherung & Vorsorge": {"Versicherung Beispiel AG"},
}

STEUER_INHALT = [
    ("Steuer: Bescheide & Nachweise",
     r"Lohnsteuerbescheinigung|Einkommensteuerbescheid|Steuerbescheid"),
    ("Steuer: Spenden", r"Zuwendungsbestätigung|Spendenbescheinigung"),
]

# Private Rechnung mit Arbeitslohn: mögliche Handwerkerleistung, von Hand prüfen
PRUEF_35A = r"Arbeitslohn|Lohnanteil|Arbeitszeit|Monteur|Montage|Stundenlohn"

3. Was unklar ist, bekommt „Prüfen“. Das gilt für neue Lieferanten, unbekannte Dokumenttypen, Platzhalterdaten und private Rechnungen mit Arbeitslohn. Damit nicht der ganze Altbestand auf der Prüfliste landet, prüft das Skript neue Lieferanten und unbekannte Typen nur bei Dokumenten ab einem Stichtag.

Voraussetzungen zum Nachbauen

• Paperless-ngx in Docker (bei mir Version 3.3, Stand Oktober 2026) und Zugriff auf docker exec auf dem Host.
• Optional paperless-ai mit einem Sprachmodell, bei mir Ollama mit qwen2.5:3b. Das Regelwerk funktioniert auch ohne KI, dann mit den Absendern, die Paperless selbst erkennt.
• Vor dem ersten Lauf, der etwas ändert, einen Dump der Datenbank ziehen. Der Modus cleanup löscht alle Tags, die nicht im Ordnungssystem stehen.
• Die Lieferantenlisten, der Stichtag und die Tag-Namen im Skript sind meine. Sie müssen zu Ihrem Archiv passen.

Erst zählen, dann anwenden

Das Skript kennt drei Modi, gesteuert über eine Umgebungsvariable:

• dry zählt nur, was es ändern würde. Das ist der Standard.
• apply setzt die Tags.
• cleanup setzt die Tags und löscht zusätzlich alle Tags, die nicht zum Ordnungssystem gehören.

Im Modus dry schreibt das Skript nichts, und zur Sicherheit läuft alles in einer Datenbank-Transaktion, die am Ende zurückgerollt wird.

MODUS = os.environ.get("REGELN_MODUS", "dry")

@transaction.atomic
def main():
    ...
    if MODUS == "dry":
        transaction.set_rollback(True)

Aufgerufen wird es direkt im Container, die Zählung steht in den Zeilen mit REGELN:

docker exec -i -e REGELN_MODUS=dry paperless-ngx \
  python3 manage.py shell < /root/paperless-regeln.py | grep ^REGELN

Stolperfallen

• Automatische Zuordnung abschalten. Paperless kann Tags selbst per Stichwort zuordnen. Bei den Tags für Steuer und Gehalt war das die Ursache der falschen Treffer. Im Regelwerk steht der Zuordnungsalgorithmus deshalb für alle festen Tags außer „Gewerbe“ auf „keiner“.
• tag.documents.clear() meiden. In der Django-Shell löst das eine interne Prüfung von Paperless (einen Signal-Handler) aus, die ein Dokument erwartet und abbricht. Zuordnungen lösche ich deshalb direkt über die Verknüpfungstabelle Document.tags.through.
• Den Mail-Abruf nicht von Hand starten. In meinem Aufbau führt ein manueller Aufruf von manage.py mail_fetcher zu „File not found“, weil die temporären Dateien fehlen. Besser den regulären Abruf abwarten.
• Platzhalterdaten abfangen. Findet die KI kein Datum, setzt sie mitunter eines im Jahr 1990 oder früher. Solche Dokumente fehlen dann in meinem monatlichen Abgleich mit der Buchhaltung, der nach Jahr filtert. Das Regelwerk markiert sie mit „Prüfen“.

Was das bringt

Aus 602 Tags sind 18 geworden. Steuerrelevante Privatbelege lassen sich je Kategorie filtern, statt sie im Frühjahr zusammenzusuchen. Die Geschäftsrechnungen legt einmal im Monat ein eigenes Skript in der Belegerfassung von Lexware Office ab, dort prüfe ich sie.

Die wichtigste Erkenntnis: Ein kleines lokales Modell liest Absender und Titel aus einem Beleg brauchbar, aber nicht fehlerfrei. Für Entscheidungen mit Folgen, etwa was in die Steuererklärung gehört, ist eine feste Regel verlässlicher und lässt sich nachvollziehen. Allerdings sind die Regeln nur so gut wie die erkannten Absender: Erkennt die KI einen Lieferanten falsch, merkt das Skript es nicht.

Übertragbar aufs Unternehmen?

Das Muster passt auf viele kleine Betriebe mit Papierkram: Die KI liest und schlägt vor, feste Regeln entscheiden, alles Unklare landet auf einer Prüfliste. Archiv und KI können dabei auf eigener Hardware laufen, die Belege gehen dann an keinen KI-Dienst. Für Betriebe gelten Aufbewahrungspflichten und die GoBD. Löschläufe und das Bereinigen von Dubletten gehören deshalb vorher mit der Steuerberatung abgestimmt.

Mehr zu lokaler KI steht auf der Seite Private AI und im Beitrag zu AnythingLLM, zu Abläufen wie diesem unter KI & Automatisierung. Wenn Sie wissen möchten, ob sich so ein Belegeingang für Ihren Betrieb lohnt, schreiben Sie mir kurz, wie Belege heute bei Ihnen ankommen.