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 denprismaWrite-Client für alle Writes, damit Replication-Lag-Issues vermieden werden. Reads können überprismaReadlaufen (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 übersemanticSearch.
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
prismaWritefür Writes,prismaReadfür Searches. - Eine Tabelle pro Collection:
vec_<collection_name>mit Columnsid TEXT PRIMARY KEY,vector vector(<dim>),payload JSONB,tenant_id TEXT GENERATED ALWAYS AS (payload->>'tenantId') STORED, pluscreated_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_idfü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 →
createCollectionmit 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
- Package
packages/vector-store/initialisieren — gemäß Repo-Convention (tsup, vitest, types-only-export für public-API). Exports:createVectorStore, InterfaceVectorStoreAdapter, TypesVectorItem,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
- Files:
- pgvector-Setup als Prisma-Migration — Migration
<timestamp>_enable_pgvectormitCREATE EXTENSION IF NOT EXISTS vector;. Plus Helper-Migration-Generator-Skript fürvec_<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
- Files:
- pgvector-Adapter implementieren — alle Interface-Methoden.
createCollectionlegt Tabelle inkl. HNSW- und GIN-Index an.upsertVectorsnutztINSERT ... ON CONFLICT (id) DO UPDATE.searchVectorsnutztORDER BY vector <=> $1 LIMIT topKmit Tenant-Filter inWHERE.deleteVectorsperDELETE 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
- Files:
- Qdrant-Adapter implementieren — Wrapper um
qdrant-js-client.createCollectionmit den passenden Vector-Params,upsertVectors(Batch-Size 256),searchVectorsmit 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
- Files:
- Factory + Auto-Select-Logik —
createVectorStoremit Namespace-Prefix, adapter-param oder env-basiert. Throws klar bei Inkonsistenzen (z.B.adapter: "qdrant"aber keinQDRANT_URLgesetzt).- Files:
packages/vector-store/src/factory.ts,packages/vector-store/src/factory.test.ts - Commit:
04/vector-store: add factory with auto adapter selection
- Files:
- Wrapper-Helpers
embedAndUpsertundsemanticSearch— 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
- Files:
- 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
- Files:
- 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
- Files:
- Backup-Strategy-Doc pro Adapter — pgvector: über Standard-Postgres-Backup mitgesichert (bereits in
03-scaling-infrastructure/backup-cli.mdetabliert). 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
- Files:
- Qdrant-Container in docker-compose (optional-Service) — als profile-gated Service in
docker-compose.ymlmit Imageqdrant/qdrant:v1.9, Volume, Health-Check. Aktivierung überCOMPOSE_PROFILES=qdrant..env.exampleenthältQDRANT_URLals optionalen Key mit Kommentar.- Files:
docker-compose.yml,.env.example - Commit:
04/vector-store: add optional qdrant service to docker-compose
- Files:
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
mustinjiziert. - 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) undbar(30 Stück); Search mit Filtercategory=fooliefert nur diese 20. - Edge-Cases: empty collection search → 0 hits; topK=0 → 0 hits; vector mit falscher Dimension → typed error.
- Integration-Test (E2E flow):
embedAndUpsertmit Test-Embedding-Provider (Mock liefert deterministische Vektoren) →semanticSearchfindet das eingefügte Item.
- Coverage-Target:
packages/vector-store/≥85%. - Test-Files:
packages/vector-store/src/**/*.test.tspackages/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)
embedAndUpsertundsemanticSearchHelpers 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.mdmit Adapter-Vergleich und Migration-Guide - Doku
docs/deploy/vector-store-backup.mdmit Backup-Strategie pro Adapter - Optional-Qdrant-Service in
docker-compose.yml(Profile-gated) .env.exampleenthältQDRANT_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_pgvectorhat ein Pendant-Down-Migration-Script (DROP EXTENSION IF EXISTS vector CASCADE;). Vorsicht: CASCADE killt allevec_*-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:
tenantIdist Pflicht-Property aufVectorItem.payload(TypeScript-erzwungen viaRecord<string, unknown> & { tenantId: string }).semanticSearchverlangt Pflicht-ParametertenantIdund injiziert ihn alsmust-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 inembedding-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 EXTENSIONbenö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_KEYgesetzt werden. Wrapper validiert: wennQDRANT_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 gegenembedding-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-verifiermit Acceptance-Criteria-Checkliste. - Code-Review:
gsd-code-revieweram Ende, mit Fokus auf SQL-Injection-Vermeidung im pgvector-Adapter (alle Tabellen-Namen aus Whitelist, alle Filter-Values parametrisiert).
Staging-Deployment-Steps
- Branch
agent/04-vector-storepushen. - Migration
enable_pgvectorauf Staging-DB laufen lassen:pnpm prisma migrate deploy. Verifizieren viaSELECT extname FROM pg_extension WHERE extname='vector';. - Bei Qdrant-Test-Setup: Qdrant-Container in Coolify-Stack hinzufügen (Profile
qdrant).QDRANT_URLundQDRANT_API_KEYals Secrets setzen. - Smoke-Tests:
pnpm tsx scripts/staging/vector-smoke.ts(neues Skript, dascreateVectorStoreaufruft, eine Test-Collection erzeugt, 100 Random-Vektoren upserted, eine Search ausführt, alles wieder löscht).- Für beide Adapter durchlaufen lassen (env-switch).
- Performance-Check: 10k Vektoren upserten, P95-Search-Latenz messen. Erwartung: pgvector <30ms bei topK=10; Qdrant <15ms.
- 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-storescaffold + 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
QdrantClientLikesurface. - 2026-05-17 11:07 — a2ca182d —
withTenantScopewrapper that injectstenantIdand refuses the baresearchVectors. - 2026-05-17 11:09 — 6d0dc128 —
createVectorStorefactory 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_ADAPTERcataloged + added to.env.example. - 2026-05-17 11:19 — f1e2674d —
docs/architecture/vector-store.mdcovering 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.)