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,255 @@
|
||||
# Embedding-Pipeline + RAG-Retrieval
|
||||
|
||||
**Status:** completed
|
||||
**Task-ID:** #50
|
||||
**Phase:** 04
|
||||
**Estimated Effort:** 1 Woche
|
||||
**Owner:** unassigned
|
||||
|
||||
## Problem
|
||||
|
||||
Damit semantische Suche und RAG (Chatbot V2 in Phase 07) funktionieren, brauchen wir eine durchgängige Pipeline die:
|
||||
|
||||
1. Text-Inhalte aus dem Domain-Model (KB-Articles, Rows-Engine-Rows, CRM-Notes) automatisch und async embedded.
|
||||
2. Eine austauschbare Embedding-Provider-Abstraktion bietet (OpenAI, Scaleway-Managed-Inference, Aleph-Alpha, Anthropic) — die Wahl darf nicht im Code festgenagelt sein.
|
||||
3. Chunking sauber löst (Token-Counting, Overlap), weil naive Long-Text-Embeddings entweder Token-Limits sprengen oder Recall verschlechtern.
|
||||
4. Tenant-Scope hart durchzieht — Embeddings dürfen niemals cross-tenant retrieved werden.
|
||||
5. Einen Retrieval-Helper bereitstellt den Chatbot-V2 ohne weiteren Glue-Code aufrufen kann.
|
||||
6. Backfill für bestehende Inhalte ermöglicht (Initial-Setup + Disaster-Recovery).
|
||||
|
||||
Aktuell existiert keiner dieser Bausteine. Ohne sie ist RAG nicht baubar.
|
||||
|
||||
## Depends on
|
||||
|
||||
- `03-scaling-infrastructure/outbox-pattern.md` (#42) — Indexer-Worker konsumiert `rag.index`-Outbox-Events. Synchrone Embedding-Pfade wären inakzeptabel langsam und würden Request-Threads blockieren.
|
||||
- `03-scaling-infrastructure/worker-queues.md` (#43) — Worker läuft als BullMQ-Job im `worker-general`.
|
||||
- `04-search-rag/vector-store.md` (#49) — die Pipeline schreibt direkt in den Vector-Store, nutzt `embedAndUpsert` und `semanticSearch`.
|
||||
- `04-search-rag/meilisearch.md` (#48) — das Pattern der Outbox-Indexer-Worker (Job-Handler-Registrierung, Idempotenz, Retry-Strategy) ist hier etabliert und wird übernommen.
|
||||
- Existierendes `packages/ai/` — wird um `embeddings/`-Modul erweitert.
|
||||
|
||||
## Blocks
|
||||
|
||||
- `07-chatbot/chatbot-v2.md` — die RAG-Variante des Chatbots nutzt `retrieveRelevantContext` direkt. Ohne Embedding-Pipeline keine RAG-Antworten.
|
||||
- diverse Phase-05-Features die "ähnliche Items vorschlagen" wollen (z.B. Knowledge-Base "verwandte Artikel"-Widget) können nach Abschluss dieser Pipeline implementiert werden.
|
||||
|
||||
## Approach
|
||||
|
||||
**Embedding-Provider-Abstraktion in `packages/ai/src/embeddings/`** mit dem gleichen Adapter-Pattern wie der Vector-Store: ein Interface, mehrere Adapter, eine Factory die per env auswählt.
|
||||
|
||||
**Indexer-Worker konsumiert generische `rag.index`-Events** mit Payload `{ tenantId, collection, sourceType, sourceId, text, metadata }`. Der Worker chunked, embedded und upserted in einem Schritt. Bei `rag.delete`-Events: deleteVectors mit id-Pattern `<sourceType>:<sourceId>:*`.
|
||||
|
||||
**Auto-Indexing-Hooks** in den Domain-Services: bei Create/Update/Delete eines indexierbaren Items wird ein Outbox-Event geschrieben. Welche Items indexierbar sind, wird durch Konvention (KB-Articles) oder durch eine `isEmbeddable`-Property (Rows-Engine, opt-in pro Entity-Definition) entschieden.
|
||||
|
||||
**RAG-Retrieval-Helper** `retrieveRelevantContext` kapselt: query-embed → vector-search (multi-collection-fan-out) → rank-merge → Source-Refs zurückgeben.
|
||||
|
||||
**Backfill-CLI** schreibt `rag.index`-Events in die Outbox für alle bestehenden Items — kein direkter Embedding-Pfad aus dem CLI-Prozess heraus, damit Quota-Konsistenz und Worker-Throughput-Limits respektiert werden.
|
||||
|
||||
**Alternativen verworfen:**
|
||||
- **Synchrones Embedding bei Save**: blockiert Save-Latenz um 200-2000ms je nach Provider; bei Provider-Outage ist Save kaputt.
|
||||
- **Direkter Worker-Trigger ohne Outbox**: würde Dual-Write zwischen Postgres-Save und Worker-Trigger einführen → Inkonsistenzen bei Crash zwischen den beiden Writes.
|
||||
- **LangChain als Framework**: viel zu groß, zu meinungsstark, zu fragile bei Version-Bumps. Wir nutzen die zwei nützlichen Bausteine (Splitter-Algorithmus, Token-Counter) eigenständig.
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. **Embedding-Provider-Interface in `packages/ai/src/embeddings/`** — Interface `EmbeddingProvider` mit Methoden:
|
||||
```ts
|
||||
interface EmbeddingProvider {
|
||||
readonly name: string;
|
||||
readonly model: string;
|
||||
readonly dimensions: number;
|
||||
readonly maxBatchSize: number;
|
||||
readonly maxTokensPerInput: number;
|
||||
embed(texts: string[]): Promise<number[][]>; // batch, gleich lang wie input
|
||||
embedSingle(text: string): Promise<number[]>;
|
||||
}
|
||||
```
|
||||
Types-Exports und Factory `createEmbeddingProvider(env?: ProviderEnv)`.
|
||||
- Files: `packages/ai/src/embeddings/types.ts`, `packages/ai/src/embeddings/factory.ts`, `packages/ai/src/embeddings/index.ts`
|
||||
- Commit: `04/embedding-pipeline: add embedding provider interface and factory`
|
||||
2. **OpenAI-Adapter** — Wrapper um OpenAI-SDK, Modelle `text-embedding-3-small` (1536d) und `text-embedding-3-large` (3072d), automatisches Batching auf 96 Inputs/Request, Retry mit exponential Backoff bei 429/5xx.
|
||||
- Files: `packages/ai/src/embeddings/providers/openai.ts`, `packages/ai/src/embeddings/providers/openai.test.ts`
|
||||
- Commit: `04/embedding-pipeline: add openai embedding adapter`
|
||||
3. **Scaleway-Managed-Inference-Adapter** — REST-Wrapper für Scaleway-Embedding-Endpoint (OpenAI-kompatibel), env `SCALEWAY_INFERENCE_URL`, `SCALEWAY_INFERENCE_TOKEN`.
|
||||
- Files: `packages/ai/src/embeddings/providers/scaleway.ts`, `packages/ai/src/embeddings/providers/scaleway.test.ts`
|
||||
- Commit: `04/embedding-pipeline: add scaleway embedding adapter`
|
||||
4. **Aleph-Alpha-Adapter** — Wrapper um Aleph-Alpha-Embedding-API (semantic_embedding), Token-Limits beachten, Batching.
|
||||
- Files: `packages/ai/src/embeddings/providers/aleph-alpha.ts`, `packages/ai/src/embeddings/providers/aleph-alpha.test.ts`
|
||||
- Commit: `04/embedding-pipeline: add aleph-alpha embedding adapter`
|
||||
5. **Anthropic-Adapter (Stub mit clear-error-throw)** — Anthropic hat noch kein offizielles Embedding-Endpoint. Adapter existiert als Platzhalter, der bei Aufruf einen klaren Fehler wirft mit Hinweis darauf, welche Provider stattdessen zu nutzen sind. Sobald Anthropic launched, wird der Stub durch eine echte Implementation ersetzt.
|
||||
- Files: `packages/ai/src/embeddings/providers/anthropic.ts`
|
||||
- Commit: `04/embedding-pipeline: add anthropic embedding adapter placeholder`
|
||||
6. **Provider-Factory mit env-Auswahl** — `AI_EMBEDDING_PROVIDER` (openai|scaleway|aleph-alpha|anthropic), `AI_EMBEDDING_MODEL` (provider-spezifisch), `AI_EMBEDDING_DIMENSIONS` (für Vector-Store-Collection-Setup). Factory validiert env-Konsistenz beim Start.
|
||||
- Files: `packages/ai/src/embeddings/factory.ts` (erweitert), `packages/ai/src/embeddings/factory.test.ts`
|
||||
- Commit: `04/embedding-pipeline: implement env-based provider selection`
|
||||
7. **Chunking-Helper `splitForEmbedding`** — Signatur:
|
||||
```ts
|
||||
splitForEmbedding(text: string, opts?: { maxTokens?: number; overlap?: number; encoding?: string }): Chunk[]
|
||||
type Chunk = { index: number; text: string; tokenCount: number; charStart: number; charEnd: number }
|
||||
```
|
||||
Token-Counting via tiktoken (für OpenAI-kompatible Modelle) oder model-spezifisch. Splits an Satzgrenzen wenn möglich (Recursive-Character-Splitter), fallback auf hard-cut. Overlap default 50 Tokens.
|
||||
- Files: `packages/ai/src/embeddings/chunking.ts`, `packages/ai/src/embeddings/chunking.test.ts`
|
||||
- Commit: `04/embedding-pipeline: add token-aware chunking helper`
|
||||
8. **Indexer-Worker im worker-general** — neuer BullMQ-Job-Handler `rag.index` und `rag.delete`. Konsumiert Outbox-Events:
|
||||
- `rag.index` payload: `{ tenantId, collection, sourceType: "kb-article" | "row" | "crm-note", sourceId, text, metadata }`. Worker: `splitForEmbedding(text)` → für jeden Chunk eine deterministische ID `<sourceType>:<sourceId>:<chunkIndex>`, payload mergt `metadata` + `{ tenantId, sourceType, sourceId, chunkIndex }` → `embedAndUpsert` in Vector-Store.
|
||||
- `rag.delete` payload: `{ tenantId, collection, sourceType, sourceId }`. Worker: Vektoren mit id-Pattern `<sourceType>:<sourceId>:*` aus Collection entfernen (Adapter unterstützt prefix-delete oder list+delete).
|
||||
- Idempotenz: re-processing eines Events liefert gleichen Endzustand. Bei Provider-Error: BullMQ-Retry mit exponential Backoff.
|
||||
- Files: `apps/worker-general/src/jobs/rag-indexer.ts`, `apps/worker-general/src/jobs/rag-indexer.test.ts`, `apps/worker-general/src/index.ts`
|
||||
- Commit: `04/embedding-pipeline: add rag-indexer worker job`
|
||||
9. **Auto-Indexing-Hooks in Domain-Services** — Outbox-Events produzieren bei:
|
||||
- KB-Article Create/Update/Delete → `rag.index` mit `sourceType: "kb-article"`, text = `title + "\n\n" + content`.
|
||||
- CRM-Notes Create/Update/Delete → `rag.index` mit `sourceType: "crm-note"`, text = note-body, metadata enthält `contactId` + `userId`.
|
||||
- Rows-Engine: opt-in pro Entity-Definition via neue Property `isEmbeddable: boolean` und `embeddableFields: string[]`. Wenn gesetzt: bei Row-Create/Update/Delete → `rag.index` mit text = concat der `embeddableFields`-Werte.
|
||||
- Files: jeweilige Domain-Service-Files, Entity-Definition-Schema-Erweiterung
|
||||
- Commits: pro Source-Type ein Commit, z.B. `04/embedding-pipeline: emit rag.index events from kb-articles`
|
||||
10. **RAG-Retrieval-Helper `retrieveRelevantContext`** — Public-API in `packages/ai/src/embeddings/retrieval.ts`:
|
||||
```ts
|
||||
retrieveRelevantContext({
|
||||
tenantId: string,
|
||||
query: string,
|
||||
topK?: number, // default 8
|
||||
collections?: string[], // default: alle aktiven RAG-Collections des Tenants
|
||||
minScore?: number, // default 0.7
|
||||
}): Promise<RetrievedContext[]>
|
||||
type RetrievedContext = {
|
||||
sourceType: string;
|
||||
sourceId: string;
|
||||
chunkIndex: number;
|
||||
text: string;
|
||||
score: number;
|
||||
metadata: Record<string, unknown>;
|
||||
}
|
||||
```
|
||||
Embedded die Query mit dem konfigurierten Provider, sucht parallel in allen relevanten Collections, merged + ranked nach Score, filtert `minScore`, gibt top-K zurück. Tenant-Scope wird durchgehalten.
|
||||
- Files: `packages/ai/src/embeddings/retrieval.ts`, `packages/ai/src/embeddings/retrieval.test.ts`
|
||||
- Commit: `04/embedding-pipeline: add retrieveRelevantContext helper for rag`
|
||||
11. **Backfill-CLI-Command** — `pnpm cli rag:reindex --tenant=<id|all> --collection=<name|all>`. Iteriert per Cursor über die Source-Tabellen (KB-Articles, CRM-Notes, embeddable Rows) und schreibt `rag.index`-Events in die Outbox. Worker-Throughput limitiert die Rate automatisch (kein DOS gegen Embedding-Provider).
|
||||
- Files: `packages/cli/src/commands/rag-reindex.ts`, `packages/cli/src/commands/rag-reindex.test.ts`
|
||||
- Commit: `04/embedding-pipeline: add cli command for rag backfill`
|
||||
12. **Doku `docs/features/rag.md`** — Architektur-Diagramm (Domain-Event → Outbox → Worker → Embedding-Provider → Vector-Store; Query-Pfad: Chatbot → retrieveRelevantContext → Vector-Store → ranked Snippets), Chunking-Tipps (richtige `maxTokens` pro Use-Case), Provider-Vergleich (Cost pro 1M Tokens, EU-Region-Verfügbarkeit, DSGVO-Status), Onboarding-Anleitung für eigene `isEmbeddable`-Entities.
|
||||
- Files: `docs/features/rag.md`
|
||||
- Commit: `04/embedding-pipeline: add user-facing rag documentation`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Unit-Tests:**
|
||||
- Provider-Adapter (jeweils mit gemockten HTTP-Calls): korrektes Batching, Retry-Verhalten bei 429/5xx, korrekte Dimension-Validierung, Token-Limit-Errors werden propagiert.
|
||||
- Factory: env-basierte Auswahl, klare Errors bei inkonsistenter Config (z.B. Provider gesetzt aber kein API-Key).
|
||||
- `splitForEmbedding`: Chunks <= maxTokens, Overlap stimmt, Satzgrenzen werden präferiert, Edge-Cases (empty string, single-word, ein einziger riesiger Satz).
|
||||
- `retrieveRelevantContext`: Tenant-Scope-Pflicht, mehrere Collections werden parallel abgefragt, minScore-Filter greift, topK-Cap eingehalten.
|
||||
- **Worker-Tests:**
|
||||
- `rag-indexer` für `rag.index`: chunked → embedded → upserted; idempotent bei Re-Play; bei Provider-Error wird Job retried (verifiziert via BullMQ-Mock).
|
||||
- `rag-indexer` für `rag.delete`: entfernt alle Chunks zu einem `sourceId`; idempotent bei wiederholtem Event.
|
||||
- Outbox-Producer-Hooks: KB-Article Create → produziert genau ein `rag.index`-Event mit korrektem Payload.
|
||||
- **Integration-Tests (mit testcontainers):**
|
||||
- Spinne Postgres-mit-pgvector + Redis (für BullMQ).
|
||||
- End-to-End: KB-Article einfügen (über Domain-Service) → Outbox-Event wird produziert → Worker konsumiert → Vector-Store enthält Chunks → `retrieveRelevantContext` mit ähnlicher Query findet die Chunks.
|
||||
- Tenant-Isolation: Tenant A indexed KB-Artikel, Tenant B macht semantische Suche → 0 Treffer.
|
||||
- Backfill: 100 bestehende KB-Articles in DB ohne Embeddings, `rag:reindex` ausführen → alle 100 landen im Vector-Store.
|
||||
- **Provider-Smoke-Test (separates Test-Suite, gated by env):**
|
||||
- Wenn `OPENAI_API_KEY` gesetzt: ein echter embed-Call gegen text-embedding-3-small, verifiziert Dimension und Score-Plausibilität.
|
||||
- Analog für Scaleway, Aleph-Alpha.
|
||||
- Tests sind via `vitest --grep=@live-provider` nur in dediziertem Lauf aktiv.
|
||||
- **Coverage-Target:** `packages/ai/src/embeddings/` ≥85%, `apps/worker-general/src/jobs/rag-indexer.ts` ≥80%.
|
||||
- **Test-Files:**
|
||||
- `packages/ai/src/embeddings/**/*.test.ts`
|
||||
- `apps/worker-general/src/jobs/rag-indexer.test.ts`
|
||||
- `packages/cli/src/commands/rag-reindex.test.ts`
|
||||
- `tests/integration/rag-pipeline.test.ts` (E2E mit testcontainers)
|
||||
|
||||
**NICHT als completed markieren bevor alle Tests grün sind. Provider-Smoke-Tests gegen mindestens einen echten Provider müssen einmal manuell durchgeführt und im Progress-Log dokumentiert sein.**
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `packages/ai/src/embeddings/` exportiert: `EmbeddingProvider`-Interface, `createEmbeddingProvider`, `splitForEmbedding`, `retrieveRelevantContext`
|
||||
- [ ] OpenAI-, Scaleway-, Aleph-Alpha-Adapter implementiert und getestet; Anthropic als Platzhalter mit klarem Throw
|
||||
- [ ] env-basierte Provider-Selektion via `AI_EMBEDDING_PROVIDER`, `AI_EMBEDDING_MODEL`, `AI_EMBEDDING_DIMENSIONS`
|
||||
- [ ] `splitForEmbedding` mit Token-Counter (tiktoken oder model-spezifisch), default 512/50 (maxTokens/overlap)
|
||||
- [ ] `rag-indexer`-Worker im `worker-general` registriert; konsumiert `rag.index` und `rag.delete`
|
||||
- [ ] Outbox-Producer-Hooks aktiv für: KB-Articles, CRM-Notes, Rows mit `isEmbeddable=true`
|
||||
- [ ] `isEmbeddable` + `embeddableFields` als opt-in-Property in Entity-Definitionen einsetzbar
|
||||
- [ ] `retrieveRelevantContext` mit Multi-Collection-Fan-Out, Tenant-Scope-Pflicht, topK + minScore-Filter
|
||||
- [ ] CLI-Command `rag:reindex --tenant --collection` produziert Backfill-Events
|
||||
- [ ] Doku `docs/features/rag.md` mit Architektur + Chunking + Provider-Vergleich + Onboarding-Guide
|
||||
- [ ] `.env.example` enthält `AI_EMBEDDING_PROVIDER`, `AI_EMBEDDING_MODEL`, `AI_EMBEDDING_DIMENSIONS`
|
||||
- [ ] Tests grün (lint, typecheck, unit, worker, integration via testcontainers)
|
||||
- [ ] Mindestens ein Provider-Smoke-Test einmal gegen echtes Endpoint gefahren und dokumentiert
|
||||
- [ ] Detail-MD Progress-Log aktualisiert
|
||||
- [ ] PROGRESS.md Status auf `completed`
|
||||
|
||||
## Rollback Strategy
|
||||
|
||||
- **Worker-Disable:** Feature-Flag `RAG_INDEXER_ENABLED=false` stoppt die Job-Handler-Registrierung. Outbox-Events sammeln sich an, werden später beim Re-Enable abgearbeitet (Outbox-Retention beachten — ggf. erhöhen vor Disable).
|
||||
- **Provider-Wechsel:** Bei Provider-Outage `AI_EMBEDDING_PROVIDER`-env umstellen und Worker neu deployen. Bestehende Embeddings im Vector-Store bleiben benutzbar wenn Dimension passt; sonst `rag:reindex --tenant=all` nach dem Wechsel.
|
||||
- **Code-Revert:** Commits sind atomic. Revert der Worker- und Hook-Commits stoppt die Pipeline. Vector-Store-Daten bleiben erhalten (kein Schema-Schaden) — können später wieder befüllt werden.
|
||||
- **Dimension-Mismatch-Recovery:** Wenn aus Versehen ein anderes Embedding-Modell mit anderer Dimension aktiviert wurde, schlägt der Vector-Store-Upsert mit klarem Error fehl. Recovery: alte Collection löschen (`vector-store deleteCollection`), neue mit korrekter Dimension anlegen (auto via `createCollection` beim ersten Upsert), `rag:reindex` triggern.
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **Tenant-Isolation ist sicherheitskritisch.** `tenantId` ist Pflicht in Event-Payload, Chunk-Metadata, Vector-Store-Payload und Retrieval-Aufruf. `retrieveRelevantContext` verlangt `tenantId` als Pflicht-Parameter — TypeScript erzwingt es.
|
||||
- **Provider-Datenabfluss:** Jeder Embed-Call schickt Text an einen externen Provider. Implikationen:
|
||||
- DSGVO: nur EU-Region-Provider (Scaleway, Aleph-Alpha) für Tenants mit EU-Daten-Anforderung. Doku in `docs/features/rag.md`.
|
||||
- Per-Tenant-Provider-Override (Phase-11-Backlog): Tenants sollen pro-Tenant einen Provider wählen können (Premium-Feature). Aktuell global-env-basiert.
|
||||
- Logging: niemals den Input-Text in Logs (nur Hashes für Debug); Embedding-Vektoren selber auch nicht (siehe Vector-Store-Security-Notes).
|
||||
- **PII in Source-Texten:** KB-Articles und CRM-Notes können PII enthalten. Kein Cross-Tenant-Leak möglich solange Tenant-Filter strikt; aber: wenn ein Tenant seinen Provider auf OpenAI setzt, akzeptiert er implizit dass die Texte an OpenAI gehen. UI-Hinweis und Opt-In-Toggle für CRM-Notes-Indexing (default off, vom Tenant explizit zu aktivieren).
|
||||
- **API-Key-Handling:** Provider-API-Keys (OpenAI/Scaleway/Aleph-Alpha) gehören in den Secret-Store, nie in `.env.example`. Worker holt sie beim Start.
|
||||
- **Rate-Limiting:** Backfill kann teuer werden. CLI-Command `rag:reindex` produziert nur Outbox-Events; Worker-Concurrency-Limit (BullMQ-`concurrency`) kontrolliert die effektive Provider-Last. Default-Concurrency: 2 für Embedding-Jobs (konservativ, kann pro Tenant erhöht werden).
|
||||
- **Cost-Guard (vorläufig):** Bis AI-Cost-Tracking (Phase 05 Task #54-#56) live ist, Worker hartcoded auf max 10k Embed-Calls pro Tenant pro Stunde, sonst Job-Stop mit Alert. Wird abgelöst sobald Quota-Enforcement aus Phase 05 verfügbar ist.
|
||||
|
||||
## Subagent Recommendations
|
||||
|
||||
- **Planning:** `Plan`-Subagent — validiert Reihenfolge der 12 Steps, prüft ob Interface-Designs mit Vector-Store-Helpers konsistent sind.
|
||||
- **Research:** `Explore`-Subagent mit Auftrag: "Recherchiere aktuelle Embedding-Provider-Konditionen: Modelle, Dimensions, Cost pro 1M Tokens, EU-Region-Verfügbarkeit für OpenAI, Scaleway-Inference, Aleph-Alpha. Liefer-Format: Markdown-Tabelle. Bestätige außerdem ob Anthropic in 2026 ein Embedding-Endpoint anbietet — wenn ja, Doku-Link."
|
||||
- **Implementation:**
|
||||
- Subagent 1: Steps 1-6 (Interface + alle Provider-Adapter + Factory). Parallel arbeitbar nach internen Sub-Splits.
|
||||
- Subagent 2: Step 7 (Chunking). Unabhängig, kann parallel zu Subagent 1 laufen.
|
||||
- Subagent 3: Steps 8-9 (Worker + Outbox-Hooks). Hängt von Subagents 1+2 ab.
|
||||
- Subagent 4: Steps 10-11 (Retrieval-Helper + CLI). Hängt von Subagent 3 ab für vollständige E2E-Tests, kann aber parallel implementiert werden.
|
||||
- Subagent 5: Step 12 (Doku). Parallel zu Subagent 4.
|
||||
- **Tests:**
|
||||
- Dedizierter Test-Subagent für die Conformance-Tests der Provider-Adapter (mit gemockten HTTP-Calls).
|
||||
- Dedizierter Test-Subagent für den E2E-Integration-Test mit testcontainers (Postgres-pgvector + Redis).
|
||||
- **Verification:** `gsd-verifier` mit Acceptance-Criteria-Checkliste.
|
||||
- **Code-Review:** `gsd-code-reviewer` am Ende mit besonderem Fokus auf: Tenant-Filter-Coverage, Secret-Handling, korrekte Dimension-Validierung.
|
||||
|
||||
## Staging-Deployment-Steps
|
||||
|
||||
1. Branch `agent/04-embedding-pipeline` pushen.
|
||||
2. Voraussetzungen auf Staging verifizieren: pgvector aktiviert (aus Task #49), Outbox läuft (Task #42), Worker-General deployed (Task #43).
|
||||
3. Embedding-Provider-Secret in Coolify setzen: `OPENAI_API_KEY` oder `SCALEWAY_INFERENCE_TOKEN` (je nach Wahl). `AI_EMBEDDING_PROVIDER`, `AI_EMBEDDING_MODEL`, `AI_EMBEDDING_DIMENSIONS` als Env-Vars.
|
||||
4. Worker-Deploy triggern; Logs prüfen: `rag-indexer registered`, `embedding-provider: <name> (<model>, <dim>d)`.
|
||||
5. Smoke-Tests:
|
||||
- In Staging-UI einen KB-Artikel mit ~500 Wörtern anlegen → innerhalb 30s Worker-Log `rag.index processed sourceId=<id> chunks=<n>` → Vector-Store-Eintrag prüfen via `pnpm tsx scripts/staging/vector-inspect.ts <tenantId> <sourceId>`.
|
||||
- `pnpm cli rag:reindex --tenant=<staging-tenant>` für KB-Articles → Worker arbeitet alle Events ab → BullMQ-Dashboard zeigt 0 pending.
|
||||
- `pnpm tsx scripts/staging/rag-query.ts <tenantId> "<test-query>"` → liefert ranked Chunks; manuelle Plausibilitätsprüfung.
|
||||
6. Tenant-Isolation auf Staging: zwei Tenants mit unterschiedlichen KB-Inhalten anlegen, gegenseitige Queries müssen 0 Treffer liefern.
|
||||
7. Cost-Beobachtung: nach Smoke-Tests Provider-Dashboard prüfen (OpenAI-Usage, Scaleway-Usage). Sicherstellen dass das Cost-Guard greift falls Backfill überdimensioniert war.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
_(leer)_
|
||||
|
||||
## Progress Log
|
||||
|
||||
- 2026-05-17 12:00 — 26ef2e2c — embedding provider interface + factory + types (`packages/ai/src/embeddings/{types,factory,index}.ts`) with registry-based adapter pattern; 15 factory tests green.
|
||||
- 2026-05-17 12:05 — 7f167a43 — OpenAI adapter (`text-embedding-3-small` default, batch 96, retry-with-jitter on 429/5xx, dimension validation, optional dims override on v3 models); 10 tests.
|
||||
- 2026-05-17 12:10 — 31b1fe1d — Scaleway adapter (OpenAI-compatible, EU residency by default, bge-multilingual-gemma2 1024d); 6 tests.
|
||||
- 2026-05-17 12:15 — fd26a9f0 — Aleph-Alpha adapter (semantic_embed endpoint, parallel single-input calls, luminous-base 5120d); 5 tests.
|
||||
- 2026-05-17 12:18 — c7c2e4e9 — Anthropic placeholder adapter (throws EMBEDDING_PROVIDER_NOT_SUPPORTED with provider-pick hint); 3 tests.
|
||||
- 2026-05-17 12:25 — ef800f6c — chunking helper `splitForEmbedding` backed by gpt-tokenizer (cl100k), default 500/50 tokens, sentence-boundary + hard-cut fallback; 10 tests.
|
||||
- 2026-05-17 12:35 — d5764a79 — `embedAndUpsert` helper enforcing tenant scope at the seam (extraPayload can't override tenantId); 7 tests.
|
||||
- 2026-05-17 12:45 — a8e69306 — rag-indexer worker job + bootstrap on `outbox.rag-index`, event-router rule, BullMQ wiring in apps/worker; 13 worker tests + router test.
|
||||
- 2026-05-17 13:00 — ce34c873 — outbox publishers `publishRagUpsertEvent`/`publishRagDeleteEvent` + KB-Article wire helper `apps/web/.../kbArticleRag.server.ts`; CRUD-call-site migration deferred per spec.
|
||||
- 2026-05-17 13:10 — 6eee711a — `retrieveRelevantContext` with multi-collection fan-out, rank-merge by score, minScore filter, topK cap; 6 tests.
|
||||
- 2026-05-17 13:20 — ad01e707 — `toolctrl-cli rag reindex --tenant --source` backfill with KB-Article source adapter; 8 tests.
|
||||
- 2026-05-17 13:25 — 9ddfa0b1 — env catalog + .env.example entries for every embedding/RAG env (AI_EMBEDDING_*, provider keys, RAG_*).
|
||||
- 2026-05-17 13:30 — 3d004d69 — `docs/features/rag.md` documenting architecture, provider matrix, tenant isolation, chunking, cost, disaster-recovery, onboarding.
|
||||
|
||||
Open follow-ups (not blocking acceptance):
|
||||
- migrate every KB CRUD call site to invoke `emitKbArticleRagUpsert` / `emitKbArticleRagDelete` (the helper is shipped; routes/admin currently delete via the legacy db helpers).
|
||||
- wire CRM-notes + embeddable rows-engine entities (source adapters + service hooks) per the documented pattern.
|
||||
- replace the hard-coded 2-concurrency cap with the per-tenant cost-guard once Phase 05 task #54-#56 lands.
|
||||
- run the manual provider-smoke-test against the deployed Scaleway endpoint (staging-step #5) and append the run notes here.
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
_(Wird nach Task-Abschluss ergänzt — insbesondere: Chunking-Größen die in Praxis funktionieren, Provider-Latenz-Vergleich, Cost-pro-Tenant-Profil, Retrieval-Quality-Beobachtungen.)_
|
||||
Reference in new issue
Block a user