Öğretici: Postgres ve pgvector ile RAG ardışık düzeni

Boru hattı beş aşamada gerçekleşir. Alındıktan sonra metin kesilir, her bir parça toplu olarak vektörleştirilir ve ardından saklanır. Sorgulamanın ardından soru, kosinüs benzerliğine göre depolanan parçalarla karşılaştırılarak vektörleştirilir ve en yakın parçacıklar, üretim modeline gönderilen istemin içine enjekte edilir.

Parçalama (tiktoken)→Gömmeler (toplu)→pgvector depolama (HNSW)→Benzerlik arama→Artırılmış üretim

Üretimde önemli olan bir mimari ayrıntı: Yerleştirme veya oluşturma sağlayıcısına yapılan ağ çağrıları sırasında hiçbir Postgres bağlantısı yapılmaz. Veritabanı işlemi, üçüncü taraf ağ gecikmesi nedeniyle paylaşılan bir PgBouncer arka ucunu asla engellememek için harici çağrıdan önce kapanır ve sonrasında yeniden açılır.

Tipik bir kendi kendine barındırılan pgvektörün aksine, bu işlem hattı için CREATE EXTENSION vector çalıştırmanıza veya kendiniz bir tablo oluşturmanıza gerek yoktur. Projenin embeddings şeması, vektör sütunları ve HNSW dizinleriyle birlikte, proje oluşturulduğunda otomatik olarak sağlanır.

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

# Projeyi oluşturun ve bu klasöre bağlayın
aura projects create mon-assistant --engine postgres
aura link --project-id <uuid-du-projet>

# Bağlantılı projenin API anahtarlarını alın
aura projects api-keys

Yerleştirme sağlayıcısı proje tarafında bir kez yapılandırılır (Stüdyo → IA → Tedarikçiler). Vektörlerinizin etkili boyutunu belirleyen bu sağlayıcıdır, dolayısıyla embeddingstablosunda kullanılan sütun.

Bir belgeyi indekslemek için bir çağrı yeterlidir: metin parçalara bölünür, her parça vektörleştirilir ve ardından istenen ad alanında saklanır. Bölme işlemi, boşluklara göre basit bir bölme değil, gerçek bir belirteç (tiktoken, kodlama o200k_base) kullanır; bu, bazı Asya dilleri gibi boşluk içermeyen metinlerde doğru kalır.

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) // { kimlik, parçalar }
}

Ham HTTP'de eşdeğer yol, projenin API anahtarıyla doğrulanan POST /v1/ai/{project_id}/rag/ingestşeklindedir.

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

Besleme varsayılan olarak önemsizdir: bir belge tanımlayıcısı otomatik olarak türetilir (içeriğin SHA-256 karması veya siz sağlarsanız metadata.document_id). Aynı içeriğin yeniden kullanılması, onları kopyalamak yerine mevcut parçaların yerini alır ve periyodik senkronizasyon işinin yeniden oynatılmasını güvenli hale getirir.

Burada özel bir sihir yok: vektörlerinizi alan tablo, boyut sınıfı başına bir vector sütunu ve sütun başına kısmi bir HNSW dizini (yalnızca onu dolduran satırlarda etkin) içeren sıradan bir Postgres tablosudur. İşte basitleştirilmiş gerçek tanımı:

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

-- Boyut sınıfına göre kısmi bir HNSW dizini
create index idx_embeddings_vec_1536 on embeddings
  using hnsw (embedding_1536 vector_cosine_ops)
  where embedding_1536 is not null;

-- 2000 boyutun ötesinde HNSW vektör türünü desteklemez:
-- sınıf 3072 için halfvec'te döküm
create index idx_embeddings_vec_3072 on embeddings
  using hnsw ((embedding_3072::halfvec(3072)) halfvec_cosine_ops)
  where embedding_3072 is not null;

Her arama, vektörleri, endeksin vector_cosine_ops ve halfvec_cosine_ops operatör sınıfları tarafından hedeflenen kosinüs mesafe operatörü (<=>) ile karşılaştırır. HNSW ve IVFFlat arasındaki geri çağırma/gecikme dengelemelerinin ayrıntıları için HNSW indekslemeye adanmış makaleye bakın. Gömme boyutunun seçimi için 768 ile 1536 ile 3072 arasındaki karşılaştırmaya bakın.

Sorgu tarafında, rag() sorunun vektörleştirilmesini, ad alanındaki benzerliğe göre aramayı, genişletilmiş istemin oluşturulmasını ve üretim modeline çağrıyı istemci tarafında tek bir ağ gidiş-dönüşünde zincirler.

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

Yanıt, oluşturulan yanıtı ve kaynaklarını, gerçekte kullanılan sağlayıcıyla birlikte taşır:

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

Alınan içerik hiçbir zaman sistem istemine ham olarak enjekte edilmez. Bu güvenilmez bir veridir (kullanıcı yüklemesi, indekslenmiş sayfa): örneğin bir kapanış bölümü etiketi ve ardından yanlış talimatlar içeren bir belge, montajdan önce nötrleştirilir, köşeli ayraçlar köşeli ayraçlarla değiştirilir, metin korunur ancak yapısı etkisiz hale getirilir.

LangChain ile PostgreSQL'de zaten bir RAG sohbet robotu oluşturduysanız, her manuel tuğlanın burada, temeldeki veritabanını değiştirmeden, sunucu tarafında yönetilen bir eşdeğeri bulunur.

Supabase üzerinde kurulu mevcut bir projeyi bu tür bir manuel montajla mı taşıyorsunuz? Arka ucun geri kalanına (şema, RLS politikaları, SDK) ilişkin geçiş mantığı, Supabase'den Aurabase'e geçiş kılavuzumuzdaele alınmıştır.

Üç ayar doğrudan maliyeti ve gecikmeyi etkiler; tümü aura-aihizmet kodunda doğrulanır. Geçici bir ekleme çağrısındaki (ağ hatası, sağlayıcı hatası 429) deneme sayısı varsayılan olarak 3'tür ve temel geri çekilme 100 ms'dir. Büyük belgeler, tek bir büyük belgede hata olmadan tedarikçilerin API tavanlarına uymak için varsayılan olarak 2048 parçayla sınırlı alt gruplara yerleştirilir. Bir korkuluk (varsayılan olarak 10.000 parça, yapılandırılabilir), anormal sayıda parça üretecek bir belgenin alımını açıkça reddeder.

Arama tarafında, HNSW aday listesinin boyutu otomatik olarak max(64, top_k × 4)olarak ayarlanır: ne kadar çok sonuç talep ederseniz, dizin hatırlanmayı korumak için o kadar çok aday araştırır. Derleminizin belirli bir profili varsa, ortam değişkeni yoluyla sabit bir değer mümkün olmaya devam eder.

Farklı modellerin vektör uzayları hiçbir zaman birbiriyle karşılaştırılmaz: her arama mevcut yerleştirme modeliyle sınırlı kalır ve modelleri değiştirmek, sonuçların tutarlılığını bozacak sessiz bir geçiş yerine açık bir yeniden indeksleme gerektirir.

Gömme boyutu, desteklenen üç sınıftan birine girmelidir: 768, 1536 veya 3072. Başka bir boyut döndüren bir sağlayıcı, açık bir hatayla reddedilir, hiçbir zaman kesilmez veya sessizce dönüştürülmez.

Gömme oluşturma, üç yerel sağlayıcı arasında yalnızca OpenAI veya Google Gemini aracılığıyla mümkündür: Anthropic/Claude genel bir yerleştirme API'si sunmaz, bu nedenle yalnızca bu ardışık düzende son yanıtı oluşturmak için kullanılır, asla vektörleştirme için kullanılmaz.

JavaScript SDK'sı, rag() çağrısındaki top_k ve threshold geçersiz kılmalarını henüz açığa çıkarmaz: Bunlara doğrudan HTTP'de erişilebilir kalır, sırasıyla [1, 50] ve [0, 1] ile sınırlıdır, ancak bugün olduğu gibi aura.ai.rag()'den erişilemez. Varsayılan benzerlik eşiği (0,3) kasıtlı olarak hoşgörülüdür; Bilgi isteminde alakasız kaynaklardan kaçınmak için onu yoğun bir külliyatla daraltın.

RAG, yapılandırılmamış içerik (belgeler, notlar, biletler) hakkındaki soruları kapsar. İlişkisel verilerinizle ilgili sorularınız için Aurabase'in yerel NL2SQL, soruyu doğrudan doğrulanmış SQL'e çevirir. Yukarıda belirtilen HNSW parametreleri ve boyut sınıflarının ayrıntıları için HNSW indeksleme hakkındaki makaleye ve yerleştirme boyutlarının karşılaştırması'ye bakın. Tam API referansı, RAG ve pgvector belgeleri ve AI Ağ Geçidi belgeleriolarak kalır.