Such-Pipeline

Das KnowledgeSDK unterstuetzt zwei Such-Modi: reine BM25-Volltextsuche und Hybrid-Suche mit Vektor-Embeddings. Diese Seite beschreibt die einzelnen Stufen der Such-Pipeline.

Uebersicht

BM25 Volltextsuche (FTS5)

Die Basis-Suche nutzt SQLites FTS5-Extension mit dem BM25-Ranking-Algorithmus. Dieser bewertet Dokumente nach Termhaeufigkeit und inverser Dokumenthaeufigkeit.

Vorteile:

• Keine externen Services oder API-Keys erforderlich
• Sehr schnelle Antwortzeiten (< 10 ms fuer typische Abfragen)
• Funktioniert vollstaendig offline

So funktioniert es:

1. Der Indexer zerlegt jedes Dokument in Tokens und speichert sie im FTS5-Index
2. Bei einer Suchanfrage wird der Query-String tokenisiert und gegen den Index gematcht
3. BM25 berechnet fuer jeden Treffer einen Relevanz-Score
4. Ergebnisse werden nach Score sortiert zurueckgegeben

// BM25-Only Suche (Standard)
const store = await createSearchStore({
  dbPath: './data/index.sqlite',
  searchMode: 'fts',
});
 
const result = await store.search('deployment kubernetes');

Hybrid-Suche

Die Hybrid-Suche kombiniert BM25 mit Vektor-Embeddings fuer deutlich bessere Ergebnisqualitaet, insbesondere bei semantischen Anfragen.

Query Expansion

Vor der eigentlichen Suche generiert der Embedding-Provider zusaetzliche Suchvarianten. Der konfigurierte domainContext hilft dem LLM, fachspezifische Synonyme und verwandte Begriffe zu finden.

Beispiel: Die Anfrage "Prozess starten" wird erweitert zu:

• "Prozess starten"
• "process instance create"
• "BPMN workflow ausfuehren"
• "Engine start process"

Diese Varianten verbessern sowohl die BM25- als auch die Vektor-Suche.

Vektor-Suche (Cosine Similarity)

Jedes Dokument wird beim Indexieren in einen hochdimensionalen Vektor umgewandelt (Embedding). Bei der Suche wird der Query-String ebenfalls in einen Vektor umgewandelt und mit allen Dokument-Vektoren verglichen.

Die Vektor-Suche findet auch Dokumente, die semantisch relevant sind, aber den exakten Suchbegriff nicht enthalten.

RRF Fusion (Reciprocal Rank Fusion)

BM25 und Vektor-Suche liefern jeweils eine eigene Rangliste. RRF kombiniert diese zu einer einzigen Ergebnisliste.

Algorithmus:

Fuer jedes Dokument wird ein kombinierter Score berechnet:

RRF-Score = 1 / (k + rank_bm25) + 1 / (k + rank_vektor)

Dabei ist k eine Konstante (typisch: 60), die verhindert, dass Top-Ergebnisse uebermaessig bevorzugt werden. Dokumente, die in beiden Listen weit oben stehen, erhalten den hoechsten kombinierten Score.

Vorteile von RRF:

• Robust gegenueber unterschiedlichen Score-Skalen
• Dokumente muessen nicht in beiden Listen vorkommen
• Keine Normalisierung der Einzel-Scores erforderlich

Reranking

Nach der RRF Fusion werden die Top-Ergebnisse optional durch einen Reranker neu bewertet. Der Reranker analysiert Query und Dokument gemeinsam und liefert praezisere Relevanz-Scores als die Einzel-Methoden.

Konfiguration

Such-Modus

Der Such-Modus wird ueber die searchMode-Option oder die Umgebungsvariable QMD_SEARCH_MODE gesteuert:

Embedding-Provider

Der Provider wird ueber embedProvider oder die Umgebungsvariable QMD_EMBED_PROVIDER konfiguriert:

Vollstaendiges Beispiel

import { createSearchStore } from '@processcube-io/knowledge-sdk';
 
const store = await createSearchStore({
  dbPath: './data/index.sqlite',
  searchMode: 'hybrid',
  embedProvider: {
    provider: 'voyage',
    apiKey: process.env.VOYAGE_API_KEY,
    domainContext: 'eine technische Dokumentation ueber Workflow-Engines und BPMN',
  },
});
 
// Suche mit Collection-Filter
const result = await store.search('Prozess deployen', {
  collection: 'engine',
  limit: 10,
});

Umgebungsvariablen (Docker / CLI)

Fuer Docker-Images und die Single-Binary werden die Optionen ueber Umgebungsvariablen gesetzt:

QMD_SEARCH_MODE=hybrid
QMD_EMBED_PROVIDER=voyage
VOYAGE_API_KEY=pa-...

Vergleich der Modi

Naechste Schritte

• Architektur — Modul-Uebersicht und Datenfluss
• Indexer & Plugins — Content-Sources und Embedding-Konfiguration
• API-Referenz — SearchStore Interface und Types
• Docker — Umgebungsvariablen fuer den Standalone-Betrieb