Quelltext der Seite Paperless-ngx: KI-Funktionen mit Ollama oder OpenAI

{{Steckbrief
| gilt_fuer   = Paperless-ngx 3.x (ab 3.0.0, aktuell 3.3.2); Sprachmodelle über Ollama (lokal) oder OpenAI-kompatible Schnittstellen; Embeddings über Hugging Face, Ollama oder OpenAI-kompatibel; externe OCR über Azure Document Intelligence
| bereich     = Server-Software
| dauer       = ca. 1–2 Stunden, zuzüglich Bereitstellung des Modellservers
| rechte      = Root auf dem Docker-Host; Superuser bzw. Recht für die Anwendungskonfiguration
| stand       = Oktober 2026
}}
'''Die KI-Funktionen von Paperless-ngx''' nutzen seit Version 3 ein Sprachmodell (LLM), um Titel, Datum, Korrespondent, Dokumenttyp, Tags und Speicherpfad vorzuschlagen, ähnliche Dokumente zu finden und Fragen zu einzelnen oder vielen Dokumenten in einem Chat zu beantworten. Sie sind standardmäßig '''ausgeschaltet''' und ergänzen die bisherige automatische Zuweisung, statt sie zu ersetzen. Weil dafür Dokumentinhalte an das Modell gehen, entscheidet die Wahl des Modellservers über den Datenschutz. Diese Anleitung zeigt die Einrichtung mit einem lokalen Ollama-Server und mit OpenAI-kompatiblen Diensten.

[[Datei:Paperless-KI.png|thumb|center|750px|KI-Funktionen in Paperless-ngx: Paperless sendet Dokumenttext und Metadaten an ein Sprachmodell – lokal über Ollama oder ein selbst betriebenes OpenAI-kompatibles Gateway, oder an einen Cloud-Anbieter; Funktionen: KI-Vorschläge für Titel, Datum, Korrespondent, Dokumenttyp, Tags und Speicherpfad, Arbeitsablauf-Aktion KI-Vorschläge anwenden, LLM-Index mit Embeddings (RAG) für ähnliche Dokumente und Dokumenten-Chat; Datenschutz: lokale Modelle bevorzugen, bei Cloud AV-Vertrag und Drittlandprüfung; Dokumentinhalte gelten als nicht vertrauenswürdige Eingabe.]]

== Was die KI-Funktionen leisten ==
{| class="wikitable"
! Funktion !! Beschreibung !! Voraussetzung
|-
| '''KI-Vorschläge''' || Schaltfläche ''Vorschlagen'' im Dokument liefert Titel, Datum, Korrespondent, Dokumenttyp, Tags, Speicherpfad; vorhandene Einträge werden bevorzugt (seit 3.1.0) || KI an, Sprachmodell
|-
| '''Arbeitsablauf-Aktion „KI-Vorschläge anwenden“''' || übernimmt die Vorschläge automatisch, z. B. für alle neuen Dokumente (seit 3.1.0) || wie oben
|-
| '''LLM-Index (RAG)''' || Vektorindex aller Dokumente; verbessert Vorschläge und findet ähnliche Dokumente || zusätzlich Embedding-Modell
|-
| '''Dokumenten-Chat''' || Fragen wie „Bis wann läuft der Leasingvertrag?“ oder „Welche Rechnungen kamen von Lieferant X?“ – mit Links zu den Quellen || LLM-Index
|}
Die bisherigen Vorschläge des eingebauten Klassifikators (ohne Sprachmodell) bleiben erhalten; unter ''Einstellungen › Dokumente'' lässt sich wählen, ob klassische, KI- oder beide Vorschläge angefordert werden. Grundlagen: [[Large Language Model]], [[Künstliche Intelligenz]].

== Lokal oder Cloud? ==
{| class="wikitable"
! Kriterium !! Lokal (Ollama, eigenes Gateway) !! Cloud (OpenAI-kompatibler Anbieter)
|-
| Datenschutz || Dokumente verlassen das Unternehmen nicht || Dokumentinhalte gehen an den Anbieter; AV-Vertrag, Standort und Drittlandübermittlung prüfen
|-
| Qualität || abhängig von Modellgröße und Hardware || große Modelle, meist bessere Ergebnisse
|-
| Kosten || Hardware (GPU empfohlen), Strom || Abrechnung je Token
|-
| Geschwindigkeit || ohne GPU langsam, teils Minuten je Dokument || schnell
|}
'''Empfehlung''' für Unternehmen mit Personal-, Gesundheits- oder Mandantenunterlagen: lokaler Betrieb. Cloud-Modelle allenfalls für unkritische Dokumentarten und nach Freigabe durch den Datenschutz.

== Schritt 1: Ollama bereitstellen ==
Ollama kann auf einem eigenen Server mit Grafikkarte oder im selben Compose-Projekt laufen:
<syntaxhighlight lang="yaml">
  ollama:
    image: ollama/ollama
    restart: unless-stopped
    volumes:
      - ./ollama:/root/.ollama
    # mit NVIDIA-GPU zusätzlich:
    # deploy:
    #   resources:
    #     reservations:
    #       devices: [{ driver: nvidia, count: all, capabilities: [gpu] }]
</syntaxhighlight>
<syntaxhighlight lang="bash">
docker compose up -d ollama
docker compose exec ollama ollama pull llama3.1        # Sprachmodell (Standard von Paperless)
docker compose exec ollama ollama pull embeddinggemma  # Embedding-Modell (Standard für Ollama)
</syntaxhighlight>
* Für deutsche Dokumente ein Modell mit guten Deutschkenntnissen wählen und testen; das Community-Wiki von Paperless-ngx sammelt Empfehlungen.
* Den Ollama-Port nicht ins Netz veröffentlichen; Paperless erreicht ihn über das Compose-Netz.

== Schritt 2: Paperless-ngx konfigurieren ==
<syntaxhighlight lang="yaml">
      PAPERLESS_AI_ENABLED: "true"
      PAPERLESS_AI_LLM_BACKEND: ollama
      PAPERLESS_AI_LLM_ENDPOINT: http://ollama:11434
      PAPERLESS_AI_LLM_MODEL: llama3.1
      PAPERLESS_AI_LLM_EMBEDDING_BACKEND: ollama
      PAPERLESS_AI_LLM_EMBEDDING_MODEL: embeddinggemma
      PAPERLESS_AI_LLM_OUTPUT_LANGUAGE: Deutsch
      PAPERLESS_AI_LLM_REQUEST_TIMEOUT: "300"
</syntaxhighlight>
{| class="wikitable"
! Einstellung !! Bedeutung !! Standard
|-
| <code>PAPERLESS_AI_ENABLED</code> || Hauptschalter || aus
|-
| <code>PAPERLESS_AI_LLM_BACKEND</code> || <code>ollama</code> oder <code>openai-like</code> || –
|-
| <code>PAPERLESS_AI_LLM_MODEL</code> || Modellname || <code>llama3.1</code> (Ollama) bzw. <code>gpt-3.5-turbo</code>
|-
| <code>PAPERLESS_AI_LLM_EMBEDDING_BACKEND</code> || <code>huggingface</code> (vollständig lokal im Container), <code>ollama</code>, <code>openai-like</code>; aktiviert den LLM-Index || –
|-
| <code>PAPERLESS_AI_LLM_CONTEXT_SIZE</code> || Kontextgröße für Anfragen || 8192
|-
| <code>PAPERLESS_AI_LLM_REQUEST_TIMEOUT</code> || Zeitlimit in Sekunden; für langsame lokale Server erhöhen || 120
|-
| <code>PAPERLESS_LLM_INDEX_TASK_CRON</code> || Aktualisierung des LLM-Index || täglich 02:10 Uhr
|-
| <code>PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS</code> || erlaubt Modellserver im internen Netz || an
|}
* Für '''OpenAI-kompatible Dienste''' <code>PAPERLESS_AI_LLM_BACKEND: openai-like</code>, <code>PAPERLESS_AI_LLM_API_KEY</code> und gegebenenfalls <code>PAPERLESS_AI_LLM_ENDPOINT</code> setzen – das funktioniert auch mit selbst betriebenen Gateways wie vLLM oder LiteLLM.
* Alle Werte lassen sich auch unter ''Anwendungskonfiguration'' einstellen; dort gespeicherte Werte haben Vorrang.
* Nach dem Neustart unter ''Einstellungen › Dokumente'' die Art der Vorschläge wählen.

== Schritt 3: Testen und schrittweise einführen ==
# Einige Dokumente im Posteingang öffnen und ''Vorschlagen'' wählen; Ergebnisse mit der eigenen Ablage vergleichen.
# Erst bei verlässlichen Ergebnissen einen Arbeitsablauf mit ''Dokument hinzugefügt'' und der Aktion '''KI-Vorschläge anwenden''' einrichten – zunächst nur für Titel und Datum, später für weitere Felder.
# Das Posteingangs-Tag beibehalten: Ein Mensch prüft die Zuordnung, bevor das Dokument als erledigt gilt.
# Den Chat (Symbol in der oberen Leiste) mit typischen Fragen testen; Antworten nennen die Quelldokumente.

== Externe OCR mit Azure ==
Unabhängig vom Sprachmodell kann Paperless-ngx die Texterkennung an '''Azure Document Intelligence''' übergeben (<code>PAPERLESS_REMOTE_OCR_ENGINE=azureai</code>, Schlüssel und Endpunkt). Mit <code>PAPERLESS_REMOTE_OCR_MODE=workflow_only</code> gehen nur Dokumente an Azure, für die ein Arbeitsablauf die Aktion ''Externe OCR'' ausführt – etwa schwer lesbare Handschriften. Die Dokumente werden dabei an Microsoft übermittelt; kostenpflichtig je Seite.

== Datenschutz und Sicherheit ==
* '''Datenfluss''': Bei Cloud-Anbietern gehen Dokumenttext und Metadaten an den Anbieter. Das ist eine Übermittlung an einen Auftragsverarbeiter – AV-Vertrag, Speicherort, Nutzung der Daten für Training und Drittlandtransfer prüfen und im Verzeichnis der Verarbeitungstätigkeiten erfassen, siehe [[DSGVO]].
* '''Besondere Kategorien''': Gesundheits-, Personal- oder Mandantendaten nicht an Cloud-Modelle senden; Arbeitsabläufe mit KI-Aktion nur für unkritische Dokumenttypen.
* '''Nicht vertrauenswürdige Inhalte''': Paperless behandelt Dokumenttext als nicht vertrauenswürdige Eingabe. Trotzdem können präparierte Dokumente versuchen, das Modell zu beeinflussen (Prompt Injection). Deshalb KI-Ergebnisse nicht ungeprüft für Berechtigungen nutzen.
* '''Rechte im Chat''': Der Chat beantwortet Fragen auf Grundlage der Dokumente, die der Benutzer sehen darf. Berechtigungen sauber setzen, siehe [[Paperless-ngx: Benutzer, Berechtigungen und Absicherung]].
* '''Internes Netz''': Wird kein lokaler Modellserver genutzt, <code>PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS=false</code> setzen, damit niemand über die Konfiguration interne Dienste anspricht.

== Hinweise ==
* '''Kosten im Blick behalten''': Bei Cloud-Anbietern verursachen Massen-Vorschläge und der tägliche Indexlauf Gebühren. Budgetgrenzen beim Anbieter setzen.
* '''Ältere CPUs''': Der klassische Klassifikator braucht SSE4.2; auf sehr alter Hardware <code>PAPERLESS_TRAIN_TASK_CRON=disable</code> setzen.
* Bei Auswahl, Betrieb und datenschutzgerechtem Einsatz lokaler KI-Modelle unterstützt Sie das [https://www.max-it.de/it-services/it-consulting/ IT-Consulting von m.a.x. it].

== Siehe auch ==
* [[Paperless-ngx]] – Überblick und alle Artikel der Reihe
* [[Paperless-ngx: Arbeitsabläufe automatisieren]]
* [[LLM]]
* [[Machine Learning]]

== Links und Quellen ==
* [https://docs.paperless-ngx.com/advanced_usage/#ai-features Paperless-ngx Dokumentation: AI features]
* [https://www.max-it.de/it-services/it-consulting/ IT-Consulting von m.a.x. it]

{{Uebermax}}
[[Kategorie:Server-Software]]