أهداف التعلم
الهدف هنا نقل vector search من demo إلى خدمة retrieval يمكن قياسها وتشغيلها. افترض فهم embeddings و RAG و SQL/API basics. لازم تقدر تصمم chunk metadata، تختار dense أو sparse أو hybrid retrieval، وتقيس الجودة والـ latency وتضمن عزل tenants.
ابدأ بمتطلبات الاسترجاع
قبل اختيار vector database، عرّف corpus، معدل الإضافة والحذف، حجم البيانات، أنواع الاستعلام، اللغات، freshness requirement، latency budget، وعدد tenants. اسأل: هل نحتاج exact keyword matching للأرقام وأكواد المنتجات؟ هل نحتاج semantic matching؟ هل توجد صلاحيات على مستوى document أو row؟
ابنِ مجموعة تقييم من queries حقيقية أو ممثلة مع relevant document IDs وأحكام relevance. من غير ground truth لا تعرف إن تغيير embedding model أو chunk size حسّن الاسترجاع أم غيّر النتائج فقط.
Chunking و Metadata Design
خزّن document ككيان أصلي و chunks كأجزاء مشتقة مرتبطة به. Metadata مفيدة: tenant_id، document_id، source، page/section، created_at، updated_at، ACL reference، content hash، parser version، chunker version، embedding model/version. لا تجعل chunk هو المصدر الوحيد للحقيقة؛ احتفظ بإمكانية إعادة بنائه من الوثيقة الأصلية.
Chunk صغير جدًا يفقد السياق ويزيد عدد النتائج؛ الكبير جدًا يخلط موضوعات ويستهلك context. قارن fixed-size و recursive/structure-aware chunking، واختبر overlap بدل اعتباره قيمة سحرية. لا تقطع code blocks أو الجداول أو الفقرات المنطقية عشوائيًا.
Dense و Sparse و Hybrid Retrieval
Dense retrieval يقارن embeddings ويلتقط تشابهًا دلاليًا، لكنه قد يفوّت identifiers الدقيقة. Sparse retrieval مثل BM25 ممتاز للكلمات والرموز النادرة. Hybrid يجمع النوعين؛ يمكن دمج الرتب عبر Reciprocal Rank Fusion أو score fusion بعد normalization مدروس. لا تجمع scores مختلفة المقاييس دون معايرة.
ANN indexes مثل HNSW أو IVF توازن بين recall والذاكرة وزمن الاستعلام والبناء. Exact search قد يكون مناسبًا لمجموعة صغيرة أو baseline. ابدأ بقياس recall مقابل exact neighbors ثم عدّل parameters على workload ممثل.
Hybrid search جوه PostgreSQL: Full-text + vector + RRF في query واحدة
ليه hybrid؟ الـ embeddings ممتازة في المعنى («إزاي أرجّع فلوسي» ≈ «سياسة الاسترداد») وضعيفة في الحاجات الحرفية: أكواد منتجات، أرقام فواتير، أسماء نادرة، error codes. الـ lexical search عكسها بالظبط. RRF بيدمج الترتيبين من غير ما تحتاج تعمل normalization للـ scores المختلفة: كل مستند بياخد 1/(k + rank) من كل قائمة.
WITH params AS (SELECT $1::vector AS qvec, websearch_to_tsquery('simple', $2) AS qts, 60 AS k),
dense AS (
SELECT id, row_number() OVER (ORDER BY embedding <=> (SELECT qvec FROM params)) AS r
FROM doc_chunks
WHERE tenant_id = $3
ORDER BY embedding <=> (SELECT qvec FROM params)
LIMIT 50
),
sparse AS (
SELECT id, row_number() OVER (ORDER BY ts_rank_cd(tsv, (SELECT qts FROM params)) DESC) AS r
FROM doc_chunks
WHERE tenant_id = $3 AND tsv @@ (SELECT qts FROM params)
ORDER BY ts_rank_cd(tsv, (SELECT qts FROM params)) DESC
LIMIT 50
)
SELECT c.id, c.content, c.source_uri,
COALESCE(1.0 / ((SELECT k FROM params) + d.r), 0) +
COALESCE(1.0 / ((SELECT k FROM params) + s.r), 0) AS rrf
FROM dense d
FULL OUTER JOIN sparse s USING (id)
JOIN doc_chunks c ON c.id = COALESCE(d.id, s.id)
ORDER BY rrf DESC
LIMIT 20;ملاحظات إنتاج: عمود tsv يكون tsvector GENERATED ALWAYS AS (to_tsvector('simple', content)) STORED عليه GIN index. الـ 'simple' config ما بيعملش stemming — مناسب للعربي والأكواد المختلطة، لكن هتخسر تطابق «تشغيل/يشغل». ولاحظ إن ترتيب PostgreSQL FTS (ts_rank) مش BM25 بالظبط؛ لو محتاج BM25 حقيقي استخدم extension أو محرك بحث مخصص — وقِس الفرق قبل ما تضيف component.
public sealed class HybridRetriever(NpgsqlDataSource db, IEmbeddingClient embed, ITenantContext tenant)
{
public async Task<IReadOnlyList<Hit>> SearchAsync(string query, int k, CancellationToken ct)
{
var qvec = await embed.EmbedAsync(query, ct); // same model+version as the index!
await using var cmd = db.CreateCommand(Sql.HybridRrf);
cmd.Parameters.AddWithValue(new Vector(qvec)); // Pgvector.Vector
cmd.Parameters.AddWithValue(query);
cmd.Parameters.AddWithValue(tenant.TenantId); // from auth, never from input
var hits = new List<Hit>(k);
await using var r = await cmd.ExecuteReaderAsync(ct);
while (await r.ReadAsync(ct) && hits.Count < k)
hits.Add(new Hit(r.GetGuid(0), r.GetString(1), r.GetString(2), r.GetDouble(3)));
return hits;
}
}
public sealed record Hit(Guid Id, string Text, string SourceUri, double Score);مثال دمج نتائج Dense و Sparse
def reciprocal_rank_fusion(result_lists, k=60):
scores = {}
for results in result_lists:
for rank, doc_id in enumerate(results, start=1):
scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + rank)
return sorted(scores.items(), key=lambda item: item[1], reverse=True)
dense = ["doc-8", "doc-2", "doc-4"]
sparse = ["doc-2", "doc-9", "doc-8"]
print(reciprocal_rank_fusion([dense, sparse]))ده مثال توضيحي للرتب فقط. في النظام الحقيقي لازم تتحقق من duplicate IDs، filters، score provenance، tie-breaking، وحدود النتائج. RRF لا يضمن relevance؛ اختبره على labeled queries.
Filtering و Tenant Isolation
فلترة tenant و ACL ليست تحسينًا اختياريًا للجودة؛ دي security boundary. يجب فرضها في retrieval query نفسها قبل إرجاع candidates، لا بعد إرسال snippets إلى LLM. لا تعتمد على tenant_id قادم من body دون ربطه بهوية المستخدم الموثقة. اختبر cross-tenant access بشكل عدائي.
تعامل مع document content على أنه untrusted input. النص المسترجع قد يحتوي prompt injection يطلب تجاهل التعليمات أو تسريب أسرار. افصل تعليمات النظام عن المحتوى، وقيّد الأدوات والصلاحيات، ولا تجعل retrieval result يمنح authorization.
Reranking و Query Transformation
استخدم reranker لإعادة ترتيب top-N candidates بعد retrieval، خصوصًا عندما تكون precision في أول النتائج مهمة. التكلفة والـ latency أعلى عادةً، لذلك قِس أثره على nDCG@k و MRR و P95 latency. Query rewriting و multi-query قد يوسّعان الاسترجاع لكنهما قد يضيفان noise وتكلفة.
Context compression مفيد لتقليل tokens، لكنه قد يحذف evidence مهمًا. احتفظ بمصدر كل claim ورابطه أو page reference حتى يستطيع النظام إظهار citations قابلة للتحقق.
Reranking: cross-encoder بعد الـ retrieval
الآلية: الـ embedding model هو bi-encoder: بيحوّل السؤال والمستند لـ vectors كل واحد لوحده، فالمقارنة رخيصة لكن سطحية. الـ cross-encoder بياخد (السؤال، المستند) مع بعض في نفس الـ forward pass، فبيشوف التفاعل بين الكلمات ويطلع relevance score أدق — لكن تكلفته لكل زوج، فما ينفعش على مليون مستند. الحل: stage 1 يجيب 50–100 مرشح بـ recall عالي، stage 2 يرتّب بالـ cross-encoder ويختار أفضل 5–10.
from sentence_transformers import CrossEncoder
# A small public cross-encoder; pick and pin one after measuring on YOUR golden set.
reranker = CrossEncoder("cross-encoder/ms-marco-MiniLM-L-6-v2", max_length=512)
def rerank(query: str, hits: list[dict], top_n: int = 8, min_score: float | None = None):
pairs = [(query, h["text"][:2000]) for h in hits] # bound the cost per pair
scores = reranker.predict(pairs, batch_size=32)
ranked = sorted(zip(hits, scores), key=lambda x: x[1], reverse=True)
if min_score is not None: # optional: drop clearly irrelevant ones
ranked = [(h, s) for h, s in ranked if s >= min_score]
return [dict(h, rerank_score=float(s)) for h, s in ranked[:top_n]]| القرار | الـ trade-off |
|---|---|
| حجم الـ candidate pool (50؟ 200؟) | أكبر = فرصة أعلى إن الإجابة تبقى في الـ pool، لكن latency الـ reranker خطّي. قِس recall@pool قبل ما تكبّره. |
| Reranker محلي vs API | المحلي: GPU/CPU وتشغيل؛ الـ API: latency شبكة وتكلفة لكل call وبيانات بتخرج. |
| min_score threshold | بيقلل الـ noise في الـ context لكن ممكن يرمي الإجابة الوحيدة الصح؛ اضبطه بالـ eval. |
متى ما تستخدمش reranker؟ لو ترتيب stage 1 كويس أصلًا والـ latency budget ضيق، أو لو الـ queries أغلبها exact lookups (IDs/codes). القياس هو الحكم: nDCG@10 قبل وبعد على نفس الـ golden set.
Evaluation Metrics
Recall@k يقيس هل relevant items موجودة ضمن أول k؛ MRR يهتم بترتيب أول نتيجة ذات صلة؛ nDCG@k يدعم درجات relevance متعددة ويكافئ الترتيب الأفضل. قس latency p50/p95، empty-result rate، filter selectivity، index freshness، و cost per query.
افصل retrieval evaluation عن answer generation evaluation. إذا الإجابة خاطئة، حدد هل السبب retrieval miss أم context assembly أم model reasoning أم citation mismatch. قيّم حسب نوع السؤال واللغة وطول الوثيقة والـ tenant، لا على متوسط واحد فقط.
Index Lifecycle و Deletion
عند تحديث الوثيقة، استخدم content hash لاكتشاف التغيير، وأعد chunking/embedding للنسخة الجديدة ثم حدّث index بصورة ذرية أو versioned. عند الحذف، احذف chunks والـ embeddings والـ cached copies والنسخ المشتقة حسب سياسة الاحتفاظ. راعِ backup/restore؛ حذف السجل من الواجهة لا يعني اختفاءه من كل النسخ.
سجّل embedding model و dimensions و normalization و chunker version. تغيير embedding space يتطلب غالبًا re-embedding وإعادة بناء index؛ لا تخلط vectors من نماذج غير متوافقة في نفس المقارنة.
Observability و Runbooks
- Trace query normalization، embedding، vector query، sparse query، reranking، و context assembly.
- راقب latency و timeouts و provider errors و empty results و top-k distribution.
- سجّل IDs والـ scores والـ versions بأقل قدر من البيانات الشخصية.
- ضع runbook لإعادة بناء index، rollback، وإعادة معالجة documents الفاشلة.
- اختبر stale index و provider outage و ACL changes و deletion propagation.
لا تسجل النص الكامل افتراضيًا؛ استخدم sampling و redaction و access control. ضع budgets للتكلفة والـ tokens، وميّز بين فشل retrieval وفشل LLM.
Capstone ومعايير الإتقان
ابنِ retrieval service لمستندات متعددة tenants: ingestion versioned، chunk metadata، dense + BM25، RRF، reranking اختياري، ACL filters، و evaluation dataset. أخرج تقريرًا يقارن recall@5 و MRR و nDCG و P95 latency والتكلفة.
- اكتب 50 query مع relevance judgments.
- قارن dense-only و BM25-only و hybrid.
- اختبر مستخدمًا يحاول استرجاع مستند tenant آخر.
- حدّث وثيقة واحذف أخرى وتحقق من freshness/deletion.
- أوقف embedding provider واختبر fallback والـ timeouts.
هل cosine similarity المرتفعة تثبت أن النتيجة صحيحة؟
هل نطبق صلاحيات tenant بعد retrieval؟
Approximate Nearest Neighbors من جوه: IVF بإيدك وقياس Recall مقابل السرعة
البحث الدقيق (exact) بيقارن الـ query بكل vector: مضمون 100% وبطيء خطيًا مع حجم البيانات. كل الـ vector databases بتستخدم بحث تقريبي بيضحّي بنسبة من الـ recall مقابل سرعة. لازم تعرف إن ده اختيار، وإن الـ recall بتاع الـ index نفسه رقم بيتقاس — ومختلف عن جودة الـ embeddings.
IVF (Inverted File) أبسط index تقريبي: قسّم الـ vectors لـ clusters بـ k-means، وعند البحث دوّر بس في أقرب كام cluster (nprobe).
import time
import numpy as np
from sklearn.cluster import KMeans
rng = np.random.default_rng(0)
N, D, K, Q = 20_000, 64, 10, 200
# clustered data (real embeddings are clustered by topic, not uniform noise)
centres = rng.normal(size=(40, D))
X = centres[rng.integers(0, 40, N)] + 0.6 * rng.normal(size=(N, D))
X /= np.linalg.norm(X, axis=1, keepdims=True) # unit vectors: dot product == cosine
queries = centres[rng.integers(0, 40, Q)] + 0.6 * rng.normal(size=(Q, D))
queries /= np.linalg.norm(queries, axis=1, keepdims=True)
# ---------- ground truth: exact (brute-force) search ----------
t0 = time.perf_counter()
exact = np.argsort(-(queries @ X.T), axis=1)[:, :K]
exact_ms = (time.perf_counter() - t0) / Q * 1000
# ---------- build the IVF index ----------
NLIST = 100
km = KMeans(n_clusters=NLIST, n_init=1, random_state=0).fit(X)
lists = [np.where(km.labels_ == c)[0] for c in range(NLIST)]
centroids = km.cluster_centers_
def search(q, nprobe):
nearest_lists = np.argsort(-(centroids @ q))[:nprobe] # 1) which clusters look promising?
candidates = np.concatenate([lists[c] for c in nearest_lists])
scores = X[candidates] @ q # 2) exact search, but only inside them
return candidates[np.argsort(-scores)[:K]], len(candidates)
print(f"dataset: {N:,} vectors, dim {D}; {NLIST} lists, average {N // NLIST} vectors per list")
print(f"{'nprobe':>6}{'recall@10':>11}{'vectors scanned':>17}{'share of data':>15}")
for nprobe in (1, 2, 5, 10, 25, 100):
hits = scanned = 0
for q, truth in zip(queries, exact):
found, n = search(q, nprobe)
hits += len(set(found) & set(truth)); scanned += n
print(f"{nprobe:>6}{hits / (Q * K):>11.3f}{scanned // Q:>17,}{scanned / Q / N:>15.1%}")
print(f"\nexact search scans 100% of the data ({exact_ms:.2f} ms/query here, growing linearly with N)")dataset: 20,000 vectors, dim 64; 100 lists, average 200 vectors per list
nprobe recall@10 vectors scanned share of data
1 0.574 234 1.2%
2 0.882 436 2.2%
5 1.000 1,057 5.3%
10 1.000 2,050 10.3%
25 1.000 4,996 25.0%
100 1.000 20,000 100.0%
exact search scans 100% of the data (0.46 ms/query here, growing linearly with N)nprobe هو الـ dial: بـ nprobe صغير بتفحص نسبة صغيرة من البيانات وبتخسر جزء من النتايج الصح — لأن جار قريب ممكن يكون وقع في cluster مجاور على الحد. كل ما تزوّده الـ recall بيقرب من 1.0 والشغل بيزيد، لحد nprobe = nlist اللي هو البحث الدقيق بالظبط.
الـ recall هنا مقاس ضد البحث الدقيق على نفس الـ vectors. ده بيقيس جودة الـ index. جودة الـ retrieval للمستخدم (هل الـ chunk المفيد رجع؟) حاجة تانية بتعتمد على الـ embedding model والـ chunking — وبتتقاس بـ golden set (شوف درس RAG). index بـ recall 0.99 فوق embeddings وحشة لسه بيرجّع نتايج وحشة، بسرعة.
HNSW (الـ default في pgvector وأغلب الأنظمة) بيوصل لنفس الهدف بطريقة تانية: graph متعدد المستويات بتتنقل فيه من جار لجار أقرب. الـ dial بتاعه ef_search بدل nprobe، وبياخد ذاكرة ووقت بناء أكتر مقابل recall/latency أحسن.
| الحجم | الاختيار المعقول | ليه |
|---|---|---|
| لحد عشرات الآلاف من الـ vectors (أو per-tenant صغير) | Exact search — من غير index | سريع كفاية، recall 100%، مفيش tuning |
| مئات الآلاف–ملايين | HNSW | أحسن recall/latency؛ التمن ذاكرة وبناء |
| ملايين كتير بذاكرة محدودة | IVF (+ quantization) | ذاكرة أقل وبناء أسرع؛ محتاج إعادة تدريب لما التوزيع يتغير |
لو الـ index رجّع أقرب 10 وبعدين فلترت بالـ tenant، ممكن يتبقى 0. ولو tenant صغير جوه index مشترك كبير، جيرانه الحقيقيين ممكن ما يظهروش أصلًا في الـ candidates. الحلول: فلترة جوه البحث (pre-filter / filtered ANN حسب دعم النظام)، partition أو index لكل tenant، أو exact search للـ tenants الصغيرة. وفي كل الحالات: قِس recall مع الفلتر مش من غيره.
خريطة تغطية الأهداف
الأهداف العشرة المدرجة في خريطة المنهج تم تناولها عبر الأقسام والتمارين أعلاه. التغطية تعني وجود شرح أو نشاط تعليمي، ولا تعني الإتقان أو الاعتماد أو الجاهزية الإنتاجية دون تنفيذ المشروع والاختبارات.
HNSW من جوه: ليه بيلاقي الجيران من غير ما يقارن بكل حاجة
IVF (اللي بنيناه في المعمل اللي فات) بيقسّم الفضاء لـ clusters ويدوّر في أقرب كام cluster. HNSW فكرته مختلفة: graph كل vector فيه متوصل بأقرب جيرانه، والبحث «مشي طمّاع» على الـ graph: تبدأ من نقطة، تروح للجار الأقرب للسؤال، وتكرر لحد ما مفيش جار أقرب.
الآلية بالترتيب:
- كل vector بيتحط في layer 0، وبيترقّى عشوائيًا لـ layers أعلى باحتمال بيقل أُسّيًا (زي skip list). فالـ layers العليا فيها نقط قليلة متباعدة = «طرق سريعة».
- الإدخال: بندوّر على أقرب نقط للـ vector الجديد بقائمة مرشحين حجمها
ef_construction، ونوصّله بأقربMمنهم (مع pruning عشان الجيران يبقوا متنوعين في الاتجاه). - البحث: نبدأ من الـ entry point في أعلى layer، ننزل layer layer، وفي layer 0 بنحتفظ بقائمة أفضل
ef_searchمرشح. كل ماef_searchأكبر = نستكشف أكتر = recall أعلى و latency أعلى.
| Parameter | بيأثر على | زيادته معناها | في pgvector |
|---|---|---|---|
M | عدد الروابط لكل نقطة | recall أعلى، ذاكرة أكبر، build أبطأ | WITH (m = 16) |
ef_construction | جودة الـ graph وقت البناء | build أبطأ بكتير، recall أحسن عند نفس ef_search | WITH (ef_construction = 64) |
ef_search | عمق البحث لكل query | recall ↑ latency ↑ — بيتغيّر من غير rebuild | SET hnsw.ef_search = 100 |
القيم الافتراضية والحدود بتتغير بين نسخ pgvector — راجع الـ README للنسخة اللي عندك قبل ما تعتمد على رقم.
HNSW مقابل IVF (IVFFlat في pgvector):
| HNSW | IVFFlat | |
|---|---|---|
| Recall/latency | أفضل trade-off عمومًا | أقل عند نفس السرعة |
| Build | أبطأ وأتقل في الذاكرة | أسرع، لكن محتاج داتا موجودة عشان يتعلم الـ centroids (ما تبنيهوش على جدول فاضي) |
| Inserts مستمرة | بتتعامل معاها كويس | الـ centroids بتقدم لو التوزيع اتغير ← rebuild دوري |
| Tuning وقت الاستعلام | hnsw.ef_search | ivfflat.probes |
في PostgreSQL ابدأ بـ HNSW وقِس. لو الذاكرة بقت المشكلة، فكّر في تقليل الأبعاد (بعض نماذج الـ embeddings بتدعم أبعاد أقل) أو quantization (halfvec أو binary في pgvector) — وكل ده لازم يتقاس على الـ golden set بتاعك مش على benchmark عام.
معمل: graph search بإيدك — recall مقابل ef، وانهيار الـ post-filter
بنبني layer 0 بتاع HNSW (graph بـ M جيران) على 1500 vector متجمّعة في 30 «موضوع» زي الـ embeddings الحقيقية، وبنقيس recall@10 وعدد مقارنات المسافة لكل query مقابل الـ brute force. بعدين بنجرب سيناريو الـ multi-tenant: tenant بيملك ~5% بس من الـ vectors، وبنفلتر بعد البحث.
import random, heapq, math, time
random.seed(7)
N, D, M, EFC = 1500, 16, 8, 40
def rnd():
v = [random.gauss(0, 1) for _ in range(D)]; n = math.sqrt(sum(x*x for x in v)); return [x/n for x in v]
# clustered data: 30 topics, like real embeddings
centers = [rnd() for _ in range(30)]
def sample():
c = random.choice(centers); v = [a + random.gauss(0, .35) for a in c]; n = math.sqrt(sum(x*x for x in v)); return [x/n for x in v]
X = [sample() for _ in range(N)]
TENANT = [0 if random.random() < 0.05 else 1 for _ in range(N)] # tenant 0 owns ~5% of vectors
calls = 0
def dist(a, b):
global calls; calls += 1
return 1 - sum(x*y for x, y in zip(a, b)) # cosine distance on unit vectors
graph = {}
def search(q, entry, ef, allowed=None):
"""Greedy best-first search on a proximity graph (HNSW layer-0 style)."""
d0 = dist(q, X[entry]); visited = {entry}
cand = [(d0, entry)]; best = [(-d0, entry)]
while cand:
d, u = heapq.heappop(cand)
if d > -best[0][0] and len(best) >= ef: break
for v in graph[u]:
if v in visited: continue
visited.add(v); dv = dist(q, X[v])
if len(best) < ef or dv < -best[0][0]:
heapq.heappush(cand, (dv, v)); heapq.heappush(best, (-dv, v))
if len(best) > ef: heapq.heappop(best)
res = sorted((-d, v) for d, v in best)
return [v for d, v in res if allowed is None or allowed(v)]
t0 = time.time()
for i in range(N):
graph[i] = []
if i == 0: continue
near = search(X[i], 0, EFC)[:M]
for v in near:
graph[i].append(v); graph[v].append(i)
if len(graph[v]) > 2 * M: # prune: keep the closest 2M links
graph[v] = sorted(graph[v], key=lambda w: dist(X[v], X[w]))[:2 * M]
build_calls = calls
print(f"built graph: N={N} D={D} M={M} efConstruction={EFC} in {time.time()-t0:.1f}s, {build_calls} distance calls")
Q = [sample() for _ in range(60)]
def exact(q, k, allowed=None):
return [i for _, i in sorted((1 - sum(a*b for a, b in zip(q, X[i])), i) for i in range(N) if allowed is None or allowed(i))[:k]]
truth = [exact(q, 10) for q in Q]
print("ef_search recall@10 dist_calls/query (brute force = %d)" % N)
for ef in (10, 20, 40, 80, 160):
calls = 0; hit = 0
for q, t in zip(Q, truth):
got = search(q, 0, ef)[:10]; hit += len(set(got) & set(t))
print(f"{ef:9d} {hit/(10*len(Q)):9.3f} {calls/len(Q):16.0f}")
own = lambda i: TENANT[i] == 0
truth_t = [exact(q, 10, own) for q in Q]
print("\nfiltered query: tenant 0 owns %.1f%% of vectors" % (100*sum(1 for t in TENANT if t == 0)/N))
for ef in (40, 160, 640):
hit = 0; empty = 0
for q, t in zip(Q, truth_t):
got = search(q, 0, ef, allowed=own)[:10]; hit += len(set(got) & set(t)); empty += (len(got) < 10)
print(f"post-filter ef={ef:4d}: recall@10={hit/(10*len(Q)):.3f} queries with <10 results={empty}/{len(Q)}")
hit = 0
for q, t in zip(Q, truth_t):
hit += len(set(exact(q, 10, own)) & set(t))
print(f"pre-filter (exact scan of tenant rows only): recall@10={hit/(10*len(Q)):.3f}, scans {sum(1 for t in TENANT if t==0)} rows")built graph: N=1500 D=16 M=8 efConstruction=40 in 1.6s, 435425 distance calls
ef_search recall@10 dist_calls/query (brute force = 1500)
10 0.810 135
20 0.933 199
40 0.987 304
80 1.000 478
160 1.000 734
filtered query: tenant 0 owns 4.7% of vectors
post-filter ef= 40: recall@10=0.185 queries with <10 results=60/60
post-filter ef= 160: recall@10=0.733 queries with <10 results=47/60
post-filter ef= 640: recall@10=1.000 queries with <10 results=0/60
pre-filter (exact scan of tenant rows only): recall@10=1.000, scans 70 rowsقراءة النتايج:
- مع
ef=40وصلنا recall عالي جدًا بحوالي 300 مقارنة بدل 1500. في ملايين الـ vectors الفرق بيبقى آلاف المرات — ده سبب وجود ANN. - الـ post-filter انهار: البحث رجّع أقرب 40 vector من كل الـ tenants، وبعد الفلترة فضل جزء صغير من الـ tenant الصح. لازم ef ضخم (640) عشان يرجع recall كامل، وده بيقرب من تكلفة الـ brute force.
- الـ pre-filter (مسح صفوف الـ tenant بس) كان دقيق ورخيص. ده الدرس الأهم في الـ multi-tenant: لما الفلتر selective جدًا، الـ index المشترك بيخسر.
Metadata filtering في الإنتاج: pre vs post vs iterative
ليه المشكلة موجودة؟ الـ ANN index بيعرف المسافة بس، مش الـ metadata. لما تكتب WHERE tenant_id = $1 ORDER BY embedding <=> $2 LIMIT 10، الـ planner عنده اختيارين: يستخدم الـ vector index ويفلتر النتيجة (post-filter — ممكن يرجّع أقل من 10)، أو يستخدم index عادي على tenant_id ويحسب المسافة لكل صفوف الـ tenant (exact، دقيق، وسريع لو الـ tenant صغير).
-- 1) Inspect what the planner actually does (always do this first)
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, embedding <=> $1 AS d
FROM doc_chunks
WHERE tenant_id = $2 AND doc_status = 'active'
ORDER BY embedding <=> $1
LIMIT 10;
-- 2) pgvector 0.8+: iterative index scans keep scanning until enough rows pass the filter
SET hnsw.iterative_scan = relaxed_order; -- or strict_order; check your pgvector version's docs
SET hnsw.max_scan_tuples = 20000; -- upper bound on work per query
-- 3) Small/medium tenants: a plain B-tree makes exact search over the tenant cheap
CREATE INDEX ON doc_chunks (tenant_id, doc_status);
-- 4) A few huge tenants: give them their own partial HNSW index
CREATE INDEX doc_chunks_t_big_hnsw ON doc_chunks
USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64)
WHERE tenant_id = '2f6c0b1e-0000-4000-8000-000000000001';| الاستراتيجية | متى | المخاطرة |
|---|---|---|
| Pre-filter + exact | الـ subset صغير (آلاف–عشرات الآلاف صف) | بتبطأ لما الـ tenant يكبر — راقب p95 لكل tenant |
| Post-filter على index مشترك | الفلتر مش selective (مثلًا 50% من الصفوف) | نتايج ناقصة بصمت مع الفلاتر الضيقة |
| Iterative scan | فلاتر متوسطة، index مشترك | latency متغيرة؛ لازم حد أقصى للشغل |
| Partitioning/partial index لكل tenant كبير | توزيع tenants غير متساوي | عدد indexes كبير = صيانة وذاكرة |
post-filter بيرجّع 3 نتايج بدل 10 ← الـ LLM بيجاوب «مفيش معلومات» ← المستخدم يفتكر المستند مش موجود. مفيش error ولا alert. راقب metric زي retrieval.result_count (histogram) و alert لو نسبة الـ queries اللي رجعت أقل من k زادت.
Multi-tenant layouts للـ vector store
| Layout | العزل | الأداء | التشغيل | مناسب لـ |
|---|---|---|---|---|
جدول واحد + tenant_id + RLS | منطقي (يعتمد على RLS/الكود) | مشكلة الفلتر الضيق | الأسهل | آلاف tenants صغيرة |
| Declarative partitioning بالـ tenant (أو hash buckets) | منطقي + فصل فيزيائي جزئي | كل partition ليها index أصغر | متوسط | tenants متوسطة/كبيرة |
| Schema/DB لكل tenant | قوي | ممتاز للـ tenant | migrations لمئات الـ DBs | enterprise بعقود عزل |
| Hybrid (pool + silo) | حسب الخطة | حسب الخطة | routing layer | SaaS بخطط مختلفة |
الاختيار ده نفسه قرار الـ SaaS isolation اللي في درس Multi-Tenant — الـ vectors لازم تمشي على نفس نموذج العزل بتاع باقي بيانات الـ tenant (مش قرار منفصل)، وإلا الـ tenant deletion والـ data residency هيبقوا كابوس.
Freshness و re-indexing: المستند اتعدّل… الـ index لسه قديم
المشكلة: الـ vector index نسخة مشتقة من المستندات. أي فرق بينهم = إجابة من نسخة قديمة، أو أسوأ: مستند اتحذف أو صلاحياته اتقفلت ولسه بيظهر في الإجابات.
- Change capture: كل تعديل على المستند يكتب event في outbox (نفس الـ transaction)، و worker يعمل re-chunk + re-embed. ده بيضمن إن مفيش تعديل يضيع لو الـ worker وقع.
- Idempotent upsert بـ content hash: لو الـ chunk ما اتغيرش (نفس الـ hash) ما تعيدش الـ embedding — بيوفر تكلفة كبيرة في التعديلات الصغيرة.
- الحذف والصلاحيات أولوية أعلى من الإضافة: تغيير ACL أو حذف لازم يتطبق فورًا على الـ metadata، حتى لو الـ re-embed يتأخر.
- Freshness SLO: مثلًا 99% من التعديلات تبان في البحث خلال 5 دقايق. قِسها بـ
indexed_at - source_updated_at.
public sealed class ReindexWorker(IOutboxReader outbox, IChunker chunker, IEmbeddingClient embed,
IChunkStore store, ILogger<ReindexWorker> log) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken ct)
{
await foreach (var evt in outbox.ReadAsync("document.changed", ct))
{
if (evt.Kind is ChangeKind.Deleted or ChangeKind.AclChanged)
{
await store.ApplyAclOrDeleteAsync(evt.TenantId, evt.DocumentId, evt.Acl, ct); // fast path
await outbox.AckAsync(evt, ct);
continue;
}
var chunks = chunker.Split(evt.Text);
var existing = await store.GetHashesAsync(evt.TenantId, evt.DocumentId, ct);
var changed = chunks.Where(c => !existing.Contains(c.ContentHash)).ToList();
var vectors = await embed.EmbedBatchAsync(changed.Select(c => c.Text).ToList(), ct);
await store.ReplaceDocumentAsync(evt.TenantId, evt.DocumentId, chunks, changed.Zip(vectors), ct);
log.LogInformation("Reindexed {Doc}: {Changed}/{Total} chunks re-embedded", evt.DocumentId, changed.Count, chunks.Count);
await outbox.AckAsync(evt, ct);
}
}
}Embedding model migration من غير downtime
ليه صعب؟ الـ vectors من نموذجين مختلفين مالهاش علاقة ببعض — حتى لو نفس عدد الأبعاد. مينفعش تخلط؛ السؤال لازم يتعمله embed بنفس النموذج اللي اتعمل بيه الـ index. فالترحيل = بناء index جديد كامل.
-- Keep vectors of different models in separate columns (or tables) with explicit versions.
ALTER TABLE doc_chunks ADD COLUMN embedding_v2 vector(1024);
ALTER TABLE doc_chunks ADD COLUMN embedding_v2_model text; -- e.g. 'provider/model@2026-05'
CREATE INDEX CONCURRENTLY doc_chunks_v2_hnsw
ON doc_chunks USING hnsw (embedding_v2 vector_cosine_ops);
-- Backfill progress, per tenant (drive throttling and the cutover decision from this)
SELECT tenant_id,
count(*) FILTER (WHERE embedding_v2 IS NULL) AS remaining,
count(*) AS total
FROM doc_chunks GROUP BY tenant_id ORDER BY remaining DESC;Checklist: (1) الـ golden set يتقاس على v1 و v2 (recall@k، nDCG، وجودة الإجابة النهائية). (2) التكلفة: backfill لملايين الـ chunks = تكلفة API + rate limits؛ احسبها قبل ما تبدأ. (3) الـ cutover لكل tenant بـ feature flag. (4) الـ query embedding version لازم يتسجل في الـ trace. (5) ما تمسحش v1 إلا بعد فترة soak.
Retrieval debugging: من «الإجابة غلط» للسبب في 15 دقيقة
- هل المستند موجود ومفهرس؟ ابحث بالـ document ID في الـ chunks: موجود؟ active؟ الـ ACL صح؟ الـ embedding model version صح؟
- هل الـ chunk الصح فيه الإجابة كاملة؟ ساعات الـ chunking قطع الجدول أو فصل العنوان عن المحتوى.
- Rank الـ chunk الصح في كل stage: dense rank، sparse rank، بعد الدمج، بعد الفلتر، بعد الـ rerank. السجل ده لازم يكون في الـ trace.
- لو dense rank سيء والـ sparse كويس: مفردات خاصة/أكواد → زوّد وزن الـ lexical أو query expansion.
- لو الاتنين سيئين: السؤال بصيغة بعيدة عن نص المستند → query rewriting، أو أضف «عنوان + ملخص» للـ chunk text قبل الـ embedding (contextual chunk headers).
- لو كان في الـ top-k واتشال: الفلتر أو الـ reranker أو حد الـ tokens في الـ context assembly.
- لو كان في الـ context والإجابة غلط: المشكلة generation مش retrieval ← روح لـ faithfulness eval.
{
"trace_id": "4bf92f3577b34da6",
"tenant": "t-042", "query_hash": "9f2c…", "embed_model": "provider/model@2026-05",
"stages": [
{"stage": "dense", "k": 50, "top": [["c-118", 0.82], ["c-907", 0.79], ["c-311", 0.77]]},
{"stage": "sparse", "k": 50, "top": [["c-311", 11.2], ["c-118", 7.9]]},
{"stage": "rrf", "top": [["c-311", 0.0325], ["c-118", 0.0323]]},
{"stage": "acl_filter", "removed": ["c-907"]},
{"stage": "rerank", "top": [["c-311", 7.1], ["c-118", 2.3]]}
],
"context_chunks": ["c-311", "c-118"], "context_tokens": 1830
}سجّل IDs والـ scores مش النصوص (PII). ولما حد يشتكي، الـ trace ده هو اللي بيحوّل «الـ AI غبي» لـ «الـ chunk الصح اتشال في الـ ACL filter عشان الـ group mapping اتغيّر امبارح».
Knowledge check
Tenant بيملك 2% من الـ vectors في index HNSW مشترك. الـ queries بتاعته بترجع نتايج ناقصة. إيه السبب الأرجح؟
غيرت الـ embedding model لنموذج بنفس عدد الأبعاد. ينفع تستخدم الـ index القديم للأسئلة الجديدة؟
إمتى reranker بيضيف قيمة قليلة؟
تمارين محلولة
1: عدّل المعمل: إيه أثر M=4 مقابل M=16 على recall عند ef=20؟
الحل: غيّر M وأعد البناء. M أصغر = graph أقل اتصالًا = البحث الطماع يقف في local minima أكتر، فالـ recall عند نفس ef ينزل، والـ build أسرع والذاكرة أقل. M أكبر بيرفع recall لكن كل خطوة بتقارن جيران أكتر (dist calls/query بتزيد). القاعدة: اضبط M مرة (وقت البناء) و ef_search باستمرار (وقت التشغيل).
2: صمّم layout لـ SaaS فيه 5,000 tenant صغير و20 tenant enterprise بملايين الـ chunks
الحل: جدول مشترك بـ RLS و B-tree على (tenant_id, status) للصغيرين (exact search رخيص)، و partition أو partial HNSW index لكل enterprise tenant (أو DB منفصلة لو العقد يطلب عزل/residency). Routing في الـ retriever حسب الـ tenant tier من الـ config. ومراقبة p95 لكل tier.
3: الـ freshness SLO اتكسر: تعديلات بتاخد ساعتين. إزاي تحقق؟
الحل: (1) طول الـ outbox queue وعمر أقدم event. (2) هل الـ embedding API عامل throttling (429)؟ (3) هل tenant واحد عمل bulk upload ملا الـ queue (محتاج fair queuing لكل tenant)؟ (4) هل في event poison بيتعاد باستمرار (dead-letter)؟ الإصلاح الأغلب: per-tenant concurrency limits + DLQ + أولوية للـ delete/ACL events.
Mini project: Retrieval quality dashboard
ابنِ لـ CAPSTONE/: (1) golden set من 60 سؤال مع الـ chunk IDs الصح (مع أسئلة exact-code وأسئلة paraphrase وأسئلة عربي). (2) script بيقيس recall@5/10 و nDCG@10 لـ dense و sparse و hybrid و hybrid+rerank. (3) جدول بالنتايج + p95 latency لكل config. معيار القبول: تقدر تدافع عن الـ config المختار برقم، وتوضح حالة واحدة على الأقل الـ hybrid صلّحها والـ dense لوحده فشل فيها.
أسئلة إنترفيو: Junior → Senior → Staff
(Junior) ليه بنستخدم ANN بدل brute force؟
(Junior) إيه فايدة hybrid search؟
(Senior) إزاي تقرر ef_search في الإنتاج؟
(Senior) اشرح خطة ترحيل embedding model لـ 50 مليون chunk.
(Staff) pgvector ولا vector DB مخصص؟ دافع عن قرارك.
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خريطة التغطية: 10 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.