RAG hattı — chunking, pgvector, 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, kalıcı Postgres/pgvector 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

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 / 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.