VektorDB

Die VektorDB speichert alle Text-Chunks als Vektoren (Embeddings) in Qdrant. Der VektorDB-Tab hat zwei Bereiche: Konnektor (Verbindungseinstellungen) und DB-Management (Dateiverwaltung in Qdrant). Ergänzend gibt es im System-Tab die Integritätsprüfung, die alle Datenschichten auf Konsistenz prüft.

Sub-Tab: Konnektor

Qdrant-Verbindungseinstellungen. Änderungen an der Verbindung oder Vektordimension erfordern eine Neuindexierung aller Datenquellen.

Feld	Typ	Standard	Beschreibung	Empfehlung
`qdrant_url`	Text	`http://localhost:6333`	URL des Qdrant-Servers (HTTP oder gRPC).	Auf dem gleichen Host: `http://localhost:6333`. Remote: `http://10.0.12.20:6333`. Qdrant Cloud: `https://xxx.eu-west-1-0.aws.cloud.qdrant.io:6333`
`qdrant_api_key`	Passwort	(leer)	Optionaler API-Key für authentifizierte Qdrant-Instanzen.	Nur nötig bei Qdrant Cloud oder wenn API-Key-Auth in der Qdrant-Config aktiviert ist. Lokal meist nicht erforderlich.
`qdrant_grpc`	Checkbox	Aus	gRPC-Protokoll statt HTTP verwenden.	gRPC ist schneller bei großen Batch-Operationen (Embedding-Upload). Erfordert Port 6334 (gRPC) statt 6333 (HTTP). Für lokale Setups ist HTTP ausreichend.
`vector_size`	Zahl	`768`	Vektordimension. Wird normalerweise automatisch vom Embedding-Modell bestimmt.	Nicht manuell ändern, es sei denn das Modell wird nicht automatisch erkannt. Standard-Werte: `nomic-embed-text` = 768 `text-embedding-3-small` = 1536 `voyage-3` = 1024

Aktionen

Button	Beschreibung
Verbindung testen	Prüft Erreichbarkeit des Qdrant-Servers und zeigt die Anzahl vorhandener Collections.
Speichern	Speichert die Verbindungseinstellungen in der Config.
Zurücksetzen	Verwirft ungespeicherte Änderungen und lädt die aktuellen Werte.

Tipp: Nach Änderung der qdrant_url immer zuerst »Verbindung testen« klicken, bevor gespeichert wird. Ein falscher Wert führt dazu, dass keine Suchergebnisse mehr geliefert werden.

Sub-Tab: DB-Management

Zeigt den Inhalt der VektorDB auf Dateiebene und ermöglicht das gezielte Löschen einzelner Dateien aus dem Index.

Datenquellen-Matrix

Die Matrix zeigt eine Übersicht aller Datenquellen × Embedding-Modelle mit der jeweiligen Chunk-Anzahl. Jede Zelle ist klickbar und öffnet die Datei-Details.

Spalte	Beschreibung
Datenquelle	Name der Datenquelle.
kb_<modell>	Eine Spalte pro Embedding-Modell (= Qdrant-Collection). Zeigt die Chunk-Anzahl für diese Datenquelle in diesem Modell. Klick öffnet die Datei-Details.
Gesamt (letzte Zeile)	Summe aller Chunks pro Modell über alle Datenquellen.

Tipp: Wenn eine Datenquelle in mehreren Modellen indexiert ist (z.B. nach einem Modellwechsel), erscheinen mehrere Spalten. Die alte Collection kann über den Konnektor-Tab oder direkt in Qdrant gelöscht werden.

Datei-Details & Löschen

Nach Klick auf eine Zelle in der Matrix öffnet sich die Datei-Detailansicht für die gewählte Datenquelle + Modell-Kombination.

Toolbar

Element	Beschreibung
Suchfeld	Filtert Dateien nach Name/Pfad (live, case-insensitiv).
Alle auswählen	Toggle: markiert/entmarkiert alle sichtbaren Dateien.
Ausgewählte löschen (N)	Löscht die markierten Dateien aus Qdrant. Bestätigung erforderlich.
Schließen	Schließt die Datei-Detailansicht.

Datei-Tabelle

Spalte	Beschreibung	Sortierbar
Checkbox	Auswahl für Batch-Löschen.	Nein
Dateipfad	Voller Pfad — Verzeichnis in grau, Dateiname normal.	Ja
Typ	Dateiendung (`.pdf`, `.docx`, ...).	Ja
Chunks	Anzahl der Chunks dieser Datei im Index.	Ja
Geändert	Änderungszeitpunkt der Quelldatei (aus dem Payload).	Ja

Löschen — Was passiert

Beim Löschen von Dateien aus der VektorDB:

Alle Chunks der Datei werden aus der Qdrant-Collection entfernt
Zuordnungen in chunk_datasources werden gelöscht
Statistiken in datasource_embeddings werden aktualisiert
Shared Chunks (Datei in mehreren Datenquellen) werden nicht gelöscht, nur die DS-ID entfernt
Der File-Hash wird nicht gelöscht — beim nächsten Indexlauf wird die Datei neu verarbeitet

Tipp: Das Löschen einzelner Dateien ist nützlich, wenn eine Datei fehlerhaft indexiert wurde (z.B. durch DDU-Fehler oder falsche Chunk-Strategie). Beim nächsten Indexlauf wird sie automatisch neu verarbeitet.

Collections & Naming

Jedes Embedding-Modell bekommt eine eigene Qdrant-Collection. Der Name wird automatisch aus dem Modellnamen abgeleitet:

# Namens-Schema
kb_{normalisierter_modellname}

# Normalisierung:
# 1. ":latest" Tag wird entfernt
# 2. Sonderzeichen werden durch "_" ersetzt

# Beispiele:
nomic-embed-text          →  kb_nomic-embed-text
nomic-embed-text:v1.5     →  kb_nomic-embed-text_v1.5
text-embedding-3-small    →  kb_text-embedding-3-small
voyage-3                  →  kb_voyage-3

Eigenschaft	Wert
Distance Metric	COSINE
Vektordimension	Automatisch vom Modell (768, 1024, 1536, ...)
Payload-Indexes	`source`, `source_key`, `directory`, `file_type`, `ds_ids`, `modified`

Tipp — Dimension-Erkennung (Cascade): Die Vektordimension wird in folgender Reihenfolge ermittelt:

Aus der KI-Backend-Konfiguration (embedding_dim)
Live-Abfrage beim Ollama-Server (/api/show)
Lookup-Tabelle bekannter Modelle (KNOWN_EMBEDDING_DIMENSIONS)
Fallback: vector_size aus der Config (Standard: 768)

Embedding-Modelle

KIara unterstützt drei Embedding-Provider. Welches Modell verwendet wird, wird im KI-Tab unter »Backends« konfiguriert.

Provider	Modelle (Beispiele)	Dimension	Batch-Limit	Besonderheit
Ollama (lokal)	`nomic-embed-text` (768) `mxbai-embed-large` (1024) `snowflake-arctic-embed` (1024)	modellabhängig	unbegrenzt (Streaming)	Läuft lokal auf der GPU. Kein API-Key nötig. `nomic-embed-text` nutzt Query/Document-Prefixes (`search_query:` / `search_document:`).
OpenAI	`text-embedding-3-small` (1536) `text-embedding-3-large` (3072)	1536 / 3072	2048 Texte/Request	Cloud-basiert. API-Key erforderlich. Höhere Qualität, aber Kosten pro Token.
Voyage AI	`voyage-3` (1024) `voyage-3-lite` (512)	1024 / 512	1000 Texte/Request	Cloud-basiert. API-Key erforderlich. Spezialisiert auf Retrieval-Qualität.

Achtung: Ein Wechsel des Embedding-Modells erfordert eine Voll-Indexierung aller Datenquellen, da die Vektordimensionen und der Vektorraum zwischen Modellen nicht kompatibel sind. Die alte Collection bleibt bestehen und kann manuell gelöscht werden.

Payload-Schema

Jeder Vektor-Punkt in Qdrant hat neben dem Embedding-Vektor ein Payload mit Metadaten. Diese Felder werden bei der Suche für Filterung und bei der Anzeige für Kontext genutzt.

Feld	Typ	Index	Beschreibung
`source`	String	KEYWORD	Absoluter Pfad der Quelldatei.
`source_key`	String	KEYWORD	Identisch zu `source`. Dedizierter Index für O(1)-Lookups.
`directory`	String	TEXT	Verzeichnispfad (ohne Dateiname).
`file_type`	String	KEYWORD	Dateiendung (z.B. `pdf`, `docx`).
`ds_ids`	Integer[]	INTEGER	IDs aller Datenquellen, die diesen Chunk enthalten. Ermöglicht datenquellenspezifische Suche und Berechtigungsprüfung.
`modified`	Datetime	DATETIME	Änderungszeitpunkt der Quelldatei.
`_text`	String	(kein Index)	Voller Textinhalt des Chunks. Wird bei der Antwortgenerierung als Kontext verwendet.

Tipp: Das ds_ids-Array ermöglicht, dass ein Chunk mehreren Datenquellen zugeordnet sein kann (z.B. wenn derselbe Pfad in zwei lokalen Datenquellen konfiguriert ist). Beim Löschen einer Datenquelle wird nur die DS-ID entfernt — der Chunk bleibt erhalten, solange noch andere DS-IDs vorhanden sind.

Integritätsprüfung

Die Integritätsprüfung (im System-Tab) vergleicht alle 4 Datenschichten auf Konsistenz. Sie erkennt verwaiste Chunks, fehlende Zuordnungen und Statistik-Abweichungen.

Prüfungen

Check	Beschreibung	Mögliche Befunde
Layer-Counts	Vergleicht die Chunk-Zähler aller Schichten: Qdrant-Punkte, Elasticsearch-Dokumente, `chunk_datasources`-Einträge und `datasource_embeddings`-Summe.	Abweichungen deuten auf nicht synchronisierte Schichten hin (z.B. nach einem Crash während der Indexierung).
DS-Coverage	Prüft für jede Datenquelle, ob die Chunk-Zähler in `chunk_datasources`, `datasource_embeddings` und `file_hashes` konsistent sind.	Warnungen pro Datenquelle, wenn Zähler auseinanderlaufen.
ES-Duplikate	Sucht nach Quellen mit ungewöhnlich vielen Elasticsearch-Einträgen (Schwelle: >5000 Einträge pro Quelle).	Hinweis auf doppelte Indexierung oder fehlende Bereinigung nach Löschen.
Orphan-Chunks	Stichproben-Scan: Prüft zufällige Chunks in Qdrant, ob sie eine Zuordnung in `chunk_datasources` haben.	Verwaiste Chunks (Orphans) haben keinen Besitzer — sie belegen Speicher und liefern möglicherweise veraltete Ergebnisse.
Overlapping DS	Erkennt Datenquellen, die auf identische oder verschachtelte Pfade zeigen.	Warnung bei identischen Pfaden (Duplikate) oder Unterverzeichnis-Beziehungen.

Gesamt-Status

Status	Bedeutung
OK	Alle Schichten konsistent. Keine Aktion nötig.
Degraded	Warnungen vorhanden, aber kein Datenverlust. Reparatur empfohlen.
Critical	Schwerwiegende Inkonsistenzen. Reparatur erforderlich.

Tipp: Für einen schnellen Überblick gibt es den Schnell-Check, der nur die Layer-Counts vergleicht (wenige Sekunden). Die Vollprüfung läuft im Hintergrund und kann bei großen Datenbeständen einige Minuten dauern.

Reparatur-Aktionen

Reparatur-Aktionen werden nur angeboten, wenn die Prüfung Probleme erkennt. Alle erfordern eine Bestätigung.

Aktion	Beschreibung	Wann verwenden
ds_ids synchronisieren	Liest alle Zuordnungen aus `chunk_datasources` und schreibt das `ds_ids`-Payload-Feld in Qdrant neu.	Wenn Datenquellen-Zuordnungen in Qdrant nicht mit der DB übereinstimmen (z.B. nach manuellem DB-Eingriff).
Statistiken korrigieren	Zählt die tatsächlichen Chunks pro Datenquelle in `chunk_datasources` und aktualisiert `datasource_embeddings.chunk_count`.	Wenn die Chunk-Zähler in der Matrix nicht mit der Realität übereinstimmen.
Verwaiste Chunks löschen	Scannt ALLE Chunks in Qdrant und löscht diejenigen ohne Zuordnung in `chunk_datasources`.	Bei Orphan-Befund. Destruktiv — nur ausführen, wenn die Vollprüfung Orphans bestätigt hat.

Achtung: »Verwaiste Chunks löschen« scannt den gesamten Qdrant-Bestand. Bei großen Collections (>100.000 Punkte) kann das mehrere Minuten dauern. Die Aktion ist nicht umkehrbar — gelöschte Chunks müssen bei Bedarf neu indexiert werden.

Die 4 Datenschichten

KIara speichert Indexdaten in 4 voneinander abhängigen Schichten. Beim Löschen einer Datenquelle müssen alle 4 Schichten bereinigt werden, damit keine verwaisten Daten zurückbleiben.

#	Schicht	Speicherort	Inhalt
1	Qdrant	Collection `kb_<modell>`	Vektor-Embeddings + Payload (Text, Metadaten, ds_ids).
2	datasource_embeddings	PostgreSQL	Aggregierte Statistiken: Chunk-Count, File-Count, letzter Indexierungszeitpunkt pro DS + Modell.
3	file_hashes	PostgreSQL (`file_hashes`-Tabelle)	Hash-Tabelle für inkrementelle Indexierung (Pfad + Größe + mtime).
4	chunk_datasources	PostgreSQL	Zuordnung: welcher Chunk gehört zu welcher Datenquelle.

Tipp: Wenn eine Datenquelle über die Admin-UI gelöscht wird, bereinigt KIara automatisch alle 4 Schichten (DS-spezifisches Löschen via Scroll+Bulk in Qdrant, Cascade in PostgreSQL, Hash-Bereinigung). Manuelles Eingreifen in einzelne Schichten (z.B. direktes Löschen in Qdrant) führt zu Inkonsistenzen, die die Integritätsprüfung erkennt.

API-Endpunkte

Die vollständige API-Referenz wird dynamisch aus der Admin-Registry generiert:

VektorDB-API — Dateiliste, Datei-Löschung, Verbindungstest
Integrity-API — Vollprüfung, Schnell-Check, Reparatur-Aktionen

Troubleshooting

Problem	Mögliche Ursache	Lösung
Verbindungstest schlägt fehl	Qdrant-Container nicht gestartet, falscher Port, Firewall	`docker ps \| grep qdrant` prüfen. `curl http://localhost:6333/healthz` testen. Standard-Port: 6333 (HTTP), 6334 (gRPC).
Collection hat falsche Dimension	Embedding-Modell gewechselt, aber alte Collection bleibt	Alte Collection manuell löschen: `curl -X DELETE http://localhost:6333/collections/kb_altes_modell`. Dann alle Datenquellen voll-indexieren.
Chunk-Zähler in Matrix stimmen nicht	Statistiken nach Crash nicht aktualisiert	Integritätsprüfung → »Statistiken korrigieren« ausführen.
Suchergebnisse enthalten gelöschte Dateien	Chunks in Qdrant nicht bereinigt (z.B. nach manuellem DB-Löschen)	Integritätsprüfung → »Verwaiste Chunks löschen«. Alternativ: Datenquelle voll-indexieren.
Qdrant Speicherverbrauch steigt	Alte Collections nach Modellwechsel, verwaiste Chunks	Nicht mehr benötigte Collections löschen. Integritätsprüfung auf Orphans prüfen. Qdrant-Dashboard: `http://localhost:6333/dashboard`.
»Dimension mismatch« bei Indexierung	Collection existiert mit alter Dimension, neues Modell hat andere	Collection löschen und neu indexieren. Passiert typischerweise bei Wechsel von `nomic-embed-text` (768) zu `voyage-3` (1024).
ds_ids in Qdrant stimmen nicht mit DB überein	Race Condition, manueller DB-Eingriff, Crash während Löschen	Integritätsprüfung → »ds_ids synchronisieren«. Schreibt alle ds_ids-Payload-Felder aus `chunk_datasources` neu.