Zum Hauptinhalt springen
KI-Engineering
12 Min. Lesezeit

Autonome Hybrid-RAG-Architektur: Browser-basierter Vektorabruf, Generative UI & Next.js 16 SSG

Vollständige architektonische Fallstudie der Plattform yusupovartur.com: Entwicklung eines Sub-5ms-Hybrid-RAG-Assistenten (Okapi BM25 + Damerau-Levenshtein + Kosinus-Ähnlichkeit), Multi-Turn-Konversationsgedächtnis, Generative-UI-Tool-Karten und über 213 lokalisierte Next.js 16 SSG-Routen ohne Vektordatenbank-Kosten.

AY
Artur Yusupov
Fullstack Web-Engineer & KI-Architekt
Autonome Hybrid-RAG-Architektur: Browser-basierter Vektorabruf, Generative UI & Next.js 16 SSG

1. Executive Summary: Das Cloud-Vektordatenbank-Antimuster

In den vergangenen zwei Jahren wurde in der Branche ein einheitliches Dogma gepredigt: *Um einen RAG-Chatbot zu bauen, muss man Pinecone, Weaviate oder Qdrant abonnieren, einen Embedding-Microservice aufsetzen und bei jedem Nutzer-Prompt einen entfernten Vektorindex abfragen.*

Während diese Architektur für Enterprise-Suchsysteme mit Millionen juristischer Akten oder Patientenakten unerlässlich ist, ist sie für Engineering-Portfolios, Dokumentationsportale und SaaS-Wissensdatenbanken mit unter 10.000 Dokumenten eine kostspielige Überdimensionierung:

  • Latenz-Belastung (Latency Tax): Jede entfernte Vektorabfrage verursacht 150ms bis 400ms an Netzwerk-Roundtrips, noch bevor die LLM-Token-Generierung überhaupt beginnt.
  • Kosten-Belastung (Cost Tax): Verwaltete Vektordatenbanken kosten 70 $ bis 250 $ pro Monat an reinen Grundgebühren im Leerlauf.
  • Single Point of Failure: Fällt der externe Vektordienst aus oder sind API-Kontingente erschöpft, fällt der Website-Assistent komplett aus.

Bei der Konzeption der Next.js 16 & Hybrid RAG Portfolio-Plattform (`yusupovartur.com`) haben wir eine autonome Hybrid-RAG-Engine entwickelt, die sowohl am Vercel Serverless Edge als auch direkt im Browser ausgeführt wird. Sie indexiert 71 kommerzielle und persönliche Fallstudien sowie 9 Architektur-Deep-Dives in 3 Sprachen (`EN`, `UA`, `ES`) in unter 5ms bei 0 $ monatlichen Datenbankkosten.


2. Architecture Decision Records (ADR)

Architekturentscheidung
In-Memory-Index zur Build-Zeit (Okapi BM25 + vorberechnete Vektoren)
Evaluierte Alternative
Cloud-Vektor-DB (Pinecone / Qdrant)
Technische Begründung (Trade-off-Analyse)
Eliminiert 150-400ms Netzwerk-Latenz und wiederkehrende Fixkosten von 70+ $/Monat. Die gesamte Wissensbasis (80+ Chunks) kompiliert in einen lazy-geladenen Bundle-Chunk (22.1 KB gzip).
Architekturentscheidung
Dual-Mode-Ausführung (`/api/chat`-Streaming + autonomer Client-Fallback)
Evaluierte Alternative
Reiner Server-LLM-Endpunkt
Technische Begründung (Trade-off-Analyse)
Auf yusupovartur.com streamt Next.js Antworten via POST /api/chat. Bei Netzausfall, Rate-Limits oder statischem Hosting synthetisiert der Client lokal deterministische Antworten ohne Fehlerbildschirme.
Architekturentscheidung
Deterministischer 7-Intent-Router (`detectQueryIntent`)
Evaluierte Alternative
Reine LLM-Klassifikation
Technische Begründung (Trade-off-Analyse)
Klassifiziert jede Anfrage in < 0,2ms in 7 Intents (project-aspect, blog, service, profile, contact, methodology, general) und verhindert Kontextverfälschungen bei Preis- oder Kontaktfragen.
Architekturentscheidung
Generative-UI-Orchestrierung im Chat
Evaluierte Alternative
Reine Markdown-Textantworten
Technische Begründung (Trade-off-Analyse)
Rendert interaktive React 19 Komponenten (ProjectToolCard, StackComparisonCard, ProjectEstimateCalculatorCard, ContactActionCard) dynamisch im Konversationsfluss zur Steigerung der B2B-Conversion.
Architekturentscheidung
Zentrales `projectRegistry` (Single Source of Truth)
Evaluierte Alternative
JSON-Duplizierung / Separates CMS
Technische Begründung (Trade-off-Analyse)
Eine einzige typisierte TypeScript-Quelle versorgt gleichzeitig generateStaticParams (240+ SSG-Routen), Schema.org JSON-LD, llms-full.txt für KI-Crawler und die interne RAG-Engine.

3. Kernmechanismen: Funktionsweise der Plattform unter der Haube

Mechanismus 1: Dreistufige hybride Scoring-Pipeline (Okapi BM25 + Damerau-Levenshtein + Kosinus-Ähnlichkeit)

Reine Vektorsuche scheitert häufig an exakten Versionen (Next.js 16 vs. Next.js 14) oder Projektnamen (IT-Magic, Unitrition, Fullstack AI Lab). Reine Schlüsselwortsuche wiederum versteht keine konzeptionellen Fragen wie *„Wie optimierst du die mobile Ladegeschwindigkeit?“*.

Unsere Engine in src/lib/ai/rag.ts kombiniert drei mathematische Signale für jedes Dokument d und die Anfrage Q:

TS
FinalScore(d, Q) = (w_bm25 * BM25(d, Q)) + (w_sem * CosineSimilarity(q, d)) + FieldBoost(d, Q) + ContextBoost(d)
1
Phase 1 - Dreisprachige Tokenisierung, Synonym-Erweiterung und Tippfehlertoleranz:

Die Anfrage wird durch foldForSearch() normalisiert, Stoppwörter in Englisch, Ukrainisch und Spanisch werden entfernt und technische Synonyme via expandTokens() hinzugefügt. Stimmt ein Begriff nicht exakt überein, korrigiert eine begrenzte Damerau-Levenshtein-Distanz (distance <= 1 für kurze, <= 2 für längere Wörter) Tippfehler in Echtzeit (z. B. Zuordnung von wpskilz zu wpskills).

2
Phase 2 - Lexikalisches Ranking mit Okapi BM25 (`k1 = 1.5, b = 0.75`):

Jedes Dokument wird anhand der inversen Dokumenthäufigkeit (IDF) bewertet, normalisiert gegen die durchschnittliche Dokumentlänge des Gesamtkorpus (avgDocLength):

TS
   const idf = Math.log(1 + (totalDocs - docFreq + 0.5) / (docFreq + 0.5))
   const tfNorm = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (docLength / avgDocLength)))
   bm25Score += idf * tfNorm
3
Phase 3 - Vektorisierte Kosinus-Ähnlichkeit und Kontext-Boost:

Numerische Vektoren werden über ein normalisiertes Skalarprodukt verglichen (calculateCosineSimilarity). Öffnet ein Besucher den Assistenten auf einer Projektseite (Active Case Study: IT-Magic), erhalten Chunks mit passendem currentProjectSlug einen deterministischen Boost von +18.0 Punkten.


Mechanismus 2: Multi-Turn-Konversationsgedächtnis und Anti-Wiederholungs-Zustandsautomat

Klassische zustandslose RAG-Chatbots scheitern oft an Folgefragen (*„Und welcher Stack kam dort zum Einsatz?“*, *„Welche Herausforderungen gab es?“*) oder wiederholen dieselben Einführungssätze mehrfach.

Unsere Engine in src/lib/ai/rag.ts löst dies über einen deterministischen Zustandsautomaten:

1
Entitätenauflösung im Verlauf (`resolveTargetProject` und `resolveBlogFromQueryOrContext`):

Erwähnt die aktuelle Nachricht kein explizites Projekt, analysiert die Engine options.history in umgekehrter chronologischer Reihenfolge, übernimmt das aktive Projekt oder den Blogpost und aktualisiert automatisch die Kontextleiste.

2
Aspektbasierte Extraktion (`detectProjectAspects`):

Der Synthesizer erkennt, ob der Nutzer nach dem Stack (technologies), der Architektur (architecture.rows), den Herausforderungen & Lösungen (challenges / solutions), den Metriken (detailMetrics) oder Links (liveUrl / githubUrl) fragt, und liefert präzise nur den angeforderten technischen Abschnitt.

3
Anti-Wiederholungs-Filter (`answeredQuestions`):

Jede beantwortete Frage wird in answeredQuestions erfasst. Dadurch filtert getContextualFollowUps() bereits behandelte Punkte heraus und schlägt den nächsten logischen Erkundungsschritt vor.


Mechanismus 3: Generative-UI-Orchestrierung im Chat-Stream

Statt nur reine Textblöcke auszugeben, analysiert ChatModal.tsx Intenterkennungen zusammen mit der RAG-Antwort und mountet interaktive React 19 Komponenten direkt in der Nachricht des Assistenten:

  • `ProjectToolCard` (`getRelevantProjectCards`): Visuelle Fallstudien-Karten mit WebP-Vorschaubildern, Kategorie-Badges, den Top-4-Technologien und Direktlinks zur Detailseite oder Live-Demo.
  • `StackComparisonCard` (`isStackComparisonQuery`): Aktiviert sich bei Anfragen wie *„Next.js vs. WordPress“* oder *„Welche Architektur wählen?“*. Rendert eine interaktive Tab-Matrix zum Vergleich von TCO, Time-to-Market, Core Web Vitals und idealen Einsatzbereichen zwischen Next.js 16, Headless WP und Custom PHP.
  • `ProjectEstimateCalculatorCard` (`isEstimateOrCalculatorQuery`): Interaktiver Echtzeit-Rechner, mit dem Projektumfang, Typ und KI-Module konfiguriert werden können, um Phasen und Lieferwochen zu kalkulieren.
  • `ContactActionCard` (`isHireOrContactQuery`): Zero-Trust-Kontaktkarte, die Base64-verschlüsselte Kanäle (E-Mail, WhatsApp, Telegram, LinkedIn) erst nach expliziter Nutzeraktion decodiert, ergänzt durch einen direkten PDF-Lebenslauf-Download.

Mechanismus 4: Synchronisation mit Next.js 16 App Router (213+ SSG-Routen) und GEO (llms.txt)

Als architektonische Fallstudie von `yusupovartur.com` demonstriert dieses System, wie Webplattform und KI-Engine eine gemeinsame Daten-Pipeline nutzen:

1
Statische Generierung in 3 Sprachen (`app/[locale]/projects/[slug]/page.tsx`):

Während des Builds durchläuft generateStaticParams() alle 71 Projekte und 9 Blog-Artikel in ['en', 'ua', 'es'] und rendert über 240 statische HTML-Seiten für das Vercel Edge Network vor.

2
Programmatisches SEO und strukturierte Schema.org JSON-LD Daten:

Jede Route erzeugt lokalisierte Metadaten, kanonische hreflang-Links (en, uk, es, x-default) und strukturierte JSON-LD-Graphen (Person, CreativeWork, TechArticle, BreadcrumbList).

3
Generative Engine Optimization (GEO - `/llms.txt` und `/llms-full.txt`):

Damit externe generative Suchmaschinen (ChatGPT Search, Perplexity, Claude, Google AI Overviews) verifizierte Daten über das Portfolio von Artur Yusupov zitieren, stellt die Domain strukturierte Markdown-Dateien nach dem llms.txt-Standard bereit.


4. Technisches Glossar: Präzise Erklärung aller Kernbegriffe

  • Hybrid RAG (Hybride Retrieval-Augmented Generation):
  • *Bedeutung:* Kombination aus exaktem lexikalischem Matching (Okapi BM25) und semantischer Vektorsuche (Kosinus-Ähnlichkeit) vor der KI-Antwortsynthese.
  • *Vorteil:* Eliminiert Halluzinationen und stellt höchste Präzision bei Technologienamen, Metriken und Fallstudien sicher.
  • Okapi BM25 (Best Matching 25):
  • *Bedeutung:* Probabilistischer Suchalgorithmus, der die Relevanz eines Dokuments basierend auf seltenen Suchbegriffen bewertet und die Dokumentlänge normalisiert.
  • *Vorteil:* Stellt sicher, dass spezifische technische Tokens wie WPGraphQL, useSyncExternalStore oder IT-Magic das exakte Zielprojekt an erster Stelle platzieren.
  • Damerau-Levenshtein-Distanz:
  • *Bedeutung:* Algorithmus zur Berechnung der minimalen Anzahl an Operationen (Einfügen, Löschen, Ersetzen oder Vertauschen benachbarter Zeichen), um eine Zeichenkette in eine andere zu überführen.
  • *Vorteil:* Bietet sofortige Tippfehlertoleranz sowohl im RAG-Assistenten als auch in der Portfolio-Suche.
  • Kosinus-Ähnlichkeit (Cosine Similarity):
  • *Bedeutung:* Mathematische Berechnung des Kosinus des Winkels zwischen zwei multidimensionalen Vektoren zur Messung der semantischen Nähe in unter 2ms.
  • *Vorteil:* Ermöglicht das konzeptionelle Erfassen der Nutzerabsicht in Deutsch, Englisch, Ukrainisch und Spanisch.
  • Generative UI:
  • *Bedeutung:* UI-Architekturmuster, bei dem der Assistent Antworten durch interaktive React-Komponenten (Rechner, Stack-Vergleiche, Projektkarten) direkt im Chatverlauf visualisiert.
  • *Vorteil:* Verwandelt einen reinen Chatbot in ein interaktives Tool zur B2B-Conversion.

5. Sicherheitsarchitektur nach dem Defense-in-Depth-Prinzip

Die Veröffentlichung der vollständigen Architektur von yusupovartur.com ist absolut sicher, da der Schutz auf kryptografischen und serverseitigen Kontrollen beruht, nicht auf Security-through-Obscurity:

1
IP-basiertes Rate-Limiting mit begrenztem LRU-Cache (`src/lib/ratelimit.ts`):

Der Endpunkt POST /api/chat erzwingt strikte IP-Kontingente (15 Anfragen pro Stunde), gestützt auf Upstash Redis in der Produktion und einen speicherbegrenzten LRU-Cache (5.000 Einträge), um RAM-Erschöpfung bei Flood-Attacken abzuwehren.

2
Schutz vor Prompt-Injection (`sanitizeUserPrompt`):

Alle eingehenden Nutzereingaben werden auf maximal 600 Zeichen begrenzt und auf typische Muster für Systemanweisungs-Umgehungen (ignore previous instructions, system:, <|im_start|>) bereinigt.

3
Keine Secrets auf dem Client & autonomer Fallback:

API-Schlüssel (OPENAI_API_KEY) liegen ausschließlich in verschlüsselten Umgebungsvariablen auf Vercel. Das Browser-Bundle enthält nur öffentliche Projektdaten und deterministische Rechenfunktionen.

4
Zero-Trust Base64-Verschleierung (`src/utils/contacts.ts`):

E-Mail, Telefonnummer, WhatsApp und Telegram werden niemals im Klartext im HTML oder SSR ausgeliefert; sie werden erst nach expliziter Nutzerinteraktion im Client aus Base64 dekodiert.

Praxiserprobter Produktiveinsatz

Wo diese Architektur produktiv eingesetzt wird

Diese Architekturmuster sind keine abstrakte Theorie - sie sind in den folgenden Live-Produkten vollständig implementiert und getestet:

Architekturberatung

Planen Sie eine Stack-Migration oder einen Neuaufbau?

Besprechen Sie Ihre Architekturanforderungen mit meinem interaktiven RAG-KI-Assistenten oder kontaktieren Sie mich direkt für eine technische Bewertung.

Direkt kontaktieren