Datenquellen

Datenquellen sind die Verbindung zwischen KIara und den Unternehmensdaten. Jede Datenquelle verbindet einen Konnektor (Dateisystem, SMB, WebDAV, E-Mail, SQL) mit konfigurierbaren Ingestion-Einstellungen (Chunking, DDU, VLM) und optionalen Zugriffsrechten (Gruppen/Benutzer).

Übersicht & Tabelle

Der Datenquellen-Tab zeigt alle konfigurierten Quellen in einer zentralen Tabelle. Es gibt keine Sub-Tabs — alle Aktionen (Erstellen, Bearbeiten, Indexieren, Löschen) sind direkt über die Tabelle erreichbar.

Tabellen-Spalten

Spalte	Beschreibung	Hinweis
Name	Anzeigename der Datenquelle. Klick öffnet das Bearbeiten-Modal.	Frei wählbar, muss nicht eindeutig sein (die ID ist intern eindeutig).
Typ	Konnektor-Typ als farbiges Badge (z.B. »SMB-Freigabe«, »E-Mail (IMAP)«).	Wird beim Erstellen festgelegt und kann nachträglich nicht geändert werden.
Quelle	Formatierte Zusammenfassung der Verbindungsdaten (z.B. `server:/Share`).	Aus der Konnektor-Konfiguration generiert.
Chunk-Strategie	Aktive Chunk-Strategie (auto, prose, code, email, ...).	Siehe Chunk-Strategie.
Chunks	Anzahl der Chunks pro Embedding-Modell, inkl. letztem Indexierungszeitpunkt.	Wird nach jeder Indexierung aktualisiert. Mehrere Modelle möglich.
Ingestion-Status	Aktueller Status: idle, running (grün), paused (orange), error (rot).	Bei laufender Indexierung wird ein Fortschrittsbalken angezeigt.
Zugriff	Zugewiesene Gruppen und Benutzer als Tag-Liste.	Ohne Zuweisung: Alle Benutzer haben Zugriff.

Aktionen pro Datenquelle

Das Drei-Punkte-Menü jeder Zeile bietet:

Aktion	Beschreibung
Bearbeiten	Öffnet das Edit-Modal mit allen Einstellungen.
Berechtigungen	Gruppen- und Benutzer-Zuweisung (siehe Zugriffsrechte).
Verbindung testen	Prüft Erreichbarkeit der Quelle (Server, Credentials, Pfad).
Status	Zeigt Ingestion-Details: Phase, Fortschritt, Fehler.
Indexieren	Inkrementelle Indexierung — nur neue/geänderte Dateien.
Voll-Indexieren	Alle Dateien neu indexieren (File-Hashes werden zurückgesetzt).
Pause / Abbrechen	Nur bei laufender Indexierung sichtbar.
Löschen	Entfernt die Datenquelle und alle zugehörigen Daten (irreversibel).

Achtung: »Löschen« entfernt die Datenquelle vollständig aus allen 4 Datenschichten: Qdrant-Vektoren, Elasticsearch-Index, File-Hashes und Datenbank (inkl. Chunk-Zuordnungen und Embedding-Statistiken). Dieser Vorgang ist nicht umkehrbar.

Konnektor-Typen

Jeder Konnektor definiert sein eigenes Config-Schema. Die Felder werden im Create/Edit-Modal dynamisch anhand des gewählten Typs gerendert. Passwort-Felder (secret: true) werden AES-verschlüsselt gespeichert und im UI maskiert angezeigt (••••••••).

Lokal

Liest Dateien aus einem lokalen Verzeichnis auf dem KIara-Server.

Feld	Typ	Pflicht	Beschreibung	Empfehlung
`path`	Text	Nein	Absoluter Pfad zum Verzeichnis. Leer = globaler Pfad aus `kiara.yaml`.	Immer einen expliziten Pfad angeben — so ist die Datenquelle unabhängig von der globalen Config. Beispiel: `/data/dokumente/technik`

Tipp: Der KIara-Prozess (User kiara) braucht Leserechte auf das Verzeichnis. Prüfen mit: sudo -u kiara ls /data/dokumente/technik

SMB-Freigabe

Verbindet sich mit Windows-Dateifreigaben (SMB/CIFS). Unterstützt Domain-Authentifizierung.

Feld	Typ	Pflicht	Standard	Beschreibung	Empfehlung
`server`	Text	Ja	—	Hostname oder IP des Fileservers.	Hostname bevorzugen (`fileserver.firma.local`).
`share`	Text	Ja	—	Name der Freigabe (ohne führenden Backslash).	Beispiel: `Documents`, `Abteilungen$`
`username`	Text	Nein	—	Windows-Benutzername für die Authentifizierung.	Dedizierten Service-Account verwenden (z.B. `svc-kiara-read`).
`password`	Passwort	Nein	—	Passwort. Wird AES-verschlüsselt gespeichert.	Leer lassen bei Edit = bestehendes Passwort beibehalten.
`domain`	Text	Nein	—	Windows-Domäne für die Authentifizierung.	Beispiel: `FIRMA` (NetBIOS-Name) oder `firma.local` (FQDN).
`sub_path`	Text + Browse	Nein	—	Unterverzeichnis innerhalb der Freigabe. Browse-Button verfügbar.	Nützlich um nur einen Teilbereich einer großen Freigabe zu indexieren.

Tipp: Der Browse-Button neben sub_path zeigt den Verzeichnisinhalt der Freigabe live an. Dafür müssen Server, Freigabe und Credentials bereits eingetragen sein.

WebDAV

Verbindet sich mit WebDAV-Servern (z.B. Nextcloud, ownCloud, SharePoint).

Feld	Typ	Pflicht	Standard	Beschreibung	Empfehlung
`url`	Text	Ja	—	Vollständige WebDAV-URL.	Nextcloud: `https://cloud.firma.de/remote.php/dav/files/USERNAME/` Trailingslash beachten!
`username`	Text	Nein	—	WebDAV-Benutzername.	Bei Nextcloud: App-Passwort verwenden (Einstellungen → Sicherheit → App-Passwörter).
`password`	Passwort	Nein	—	Passwort. Wird verschlüsselt gespeichert.	—
`base_path`	Text + Browse	Nein	`/`	Basispfad innerhalb der WebDAV-Struktur. Browse-Button verfügbar.	Beispiel: `/Dokumente/Projekte`

E-Mail (IMAP)

Indexiert E-Mails inkl. Anhänge über IMAP. Unterstützt SSL und Ordner-Auswahl.

Feld	Typ	Pflicht	Standard	Beschreibung	Empfehlung
`server`	Text	Ja	—	IMAP-Server (Hostname oder IP).	Beispiel: `mail.firma.de`
`port`	Zahl	Nein	`993`	IMAP-Port. 993 = SSL (Standard), 143 = unverschlüsselt.	993 mit SSL empfohlen.
`ssl`	Checkbox	Nein	An	SSL/TLS-Verschlüsselung aktivieren.	Immer aktiviert lassen.
`username`	Text	Nein	—	IMAP-Benutzername (oft die E-Mail-Adresse).	Beispiel: `benutzer@firma.de`
`password`	Passwort	Nein	—	IMAP-Passwort. Wird verschlüsselt gespeichert.	Bei Microsoft 365: App-Passwort verwenden (MFA-kompatibel).
`folders`	Text / Ordner-Picker	Nein	`INBOX`	Kommaseparierte Liste oder Auswahl über den Ordner-Picker-Button. Der Picker lädt die Ordner-Hierarchie vom Server.	Beispiel: `INBOX, Sent, Archive/2025` Ordner-Picker empfohlen — zeigt die exakten Server-seitigen Namen.
`since_days`	Zahl	Nein	`90`	Nur E-Mails der letzten N Tage indexieren.	90-180 Tage für die meisten Fälle. Zu große Zeiträume erhöhen Indexierungszeit und Speicherbedarf.
`download_attachments`	Checkbox	Nein	An	E-Mail-Anhänge herunterladen und indexieren.	Aktiviert lassen — Anhänge enthalten oft die relevantesten Informationen.
`max_attachment_mb`	Zahl	Nein	`25`	Maximale Größe einzelner Anhänge in MB.	25 MB reicht für die meisten Dokumente. Sehr große Anhänge (CAD, Videos) sind selten nützlich für RAG.

Tipp — IMAP-Ordnernamen: IMAP-Server verwenden verschiedene Namenskonventionen. Der Ordner-Picker-Button lädt die exakten Namen vom Server — das vermeidet Tippfehler. Häufige Unterschiede:

Outlook/Exchange: Sent Items, Deleted Items
Dovecot: Sent, Trash
Gmail: [Gmail]/Sent Mail, [Gmail]/Trash

Exchange Online (OAuth2)

Verbindet sich mit Microsoft 365 / Exchange Online über OAuth2 (App-Registrierung in Entra ID). Kein Benutzer-Passwort nötig — Authentifizierung läuft über Client-ID und Client-Secret.

Feld	Typ	Pflicht	Standard	Beschreibung	Empfehlung
`tenant_id`	Text	Ja	—	Azure AD / Entra ID Tenant-ID (UUID).	Zu finden in Entra Admin Center → Übersicht → Tenant-ID.
`client_id`	Text	Ja	—	Anwendungs-ID der App-Registrierung (UUID).	Eigene App-Registrierung für KIara anlegen mit `Mail.Read`-Berechtigung (Application).
`client_secret`	Passwort	Ja	—	Client-Secret der App-Registrierung. Wird verschlüsselt gespeichert.	Ablaufdatum beachten! Azure-Secrets haben ein maximales Alter von 2 Jahren.
`username`	Text	Ja	—	E-Mail-Adresse des Postfachs, das gelesen werden soll.	Beispiel: `team-support@firma.de` (Shared Mailbox möglich).
`folders`	Text / Ordner-Picker	Nein	`INBOX`	Kommasepariert oder per Ordner-Picker.	Beispiel: `INBOX, Sent Items`
`since_days`	Zahl	Nein	`90`	Zeitraum in Tagen.	Siehe IMAP.
`download_attachments`	Checkbox	Nein	An	Anhänge herunterladen und indexieren.	—
`max_attachment_mb`	Zahl	Nein	`25`	Maximale Anhang-Größe in MB.	—

Tipp — Azure App-Registrierung für KIara:

Entra Admin Center → App-Registrierungen → Neue Registrierung
Name: KIara Mail Reader
API-Berechtigungen → Microsoft Graph → Anwendungsberechtigung → Mail.Read
Admin-Zustimmung erteilen
Zertifikate & Geheimnisse → Neues Client-Secret erstellen
Tenant-ID, Client-ID und Secret in KIara eintragen

SQL-Datenbank

Indexiert Daten aus relationalen Datenbanken. Unterstützt PostgreSQL, MSSQL und MySQL. Jede Zeile wird anhand eines konfigurierbaren Templates zu einem Text-Chunk.

Feld	Typ	Pflicht	Standard	Beschreibung	Empfehlung
`dsn`	Passwort	Ja	—	Verbindungsstring (DSN). Wird verschlüsselt gespeichert.	Formate: `postgresql://user:pass@host:5432/dbname` `mssql+pyodbc://user:pass@host/db?driver=ODBC+Driver+18` `mysql://user:pass@host:3306/dbname`
`driver`	Dropdown	Nein	`auto`	Datenbank-Treiber.	Optionen: `auto` (aus DSN erkennen), `postgresql`, `mssql`, `mysql`. `auto` reicht in den meisten Fällen.
`query`	Textarea	Nein	—	SQL-Abfrage, die die zu indexierenden Daten liefert.	Beispiel: `SELECT id, titel, beschreibung, kategorie FROM protokolle` Die Query sollte die ID-Spalte und alle Text-relevanten Spalten enthalten.
`text_columns`	Text	Nein	—	Kommaseparierte Liste der Spalten, die als Text indexiert werden.	Beispiel: `beschreibung, massnahme, kommentar`
`id_column`	Text	Nein	`id`	Primärschlüssel-Spalte für inkrementelle Updates.	Muss eindeutig sein. Standard `id` passt für die meisten Tabellen.
`timestamp_column`	Text	Nein	—	Zeitstempel-Spalte für inkrementelle Updates.	Beispiel: `updated_at`. Wenn gesetzt, werden nur Zeilen indexiert, die neuer sind als der letzte Lauf.
`text_template`	Text	Nein	—	Template für die Textgenerierung aus Spalten.	Beispiel: `{titel}: {beschreibung} (Kategorie: {kategorie})` Platzhalter sind Spaltennamen in geschweiften Klammern. Ohne Template werden alle Text-Spalten konkateniert.

Tipp: Der SQL-Konnektor ist ideal für ERP-Daten, Ticket-Systeme oder Protokoll-Datenbanken. Mit timestamp_column und id_column werden nur geänderte Zeilen neu indexiert — das spart bei großen Tabellen erheblich Zeit.

Ingestion-Einstellungen

Die erweiterten Einstellungen im Create/Edit-Modal steuern, wie Dokumente verarbeitet und in Chunks zerlegt werden. Sie sind hinter einem »Erweiterte Einstellungen«-Aufklapper gruppiert.

Chunk-Strategie

Die Chunk-Strategie bestimmt, wie Dokumente in indexierbare Text-Abschnitte (Chunks) zerlegt werden. Jede Strategie hat eigene Defaults für Chunk-Größe und Überlappung.

Strategie	Chunk-Größe	Überlappung	Einsatzgebiet
auto (empfohlen)	variabel	variabel	Erkennt automatisch: Prosa, tabellarisch, Code, Markdown, E-Mail. Beste Wahl für gemischte Datenquellen.
prose	768	150	Fließtext, Berichte, Dokumentationen.
tabular	256	0	Tabellen, CSV, strukturierte Daten. Keine Überlappung, da Zeilen unabhängig.
structured	384	50	XML, JSON, strukturierte Konfigurationsdateien.
code	512	100	Quellcode — chunked nach Funktionen/Klassen, nicht nach Zeichenzahl.
email	640	100	E-Mails — berücksichtigt Header, Body und Signatur-Trennung.
custom	frei (100–10.000)	frei (0–5.000)	Manuelle Konfiguration. Blendet Felder für Chunk Size und Overlap ein.

Tipp: auto ist die beste Wahl für die meisten Datenquellen. custom nur verwenden, wenn die automatische Erkennung nachweislich schlechte Ergebnisse liefert (z.B. bei sehr speziellen Dokumentformaten).

Document Understanding (DDU)

Feld	Standard	Beschreibung
`DDU aktivieren`	Aus	Aktiviert Docling Document Understanding — konvertiert PDF, Office-Dokumente und Bilder über ein Deep-Learning-Modell zu Markdown. Deutlich bessere Ergebnisse bei komplexen Layouts (Tabellen, Spalten, Grafiken).
`DDU OCR für Bilder`	An	Nur wenn DDU aktiviert. Führt OCR auf eingebetteten Bildern durch. Nützlich für gescannte PDFs.

Achtung: DDU benötigt den Docling-Proxy-Service auf dem Ollama-Server (Port 5001) und ca. 7 GiB VRAM. Die Verarbeitungszeit pro Datei ist deutlich höher als ohne DDU. Für große Datenquellen (>1000 Dateien) kann die Erstindexierung mehrere Stunden dauern.

Vision Language Model (VLM)

Feld	Standard	Beschreibung
`VLM aktivieren`	Aus	Aktiviert die Bildbeschreibung über ein Vision Language Model. Bilder (PNG, JPG, etc.) werden durch das VLM beschrieben und der resultierende Text wird indexiert. Unterstützt 20+ Bildformate.

Tipp: VLM ist besonders nützlich für Datenquellen mit vielen Bildern (z.B. technische Zeichnungen, Fotos, Screenshots). Ohne VLM werden Bilddateien übersprungen.

Dateityp-Filter & Ausschlussmuster

Feld	Typ	Beschreibung	Beispiel
`Dateitypen`	Text (kommasepariert)	Nur diese Dateitypen indexieren. Leer = alle unterstützten Typen.	`.pdf, .docx, .xlsx, .txt`
`Ausschlussmuster`	Text (Glob-Syntax)	Dateien/Verzeichnisse ausschließen.	`/tmp/, .bak, /archiv/*`
`Alle Textdateien akzeptieren`	Checkbox	Wenn aktiviert, werden auch Dateien ohne bekannte Endung indexiert, sofern sie als Text erkannt werden (Charset-Erkennung).	Nützlich für Logdateien, Config-Dateien ohne Endung.
`E-Mail-Anhänge indexieren`	Checkbox (nur Mail)	Nur für IMAP/Exchange: Steuert ob Anhänge indexiert werden.	Standard: An.

Sync-Intervall

Wert	Beschreibung
`global`	Verwendet den Systemstandard aus `kiara.yaml`.
`manual`	Keine automatische Synchronisierung — nur manuell über die UI oder API.
`daily`	Täglich (einmal pro 24h).
`weekly`	Wöchentlich.
`monthly`	Monatlich.
`custom`	Benutzerdefinierter Cron-Ausdruck.

Tipp: Für Datenquellen die sich selten ändern (z.B. Archiv-Freigaben) ist weekly oder monthly sinnvoll. Für E-Mail-Quellen empfiehlt sich daily, damit neue Mails zeitnah verfügbar sind.

Contextual Retrieval

Contextual Retrieval reichert Chunks waehrend der Ingestion mit LLM-generiertem Kontext an. Pro Chunk wird ein 2-3-Satz-Prefix erzeugt, der den Chunk im Dokumentkontext verortet. Dadurch verbessern sich sowohl Vektor-Embeddings als auch BM25-Suche.

Feld	Typ	Beschreibung
`Contextual Retrieval aktivieren`	Checkbox	Aktiviert Enrichment fuer diese Datenquelle. Setzt voraus, dass der globale Schalter `enrichment.enabled` aktiv ist.
`Prompt-Template`	Dropdown	Welcher Enrichment-Prompt verwendet wird. `(Standard)` nutzt das System-Template.
`Enrichment-Backend`	Dropdown	Welches LLM-Backend den Kontext generiert. Pflichtfeld wenn Enrichment aktiv ist.

Wichtig: Ein Enrichment-Backend muss explizit gewaehlt werden. Es gibt keinen stillen Fallback auf ein Standard-Backend.

Ausfuehrliche Dokumentation (Prompts, Versionierung, Integritaetspruefung, Performance, API-Endpunkte) im eigenen Guide »Contextual Retrieval«.

ColBERT

ColBERT speichert pro Chunk Token-Level-Vektoren statt eines einzelnen Vektors. Beim Retrieval wird per MaxSim-Scoring ueber alle Token-Paare gematcht — ideal fuer Multi-Aspekt-Queries, bei denen verschiedene Begriffe an verschiedenen Stellen im Dokument vorkommen.

Feld	Typ	Beschreibung
`ColBERT`	Checkbox	Aktiviert ColBERT-Indexierung fuer diese Datenquelle. Setzt voraus, dass der globale Schalter `retrieval.colbert.enabled` aktiv ist (Admin-UI → KI → Indexierung).

Speicherbedarf: ColBERT benoetigt ca. 40x mehr Speicher als Standard-Embeddings. Nur fuer Datenquellen aktivieren, bei denen Multi-Aspekt-Queries haeufig sind.

Ausfuehrliche Dokumentation (Token-Level Matching, Voraussetzungen, Speicherbedarf, Wechselwirkung mit RRF-Fusion, Fallback-Verhalten) im eigenen Guide »ColBERT«.

Zugriffsrechte

Über das Berechtigungs-Modal können einer Datenquelle Gruppen und/oder einzelne Benutzer zugewiesen werden. Nur zugewiesene Benutzer (direkt oder über eine Gruppe) sehen Ergebnisse aus dieser Datenquelle in ihren Chat-Antworten.

Regel	Beschreibung
Keine Zuweisung	Alle Benutzer haben Zugriff (Standard für neue Datenquellen).
Gruppen zugewiesen	Nur Mitglieder der zugewiesenen Gruppen haben Zugriff.
Benutzer zugewiesen	Nur die zugewiesenen Benutzer haben Zugriff.
Gruppen + Benutzer	Vereinigung: Gruppenmitglieder UND direkt zugewiesene Benutzer haben Zugriff.

Tipp: Die Zuweisung erfolgt im Replace-All-Modus — beim Speichern werden alle bestehenden Zuweisungen durch die aktuelle Auswahl ersetzt. Das bedeutet: Wenn alle Checkboxen abgewählt werden, wird der Zugriff für alle geöffnet (keine Einschränkung).

Indexierung steuern

Inkrementelle vs. Voll-Indexierung

Modus	Beschreibung	Wann verwenden
Indexieren	Vergleicht File-Hashes (Pfad + Größe + mtime). Nur neue oder geänderte Dateien werden verarbeitet. Bestehende Chunks bleiben erhalten.	Standardfall — für regelmäßige Updates.
Voll-Indexieren	Setzt alle File-Hashes zurück und verarbeitet jede Datei neu. Bestehende Chunks werden vorher gelöscht.	Nach Änderung der Chunk-Strategie, nach DDU-Aktivierung, bei Verdacht auf inkonsistente Daten.

Pipeline-Phasen

Die Indexierung durchläuft folgende Phasen (sichtbar im Status-Dialog):

Scanning — Dateien auflisten und Hashes berechnen
Loading — Dateien laden und in Text konvertieren (ggf. via DDU/VLM)
Chunking — Text in Chunks zerlegen
Embedding — Chunks vektorisieren und in Qdrant speichern

Pause und Abbruch

Pause — Unterbricht die Pipeline nach dem aktuellen Batch. Kann fortgesetzt werden.
Abbrechen — Bricht die Pipeline ab. Bereits verarbeitete Dateien behalten ihren Hash — ein erneuter »Indexieren«-Lauf setzt an der Stelle fort.

Tipp — Circuit-Breaker: Nach 10 aufeinanderfolgenden Fehlern bricht die Pipeline automatisch ab (Circuit-Breaker). Das verhindert Endlosschleifen bei systematischen Problemen (z.B. DDU-Service nicht erreichbar).

API-Endpunkte

Die vollständige API-Referenz für Datenquellen wird dynamisch aus der Admin-Registry generiert und ist im API-Katalog verfügbar:

Datenquellen-API — CRUD, Verbindungstest, Gruppen-/Benutzer-Zuweisung, Ingestion-Status

Troubleshooting

Problem	Mögliche Ursache	Lösung
Verbindungstest SMB schlägt fehl	Firewall, falscher Share-Name, fehlende Credentials	Vom KIara-Server testen: `smbclient //server/share -U user%pass`. Domain-Format prüfen: `DOMAIN\user` oder `user@domain`.
WebDAV »401 Unauthorized«	Falsches Passwort oder App-Passwort nötig	Bei Nextcloud mit 2FA: App-Passwort generieren unter Einstellungen → Sicherheit → Geräte & Sitzungen.
IMAP-Ordner werden nicht gefunden	Falsche Ordnernamen, Server-spezifische Konvention	Ordner-Picker verwenden statt manueller Eingabe.
Exchange: »Token-Fehler«	Client-Secret abgelaufen, fehlende Admin-Zustimmung	Entra Admin Center: App → Zertifikate & Geheimnisse prüfen. API-Berechtigungen: Admin-Zustimmung erteilt?
SQL: »Treiber nicht gefunden«	Fehlende System-Bibliothek	MSSQL: `apt install unixodbc-dev` + ODBC-Treiber installieren. MySQL: `pip install pymysql` im KIara-venv.
Indexierung bricht nach 10 Dateien ab	Circuit-Breaker ausgelöst (10 aufeinanderfolgende Fehler)	Ursache im Ingestion-Status prüfen (Fehlermeldung pro Datei). Häufig: DDU-Timeout, Dateiberechtigungen, korrupte Dateien.
Chunks sind 0 nach Indexierung	Keine unterstützten Dateitypen, Dateityp-Filter zu restriktiv	Dateityp-Filter prüfen. `Alle Textdateien akzeptieren` aktivieren für Dateien ohne Endung.
DDU-Fehler: »Timeout«	Docling-Proxy nicht erreichbar oder überlastet	Status prüfen: `systemctl status docling-proxy` auf dem Ollama-Server (10.0.12.16). VRAM-Auslastung prüfen: `nvidia-smi`.