Paperless-ngx mit KI einrichten: die native KI ab Version 3 lokal mit Ollama

Paperless-ngx mit KI einsetzen? WZ-IT richtet die native KI in Paperless-ngx ein, bindet lokale Modelle an und betreibt die Instanz auf Wunsch dauerhaft, siehe Paperless-ngx bei WZ-IT und Paperless-AI und KI-Anbindung. Termin vereinbaren

Wer Paperless-ngx mit KI nutzen wollte, brauchte bisher ein Zusatzprojekt wie Paperless-AI. Seit Version 3.0.0 vom 22. Juli 2026 bringt Paperless-ngx die KI selbst mit: Vorschläge für Titel, Tags, Korrespondent und Dokumenttyp, einen Chat über einzelne Dokumente oder das ganze Archiv und einen Vektor-Index für ähnliche Dokumente. Mit Version 3.1.0 kam eine Workflow-Aktion dazu, die diese Vorschläge automatisch anwendet.

Gleichzeitig steht im Repository von Paperless-AI seit März 2026 der Hinweis "This repo is currently not maintained" (clusterzx/paperless-ai). Für neue Installationen ist die native Integration damit der naheliegende Weg, für bestehende Paperless-AI-Setups stellt sich die Frage nach dem Umstieg.

Dieser Beitrag zeigt die Einrichtung mit einem lokalen Ollama-Server per Docker Compose, alle KI-Variablen mit Standardwerten, die Modellwahl für deutsche Dokumente, die automatische Verschlagwortung per Workflow, den Datenfluss und den Umstieg von Paperless-AI. Alle Angaben beziehen sich auf Paperless-ngx 3.2.1 (Stand Oktober 2026).

Inhaltsverzeichnis

1. Das Wichtigste in Kürze
2. Was die native KI in Paperless-ngx kann
3. Was sich seit Version 3 geändert hat
4. Voraussetzungen und Hardware
5. Schritt für Schritt: Paperless-ngx mit Ollama per Docker Compose
6. Alle KI-Variablen im Überblick
7. Modellwahl für Generierung und Embeddings
8. Automatisch verschlagworten mit der Workflow-Aktion
9. Datenschutz: welche Daten das System verlassen
10. Native KI vs. Paperless-AI im Vergleich
11. Umstieg von Paperless-AI
12. Grenzen im Stand Oktober 2026
13. Unser Vorgehen bei WZ-IT
14. Weiterführende Guides

Das Wichtigste in Kürze

Quellen: Konfiguration, Abschnitt AI, Advanced Usage, AI features, Release-Übersicht, Quellcode vector_store.py.

Was die native KI in Paperless-ngx kann

Die Dokumentation beschreibt drei Funktionen, die alle optional sind und die bestehende Zuordnung ohne LLM nicht ersetzen (Advanced Usage):

Zwei Details sind für den Betrieb wichtig:

• Vorschläge beim Öffnen. Für Dokumente mit Posteingangs-Tag werden Vorschläge automatisch angefragt, sobald das Dokument geöffnet wird. Seit 3.2.0 lässt sich das unter Einstellungen > Dokumente abschalten (Usage, Document Suggestions). Mit lokalem Modell bedeutet jedes Öffnen eine Anfrage an die GPU.
• Berechtigungen. Der Chat sucht nur in Dokumenten, die der angemeldete Nutzer sehen darf. Der Quellcode filtert die Vektorsuche auf die erlaubten Dokument-IDs (chat.py). Vorschläge setzen seit 3.0.0 Änderungsrechte am Dokument voraus (Release 3.0.0).

Was sich seit Version 3 geändert hat

Wer von 2.x kommt, sollte vor dem Update die Breaking Changes von 3.0.0 lesen. Dazu gehören unter anderem der Wegfall der Dokumentverschlüsselung, der API-Version 1 und der Unterstützung für Python 3.10 (Release 3.0.0). Für Docker-Installationen gilt wie immer: erst sichern, dann das Image aktualisieren.

Voraussetzungen und Hardware

• Paperless-ngx ab 3.1.0, besser die aktuelle 3.2.1, wenn die Workflow-Aktion genutzt werden soll. Wie eine Installation mit Docker und Caddy aufgesetzt wird, zeigt der Guide Paperless-ngx auf Ubuntu mit Caddy.
• Ollama als Container auf demselben Host oder als eigener Server im internen Netz (Ollama, Docker). Auf einem anderen Server sollte der Ollama-Port nur aus dem Paperless-Netz erreichbar sein. Warum ein offen erreichbares Ollama ein Risiko ist, zeigt der Beitrag zu Bleeding Llama.
• GPU für brauchbare Antwortzeiten. Ollama läuft auch auf der CPU, Vorschläge dauern dann aber deutlich länger. Für NVIDIA-GPUs im Container ist das NVIDIA Container Toolkit nötig.

Zur Größenordnung: Das Modell muss samt Kontext in den GPU-Speicher passen. Die Downloadgrößen aus der Ollama-Bibliothek geben die Untergrenze an:

Paperless-ngx sendet standardmäßig einen Kontext von 8.192 Token an Ollama (PAPERLESS_AI_LLM_CONTEXT_SIZE, für Ollama als num_ctx). Der Speicherbedarf liegt daher über der Downloadgröße. Wie sich GPU-Speicher für Modelle und Kontext berechnen lässt, erklärt der Artikel GPU-VRAM für LLMs dimensionieren.

Schritt für Schritt: Paperless-ngx mit Ollama per Docker Compose

Grundlage ist die offizielle docker-compose.postgres.yml. Ergänzt werden ein Ollama-Dienst und die KI-Variablen im Dienst webserver.

1. Compose-Datei erweitern

services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless   # in Produktion ändern

  ollama:
    image: docker.io/ollama/ollama:latest
    restart: unless-stopped
    volumes:
      - ollama:/root/.ollama
    # kein "ports:" nötig, Paperless erreicht Ollama über das Compose-Netz
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest   # in Produktion auf eine Version festlegen
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - ollama
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
      # KI
      PAPERLESS_AI_ENABLED: "true"
      PAPERLESS_AI_LLM_BACKEND: ollama
      PAPERLESS_AI_LLM_ENDPOINT: http://ollama:11434
      PAPERLESS_AI_LLM_MODEL: gemma3:12b
      PAPERLESS_AI_LLM_EMBEDDING_BACKEND: ollama
      PAPERLESS_AI_LLM_EMBEDDING_MODEL: bge-m3
      PAPERLESS_AI_LLM_REQUEST_TIMEOUT: "300"

volumes:
  data:
  media:
  pgdata:
  redisdata:
  ollama:

Der Block deploy.resources.reservations.devices reserviert die NVIDIA-GPU für den Ollama-Container (Docker, GPU-Unterstützung in Compose). Ohne GPU wird er entfernt. Läuft Ollama auf einem anderen Server, entfällt der Dienst ollama, und PAPERLESS_AI_LLM_ENDPOINT zeigt auf dessen interne Adresse.

2. Starten und Modelle laden

docker compose pull
docker compose up -d
docker compose exec ollama ollama pull gemma3:12b
docker compose exec ollama ollama pull bge-m3

3. LLM-Index aufbauen

Der Index wird beim ersten Aktivieren und nach jedem Wechsel des Embedding-Modells komplett neu aufgebaut (Administration, LLM-Index):

docker compose exec webserver document_llmindex rebuild

Danach hält ein geplanter Task den Index aktuell, standardmäßig täglich um 02:10 Uhr (PAPERLESS_LLM_INDEX_TASK_CRON, Standard 10 2 * * *). Bei großen Archiven dauert der erste Aufbau entsprechend lange; die Embeddings laufen über dieselbe GPU wie die Vorschläge.

4. In der Oberfläche prüfen

• Ein Dokument öffnen und das Menü neben dem Vorschlagen-Button aufklappen. Die KI-Vorschläge erscheinen dort zusätzlich zu den klassischen Vorschlägen.
• Den Chat in der oberen Leiste öffnen. In der Detailansicht bezieht er sich auf das geöffnete Dokument, in Listen auf alle sichtbaren Dokumente.

Die KI-Einstellungen lassen sich auch unter Einstellungen > Anwendungskonfiguration setzen. Werte in der Datenbank haben Vorrang vor den Umgebungsvariablen (Advanced Usage). Wer die Konfiguration in Compose pflegt, sollte die Felder in der Oberfläche leer lassen, sonst wirkt eine Änderung in der Compose-Datei nicht.

5. Bei Updates

Seit Version 3 gehört die Migration des LLM-Index zum Update-Ablauf. Im Docker-Image läuft document_llmindex migrate beim Start des Containers automatisch (Init-Skript init-llmindex-migrate). Bei Bare-Metal-Installationen ist der Befehl ein eigener Schritt nach der Datenbankmigration (Administration, Updating).

Der Index liegt im Volume data unter llm_index und gehört damit in die bestehende Sicherung.

Alle KI-Variablen im Überblick

Quelle: Paperless-ngx Konfiguration, Abschnitt AI, Stand Version 3.2.1.

Zu PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS: Für ein lokales Ollama muss der Wert auf true bleiben, sonst blockiert Paperless-ngx Adressen wie http://ollama:11434. Auf false gehört er nur, wenn ausschließlich ein externer Anbieter genutzt wird und Anfragen ins interne Netz ausgeschlossen sein sollen.

Modellwahl für Generierung und Embeddings

Paperless-ngx nutzt zwei getrennte Modelle. Das Wiki des Projekts gibt dazu Hinweise, aber ausdrücklich keine Benchmarks (AI Model Recommendations):

• Generierungsmodell (PAPERLESS_AI_LLM_MODEL): ein Instruktions- oder Chatmodell, das strukturierte Ausgaben zuverlässig liefert. Mit einem kleinen Modell beginnen und nur dann größer werden, wenn die Qualität nicht reicht.
• Embedding-Modell (PAPERLESS_AI_LLM_EMBEDDING_MODEL): Das Standardmodell für Hugging Face, all-MiniLM-L6-v2, ist für überwiegend englische Archive gedacht. Für mehrsprachige Archive nennt das Wiki intfloat/multilingual-e5-small, intfloat/multilingual-e5-base und BAAI/bge-m3.

Für ein deutschsprachiges Archiv folgt daraus:

Getestet wird am besten mit einer Stichprobe typischer Dokumente: Rechnungen, Verträge, Behördenpost, Scans schlechter Qualität. Wie sich Modelle für den Selbstbetrieb einordnen lassen, beschreibt der Artikel Welches LLM selbst hosten?. Ist bereits die Texterkennung das Problem, hilft der Vergleich Vision-Language-Modelle für OCR.

Automatisch verschlagworten mit der Workflow-Aktion

Die Vorschläge allein ändern nichts am Dokument. Für eine automatische Zuordnung gibt es seit 3.1.0 die Workflow-Aktion "Apply AI Suggestions" (Usage, Workflows). Sie fragt dieselben Vorschläge ab wie die Dokumentansicht und wendet sie an.

Ein bewährter Aufbau für den Einstieg:

1. Trigger "Document Added", gefiltert auf den Posteingangs-Tag oder einen Eingangsordner.
2. Aktion "Apply AI Suggestions" mit Korrespondent, Dokumenttyp und Tags, "Fehlende Elemente anlegen" aus.
3. Zweite Aktion (Zuweisung): ein Tag wie ki-vorschlag, damit sich KI-bearbeitete Dokumente gezielt prüfen lassen.
4. Nach einigen Wochen Stichproben auswerten und erst dann Titel und Datum mit Überschreiben hinzunehmen.

Die Dokumentation weist darauf hin, dass jedes passende Dokument eine Anfrage an das Modell auslöst. Ein Workflow über das gesamte Archiv kann die Aufgabenwarteschlange lange belegen und die Verarbeitung neuer Dokumente verzögern. Für Altbestände deshalb in kleinen Tranchen arbeiten.

Datenschutz: welche Daten das System verlassen

Paperless-ngx sendet für Vorschläge, Chat und Embeddings den Dokumentinhalt und Metadaten an das konfigurierte Backend (Usage, AI Features). Wohin die Daten gehen, hängt allein von der Konfiguration ab:

Remote OCR ist eine eigene Funktion aus Version 3.0.0 und standardmäßig aus (Usage, Remote OCR). Ist sie aktiv, werden im Modus always alle unterstützten Dokumente an Azure gesendet. Seit 3.1.0 lässt sich mit PAPERLESS_REMOTE_OCR_MODE=workflow_only auf einzelne Dokumente per Workflow beschränken. Wer lokale KI wegen des Datenschutzes wählt, sollte Remote OCR nicht nebenbei aktivieren.

Die Dokumentation behandelt Dokumentinhalte gegenüber dem Modell als nicht vertrauenswürdige Daten. Ein Dokument kann Text enthalten, der wie eine Anweisung an das Modell formuliert ist. Bei automatischen Workflows ist das ein Argument, "Fehlende Elemente anlegen" und "Überschreiben" zurückhaltend zu nutzen. Hintergrund dazu im Artikel Prompt Injection: Schutz für KI-Anwendungen.

Native KI vs. Paperless-AI im Vergleich

Quellen: Paperless-ngx Advanced Usage, Paperless-AI README, Paperless-AI Beispielkonfiguration, Paperless-AI Releases.

Paperless-AI bleibt nur dort im Vorteil, wo ein eigener System-Prompt oder das Befüllen benutzerdefinierter Felder gebraucht wird. Dem steht ein Projekt ohne Sicherheitsupdates gegenüber, das mit einem API-Token weitreichenden Zugriff auf das Archiv hat.

Umstieg von Paperless-AI

Der Umstieg lässt sich ohne Datenverlust in sechs Schritten durchführen. Paperless-AI schreibt seine Ergebnisse direkt in Paperless-ngx; Tags, Korrespondenten und Titel bleiben also erhalten.

1. Sichern und aktualisieren. Paperless-ngx sichern, Breaking Changes von 3.0.0 prüfen und auf 3.2.1 aktualisieren.
2. Konfiguration festhalten. Aus der Paperless-AI-Konfiguration notieren: Modell und Endpunkt (OLLAMA_API_URL, OLLAMA_MODEL bzw. CUSTOM_BASE_URL), den Filter-Tag (TAGS), den Verarbeitet-Tag (AI_PROCESSED_TAG_NAME) und eigene Anpassungen am SYSTEM_PROMPT.
3. Paperless-AI stoppen. Den Container anhalten, aber noch nicht löschen. So laufen nicht zwei Systeme parallel auf denselben Dokumenten.
4. Native KI aktivieren. Den bisherigen Ollama-Endpunkt als PAPERLESS_AI_LLM_ENDPOINT eintragen, Embedding-Backend setzen und document_llmindex rebuild ausführen.
5. Workflow nachbauen. Den bisherigen Filter-Tag als Workflow-Filter verwenden, "Apply AI Suggestions" mit den bisher genutzten Feldern anlegen und den Verarbeitet-Tag über eine Zuweisungsaktion setzen.
6. Prüfen und abbauen. Eine Stichprobe von neuen Dokumenten vergleichen. Danach den Paperless-AI-Container und seine Daten entfernen und den API-Token in Paperless-ngx widerrufen.

Was sich nicht übertragen lässt: ein angepasster System-Prompt und die Befüllung benutzerdefinierter Felder. Wer darauf angewiesen ist, sollte das vor dem Umstieg mit den Fachbereichen klären. Die bisherigen Anleitungen zu Paperless-AI und zum Paperless-AI-Installer bleiben für bestehende Installationen verfügbar.

Grenzen im Stand Oktober 2026

Einige Einschränkungen aus der Zeit von Version 3.0 bestehen in 3.2.1 weiter. Sie sind im Quellcode nachvollziehbar:

Für die Praxis heißt das: Vorschläge und die Workflow-Aktion sind mit Prüfschritt für den produktiven Einsatz geeignet. Der Chat taugt als Suchhilfe für Fragen wie "Wann endet der Mietvertrag?", ersetzt aber keine Recherche über viele Dokumente mit vollständiger Quellenliste. Wer das braucht, setzt auf eine eigene RAG-Anwendung, wie im Artikel Dokumente mit KI verarbeiten beschrieben.

Unser Vorgehen bei WZ-IT

WZ-IT betreibt Paperless-ngx für Unternehmen und richtet die KI-Anbindung ein. Bei einer Einführung der nativen KI gehen wir in fünf Schritten vor:

1. Bestand aufnehmen. Version, Dokumentenmenge, Sprachen, vorhandene Regeln und eine eventuell laufende Paperless-AI-Installation erfassen.
2. Modellstandort festlegen. Je nach Vertraulichkeit Ollama auf vorhandener Hardware, einem GPU-Server oder einem AI Cube im eigenen Haus; Cloud-APIs nur nach ausdrücklicher Entscheidung.
3. Einrichten und testen. Update auf 3.2.1, KI-Variablen setzen, Index aufbauen und Vorschläge an einer Stichprobe mit den Fachbereichen bewerten.
4. Workflows aufbauen. Automatische Zuordnung mit Prüf-Tag, Altbestand in Tranchen, Paperless-AI kontrolliert abbauen.
5. Betreiben. Updates inklusive Index-Migration, Sicherung von Dokumenten und Index, Monitoring der Aufgabenwarteschlange.

Managed Open Source wie Paperless-ngx kostet bei WZ-IT ab 129,90 € netto je Workload und Monat (Managed Open Source). Für lokale Modelle mit sensiblen Dokumenten steht der AI Cube für 6.490 € netto einmalig plus AI Cube Care ab 349,90 € netto im Monat zur Verfügung. Support, Beratung und Implementierung durch WZ-IT.

Weiterführende Guides

• Paperless-ngx auf Ubuntu mit Caddy installieren, die Grundinstallation mit Docker und automatischen Zertifikaten.
• Paperless-AI installieren, die bisherige Erweiterung für bestehende Installationen.
• Paperless-AI-Installer per Einzeiler, Installation per Skript.
• Vision-Language-Modelle für lokale OCR, wenn die Texterkennung selbst verbessert werden soll.
• Dokumente automatisch auslesen mit selbst gehosteter KI, Rechnungen und Lieferscheine strukturiert erfassen.
• Dokumente mit KI verarbeiten, von OCR bis zur intelligenten Dokumentenverarbeitung.
• Welches LLM selbst hosten?, Modelle für den Eigenbetrieb einordnen.
• vLLM vs. Ollama, welcher Inferenzserver wofür passt.
• KI-Lösungen von WZ-IT, der Hub mit allen Angeboten zu lokaler KI.

Paperless-ngx mit lokaler KI einführen? Wir richten die native KI ein, übertragen eine bestehende Paperless-AI-Konfiguration in Workflows und betreiben die Instanz auf Wunsch dauerhaft. Termin vereinbaren

Quellen

• Paperless-ngx Release 3.0.0
• Paperless-ngx Release 3.0.5
• Paperless-ngx Release 3.1.0
• Paperless-ngx Release 3.1.3
• Paperless-ngx Release 3.2.0
• Paperless-ngx Release 3.2.1
• Paperless-ngx Releases
• Paperless-ngx Docs, Konfiguration: AI
• Paperless-ngx Docs, Advanced Usage: AI features
• Paperless-ngx Docs, Usage: AI Features
• Paperless-ngx Docs, Usage: Apply AI Suggestions
• Paperless-ngx Docs, Usage: Remote OCR
• Paperless-ngx Docs, Administration: LLM-Index
• Paperless-ngx, Init-Skript init-llmindex-migrate (v3.2.1)
• Paperless-ngx Wiki, AI Model Recommendations
• Paperless-ngx, docker-compose.postgres.yml (v3.2.1)
• Paperless-ngx Quellcode, chat.py (v3.2.1)
• Paperless-ngx Quellcode, chat.service.ts (v3.2.1)
• Paperless-ngx Quellcode, chat.component.html (v3.2.1)
• Paperless-ngx Quellcode, vector_store.py (v3.2.1)
• Paperless-AI Repository mit Wartungshinweis
• Paperless-AI Releases
• Paperless-AI Beispielkonfiguration .env.example
• Ollama Docs, Docker
• Docker Docs, GPU-Unterstützung in Compose
• Ollama-Bibliothek: gemma3
• Ollama-Bibliothek: qwen3
• Ollama-Bibliothek: llama3.1
• Ollama-Bibliothek: bge-m3
• Ollama-Bibliothek: embeddinggemma