RAG StepLab
In English. RAG StepLab is an interactive learning lab that makes every
step of a retrieval-augmented generation (RAG) pipeline visible on a real PDF,
with the evidence behind each result.
- Live app: https://rag-steplab.vercel.app (sign-in required; a fictional
sample PDF is one click away).
- What you can do: parse a PDF with Docling and inspect its structure and
OCR provenance, compare chunking strategies, create embeddings, ask questions
with dense/keyword/hybrid retrieval and optional reranking, trace the grounded
answer back to its citations, and evaluate runs against golden questions side
by side. The interface is available in English and Turkish.
- Screenshots: Ekran görüntüleri below.
- Run it locally: Yerel kurulum (Node.js, Python and a
Supabase project).
- License: MIT.
The rest of this README is in Turkish and is the canonical reference.
RAG'in her adımını gerçek dokümanınızla, kanıtıyla birlikte görün, değiştirin ve
karşılaştırın. RAG StepLab, geliştiricilerin retrieval-augmented generation
akışını aşama aşama incelediği etkileşimli bir öğrenme laboratuvarıdır.
Canlı uygulama: https://rag-steplab.vercel.app
Laboratuvar; doküman alımı ve parsing, chunking ve embedding, dense/keyword/
hybrid retrieval, isteğe bağlı reranking, grounded generation, citations,
evaluation ve run karşılaştırmasını kapsar.
Ekran görüntüleri
Görüntüler, CI ile aynı Linux ortamında üretilen görsel regresyon referanslarından
(e2e/visual/reference/production/overview.png, playground-answer-dark.png)
seçilir ve seeded demo verisini gösterir.
Ne görürsünüz
Sol menüdeki aşamalar gerçek bir PDF üzerinde sırayla ilerler; her aşama bir
öncekinin kalıcı çıktısını kullanır.
| Aşama | Ne görürsünüz |
|---|
| Overview | Seçili dokümanın pipeline yolculuğu, sıradaki adım ve örnek PDF ile ilk deneme |
| Documents | Yüklenen PDF'ler, önizleme ve doküman yönetimi |
| Parsing | Docling sonucu: sayfalar, başlıklar, tablolar, Markdown ve kaynak bölgeleri (native/OCR provenance, tanısal OCR skoru) |
| Chunking | Strateji ve ayara göre üretilen chunk'lar ve kaynak öğelere lineage bağlantısı |
| Embeddings | Embedding çalıştırmaları ve hazır olan indeks |
| Playground | Soru sorma: dense/keyword/hybrid retrieval, reranking, context, grounded cevap ve citations |
| Evaluation | Dataset, case bazlı metrikler ve iki run'ın yan yana karşılaştırması |
| Settings | Dil (TR/EN) ve görünüm (System/Light/Dark) tercihleri |
Run'lar ve provenance oturumlar arasında korunur. Downstream sonuç ancak gerekli
upstream lineage tamamlanmış ve uyumluysa kullanılabilir; reparse veya rechunk
sonrası eski downstream çıktıları kullanılmaz.
İlk deneme
Giriş yaptıktan sonra Overview'da Örnek PDF ile dene seçeneğini kullanın
veya kendi PDF'nizi ekleyin; ardından dokümanı Parse → Chunking → Embeddings
aşamalarında işleyip Playground ve Evaluation'a geçin. public/samples/
altındaki TR/EN kurgusal kent bisikleti PDF'leri normal upload ve gerçek
pipeline'ı kullanır; örnek düğmesi sahte parse, chunk veya cevap üretmez. Örnek
sorular yalnız seçili dokümanın SHA-256 değeri bu dosyalardan biriyle eşleşirse
gösterilir. Parse ve sonraki provider aşamaları servis erişimi gerektirir ve
maliyet doğurabilir.
Örnek PDF'lerin deterministik üretimi ve doğrulaması için
scripts/sample-fonts/README.md dosyasına
bakın; içerik değişirse lib/sample-documents.ts içindeki SHA-256 değerlerini
de güncelleyin.
Mimari
PDF → private Supabase Storage → queued parse → Modal API/worker
→ parse ve chunk lineage'ı → embeddings → retrieval/reranking
→ context ve generation → evaluation
Next.js arayüzü (Vercel) yalnız FastAPI RAG Core ile konuşur; FastAPI ve Docling
worker'ları Modal üzerinde çalışır, kalıcı veri Supabase PostgreSQL + pgvector ve
private Storage'dadır, embedding/generation/rerank/judge çağrıları Gemini'yedir.
Auth ve owner-scoped persistence kullanıcı verisini yalıtır. Retrieved document
metni modele verilmiş talimat değil, güvenilmeyen veridir. Kişisel veya hassas
PDF'leri public deployment'a yüklemeyin. Ayrıntılar:
docs/deployment.md.
Yerel kurulum
Gereksinimler: Node.js 22 (CI'daki sürüm), Python 3.13
(.python-version) ve bir Supabase projesi. Uygulamadaki tüm
rotalar giriş ister ve tek giriş yöntemi Google'dır; bu yüzden Google provider'ı
etkin ve http://localhost:3000/auth/callback redirect URL'sine izin veren bir
Supabase Auth (hosted proje ya da supabase start ile local stack) gerekir.
-
Frontend bağımlılıklarını kurun ve environment şablonunu kopyalayın:
npm install
Copy-Item .env.example .env
-
.env içinde en az NEXT_PUBLIC_SUPABASE_URL,
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY ile backend'in JWT doğrulaması için
SUPABASE_URL değerlerini kendi Supabase projenizle doldurun.
SUPABASE_JWT_ISSUER ve SUPABASE_JWT_JWKS_URL şablonda <project-ref>
placeholder'ı taşır ve doluysa SUPABASE_URL'den türetilen değerlerin önüne
geçer; bunları aynı proje adresiyle güncelleyin ya da boş bırakın. Değişken
açıklamaları .env.example içindedir; secret'ları source control'a eklemeyin.
-
Backend'i kurun (virtual environment, bağımlılıklar, OCR modelleri, kalıcı
Supabase/Gemini seçenekleri): backend/README.md.
-
Frontend ve (API adresi local ise) FastAPI'yi birlikte başlatın:
npm run dev
Uygulama http://localhost:3000 adresinde açılır; giriş (ilk girişte hesap
oluşturma dahil) Supabase Auth üzerinden Google ile devam et ile yapılır.
NEXT_PUBLIC_API_BASE_URL hosted bir API'yi
gösteriyorsa yalnız frontend başlar; seçim ayrıntıları
backend/README.md içindedir.
Proje kaynakları
Sınırlar
RAG StepLab bir öğrenme laboratuvarıdır; üretim RAG ürünü ya da doğruluk
garantisi veren bir değerlendirme sistemi değildir. OCR confidence ve
citation geçerliliği gibi skorlar tanısaldır, doğruluk kanıtı değildir.
Seeded testler hosted provider kalitesini kanıtlamaz; gerçek Docling, Gemini ve
corpus davranışı ayrı yetkili doğrulama gerektirir.
Lisans
MIT.
