Samouczek: Potok RAG z Postgres i pgvector

Rurociąg przebiega w pięciu etapach. Po spożyciu tekst jest cięty, każdy fragment jest wektoryzowany wsadowo, a następnie przechowywany. Podczas wykonywania zapytania pytanie jest kolejno wektoryzowane w porównaniu z fragmentami przechowywanymi na podstawie podobieństwa cosinus, a najbliższe fragmenty są wstrzykiwane do podpowiedzi wysyłanej do modelu generującego.

Porcjowanie (tiktoken) → Osadzanie (wsadowo) → Magazyn pgvector (HNSW) → Wyszukiwanie podobieństwa → Generowanie rozszerzone

Detal architektoniczny mający znaczenie w produkcji: podczas połączeń sieciowych z dostawcą osadzania lub generowania nie jest utrzymywane żadne połączenie Postgres. Transakcja DB zamyka się przed połączeniem zewnętrznym i otwiera się ponownie po, aby nigdy nie blokować współdzielonego backendu PgBouncer ze względu na opóźnienia w sieci innej firmy.

W przeciwieństwie do typowego pgvectora, który jest hostowany samodzielnie, nie musisz uruchamiać CREATE EXTENSION vector ani samodzielnie tworzyć tabeli dla tego potoku. Schemat embeddings projektu z kolumnami wektorowymi i indeksami HNSW jest udostępniany automatycznie podczas tworzenia projektu.

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

# Utwórz projekt i połącz go z tym folderem
aura projects create mon-assistant --engine postgres
aura link --project-id <uuid-du-projet>

# Pobierz klucze API połączonego projektu
aura projects api-keys

Dostawca osadzania konfigurowany jest jednorazowo, po stronie projektu (Studio → IA → Dostawcy). To właśnie ten dostawca określa efektywny wymiar Twoich wektorów, a zatem kolumnę używaną w tabeli embeddings.

Do zaindeksowania dokumentu wystarczy jedno wywołanie: tekst jest dzielony na fragmenty, każdy fragment jest wektoryzowany, a następnie zapisywany w żądanej przestrzeni nazw. Przy podziale używany jest prawdziwy tokenizer (tiktoken, kodowanie o200k_base), a nie proste dzielenie spacjami, które pozostaje poprawne w przypadku tekstu bez spacji, jak w niektórych językach azjatyckich.

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) // { identyfikator, kawałki }
}

W surowym protokole HTTP równoważna trasa to POST /v1/ai/{project_id}/rag/ingest, uwierzytelniana za pomocą klucza API projektu.

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" }
  }'

Pozyskiwanie jest domyślnie idempotentne: identyfikator dokumentu jest generowany automatycznie (skrót SHA-256 treści lub metadata.document_id, jeśli go podasz). Ponowne wykorzystanie tej samej treści powoduje zastąpienie jej istniejących fragmentów zamiast ich duplikowania, dzięki czemu okresowe zadanie synchronizacji można bezpiecznie odtwarzać.

Nie ma tu żadnej zastrzeżonej magii: tabela, która odbiera twoje wektory, jest zwykłą tabelą Postgres, z jedną kolumną vector na klasę wymiaru i częściowym indeksem HNSW na kolumnę (aktywnym tylko w wierszach, które ją zapełniają). Oto jego prawdziwa definicja, uproszczona:

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()
);

-- Częściowy indeks HNSW według klasy wymiaru
create index idx_embeddings_vec_1536 on embeddings
  using hnsw (embedding_1536 vector_cosine_ops)
  where embedding_1536 is not null;

-- Poza wymiarami 2000 HNSW nie obsługuje typu wektorowego:
-- odlany w halfvec dla klasy 3072
create index idx_embeddings_vec_3072 on embeddings
  using hnsw ((embedding_3072::halfvec(3072)) halfvec_cosine_ops)
  where embedding_3072 is not null;

Każde wyszukiwanie porównuje wektory z cosinusowym operatorem odległości (<=>), będącym celem klas operatorów vector_cosine_ops i halfvec_cosine_ops indeksu. Aby uzyskać szczegółowe informacje na temat kompromisów w zakresie wycofania/opóźnienia HNSW w porównaniu z IVFFlat, zobacz artykuł poświęcony indeksowaniu HNSW. Aby wybrać sam wymiar osadzania, zobacz porównanie 768 vs 1536 vs 3072.

Po stronie zapytania rag() łączy wektoryzację pytania, wyszukiwanie według podobieństwa w przestrzeni nazw, konstrukcję rozszerzonego znaku zachęty i wywołanie modelu generacji w ramach jednej operacji sieciowej po stronie klienta.

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)
}

Odpowiedź zawiera wygenerowaną odpowiedź i jej źródła, z faktycznie wykorzystanym dostawcą:

{
  "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
  }
}

Pobrana treść nigdy nie jest wstrzykiwana w postaci surowej do zachęty systemowej. Są to dane niewiarygodne (przesłane przez użytkownika, strona zindeksowana): dokument zawierający np. znacznik sekcji zamykającej, po którym następują fałszywe instrukcje, jest przed montażem neutralizowany, nawiasy ostrokątne zastąpione nawiasami ostrokątnymi, tekst zachowany, ale pozbawiona struktury.

Jeśli zbudowałeś już chatbota RAG na PostgreSQL z LangChain, każdy ręczny klocek ma tutaj odpowiednik zarządzany po stronie serwera, bez zmiany podstawowej bazy danych.

Czy migrujesz istniejący projekt zbudowany na Supabase z tego rodzaju ręcznym montażem? Logikę migracji pozostałej części backendu (schemat, zasady RLS, SDK) omówiono w naszym przewodniku migracji Supabase do Aurabase.

Trzy ustawienia bezpośrednio wpływają na koszt i opóźnienia, wszystkie weryfikowane w kodzie usługi aura-ai. Liczba prób tymczasowego połączenia osadzającego (awaria sieci, błąd dostawcy 429) wynosi domyślnie 3, z podstawowym opóźnieniem wynoszącym 100 ms. Duże dokumenty są domyślnie umieszczane w podpartiach ograniczonych do 2048 fragmentów, aby przestrzegać pułapów API dostawców bez utraty pojedynczego, ogromnego dokumentu. Poręcz (domyślnie 10 000 fragmentów, konfigurowalna) wyraźnie odrzuca przyjęcie dokumentu, który wygenerowałby nieprawidłową liczbę fragmentów.

Po stronie wyszukiwania rozmiar listy kandydatów HNSW automatycznie dostosowuje się do max(64, top_k × 4): im więcej żądanych wyników, tym więcej kandydatów bada indeks, aby zachować ich zapamiętanie. Stała wartość pozostaje możliwa poprzez zmienną środowiskową, jeśli korpus ma określony profil.

Przestrzenie wektorowe różnych modeli nigdy nie są ze sobą porównywane: każde wyszukiwanie ogranicza się do bieżącego modelu osadzania, a zmiana modeli wymaga jawnego ponownego indeksowania, a nie cichego przełącznika, który zakłóciłby spójność wyników.

Wymiar osadzania musi należeć do jednej z trzech obsługiwanych klas: 768, 1536 lub 3072. Dostawca, który zwraca inny wymiar, jest odrzucany z jawnym błędem, nigdy nie jest obcinany ani dyskretnie rzutowany.

Generowanie osadzania jest dostępne tylko za pośrednictwem OpenAI lub Google Gemini wśród trzech natywnych dostawców: Anthropic/Claude nie udostępnia publicznego interfejsu API osadzania, więc jest używany tylko do generowania ostatecznej odpowiedzi w tym potoku, nigdy do wektoryzacji.

JavaScript SDK nie udostępnia jeszcze przesłonięć top_k i threshold w wywołaniu rag(): pozostają one dostępne w bezpośrednim HTTP, z ograniczeniem odpowiednio do [1, 50] i [0, 1], ale nie z aura.ai.rag(), jak ma to miejsce obecnie. Domyślny próg podobieństwa (0,3) jest celowo liberalny; zawęź go do gęstego korpusu, aby uniknąć nieistotnych źródeł w podpowiedzi.

Wytyczne obejmują pytania dotyczące treści nieustrukturyzowanych (dokumenty, notatki, bilety). W przypadku pytań dotyczących danych relacyjnych natywna wersja Aurabase NL2SQL bezpośrednio tłumaczy pytanie na zatwierdzony kod SQL. Szczegóły dotyczące parametrów HNSW i klas wymiarów wymienionych powyżej można znaleźć w artykule na temat indeksowania HNSW i porównaniu wymiarów osadzania. Pełną dokumentacją API pozostaje dokumentacja RAG i pgvector i dokumentacja AI Gateway.