themis docs features features_vector_ops

Vector Operations

Dieses Dokument beschreibt die Vektor-Indexierungs- und Suchoperationen in Themis.

Übersicht

Der VectorIndexManager unterstützt:

• Batch-Einfügung (POST /vector/batch_insert) für performante Massenimporte
• Gezielte Löschung (DELETE /vector/by-filter) via PK-Liste oder Key-Präfix
• KNN-Suche (POST /vector/search) mit optionaler Cursor-Pagination
• Persistenz (POST /vector/index/save, POST /vector/index/load) für HNSW-Index
• Konfiguration (GET/PUT /vector/index/config) zur Laufzeit (z. B. efSearch)
• Statistiken (GET /vector/index/stats) für Index-Kennzahlen

Distanzmetriken

Themis unterstützt drei Distanzmetriken für Vektorsuche:

• L2 (Euklidische Distanz): $d(a,b) = \sqrt{\sum_i (a_i - b_i)^2}$

  • Verwendet für: Absolute Distanzen im Vektorraum
  • "Lower is better" Semantik

• COSINE (Kosinus-Ähnlichkeit): $d(a,b) = 1 - \frac{a \cdot b}{||a|| \cdot ||b||}$

  • Vektoren werden automatisch normalisiert (L2-Norm)
  • Verwendet für: Richtungsähnlichkeit (z. B. Textembeddings)
  • "Lower is better" Semantik (1 - Kosinus-Ähnlichkeit)

• DOT (Skalarprodukt): $d(a,b) = -a \cdot b$

  • Keine Normalisierung (Rohwerte werden verwendet)
  • Negiert für "lower is better" Semantik (HNSW verwendet Distanzen)
  • Verwendet für: Maximum Inner Product Search (MIPS), Pre-normalisierte Embeddings
  • Hinweis: Bei DOT wird kein Normalisierungsschritt angewendet. Wenn normalisierte Suche gewünscht ist, verwenden Sie COSINE.

Metrik-Auswahl: Konfiguriert in /vector/index/config via metric-Feld:

{
  "metric": "DOT",  // oder "L2", "COSINE"
  "dimension": 768,
  "efSearch": 64
}

Batch Insert

Endpoint

POST /vector/batch_insert

Anfrage

{
  "vector_field": "embedding",  // Standard: "embedding"
  "items": [
    {
      "pk": "doc1",
      "vector": [0.1, 0.2, 0.3],
      "fields": {
        "title": "Beispiel",
        "category": "test"
      }
    },
    {
      "pk": "doc2",
      "vector": [0.4, 0.5, 0.6],
      "fields": {
        "title": "Another",
        "category": "demo"
      }
    }
  ]
}

Antwort

{
  "inserted": 2,
  "errors": 0,
  "objectName": "vectors",
  "dimension": 3
}

Best Practices

• Batch-Größe: 100–1000 Einträge pro Request für optimales Latenz/Durchsatz-Verhältnis
• Auto-Init: Wenn dimension = 0, wird der Index automatisch mit der Dimension des ersten Vektors initialisiert
• Fehlerbehandlung: Einzelne fehlerhafte Items werden übersprungen; errors-Feld zählt Ausnahmen
• Transaktionssicherheit: Jedes Item wird atomar geschrieben (RocksDB WriteBatch)

Delete by Filter

Endpoint

DELETE /vector/by-filter

Anfrage (PK-Liste)

{
  "pks": ["doc1", "doc2", "doc3"]
}

Anfrage (Präfix-Filter)

{
  "prefix": "temp-"
}

Antwort

{
  "deleted": 3,
  "method": "pks"  // oder "prefix"
}

Anwendungsfälle

• Cleanup: Löschen temporärer oder veralteter Vektoren via Präfix (z. B. tmp-, staging-)
• Bulk-Removal: Liste spezifischer Dokument-IDs nach Qualitätskontrolle
• Namensraum-Bereinigung: Entfernen aller Einträge eines bestimmten Namensraums

KNN-Suche mit Cursor-Pagination

Endpoint

POST /vector/search

Anfrage (Legacy-Modus)

{
  "vector": [0.1, 0.2, 0.3],
  "k": 10
}

Antwort (Legacy)

{
  "results": [
    {"pk": "doc1", "distance": 0.05},
    {"pk": "doc2", "distance": 0.12}
  ],
  "k": 10,
  "count": 2
}

Anfrage (Cursor-Pagination)

{
  "vector": [0.1, 0.2, 0.3],
  "k": 10,
  "use_cursor": true,
  "cursor": "20"  // optional; Offset der vorherigen Seite
}

Antwort (Cursor-Pagination)

{
  "items": [
    {"pk": "doc21", "distance": 0.08},
    {"pk": "doc22", "distance": 0.09}
  ],
  "batch_size": 2,
  "has_more": true,
  "next_cursor": "30"
}

Best Practices

• Page-Size: k = 10–100 für typische UI-Pagination; k = 100–1000 für Batch-Verarbeitung
• HNSW efSearch: Setze efSearch ≥ k für gute Recall; 64–128 ist ein guter Start
• Distanz-Metrik: COSINE (Standard) für normalisierte Embeddings, L2 für räumliche Daten
• Cursor-Verwendung: Für große Result-Sets (> k) aktiviere use_cursor um Memory-Druck zu reduzieren

Persistenz

Speichern

POST /vector/index/save
{ "directory": "./data/vector_index" }

Speichert:

• meta.txt: objectName, dimension, metric, efSearch, M, efConstruction
• labels.txt: PK-Mapping (id → PK)
• index.bin: HNSW-Struktur (wenn HNSW aktiviert)

Laden

POST /vector/index/load
{ "directory": "./data/vector_index" }

Lädt den Index aus persistierten Dateien; überschreibt aktuelle In-Memory-Struktur.

Auto-Save

Setze auto_save=true und savePath via VectorIndexManager::setAutoSavePath() für automatisches Speichern beim Server-Shutdown.

Konfiguration zur Laufzeit

GET /vector/index/config

{
  "objectName": "vectors",
  "dimension": 768,
  "metric": "COSINE",  // oder "L2", "DOT"
  "efSearch": 64,
  "M": 16,
  "efConstruction": 200,
  "hnswEnabled": true
}

PUT /vector/index/config

{
  "efSearch": 128
}

Hinweis: M und efConstruction erfordern Index-Rebuild und können zur Laufzeit nicht geändert werden.

Statistiken

GET /vector/index/stats

{
  "objectName": "vectors",
  "dimension": 768,
  "metric": "COSINE",  // oder "L2", "DOT"
  "vectorCount": 123456,
  "efSearch": 64,
  "M": 16,
  "efConstruction": 200,
  "hnswEnabled": true
}

Performance-Ziele

Operation	Ziel	Bemerkungen
Batch Insert	< 500 ms / 1000 Items	Mit HNSW M=16, efConstruction=200
KNN Search (k=10)	< 10 ms	efSearch=64, ~100k Vektoren
Delete by PKs (100)	< 50 ms	Markiert als gelöscht in HNSW
Delete by Prefix	< 200 ms / 1000 Items	Scan + Batch-Delete
Index Save	< 2 s / 100k Vectors	Abhängig von IO-Geschwindigkeit
Index Load	< 1 s / 100k Vectors	Memory-Mapping wenn möglich

Metriken (Prometheus)

Die folgenden Metriken sind unter GET /metrics verfügbar:

• vccdb_vector_index_size_bytes: Geschätzte Größe des In-Memory-Index
• vccdb_vector_search_duration_ms: Histogram der Suchlatenz in Millisekunden
• vccdb_vector_batch_insert_duration_ms: Histogram der Batch-Insert-Latenz
• vccdb_vector_batch_insert_total: Counter der gesamten Batch-Insert-Operationen
• vccdb_vector_batch_insert_items_total: Counter aller eingefügten Items
• vccdb_vector_delete_by_filter_total: Counter der Delete-by-Filter-Operationen
• vccdb_vector_delete_by_filter_items_total: Counter aller gelöschten Items

Häufige Fragen (FAQ)

Q: Wie gehe ich mit großen Datenmengen um (> 1 Mio. Vektoren)?

A:

1. Batch-Insert in Blöcken von 500–1000 Items
2. Setze M=32 und efConstruction=400 für bessere Qualität (höhere Build-Zeit)
3. Nutze efSearch=128–200 zur Suche für höhere Recall
4. Aktiviere Auto-Save + regelmäßige Checkpoints
5. Erwäge Sharding (mehrere Indizes) für Skalierung über 10 Mio. Vektoren

Q: Wie optimiere ich die Suche für niedrige Latenz?

A:

1. Reduziere efSearch auf 32–64 (Kompromiss: niedrigere Recall)
2. Setze k so niedrig wie möglich (z. B. k=10 statt k=100)
3. Nutze Cursor-Pagination für große Result-Sets
4. Cache häufige Queries (siehe docs/cdc.md für Semantic Cache)

Q: Kann ich mehrere Vektorindizes parallel betreiben?

A: Im aktuellen MVP unterstützt VectorIndexManager einen Index pro Instanz. Für mehrere Namensräume:

• Option 1: Separater VectorIndexManager pro Namespace (mehrere Server-Instanzen)
• Option 2: Präfix-Trennung im objectName (z. B. docs_en, docs_de)

Q: Was passiert bei Dimensionskonflikten?

A: Wenn ein Vektor mit falscher Dimension eingefügt wird:

• Batch-Insert: Item wird übersprungen, errors-Counter erhöht
• Single-Insert: Fehler wird sofort zurückgegeben
• Search: Anfrage wird abgelehnt mit HTTP 400

Q: Wie werden gelöschte Vektoren behandelt?

A:

• HNSW: markDelete() markiert Vektoren als gelöscht; physisches Entfernen erfordert Rebuild
• Cache: Sofortige Entfernung aus PK-Mapping und Cache
• RocksDB: Löschung via WriteBatch (kompaktiert in nächster Compaction)

Beispiele

1. Massenimport aus CSV

import csv
import requests
import numpy as np

url = "http://localhost:8765/vector/batch_insert"
batch_size = 500

with open("embeddings.csv") as f:
    reader = csv.DictReader(f)
    batch = []
    for row in reader:
        vec = np.fromstring(row["embedding"], sep=",").tolist()
        batch.append({
            "pk": row["id"],
            "vector": vec,
            "fields": {"title": row["title"]}
        })
        if len(batch) >= batch_size:
            resp = requests.post(url, json={"items": batch})
            print(f"Inserted {resp.json()['inserted']}, errors: {resp.json()['errors']}")
            batch = []
    if batch:
        resp = requests.post(url, json={"items": batch})
        print(f"Final batch: {resp.json()['inserted']} inserted")

2. Präfix-basierte Bereinigung

# Alle temporären Vektoren löschen
curl -X DELETE http://localhost:8765/vector/by-filter \
  -H "Content-Type: application/json" \
  -d '{"prefix": "temp-"}'

# Ausgabe: {"deleted": 42, "method": "prefix"}

3. Paginierte Suche

import requests

url = "http://localhost:8765/vector/search"
query_vec = [0.1, 0.2, 0.3]  # Beispiel-Embedding
cursor = None
all_results = []

while True:
    payload = {"vector": query_vec, "k": 20, "use_cursor": True}
    if cursor:
        payload["cursor"] = cursor
    
    resp = requests.post(url, json=payload).json()
    all_results.extend(resp["items"])
    
    if not resp["has_more"]:
        break
    cursor = resp["next_cursor"]

print(f"Total results: {len(all_results)}")

Siehe auch

• AQL Syntax – Hybrid-Queries mit Vektorsuche
• Indexes – Sekundär- und Range-Indizes
• Deployment – Production-Setup und Tuning
• Tracing – Performance-Debugging mit OpenTelemetry