RAG pipeline — chunking, vektör depoları, GraphRAG

@gnldev/rag, bir bilgi tabanını agent'ın çağırabileceği bir tool'a dönüştürür. Kritik fark: RAG tool'u runDurable içinde kullanıldığında sonucu journal'lanır → resume/replay'de aynı dokümanlar döner, yeni embed/query çağrısı yapılmaz (exactly-once RAG) — bir kez koşmuş bir getirme, yeniden çağrılmak yerine journal'dan oynatılır.

Hat üç parçadan oluşur: (1) chunking — ham metin/dokümanları parçalara böler; (2) vektör store — bellek içi, dayanıklı Postgres/pgvector, bir Qdrant, Chroma ya da Weaviate sunucusu veya benzerlik grafı (GraphRAG); (3) createRagTool — embed + query + opsiyonel rerank'i tek tool'ta paketler.

chunkText ham metni parçalara böler; üç strateji: recursive (varsayılan — paragraf → satır → cümle → kelime sınırlarını tercih ederek böler), markdown (başlık hiyerarşisine göre bölümler; her parçaya heading breadcrumb metadata'sı ekler) ve character (sabit pencere). Ardışık parçalar overlap ile örtüşür (bağlam sürekliliği).

chunkDocuments ise VectorDoc'ları bölüp indexDocuments'a hazır liste üretir. Parça id'si <docId>#<i> — deterministik, böylece yeniden indexleme aynı id'lere upsert eder, çift kayıt üretmez. Tek parçaya sığan doküman bölünmeden geçer (gereksiz #0 türetimi yok).

import { chunkDocuments, indexDocuments, InMemoryVectorStore } from '@gnldev/rag';

const chunks = chunkDocuments(docs, {
  size: 1200, overlap: 120, strategy: 'markdown',
});
// chunks[i].id === 'guide#3', metadata: { source: 'guide', chunk: 3, heading: 'Kurulum > Docker' }

const store = new InMemoryVectorStore();
await indexDocuments(store, chunks, embed);

PostgresVectorStoreile InMemoryVectorStore aynı arayüzü pgvector üzerinde kalıcı olarak sunar — enjekte edilebilir bir pool alır, pg sürücüsünü lazy yükler, HNSW veya ivfflat indeksi destekler. Böylece gerçek müşteri projelerinde bilgi tabanı yeniden başlatmalar arası kalıcıdır.

import { PostgresVectorStore, createRagTool } from '@gnldev/rag';
import { Pool } from 'pg';

const store = new PostgresVectorStore({
  pool: new Pool({ connectionString: process.env.DATABASE_URL }),
  dimension: 1536,
  index: 'hnsw',
});
await store.upsert(items); // the same signature as InMemory

Vektörleriniz ayrı bir vektör veritabanında duruyorsa, beş depo onları sunucunun REST API'si üzerinden orada tutar, ek paket gerekmez: QdrantVectorStore, ChromaVectorStore (Chroma 1.x), WeaviateVectorStore (Weaviate 1.x), ElasticsearchVectorStore (Elasticsearch 9.x) ve OpenSearchVectorStore (OpenSearch 3.x). Her çağrının bir süre sınırı var (timeoutMs, varsayılan 30 sn). Koleksiyon ilk yazmada, o yazmanın vektör uzunluğuyla (ya da dimension ile) kurulur; API anahtarı bir başlıkta gider, hiçbir hata mesajına girmez.

import { QdrantVectorStore, ChromaVectorStore, WeaviateVectorStore, ElasticsearchVectorStore, OpenSearchVectorStore } from '@gnldev/rag';

const qdrant = new QdrantVectorStore({ url: 'https://qdrant.internal:6333', apiKey: process.env.QDRANT_API_KEY });
const chroma = new ChromaVectorStore({ url: 'http://chroma.internal:8000', apiKey: process.env.CHROMA_TOKEN });
const weaviate = new WeaviateVectorStore({ url: 'https://weaviate.internal:8080', apiKey: process.env.WEAVIATE_API_KEY });
const es = new ElasticsearchVectorStore({ url: 'https://es.internal:9200', apiKey: process.env.ES_API_KEY });
const os = new OpenSearchVectorStore({ url: 'https://opensearch.internal:9200', auth: { username: 'gnl', password: process.env.OPENSEARCH_PASSWORD! } });
// each: createRagTool({ store: weaviate, embed })

Hepsi diğer depolarla aynı kurallara uyar ve aynı 20 senaryoluk vektör setiyle ölçülür: sahip, namespace ve paylaşım her kaydın id'sinin parçasıdır, bu yüzden bir yazma başka bir sahibin belgesini ele geçiremez, iki süreç yarışsa bile; filtre sıralamadan önce daraltır; top-K sınırındaki eşit skorlar bütünüyle okunup id'ye göre sıralanır. Sonuncusu Chroma ve Weaviate'te emek ister: aramaları yaklaşıktır ve aynı vektörün bazı kopyalarını kaçırır (Weaviate: limit 4.000 iken 3.000 kopyanın 2.974'ü), bu yüzden eşitlik tam olarak okunur.

GraphRag, parçalar arası bir benzerlik grafı arasındaki (graph-retrieval deseni, her şeyle aynı journal'ın üstünde GraphRAG paritesi). Düz vektör aramasının kaçırdığını yakalar: sorguya doğrudan benzemeyen ama sorguya benzeyen parçalarla güçlü bağlantılı parçalar (dolaylı ilgi) da sonuçlara katılır. VectorStore arayüzünü implemente ettiğinden createRagTool'a drop-in'dir.

Parametreler: threshold (kenar eşiği, varsayılan 0.75), hops (komşu genişletme derinliği, varsayılan 1; 0 = düz vektör araması), decay (hop başına skor zayıflatma, varsayılan 0.7) ve seeds (genişletmeye tohum olan doğrudan sonuç sayısı, varsayılan 4). Bir düğüme birden çok yoldan ulaşılırsa en yüksek skoru korunur; eşit skorda id ile deterministik sıra.

import { GraphRag, createRagTool } from '@gnldev/rag';

const graph = new GraphRag({ threshold: 0.75, hops: 1, decay: 0.7, seeds: 4 });
await graph.upsert(items); // edges are built incrementally

const ragTool = createRagTool({ store: graph, embed, topK: 6 });

createRagTool embed + store.query + opsiyonel rerank'i tek tool'ta paketler. Herhangi bir VectorStore (InMemory / Postgres / Qdrant / Chroma / Weaviate / GraphRag) ile çalışır. runDurable içinde durableTool sonucu journal'ladığından resume'da aynı dokümanlar döner; yeni embed/query/rerank çağrısı koşmaz.