rag-pipeline-lib 0.2.0

Production-grade RAG: BGE-M3 + FAISS + BM25 + RRF + Reranker + HyDE

RAG Pipeline v2.0

Production-grade Retrieval-Augmented Generation pipeline.

Mimari

Sorgu
  │
  ├─► HyDE (Query Expansion)
  │       LLM ile varsayımsal belge üret → embed et
  │
  ├─► Hybrid Retrieval
  │       Dense (FAISS/BGE-M3) + Sparse (BM25) → RRF Fusion → candidate_k aday
  │
  ├─► Cross-Encoder Reranker (BGE-Reranker-v2-M3)
  │       candidate_k → top_k nihai sonuç
  │
  └─► LLM (vLLM / HuggingFace)
          Context + Soru → Yanıt

Kurulum

# Temel kurulum
pip install -e .

# Tüm opsiyonel bağımlılıklarla
pip install -e ".[all]"

# Sadece geliştirme araçları
pip install -e ".[dev]"

Hızlı Başlangıç

# Terminal 1: vLLM sunucusu
vllm serve google/gemma-3-27b-it --dtype bfloat16 --port 8000

# Terminal 2: Pipeline
python main.py

Konfigürasyon

Ayarlar config.py içinde Pydantic Settings ile yönetilir. Ortam değişkeni veya .env dosyasıyla override edilebilir:

# Ortam değişkeni ile
RAG_TOP_K=10 RAG_USE_HYDE=false python main.py

# .env dosyası ile
echo "RAG_TOP_K=10" >> .env
echo "RAG_USE_HYDE=false" >> .env
python main.py

Tüm Ayarlar

Değişken	Default	Açıklama
RAG_EMBEDDING_BACKEND	huggingface	huggingface veya ollama
RAG_EMBED_MODEL	BAAI/bge-m3	HuggingFace embedding modeli
RAG_LLM_BACKEND	vllm	vllm veya huggingface
RAG_VLLM_BASE_URL	http://localhost:8000/v1	vLLM sunucu adresi
RAG_VLLM_MODEL	google/gemma-3-27b-it	LLM model adı
RAG_USE_RERANKER	true	Reranker aktif/pasif
RAG_RERANKER_MODEL	BAAI/bge-reranker-v2-m3	Reranker modeli
RAG_USE_HYDE	true	HyDE aktif/pasif
RAG_CHUNK_SIZE	450	Chunk karakter boyutu
RAG_CHUNK_OVERLAP	100	Chunk overlap
RAG_CANDIDATE_K	50	Stage 1 aday sayısı
RAG_TOP_K	5	LLM'e verilecek context sayısı
RAG_OBS_LOG_PATH	./obs_log.jsonl	Observability log dosyası

Proje Yapısı

rag_project/
├── main.py                          # Giriş noktası
├── config.py                        # Merkezi ayar yönetimi
├── pyproject.toml
├── setup.py
├── LICENSE
├── README.md
└── rag_pipeline/
    ├── __init__.py
    ├── pipeline.py                  # Ana RAGPipeline sınıfı
    ├── chunking/
    │   ├── __init__.py
    │   └── strategies.py            # Fixed / Semantic / Markdown / Paragraph / Router
    ├── document_loaders/
    │   ├── __init__.py
    │   └── loaders.py               # TXT / PDF / CSV / JSONL / Excel / Word
    ├── embeddings/
    │   ├── __init__.py
    │   └── backends.py              # HuggingFace / Ollama + LRU cache
    ├── llms/
    │   ├── __init__.py
    │   └── backends.py              # OpenAI-compat (vLLM) / HuggingFace
    ├── vector_stores/
    │   ├── __init__.py
    │   └── faiss_store.py           # FAISS disk-persist + metadata filtre
    └── retrievers/
        ├── __init__.py
        ├── hybrid.py                # BM25 + Dense → RRF
        ├── reranker.py              # CrossEncoder reranker
        └── query_expansion.py      # HyDE

Testler

pip install -e ".[dev]"
pytest
pytest --cov=rag_pipeline --cov-report=term-missing

Observability

Her sorgu obs_log.jsonl dosyasına JSONL formatında loglanır:

{
  "ts": "2025-01-01T12:00:00",
  "query": "Soru metni",
  "expanded_query": "HyDE ile genişletilmiş sorgu",
  "n_candidates": 50,
  "n_final": 5,
  "scores_before": [0.82, 0.79, ...],
  "scores_after": [0.94, 0.91, ...],
  "latency": {
    "hyde_ms": 420,
    "retrieve_ms": 85,
    "rerank_ms": 210,
    "llm_ms": 1840,
    "total_ms": 2560
  },
  "answer_len": 312
}

Bu log dosyasını RAGAS veya LLM-as-judge ile periyodik olarak değerlendirerek pipeline kalitesini takip edebilirsiniz.