Capstone Module 7: Turkish Semantic Search System — sentence-transformers + FAISS + Mini-RAG

Capstone Akışı (10 Aşama)#

1. Sistem mimarisi — semantic search vs keyword, RAG flow
2. Türkçe sentence-transformer modeli — model seçimi (TR-tuned)
3. Dokuman corpus — Wikipedia subset veya Türkçe blog corpus
4. Embedding pipeline — batch encoding, dimensionality
5. FAISS index — IndexFlatIP vs IndexIVFPQ
6. Query pipeline — query embed → top-k retrieve
7. Mini-RAG — retrieved docs + LLM generation
8. Evaluation — recall@k, MRR, NDCG metrikleri
9. Production deployment — FastAPI service, caching
10. Improvements — re-ranking, hybrid search, monitoring

1. Sistem Mimarisi#

1.1 Semantic search vs keyword search#

• Keyword (BM25): 'Türkiye'nin başkenti' query → docs with these literal words
• Semantic: 'ülkenin merkezi' query → understands semantic, retrieves 'Türkiye'nin başkenti' content

1.2 RAG (Retrieval-Augmented Generation) flow#

[1] User query: "İstanbul'un en yüksek noktası neresidir?"
     ↓
[2] Query embedding (sentence-transformer)
     ↓
[3] FAISS top-k search (vector index)
     ↓
[4] Retrieved documents (top-5 chunks)
     ↓
[5] Prompt construction: query + retrieved docs
     ↓
[6] LLM generation (GPT-4 / Claude / Llama)
     ↓
[7] Final answer (grounded in retrieved facts)

1.3 Embedding aşamasında olan#

1.4 Capstone scope#

• Türkçe sentence-transformers model load
• 10K Türkçe Wikipedia paragrafı index
• Query → top-5 retrieve
• (Opsiyonel) LLM ile generation
• Evaluation
• Mini FastAPI service

2. Türkçe Sentence-Transformer Modeli#

2.1 Popüler seçenekler (2026)#

2.2 Tavsiye#

2.3 Install + load#

pip install sentence-transformers faiss-cpu  # veya faiss-gpu

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("BAAI/bge-m3")
print(f"Embedding dim: {model.get_sentence_embedding_dimension()}")  # 1024

2.4 Encoding#

text = "İstanbul'un en yüksek noktası Çamlıca Tepesi'dir."
emb = model.encode(text)
print(f"Vector shape: {emb.shape}")  # [1024]
print(f"Norm: {emb.norm():.3f}")     # already normalized by SBERT

2.5 Batch encoding#

texts = ["cümle 1", "cümle 2", ...]
embs = model.encode(texts, batch_size=32, show_progress_bar=True)
# embs shape: [N, 1024]

5. FAISS Vector Index#

5.1 FAISS nedir#

5.2 Index types#

5.3 Build index#

import faiss
import numpy as np

d = 1024  # embedding dim
index = faiss.IndexFlatIP(d)   # inner product (cosine for normalized)

# Add embeddings
embs_np = embs.astype("float32")
index.add(embs_np)
print(f"Indexed {index.ntotal} vectors")

5.4 Save + load#

faiss.write_index(index, "tr-wiki-faiss.index")
# ...
index = faiss.read_index("tr-wiki-faiss.index")

5.5 Search#

query = "İstanbul'un en yüksek tepesi neresidir?"
q_emb = model.encode(query).astype("float32")
q_emb = q_emb.reshape(1, -1)

k = 5
scores, indices = index.search(q_emb, k)
print(scores)    # [[0.87, 0.85, 0.83, 0.80, 0.78]]
print(indices)   # [[423, 8912, 1023, 456, 6789]]

5.6 Production: IndexIVFPQ for scale#

nlist = 100  # number of clusters
m = 16       # number of subquantizers
bits = 8     # bits per subquantizer

quantizer = faiss.IndexFlatIP(d)
index = faiss.IndexIVFPQ(quantizer, d, nlist, m, bits)
index.train(embs_np)
index.add(embs_np)
index.nprobe = 10   # search depth

5.7 GPU acceleration#

res = faiss.StandardGpuResources()
index_gpu = faiss.index_cpu_to_gpu(res, 0, index)

8. Evaluation Metrikleri#

8.1 Recall@k#

Recall@5 = |{queries where correct doc in top-5}| / total_queries

8.2 MRR (Mean Reciprocal Rank)#

MRR = mean(1 / rank_of_correct_doc)

8.3 NDCG (Normalized Discounted Cumulative Gain)#

8.4 Türkçe benchmark#

8.5 Empirical (capstone results)#

• Recall@5: ~0.85
• MRR: ~0.65
• Search latency: 5 ms (CPU)

9. FastAPI Service Deploy#

9.1 Service code#

from fastapi import FastAPI
from pydantic import BaseModel
from sentence_transformers import SentenceTransformer
import faiss
import numpy as np

app = FastAPI()

# Globals (load once)
model = SentenceTransformer("BAAI/bge-m3")
index = faiss.read_index("tr-wiki-faiss.index")
with open("docs.txt") as f:
    docs = [line.strip() for line in f]

class Query(BaseModel):
    text: str
    k: int = 5

@app.post("/search")
def search(q: Query):
    q_emb = model.encode([q.text]).astype("float32")
    scores, indices = index.search(q_emb, q.k)
    return {
        "results": [
            {"doc": docs[i], "score": float(scores[0][j])}
            for j, i in enumerate(indices[0])
        ]
    }

9.2 Run#

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

9.3 Production considerations#

• Cold start: model + index load ~5 sec. K8s liveness probe / readiness probe tune et.
• Memory: BAAI/bge-m3 ~2 GB RAM. Pod limit 4 GB minimum.
• Throughput: CPU 100-500 q/s, GPU 5000+ q/s.
• Caching: query hash → cached result (Redis). Aynı query'leri skip et.

Modül 7 Envanteri (Tamamlandı)#

Genel Müfredat İlerleme#