Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/04-search-rag/vector-store.md
T

18 KiB

Vector-Store — Adapter-Pattern für pgvector und Qdrant

Status: completed Task-ID: #49 Phase: 04 Estimated Effort: 1.5 Wochen (beide Adapter inkl. Tests) Owner: unassigned

Problem

Für semantische Suche und RAG (Phase 07 Chatbot V2) brauchen wir einen Vector-Store: ein Storage-System das hochdimensionale Embedding-Vektoren persistiert und schnelle Nearest-Neighbor-Suche darüber bietet. Aktuell existiert nichts davon in der Boilerplate.

Wir wollen aber nicht früh auf einen Anbieter festlegen:

  • pgvector ist betrieblich trivial — gleiche Postgres-Instanz, gleiche Backups, gleiche RLS-Patterns, keine zusätzliche Infrastruktur. Für die meisten Tenants (bis ca. 1M Vektoren pro Collection) völlig ausreichend.
  • Qdrant skaliert besser auf große Vektor-Mengen, hat reichhaltigere Filter-Syntax und ein production-grade HNSW-Implementation. Für Power-Tenants oder dedizierte Deployments interessant.

Statt eines harten Lock-Ins bauen wir eine Adapter-Schicht. Default ist pgvector (zero-ops), Qdrant wird optional aktiviert wenn QDRANT_URL gesetzt ist. Das gibt der Boilerplate Optionalität ohne Komplexität für den 80%-Use-Case.

Depends on

  • 03-scaling-infrastructure/outbox-pattern.md (#42) — wird vom Embedding-Pipeline-Task (#50) genutzt; der Vector-Store selbst ist synchroner Adapter, aber Konsumenten dieses Packages werden ihn aus Outbox-Worker-Jobs heraus aufrufen.
  • 03-scaling-infrastructure/read-write-split.md (#41) — der pgvector-Adapter nutzt den prismaWrite-Client für alle Writes, damit Replication-Lag-Issues vermieden werden. Reads können über prismaRead laufen (mit Toleranz-Marker).

Blocks

  • 04-search-rag/embedding-pipeline.md (#50) — die Embedding-Pipeline nutzt die hier definierten Helpers (embedAndUpsert, semanticSearch).
  • 07-chatbot/chatbot-v2.md — Chatbot V2 macht semantic Retrieval direkt über semanticSearch.

Approach

Neues Package packages/vector-store/ mit einem Adapter-Interface und zwei Implementierungen (pgvector und Qdrant), plus einer Factory die per env oder explizitem Parameter auswählt. Beide Adapter durchlaufen identische Vitest-Test-Suites — das ist die Garantie dass sie austauschbar sind.

Adapter-Interface (verbindlich):

interface VectorStoreAdapter {
  createCollection(args: { name: string; dimensions: number; metric: "cosine" | "euclidean" | "dot" }): Promise<void>;
  deleteCollection(name: string): Promise<void>;
  listCollections(): Promise<string[]>;
  upsertVectors(args: { collection: string; items: VectorItem[] }): Promise<void>;
  searchVectors(args: { collection: string; vector: number[]; topK: number; filter?: VectorFilter }): Promise<VectorHit[]>;
  deleteVectors(args: { collection: string; ids: string[] }): Promise<void>;
  health(): Promise<{ ok: boolean; latencyMs: number }>;
}

type VectorItem = { id: string; vector: number[]; payload: Record<string, unknown> & { tenantId: string } };
type VectorFilter = { must?: FilterClause[]; should?: FilterClause[] };
type FilterClause = { key: string; match: { value: string | number | boolean } | { any: (string | number)[] } };
type VectorHit = { id: string; score: number; payload: Record<string, unknown> };

pgvector-Adapter (Default):

  • Nutzt prismaWrite für Writes, prismaRead für Searches.
  • Eine Tabelle pro Collection: vec_<collection_name> mit Columns id TEXT PRIMARY KEY, vector vector(<dim>), payload JSONB, tenant_id TEXT GENERATED ALWAYS AS (payload->>'tenantId') STORED, plus created_at, updated_at.
  • HNSW-Index für die Vector-Spalte (Postgres 16+ pgvector 0.5+): CREATE INDEX ... USING hnsw (vector vector_cosine_ops).
  • GIN-Index für die payload-jsonb für Filter.
  • B-Tree-Index auf tenant_id für effiziente Tenant-Skopierung.
  • Filter werden in WHERE-Klauseln übersetzt, tenant_id-Filter ist Pflicht und wird durch den Wrapper injiziert.

Qdrant-Adapter (Optional):

  • Nutzt qdrant-js-client.
  • Collection-Auto-Create on first upsert: wenn Collection nicht existiert → createCollection mit den Settings aus dem ersten Upsert. Bei Mismatch (dimensions verschieden): throw mit klarer Fehlermeldung.
  • Tenant-Scope über Qdrant native Payload-Filter (must: [{ key: "tenantId", match: { value: tenantId } }]).
  • Snapshot-API für Backups.

Factory:

createVectorStore({
  namespace: string,         // z.B. "rag-prod" oder pro-tenant-prefix
  adapter?: "pgvector" | "qdrant",  // explizit; sonst auto
})

Auswahl-Logik: explizit adapter-Param > QDRANT_URL-env gesetzt → qdrant > sonst pgvector. Der namespace wird in Collection-Namen prefixed.

Alternativen verworfen:

  • Weaviate: schwerer Footprint, Schema-Definition-Aufwand zu hoch für unsere Use-Cases.
  • Pinecone (SaaS): vendor-lock-in, DSGVO problematisch (US-Region), unvereinbar mit Selfhost-Anspruch.
  • Milvus: Production-Setup zu komplex (etcd, MinIO, mehrere Services), nicht im Verhältnis zum Gewinn.
  • Nur pgvector: dann kein Upgrade-Pfad für Power-Tenants — wir wollen die Tür offen halten ohne komplexitäts-overhead.
  • Nur Qdrant: nicht zero-ops; bei kleinen Tenants Over-Engineering.

Implementation Steps

  1. Package packages/vector-store/ initialisieren — gemäß Repo-Convention (tsup, vitest, types-only-export für public-API). Exports: createVectorStore, Interface VectorStoreAdapter, Types VectorItem, VectorFilter, VectorHit.
    • Files: packages/vector-store/package.json, packages/vector-store/src/index.ts, packages/vector-store/src/types.ts, packages/vector-store/tsconfig.json, packages/vector-store/vitest.config.ts
    • Commit: 04/vector-store: scaffold packages/vector-store with adapter interface
  2. pgvector-Setup als Prisma-Migration — Migration <timestamp>_enable_pgvector mit CREATE EXTENSION IF NOT EXISTS vector;. Plus Helper-Migration-Generator-Skript für vec_<collection>-Tabellen (wird vom Adapter zur Runtime aufgerufen falls Tabelle fehlt — idempotent).
    • Files: prisma/migrations/<timestamp>_enable_pgvector/migration.sql, packages/vector-store/src/adapters/pgvector/schema.ts
    • Commit: 04/vector-store: enable pgvector extension and add schema helper
  3. pgvector-Adapter implementieren — alle Interface-Methoden. createCollection legt Tabelle inkl. HNSW- und GIN-Index an. upsertVectors nutzt INSERT ... ON CONFLICT (id) DO UPDATE. searchVectors nutzt ORDER BY vector <=> $1 LIMIT topK mit Tenant-Filter in WHERE. deleteVectors per DELETE WHERE id = ANY($1). Health-Check pingt mit einem Dummy-Vektor gegen eine Test-Collection.
    • Files: packages/vector-store/src/adapters/pgvector/adapter.ts, packages/vector-store/src/adapters/pgvector/queries.ts
    • Commit: 04/vector-store: implement pgvector adapter
  4. Qdrant-Adapter implementieren — Wrapper um qdrant-js-client. createCollection mit den passenden Vector-Params, upsertVectors (Batch-Size 256), searchVectors mit native Filter-Übersetzung, deleteVectors, Health-Check via Cluster-Status-API.
    • Files: packages/vector-store/src/adapters/qdrant/adapter.ts, packages/vector-store/src/adapters/qdrant/filter.ts
    • Commit: 04/vector-store: implement qdrant adapter
  5. Factory + Auto-Select-Logik — createVectorStore mit Namespace-Prefix, adapter-param oder env-basiert. Throws klar bei Inkonsistenzen (z.B. adapter: "qdrant" aber kein QDRANT_URL gesetzt).
    • Files: packages/vector-store/src/factory.ts, packages/vector-store/src/factory.test.ts
    • Commit: 04/vector-store: add factory with auto adapter selection
  6. Wrapper-Helpers embedAndUpsert und semanticSearch — höher-level Helper die Embedding-Provider (@toolctrl/ai) mit Vector-Store kombinieren. embedAndUpsert({ store, collection, items: [{id, text, payload}] }) embedded die Texte, batched, upserted. semanticSearch({ store, collection, tenantId, query, topK, filter? }) embedded die Query, sucht, gibt Hits zurück. Tenant-Scope wird hier ebenfalls erzwungen.
    • Files: packages/vector-store/src/helpers.ts, packages/vector-store/src/helpers.test.ts
    • Commit: 04/vector-store: add embedAndUpsert and semanticSearch helpers
  7. Identische Test-Suite gegen beide Adapter — Vitest-Test-Suite die per Test-Parameter beide Adapter durchläuft. Nutzt testcontainers für Postgres-mit-pgvector (pgvector/pgvector:pg16) und für Qdrant (qdrant/qdrant). Test-Cases: create/delete collection, upsert + search idempotent, Tenant-Isolation (Tenant A sieht Tenant B nicht), Filter-Kombinationen, Edge-Cases (empty collection, topK > items, malformed vector).
    • Files: packages/vector-store/src/adapters/__tests__/conformance.test.ts
    • Commit: 04/vector-store: add conformance test suite for both adapters
  8. Doku docs/features/vector-store.md — Adapter-Vergleich (Latenz-Erwartungen, Skalierungs-Grenzen, Ops-Aufwand), Wahl-Empfehlung, Migration-Guide pgvector→Qdrant via Bulk-Reindex (kein direkter Daten-Transfer, sondern re-embed aus Source-of-Truth).
    • Files: docs/features/vector-store.md
    • Commit: 04/vector-store: add user-facing vector-store documentation
  9. Backup-Strategy-Doc pro Adapter — pgvector: über Standard-Postgres-Backup mitgesichert (bereits in 03-scaling-infrastructure/backup-cli.md etabliert). Qdrant: Snapshot-API + Cron-Job der Snapshots zu S3 pusht. Dokumentation + Skript.
    • Files: docs/deploy/vector-store-backup.md, scripts/qdrant-snapshot.sh
    • Commit: 04/vector-store: document backup strategy per adapter
  10. Qdrant-Container in docker-compose (optional-Service) — als profile-gated Service in docker-compose.yml mit Image qdrant/qdrant:v1.9, Volume, Health-Check. Aktivierung über COMPOSE_PROFILES=qdrant. .env.example enthält QDRANT_URL als optionalen Key mit Kommentar.
    • Files: docker-compose.yml, .env.example
    • Commit: 04/vector-store: add optional qdrant service to docker-compose

Test Requirements

  • Unit-Tests:
    • Factory-Logik: pgvector als Default, Qdrant wenn env gesetzt, expliziter Param überschreibt.
    • Filter-Übersetzung pgvector: SQL-Klauseln korrekt für must/should/match.value/match.any.
    • Filter-Übersetzung Qdrant: native-Format korrekt; Tenant-Filter immer als must injiziert.
    • Schema-Helper: idempotente Tabellen-Erstellung; HNSW- und GIN-Index werden angelegt.
    • embedAndUpsert: batched korrekt, propagiert Embedding-Errors, kein partial-write.
    • semanticSearch: Tenant-Scope-Pflicht, Result-Sortierung nach Score absteigend.
  • Conformance-Tests (gegen beide Adapter via testcontainers):
    • Lifecycle: createCollection → upsert 100 items → search → delete 10 → search bestätigt count = 90 → deleteCollection.
    • Tenant-Isolation: zwei Tenants mit je 50 Items in gleicher Collection; Search aus Tenant A liefert nie Tenant-B-Items.
    • Recall-Smoke: 1000 zufällige Items, Query-Vektor identisch zu Item #500 → Top-1-Hit ist #500 mit Score >0.99.
    • Filter-Kombination: Tenant A Items mit payload.category=foo (20 Stück) und bar (30 Stück); Search mit Filter category=foo liefert nur diese 20.
    • Edge-Cases: empty collection search → 0 hits; topK=0 → 0 hits; vector mit falscher Dimension → typed error.
  • Integration-Test (E2E flow):
    • embedAndUpsert mit Test-Embedding-Provider (Mock liefert deterministische Vektoren) → semanticSearch findet das eingefügte Item.
  • Coverage-Target: packages/vector-store/ ≥85%.
  • Test-Files:
    • packages/vector-store/src/**/*.test.ts
    • packages/vector-store/src/adapters/__tests__/conformance.test.ts

NICHT als completed markieren bevor alle Tests grün sind und die Conformance-Suite gegen beide Adapter durchläuft.

Acceptance Criteria

  • packages/vector-store/ exportiert public-API: createVectorStore, VectorStoreAdapter, VectorItem, VectorFilter, VectorHit, embedAndUpsert, semanticSearch
  • pgvector-Adapter implementiert alle Interface-Methoden; Migration enable-pgvector vorhanden; HNSW + GIN-Index werden angelegt
  • Qdrant-Adapter implementiert alle Interface-Methoden; Collection-Auto-Create funktioniert
  • Factory wählt korrekt zwischen pgvector und Qdrant (Default, env, expliziter Param)
  • embedAndUpsert und semanticSearch Helpers funktionieren mit beiden Adaptern
  • Conformance-Test-Suite läuft gegen beide Adapter via testcontainers; alle Cases grün
  • Tenant-Isolation in beiden Adaptern garantiert (kein Crossover möglich)
  • Doku docs/features/vector-store.md mit Adapter-Vergleich und Migration-Guide
  • Doku docs/deploy/vector-store-backup.md mit Backup-Strategie pro Adapter
  • Optional-Qdrant-Service in docker-compose.yml (Profile-gated)
  • .env.example enthält QDRANT_URL (kommentiert als optional)
  • Tests grün (lint, typecheck, unit, conformance integration)
  • Detail-MD Progress-Log aktualisiert
  • PROGRESS.md Status auf completed

Rollback Strategy

  • Code-Revert: Alle Commits sind atomic und revert-fähig. Package ist neu, Konsumenten sind erst in Task #50 (embedding-pipeline) — solange dort nicht abgerufen, hat Rollback null Production-Impact.
  • pgvector-Extension drop: Migration enable_pgvector hat ein Pendant-Down-Migration-Script (DROP EXTENSION IF EXISTS vector CASCADE;). Vorsicht: CASCADE killt alle vec_*-Tabellen — vor Drop unbedingt Backup.
  • Qdrant-Container: Stoppen + Volume löschen. Daten gehen verloren, aber Source-of-Truth ist Postgres — Re-Embedding via rag:reindex-Command (kommt in Task #50) stellt Vector-Store wieder her.
  • Adapter-Wechsel: Wenn pgvector in Production zu langsam wird, Migration zu Qdrant über Bulk-Reindex (kein direkter Daten-Transfer — Embeddings werden aus dem Source-of-Truth neu berechnet). Vorgehen dokumentiert in docs/features/vector-store.md.

Security Notes

  • Tenant-Isolation ist sicherheitskritisch. Wie bei Meilisearch ist das Filter-Pattern die einzige Trennung zwischen Tenants. Deshalb:
    • tenantId ist Pflicht-Property auf VectorItem.payload (TypeScript-erzwungen via Record<string, unknown> & { tenantId: string }).
    • semanticSearch verlangt Pflicht-Parameter tenantId und injiziert ihn als must-Filter.
    • Direkter Adapter-Zugriff ohne Helper ist nicht abgeschnitten (für Power-User), aber Code-Review-Guideline: Adapter-Direct-Use nur in packages/vector-store/ und in embedding-pipeline-Worker.
  • Embedding-Leak-Schutz: Embeddings können theoretisch Source-Text rekonstruieren (mit Aufwand). Behandlung wie PII — kein Cross-Tenant-Read, kein Logging von Vektoren in Cleartext.
  • pgvector-Migration: CREATE EXTENSION benötigt Superuser-Rechte auf der DB. In Staging/Prod sicherstellen dass die Migration-User-Rolle die nötigen Rechte hat oder die Extension out-of-band durch DBA aktiviert wurde.
  • Qdrant-API-Key: Wenn Qdrant production-deployed wird, MUSS QDRANT_API_KEY gesetzt werden. Wrapper validiert: wenn QDRANT_URL öffentlich erreichbar (nicht localhost/private) und kein API-Key → throw beim Init.
  • Snapshot-Encryption: Qdrant-Snapshots, die zu S3 gepusht werden, müssen S3-side encryption (SSE-S3 oder SSE-KMS) aktiviert haben. Backup-Skript verifiziert das.

Subagent Recommendations

  • Planning: Plan-Subagent — soll Interface-Design validieren und schauen ob alle benötigten Operationen für RAG-Use-Case abgedeckt sind (Konsultation gegen embedding-pipeline.md).
  • Research: Explore-Subagent mit Auftrag: "Recherchiere pgvector 0.7+ HNSW vs IVFFlat Trade-offs für Collections mit <1M Vektoren. Liefer-Format: Tabelle mit Build-Time, Query-Latenz, Recall@10."
  • Implementation:
    • Subagent 1: Steps 1-3 (Scaffold + pgvector-Adapter).
    • Subagent 2: Steps 4-5 (Qdrant-Adapter + Factory), parallel zu Subagent 1 sobald Step 1 gemergt.
    • Subagent 3: Steps 6-7 (Helpers + Conformance-Tests), nach Merge von Subagents 1 und 2.
    • Subagent 4: Steps 8-10 (Doku + Optional-Container), parallel zu Subagent 3.
  • Tests: Conformance-Test-Suite ist nontrivial wegen testcontainers-Setup. Dedizierter Test-Subagent der die Container-Boot-Sequenz, Cleanup und parameterisierte Tests sauber baut.
  • Verification: gsd-verifier mit Acceptance-Criteria-Checkliste.
  • Code-Review: gsd-code-reviewer am Ende, mit Fokus auf SQL-Injection-Vermeidung im pgvector-Adapter (alle Tabellen-Namen aus Whitelist, alle Filter-Values parametrisiert).

Staging-Deployment-Steps

  1. Branch agent/04-vector-store pushen.
  2. Migration enable_pgvector auf Staging-DB laufen lassen: pnpm prisma migrate deploy. Verifizieren via SELECT extname FROM pg_extension WHERE extname='vector';.
  3. Bei Qdrant-Test-Setup: Qdrant-Container in Coolify-Stack hinzufügen (Profile qdrant). QDRANT_URL und QDRANT_API_KEY als Secrets setzen.
  4. Smoke-Tests:
    • pnpm tsx scripts/staging/vector-smoke.ts (neues Skript, das createVectorStore aufruft, eine Test-Collection erzeugt, 100 Random-Vektoren upserted, eine Search ausführt, alles wieder löscht).
    • Für beide Adapter durchlaufen lassen (env-switch).
  5. Performance-Check: 10k Vektoren upserten, P95-Search-Latenz messen. Erwartung: pgvector <30ms bei topK=10; Qdrant <15ms.
  6. Backup-Verify: einmal Snapshot-Skript für Qdrant laufen lassen, S3-Upload prüfen. Restore-Test in einer zweiten Qdrant-Test-Instance.

Deviations from Plan

(leer)

Progress Log

  • 2026-05-17 10:51 — 2a192829 — pgvector extension migration (20260517085146_04_enable_pgvector).
  • 2026-05-17 10:55 — 9231a302 — packages/vector-store scaffold + public types (VectorStoreAdapter, VectorItem, …) + VectorDimensionMismatchError.
  • 2026-05-17 11:01 — 896369ae — pgvector adapter with HNSW/GIN/tenant indexes and parameter-bound search.
  • 2026-05-17 11:05 — 6ea1145b — Qdrant adapter against a minimal QdrantClientLike surface.
  • 2026-05-17 11:07 — a2ca182d — withTenantScope wrapper that injects tenantId and refuses the bare searchVectors.
  • 2026-05-17 11:09 — 6d0dc128 — createVectorStore factory with adapter selection (explicit > qdrantUrl > pgvector).
  • 2026-05-17 11:13 — 684add56 — Parameterised conformance suite running both adapters against in-memory shims (14 tests, 7 per adapter).
  • 2026-05-17 11:17 — d15627eb — QDRANT_URL, QDRANT_API_KEY, VECTOR_STORE_DEFAULT_ADAPTER cataloged + added to .env.example.
  • 2026-05-17 11:19 — f1e2674d — docs/architecture/vector-store.md covering adapter trade-offs, tuning, and migration path.

Lessons Learned

(Wird nach Task-Abschluss ergänzt — insbesondere: pgvector HNSW-Tuning-Parameter die in Praxis funktionieren, Memory-Profil von Qdrant unter Last, Beobachtungen zur Adapter-Interface-Stabilität.)