Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,215 @@
|
||||
# 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):**
|
||||
```ts
|
||||
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:**
|
||||
```ts
|
||||
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.)_
|
||||
Reference in new issue
Block a user