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). Ergaenzend gibt es im System-Tab die Integritaetspruefung, die alle Datenschichten auf Konsistenz prueft.

Sub-Tab: Konnektor

Qdrant-Verbindungseinstellungen. Aenderungen 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 fuer authentifizierte Qdrant-Instanzen.	Nur noetig 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 grossen Batch-Operationen (Embedding-Upload). Erfordert Port 6334 (gRPC) statt 6333 (HTTP). Fuer lokale Setups ist HTTP ausreichend.
`vector_size`	Zahl	`768`	Vektordimension. Wird normalerweise automatisch vom Embedding-Modell bestimmt.	Nicht manuell aendern, 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	Prueft Erreichbarkeit des Qdrant-Servers und zeigt die Anzahl vorhandener Collections.
Speichern	Speichert die Verbindungseinstellungen in der Config.
Zuruecksetzen	Verwirft ungespeicherte Aenderungen und laedt die aktuellen Werte.

Tipp: Nach Aenderung der qdrant_url immer zuerst »Verbindung testen« klicken, bevor gespeichert wird. Ein falscher Wert fuehrt dazu, dass keine Suchergebnisse mehr geliefert werden.

Sub-Tab: DB-Management

Zeigt den Inhalt der VektorDB auf Dateiebene und ermoeglicht das gezielte Loeschen einzelner Dateien aus dem Index.

Datenquellen-Matrix

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

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

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

Datei-Details & Loeschen

Nach Klick auf eine Zelle in der Matrix oeffnet sich die Datei-Detailansicht fuer die gewaehlte Datenquelle + Modell-Kombination.

Toolbar

Element	Beschreibung
Suchfeld	Filtert Dateien nach Name/Pfad (live, case-insensitiv).
Alle auswaehlen	Toggle: markiert/entmarkiert alle sichtbaren Dateien.
Ausgewaehlte loeschen (N)	Loescht die markierten Dateien aus Qdrant. Bestaetigung erforderlich.
Schliessen	Schliesst die Datei-Detailansicht.

Datei-Tabelle

Spalte	Beschreibung	Sortierbar
Checkbox	Auswahl fuer Batch-Loeschen.	Nein
Dateipfad	Voller Pfad — Verzeichnis in grau, Dateiname normal.	Ja
Typ	Dateiendung (`.pdf`, `.docx`, ...).	Ja
Chunks	Anzahl der Chunks dieser Datei im Index.	Ja
Geaendert	Aenderungszeitpunkt der Quelldatei (aus dem Payload).	Ja

Loeschen — Was passiert

Beim Loeschen von Dateien aus der VektorDB:

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

Tipp: Das Loeschen einzelner Dateien ist nuetzlich, wenn eine Datei fehlerhaft indexiert wurde (z.B. durch DDU-Fehler oder falsche Chunk-Strategie). Beim naechsten 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 unterstuetzt 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)	modellabhaengig	unbegrenzt (Streaming)	Laeuft lokal auf der GPU. Kein API-Key noetig. `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. Hoehere Qualitaet, 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-Qualitaet.

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 geloescht werden.

Payload-Schema

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

Feld	Typ	Index	Beschreibung
`source`	String	KEYWORD	Absoluter Pfad der Quelldatei.
`source_key`	String	KEYWORD	Identisch zu `source`. Dedizierter Index fuer 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. Ermoeglicht datenquellenspezifische Suche und Berechtigungspruefung.
`modified`	Datetime	DATETIME	Aenderungszeitpunkt der Quelldatei.
`_text`	String	(kein Index)	Voller Textinhalt des Chunks. Wird bei der Antwortgenerierung als Kontext verwendet.

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

Integritaetspruefung

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

Pruefungen

Check	Beschreibung	Moegliche Befunde
Layer-Counts	Vergleicht die Chunk-Zaehler aller Schichten: Qdrant-Punkte, Elasticsearch-Dokumente, `chunk_datasources`-Eintraege und `datasource_embeddings`-Summe.	Abweichungen deuten auf nicht synchronisierte Schichten hin (z.B. nach einem Crash waehrend der Indexierung).
DS-Coverage	Prueft fuer jede Datenquelle, ob die Chunk-Zaehler in `chunk_datasources`, `datasource_embeddings` und `file_hashes` konsistent sind.	Warnungen pro Datenquelle, wenn Zaehler auseinanderlaufen.
ES-Duplikate	Sucht nach Quellen mit ungewoehnlich vielen Elasticsearch-Eintraegen (Schwelle: >5000 Eintraege pro Quelle).	Hinweis auf doppelte Indexierung oder fehlende Bereinigung nach Loeschen.
Orphan-Chunks	Stichproben-Scan: Prueft zufaellige Chunks in Qdrant, ob sie eine Zuordnung in `chunk_datasources` haben.	Verwaiste Chunks (Orphans) haben keinen Besitzer — sie belegen Speicher und liefern moeglicherweise 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 noetig.
Degraded	Warnungen vorhanden, aber kein Datenverlust. Reparatur empfohlen.
Critical	Schwerwiegende Inkonsistenzen. Reparatur erforderlich.

Tipp: Fuer einen schnellen Ueberblick gibt es den Schnell-Check, der nur die Layer-Counts vergleicht (wenige Sekunden). Die Vollpruefung laeuft im Hintergrund und kann bei grossen Datenbestaenden einige Minuten dauern.

Reparatur-Aktionen

Reparatur-Aktionen werden nur angeboten, wenn die Pruefung Probleme erkennt. Alle erfordern eine Bestaetigung.

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 uebereinstimmen (z.B. nach manuellem DB-Eingriff).
Statistiken korrigieren	Zaehlt die tatsaechlichen Chunks pro Datenquelle in `chunk_datasources` und aktualisiert `datasource_embeddings.chunk_count`.	Wenn die Chunk-Zaehler in der Matrix nicht mit der Realitaet uebereinstimmen.
Verwaiste Chunks loeschen	Scannt ALLE Chunks in Qdrant und loescht diejenigen ohne Zuordnung in `chunk_datasources`.	Bei Orphan-Befund. Destruktiv — nur ausfuehren, wenn die Vollpruefung Orphans bestaetigt hat.

Achtung: »Verwaiste Chunks loeschen« scannt den gesamten Qdrant-Bestand. Bei grossen Collections (>100.000 Punkte) kann das mehrere Minuten dauern. Die Aktion ist nicht umkehrbar — geloeschte Chunks muessen bei Bedarf neu indexiert werden.

Die 4 Datenschichten

KIara speichert Indexdaten in 4 voneinander abhaengigen Schichten. Beim Loeschen einer Datenquelle muessen alle 4 Schichten bereinigt werden, damit keine verwaisten Daten zurueckbleiben.

#	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	SQLite (`/var/lib/kiara/chromadb/file_hashes.db`)	Hash-Tabelle fuer inkrementelle Indexierung (Pfad + Groesse + mtime).
4	chunk_datasources	PostgreSQL	Zuordnung: welcher Chunk gehoert zu welcher Datenquelle.

Tipp: Wenn eine Datenquelle ueber die Admin-UI geloescht wird, bereinigt KIara automatisch alle 4 Schichten (DS-spezifisches Loeschen via Scroll+Bulk in Qdrant, Cascade in PostgreSQL, Hash-Bereinigung). Manuelles Eingreifen in einzelne Schichten (z.B. direktes Loeschen in Qdrant) fuehrt zu Inkonsistenzen, die die Integritaetspruefung erkennt.

API-Endpunkte

Die vollstaendige API-Referenz wird dynamisch aus der Admin-Registry generiert:

VektorDB-API — Dateiliste, Datei-Loeschung, Verbindungstest
Integrity-API — Vollpruefung, Schnell-Check, Reparatur-Aktionen

Troubleshooting

Problem	Moegliche Ursache	Loesung
Verbindungstest schlaegt fehl	Qdrant-Container nicht gestartet, falscher Port, Firewall	`docker ps \| grep qdrant` pruefen. `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 loeschen: `curl -X DELETE http://localhost:6333/collections/kb_altes_modell`. Dann alle Datenquellen voll-indexieren.
Chunk-Zaehler in Matrix stimmen nicht	Statistiken nach Crash nicht aktualisiert	Integritaetspruefung → »Statistiken korrigieren« ausfuehren.
Suchergebnisse enthalten geloeschte Dateien	Chunks in Qdrant nicht bereinigt (z.B. nach manuellem DB-Loeschen)	Integritaetspruefung → »Verwaiste Chunks loeschen«. Alternativ: Datenquelle voll-indexieren.
Qdrant Speicherverbrauch steigt	Alte Collections nach Modellwechsel, verwaiste Chunks	Nicht mehr benoetigte Collections loeschen. Integritaetspruefung auf Orphans pruefen. Qdrant-Dashboard: `http://localhost:6333/dashboard`.
»Dimension mismatch« bei Indexierung	Collection existiert mit alter Dimension, neues Modell hat andere	Collection loeschen und neu indexieren. Passiert typischerweise bei Wechsel von `nomic-embed-text` (768) zu `voyage-3` (1024).
ds_ids in Qdrant stimmen nicht mit DB ueberein	Race Condition, manueller DB-Eingriff, Crash waehrend Loeschen	Integritaetspruefung → »ds_ids synchronisieren«. Schreibt alle ds_ids-Payload-Felder aus `chunk_datasources` neu.