Tutorial: RAG-Pipeline mit Postgres und pgvector

Die Pipeline erfolgt in fünf Stufen. Bei der Aufnahme wird der Text zerschnitten, jeder Block wird stapelweise vektorisiert und dann gespeichert. Bei der Abfrage wird die Frage der Reihe nach vektorisiert, mit den durch Kosinusähnlichkeit gespeicherten Blöcken verglichen und die nächstgelegenen Schnipsel werden in die an das Generierungsmodell gesendete Eingabeaufforderung eingefügt.

Chunking (tiktoken)→Einbettungen (Batch)→pgvector storage (HNSW)→Ähnlichkeitssuche→Erweiterte Generierung

Ein architektonisches Detail, das in der Produktion von Bedeutung ist: Bei Netzwerkanrufen an den Einbettungs- oder Generierungsanbieter wird keine Postgres-Verbindung aufrechterhalten. Die DB-Transaktion wird vor dem externen Aufruf geschlossen und danach erneut geöffnet, um niemals ein gemeinsam genutztes PgBouncer-Backend für Netzwerklatenz von Drittanbietern zu blockieren.

Im Gegensatz zu einem typischen selbstgehosteten pgvector müssen Sie für diese Pipeline weder CREATE EXTENSION vector ausführen noch selbst eine Tabelle erstellen. Das embeddings-Schema des Projekts mit seinen Vektorspalten und HNSW-Indizes wird automatisch bereitgestellt, wenn das Projekt erstellt wird.

# Aurabase-Konto + CLI
npm i -g @aurabase/cli
aura login

# Erstellen Sie das Projekt und verknüpfen Sie es mit diesem Ordner
aura projects create mon-assistant --engine postgres
aura link --project-id <uuid-du-projet>

# Rufen Sie die API-Schlüssel des verknüpften Projekts ab
aura projects api-keys

Der Einbettungsanbieter wird einmalig auf Projektseite konfiguriert (Studio → IA → Lieferanten). Es ist dieser Anbieter, der die effektive Dimension Ihrer Vektoren bestimmt, also die Spalte, die in der Tabelle embeddingsverwendet wird.

Ein Aufruf reicht aus, um ein Dokument zu indizieren: Der Text wird in Blöcke unterteilt, jeder Block wird vektorisiert und dann im angeforderten Namensraum gespeichert. Die Aufteilung verwendet einen echten Tokenizer (tiktoken, Kodierung o200k_base), keine einfache Aufteilung nach Leerzeichen, die bei Text ohne Leerzeichen wie in einigen asiatischen Sprachen korrekt bleibt.

import { aura } from '@/lib/aurabase'

export async function POST(req: Request) {
  const { content, metadata } = await req.json()

  const { data, error } = await aura.ai.ragIngest({
    namespace: 'docs-produit',
    content,
    metadata,
  })

  if (error) return Response.json({ error }, { status: 400 })
  return Response.json(data) // { id, chunks }
}

In rohem HTTP ist die entsprechende Route POST /v1/ai/{project_id}/rag/ingest, authentifiziert durch den API-Schlüssel des Projekts.

curl -X POST https://<votre-gateway>/v1/ai/<project_id>/rag/ingest \
  -H "apikey: <votre-cle-api>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "docs-produit",
    "content": "Le texte complet de votre document ici...",
    "metadata": { "source": "guide-utilisateur.pdf" }
  }'

Die Aufnahme ist standardmäßig idempotent: Eine Dokumentkennung wird automatisch abgeleitet (SHA-256-Hash des Inhalts oder metadata.document_id, wenn Sie ihn angeben). Durch die erneute Einbindung desselben Inhalts werden dessen vorhandene Blöcke ersetzt, anstatt sie zu duplizieren, sodass ein regelmäßiger Synchronisierungsauftrag sicher wiederholt werden kann.

Hier gibt es keine proprietäre Magie: Die Tabelle, die Ihre Vektoren empfängt, ist eine gewöhnliche Postgres-Tabelle mit einer vector-Spalte pro Dimensionsklasse und einem partiellen HNSW-Index pro Spalte (aktiv nur für die Zeilen, die sie füllen). Hier ist die tatsächliche Definition, vereinfacht:

create table embeddings (
  id               uuid primary key default gen_random_uuid(),
  project_id       text not null,
  namespace        text not null,
  content          text not null,
  embedding_768    vector(768),
  embedding_1536   vector(1536),
  embedding_3072   vector(3072),
  embedding_model  text,
  dims             int,
  metadata         jsonb default '{}'::jsonb,
  created_at       timestamptz not null default now()
);

-- Ein partieller HNSW-Index nach Dimensionsklasse
create index idx_embeddings_vec_1536 on embeddings
  using hnsw (embedding_1536 vector_cosine_ops)
  where embedding_1536 is not null;

-- Über 2000 Dimensionen hinaus unterstützt HNSW den Vektortyp nicht:
-- in Halbvec gegossen für Baureihe 3072
create index idx_embeddings_vec_3072 on embeddings
  using hnsw ((embedding_3072::halfvec(3072)) halfvec_cosine_ops)
  where embedding_3072 is not null;

Bei jeder Suche werden die Vektoren mit dem Kosinus-Abstandsoperator (<=>) verglichen, auf den die Operatorklassen vector_cosine_ops und halfvec_cosine_ops des Index abzielen. Einzelheiten zu den Recall-/Latenz-Kompromissen von HNSW gegenüber IVFFlat finden Sie im Artikel zur HNSW-Indizierung. Für die Wahl der Einbettungsdimension selbst siehe den Vergleich 768 vs 1536 vs 3072.

Auf der Abfrageseite verkettet rag() die Vektorisierung der Frage, die Suche nach Ähnlichkeit im Namespace, die Konstruktion des erweiterten Prompts und den Aufruf des Generierungsmodells in einem einzigen Netzwerk-Roundtrip auf der Client-Seite.

import { aura } from '@/lib/aurabase'

export async function POST(req: Request) {
  const { question } = await req.json()

  const { data, error } = await aura.ai.rag({
    question,
    namespace: 'docs-produit',
  })

  if (error) return Response.json({ error }, { status: 400 })
  return Response.json(data)
}

Die Antwort enthält die generierte Antwort und ihre Quellen sowie den tatsächlich verwendeten Anbieter:

{
  "data": {
    "answer": "D'après la documentation, ...",
    "sources": [
      { "id": "...", "content": "...", "similarity": 0.87 }
    ],
    "model": "claude-3-5-sonnet",
    "tokens": 412,
    "provider": "anthropic",
    "fallback_used": false
  }
}

Der abgerufene Inhalt wird niemals roh in die Systemeingabeaufforderung eingefügt. Hierbei handelt es sich um unzuverlässige Daten (Benutzer-Upload, indizierte Seite): Ein Dokument, das beispielsweise ein Schlussabschnitts-Tag gefolgt von falschen Anweisungen enthält, wird vor dem Zusammensetzen neutralisiert, seine spitzen Klammern werden durch Klammern ersetzt, der Text bleibt erhalten, die Struktur wird jedoch entschärft.

Wenn Sie mit LangChain bereits einen RAG-Chatbot auf PostgreSQL erstellt haben, verfügt jeder manuelle Baustein hier über ein serverseitig verwaltetes Äquivalent, ohne die zugrunde liegende Datenbank zu ändern.

Migrieren Sie ein bestehendes, auf Supabase erstelltes Projekt mit dieser Art der manuellen Montage? Die Migrationslogik für den Rest des Backends (Schema, RLS-Richtlinien, SDK) wird in unserem Migrationsleitfaden von Supabase zu Aurabasebehandelt.

Three settings directly affect cost and latency, all verified in the aura-aiservice code. The number of attempts on a transient embedding call (network failure, provider error 429) is 3 by default, with a base backoff of 100 ms. Große Dokumente werden standardmäßig in Teilstapel eingebettet, die auf 2048 Blöcke begrenzt sind, um die API-Obergrenzen der Lieferanten zu respektieren, ohne dass es bei einem einzigen riesigen Dokument zu Fehlern kommt. Eine Leitplanke (standardmäßig 10.000 Blöcke, konfigurierbar) lehnt explizit die Aufnahme eines Dokuments ab, das eine abweichende Anzahl von Blöcken erzeugen würde.

Auf der Suchseite passt sich die Größe der HNSW-Kandidatenliste automatisch an max(64, top_k × 4)an: Je mehr Ergebnisse Sie anfordern, desto mehr Kandidaten werden vom Index untersucht, um die Erinnerung zu wahren. A fixed value remains possible via an environment variable if your corpus has a particular profile.

Die Vektorräume verschiedener Modelle werden niemals miteinander verglichen: Jede Suche bleibt auf das aktuelle Einbettungsmodell beschränkt, und ein Wechsel der Modelle erfordert eine explizite Neuindizierung und nicht einen stillen Wechsel, der die Konsistenz der Ergebnisse beeinträchtigen würde.

Die Einbettungsdimension muss in eine der drei unterstützten Klassen fallen: 768, 1536 oder 3072. Ein Anbieter, der eine andere Dimension zurückgibt, wird mit einem expliziten Fehler abgelehnt, niemals abgeschnitten oder stillschweigend umgewandelt.

Die Einbettungsgenerierung ist bei den drei nativen Anbietern nur über OpenAI oder Google Gemini verfügbar: Anthropic/Claude stellt keine öffentliche Einbettungs-API zur Verfügung, daher wird sie nur zum Generieren der endgültigen Antwort in dieser Pipeline verwendet, niemals zur Vektorisierung.

Das JavaScript SDK stellt die Überschreibungen top_k und threshold beim rag()-Aufruf noch nicht zur Verfügung: Sie bleiben im direkten HTTP zugänglich und auf [1, 50] bzw. [0, 1] beschränkt, jedoch nicht wie heute über aura.ai.rag(). The default similarity threshold (0.3) is deliberately permissive; narrow it down to a dense corpus to avoid irrelevant sources in the prompt.

The RAG covers questions on unstructured content (documents, notes, tickets). For questions about your relational data, Aurabase's native NL2SQL directly translates a question into validated SQL. For details of the HNSW parameters and dimension classes mentioned above, see the article on HNSW indexing and the comparison of embedding dimensions. The full API reference remains the RAG & pgvector documentation and the AI Gateway documentation.