Paperless-ngx: KI-Funktionen mit Ollama oder OpenAI
Auf einen Blick
| Gilt für | 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.
Was die KI-Funktionen leisten
| 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?
| 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:
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] }]
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)
- 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
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"
| Einstellung | Bedeutung | Standard |
|---|---|---|
PAPERLESS_AI_ENABLED |
Hauptschalter | aus |
PAPERLESS_AI_LLM_BACKEND |
ollama oder openai-like |
– |
PAPERLESS_AI_LLM_MODEL |
Modellname | llama3.1 (Ollama) bzw. gpt-3.5-turbo
|
PAPERLESS_AI_LLM_EMBEDDING_BACKEND |
huggingface (vollständig lokal im Container), ollama, openai-like; aktiviert den LLM-Index |
– |
PAPERLESS_AI_LLM_CONTEXT_SIZE |
Kontextgröße für Anfragen | 8192 |
PAPERLESS_AI_LLM_REQUEST_TIMEOUT |
Zeitlimit in Sekunden; für langsame lokale Server erhöhen | 120 |
PAPERLESS_LLM_INDEX_TASK_CRON |
Aktualisierung des LLM-Index | täglich 02:10 Uhr |
PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS |
erlaubt Modellserver im internen Netz | an |
- Für OpenAI-kompatible Dienste
PAPERLESS_AI_LLM_BACKEND: openai-like,PAPERLESS_AI_LLM_API_KEYund gegebenenfallsPAPERLESS_AI_LLM_ENDPOINTsetzen – 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 (PAPERLESS_REMOTE_OCR_ENGINE=azureai, Schlüssel und Endpunkt). Mit PAPERLESS_REMOTE_OCR_MODE=workflow_only 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,
PAPERLESS_AI_LLM_ALLOW_INTERNAL_ENDPOINTS=falsesetzen, 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
PAPERLESS_TRAIN_TASK_CRON=disablesetzen. - Bei Auswahl, Betrieb und datenschutzgerechtem Einsatz lokaler KI-Modelle unterstützt Sie das 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
Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung?
