Software Engineer Encyclopedia
0%
Domain 12 · RAG, Agents & MCP · Topic 12.5

هندسة الاسترجاع المتجهي في الإنتاج

Production Vector Retrieval Engineering

Design, evaluate and operate retrieval systems with hybrid search, isolation, index lifecycle and observability.

  • Professional Engineering
  • ~21 min read
  • 24 sections
  • 9 code examples
  • 2 diagrams
  • 11 questions
  • Priority L2 · Essential
  • PostgreSQL 16+ · pgvector 0.8+ (راجع الـ README للنسخة عندك) · .NET 9 + Npgsql · Python 3 (المعمل stdlib، executed)

بعد الدرس ده هتقدر

  • تشرح HNSW وIVF من جوه وتضبط M وef_construction وef_search بالقياس
  • تحل مشكلة filtered search في index مشترك (pre/post/iterative/partial index)
  • تكتب hybrid search بـ RRF جوه PostgreSQL وتضيف cross-encoder reranking
  • تختار layout للـ vectors في SaaS متعدد المستأجرين
  • تحافظ على freshness وتنفّذ embedding model migration من غير downtime
  • تتبع retrieval bug من العَرَض للسبب بـ trace مرحلي

المتطلبات قبل ما تبدأ

مستوى التعمق المطلوب

PRODUCTION ENGINEERINGصمّم retrieval pipeline قابلة للقياس مع عزل البيانات وتحديث الفهارس ومراقبة الجودة.

01

أهداف التعلم

Learning outcomes

الهدف هنا نقل vector search من demo إلى خدمة retrieval يمكن قياسها وتشغيلها. افترض فهم embeddings و RAG و SQL/API basics. لازم تقدر تصمم chunk metadata، تختار dense أو sparse أو hybrid retrieval، وتقيس الجودة والـ latency وتضمن عزل tenants.

02

ابدأ بمتطلبات الاسترجاع

Define retrieval requirements

قبل اختيار 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 حسّن الاسترجاع أم غيّر النتائج فقط.

03

Chunking و Metadata Design

Document and chunk model

خزّن 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 أو الجداول أو الفقرات المنطقية عشوائيًا.

04

Dense و Sparse و Hybrid Retrieval

Candidate generation

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) من كل قائمة.

SQLhybrid_rrf.sql
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.

C#HybridRetriever.cs
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);
05

مثال دمج نتائج Dense و Sparse

Rank fusion example
PythonReciprocal Rank Fusion
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.

06

Filtering و Tenant Isolation

Security boundary

فلترة tenant و ACL ليست تحسينًا اختياريًا للجودة؛ دي security boundary. يجب فرضها في retrieval query نفسها قبل إرجاع candidates، لا بعد إرسال snippets إلى LLM. لا تعتمد على tenant_id قادم من body دون ربطه بهوية المستخدم الموثقة. اختبر cross-tenant access بشكل عدائي.

تعامل مع document content على أنه untrusted input. النص المسترجع قد يحتوي prompt injection يطلب تجاهل التعليمات أو تسريب أسرار. افصل تعليمات النظام عن المحتوى، وقيّد الأدوات والصلاحيات، ولا تجعل retrieval result يمنح authorization.

07

Reranking و Query Transformation

Second-stage relevance

استخدم 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.

Pythonrerank.py
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.

08

Evaluation Metrics

Measure retrieval quality

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، لا على متوسط واحد فقط.

09

Index Lifecycle و Deletion

Updates and governance

عند تحديث الوثيقة، استخدم content hash لاكتشاف التغيير، وأعد chunking/embedding للنسخة الجديدة ثم حدّث index بصورة ذرية أو versioned. عند الحذف، احذف chunks والـ embeddings والـ cached copies والنسخ المشتقة حسب سياسة الاحتفاظ. راعِ backup/restore؛ حذف السجل من الواجهة لا يعني اختفاءه من كل النسخ.

سجّل embedding model و dimensions و normalization و chunker version. تغيير embedding space يتطلب غالبًا re-embedding وإعادة بناء index؛ لا تخلط vectors من نماذج غير متوافقة في نفس المقارنة.

10

Observability و Runbooks

Operate retrieval
  • 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.

11

Capstone ومعايير الإتقان

Production retrieval lab

ابنِ retrieval service لمستندات متعددة tenants: ingestion versioned، chunk metadata، dense + BM25، RRF، reranking اختياري، ACL filters، و evaluation dataset. أخرج تقريرًا يقارن recall@5 و MRR و nDCG و P95 latency والتكلفة.

  1. اكتب 50 query مع relevance judgments.
  2. قارن dense-only و BM25-only و hybrid.
  3. اختبر مستخدمًا يحاول استرجاع مستند tenant آخر.
  4. حدّث وثيقة واحذف أخرى وتحقق من freshness/deletion.
  5. أوقف embedding provider واختبر fallback والـ timeouts.
هل cosine similarity المرتفعة تثبت أن النتيجة صحيحة؟
لا؛ هي إشارة ترتيب تعتمد على النموذج والبيانات. الجودة تُقاس بأحكام relevance على استعلامات ممثلة.
هل نطبق صلاحيات tenant بعد retrieval؟
لا. يجب تقييد الاستعلام بالـ tenant والـ ACL قبل إرجاع أي candidate أو context.
12

Approximate Nearest Neighbors من جوه: IVF بإيدك وقياس Recall مقابل السرعة

Exact search vs an inverted-file index: the recall/latency dial, executed
Deep dive

البحث الدقيق (exact) بيقارن الـ query بكل vector: مضمون 100% وبطيء خطيًا مع حجم البيانات. كل الـ vector databases بتستخدم بحث تقريبي بيضحّي بنسبة من الـ recall مقابل سرعة. لازم تعرف إن ده اختيار، وإن الـ recall بتاع الـ index نفسه رقم بيتقاس — ومختلف عن جودة الـ embeddings.

IVF (Inverted File) أبسط index تقريبي: قسّم الـ vectors لـ clusters بـ k-means، وعند البحث دوّر بس في أقرب كام cluster (nprobe).

Pythonivf_index.py — build with k-means, search with nprobe, measure recall@10 and work doneExecuted ✓
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)")
ConsoleOutput — captured from a real run
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)ذاكرة أقل وبناء أسرع؛ محتاج إعادة تدريب لما التوزيع يتغير
الفلترة + ANN = مصيدة

لو الـ index رجّع أقرب 10 وبعدين فلترت بالـ tenant، ممكن يتبقى 0. ولو tenant صغير جوه index مشترك كبير، جيرانه الحقيقيين ممكن ما يظهروش أصلًا في الـ candidates. الحلول: فلترة جوه البحث (pre-filter / filtered ANN حسب دعم النظام)، partition أو index لكل tenant، أو exact search للـ tenants الصغيرة. وفي كل الحالات: قِس recall مع الفلتر مش من غيره.

13

خريطة تغطية الأهداف

Learning objective coverage

الأهداف العشرة المدرجة في خريطة المنهج تم تناولها عبر الأقسام والتمارين أعلاه. التغطية تعني وجود شرح أو نشاط تعليمي، ولا تعني الإتقان أو الاعتماد أو الجاهزية الإنتاجية دون تنفيذ المشروع والاختبارات.

14

HNSW من جوه: ليه بيلاقي الجيران من غير ما يقارن بكل حاجة

How HNSW navigates a proximity graph
Deep dive

IVF (اللي بنيناه في المعمل اللي فات) بيقسّم الفضاء لـ clusters ويدوّر في أقرب كام cluster. HNSW فكرته مختلفة: graph كل vector فيه متوصل بأقرب جيرانه، والبحث «مشي طمّاع» على الـ graph: تبدأ من نقطة، تروح للجار الأقرب للسؤال، وتكرر لحد ما مفيش جار أقرب.

Layer 2Layer 1Layer 0 (all)green = nearest neighbour found
HNSW: sparse upper layers give long jumps; the dense bottom layer gives precision

الآلية بالترتيب:

  1. كل vector بيتحط في layer 0، وبيترقّى عشوائيًا لـ layers أعلى باحتمال بيقل أُسّيًا (زي skip list). فالـ layers العليا فيها نقط قليلة متباعدة = «طرق سريعة».
  2. الإدخال: بندوّر على أقرب نقط للـ vector الجديد بقائمة مرشحين حجمها ef_construction، ونوصّله بأقرب M منهم (مع pruning عشان الجيران يبقوا متنوعين في الاتجاه).
  3. البحث: نبدأ من الـ 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_searchWITH (ef_construction = 64)
ef_searchعمق البحث لكل queryrecall ↑ latency ↑ — بيتغيّر من غير rebuildSET hnsw.ef_search = 100

القيم الافتراضية والحدود بتتغير بين نسخ pgvector — راجع الـ README للنسخة اللي عندك قبل ما تعتمد على رقم.

HNSW مقابل IVF (IVFFlat في pgvector):

HNSWIVFFlat
Recall/latencyأفضل trade-off عمومًاأقل عند نفس السرعة
Buildأبطأ وأتقل في الذاكرةأسرع، لكن محتاج داتا موجودة عشان يتعلم الـ centroids (ما تبنيهوش على جدول فاضي)
Inserts مستمرةبتتعامل معاها كويسالـ centroids بتقدم لو التوزيع اتغير ← rebuild دوري
Tuning وقت الاستعلامhnsw.ef_searchivfflat.probes
الاختيار العملي

في PostgreSQL ابدأ بـ HNSW وقِس. لو الذاكرة بقت المشكلة، فكّر في تقليل الأبعاد (بعض نماذج الـ embeddings بتدعم أبعاد أقل) أو quantization (halfvec أو binary في pgvector) — وكل ده لازم يتقاس على الـ golden set بتاعك مش على benchmark عام.

15

معمل: graph search بإيدك — recall مقابل ef، وانهيار الـ post-filter

Executed lab: ef_search trade-off and filtered-search recall collapse
Practical

بنبني layer 0 بتاع HNSW (graph بـ M جيران) على 1500 vector متجمّعة في 30 «موضوع» زي الـ embeddings الحقيقية، وبنقيس recall@10 وعدد مقارنات المسافة لكل query مقابل الـ brute force. بعدين بنجرب سيناريو الـ multi-tenant: tenant بيملك ~5% بس من الـ vectors، وبنفلتر بعد البحث.

Pythonhnsw_lab.pyExecuted ✓
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")
ConsoleOutput — captured from a real run
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 المشترك بيخسر.
16

Metadata filtering في الإنتاج: pre vs post vs iterative

Filtered vector search strategies in PostgreSQL/pgvector
Deep dive

ليه المشكلة موجودة؟ الـ 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 صغير).

SQLfiltered_search.sql
-- 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 كبير = صيانة وذاكرة
Failure mode صامت

post-filter بيرجّع 3 نتايج بدل 10 ← الـ LLM بيجاوب «مفيش معلومات» ← المستخدم يفتكر المستند مش موجود. مفيش error ولا alert. راقب metric زي retrieval.result_count (histogram) و alert لو نسبة الـ queries اللي رجعت أقل من k زادت.

17

Multi-tenant layouts للـ vector store

Shared index, partition, or index per tenant
Deep dive
Layoutالعزلالأداءالتشغيلمناسب لـ
جدول واحد + tenant_id + RLSمنطقي (يعتمد على RLS/الكود)مشكلة الفلتر الضيقالأسهلآلاف tenants صغيرة
Declarative partitioning بالـ tenant (أو hash buckets)منطقي + فصل فيزيائي جزئيكل partition ليها index أصغرمتوسطtenants متوسطة/كبيرة
Schema/DB لكل tenantقويممتاز للـ tenantmigrations لمئات الـ DBsenterprise بعقود عزل
Hybrid (pool + silo)حسب الخطةحسب الخطةrouting layerSaaS بخطط مختلفة

الاختيار ده نفسه قرار الـ SaaS isolation اللي في درس Multi-Tenant — الـ vectors لازم تمشي على نفس نموذج العزل بتاع باقي بيانات الـ tenant (مش قرار منفصل)، وإلا الـ tenant deletion والـ data residency هيبقوا كابوس.

18

Freshness و re-indexing: المستند اتعدّل… الـ index لسه قديم

Keeping the index in sync with the source of truth
Deep dive

المشكلة: الـ 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.
C#ReindexWorker.cs
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);
        }
    }
}
19

Embedding model migration من غير downtime

Changing the embedding model safely
Deep dive

ليه صعب؟ الـ vectors من نموذجين مختلفين مالهاش علاقة ببعض — حتى لو نفس عدد الأبعاد. مينفعش تخلط؛ السؤال لازم يتعمله embed بنفس النموذج اللي اتعمل بيه الـ index. فالترحيل = بناء index جديد كامل.

1. Dual-writenew docs → v1 + v22. Backfill v2throttled batches3. Shadow evalgolden set + live4. Switch aliasflag per tenant5. Retire v1after soakRollback at any step = flip the alias back to v1v1 stays complete and current until step 5
Embedding migration: dual-write, backfill, shadow-evaluate, then switch the alias
SQLembedding_versions.sql
-- 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.

20

Retrieval debugging: من «الإجابة غلط» للسبب في 15 دقيقة

A systematic retrieval debugging procedure
Practical
  1. هل المستند موجود ومفهرس؟ ابحث بالـ document ID في الـ chunks: موجود؟ active؟ الـ ACL صح؟ الـ embedding model version صح؟
  2. هل الـ chunk الصح فيه الإجابة كاملة؟ ساعات الـ chunking قطع الجدول أو فصل العنوان عن المحتوى.
  3. Rank الـ chunk الصح في كل stage: dense rank، sparse rank، بعد الدمج، بعد الفلتر، بعد الـ rerank. السجل ده لازم يكون في الـ trace.
  4. لو dense rank سيء والـ sparse كويس: مفردات خاصة/أكواد → زوّد وزن الـ lexical أو query expansion.
  5. لو الاتنين سيئين: السؤال بصيغة بعيدة عن نص المستند → query rewriting، أو أضف «عنوان + ملخص» للـ chunk text قبل الـ embedding (contextual chunk headers).
  6. لو كان في الـ top-k واتشال: الفلتر أو الـ reranker أو حد الـ tokens في الـ context assembly.
  7. لو كان في الـ context والإجابة غلط: المشكلة generation مش retrieval ← روح لـ faithfulness eval.
JSONretrieval-trace.json (one query)
{
  "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
}
Production note

سجّل IDs والـ scores مش النصوص (PII). ولما حد يشتكي، الـ trace ده هو اللي بيحوّل «الـ AI غبي» لـ «الـ chunk الصح اتشال في الـ ACL filter عشان الـ group mapping اتغيّر امبارح».

21

Knowledge check

Check your understanding
Basics

Tenant بيملك 2% من الـ vectors في index HNSW مشترك. الـ queries بتاعته بترجع نتايج ناقصة. إيه السبب الأرجح؟

غيرت الـ embedding model لنموذج بنفس عدد الأبعاد. ينفع تستخدم الـ index القديم للأسئلة الجديدة؟

إمتى reranker بيضيف قيمة قليلة؟

22

تمارين محلولة

Solved exercises
Practical
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.

23

Mini project: Retrieval quality dashboard

Mini project
Practical

ابنِ لـ 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 لوحده فشل فيها.

24

أسئلة إنترفيو: Junior → Senior → Staff

Interview ladder
Basics
(Junior) ليه بنستخدم ANN بدل brute force؟
لأن المقارنة بكل vector خطية في عدد الـ vectors؛ ANN (HNSW/IVF) بيقارن بجزء صغير مقابل خسارة بسيطة في الـ recall بنتحكم فيها بـ parameters.
(Junior) إيه فايدة hybrid search؟
الـ dense بيلقط المعنى والـ lexical بيلقط الكلمات الحرفية (أكواد، أسماء)، والدمج بـ RRF بيغطي الاتنين من غير normalization للـ scores.
(Senior) إزاي تقرر ef_search في الإنتاج؟
تقيس منحنى recall@k مقابل p95 latency على golden set واقعي، وتختار أقل قيمة بتحقق هدف الـ recall جوه الـ latency budget، وممكن تخليها ديناميكية (أعلى للـ queries المهمة/الفلاتر الضيقة).
(Senior) اشرح خطة ترحيل embedding model لـ 50 مليون chunk.
عمود/جدول جديد، dual-write، backfill throttled بأولوية الـ tenants النشطة، shadow eval على golden set وعينة live، cutover بـ flag لكل tenant، soak، ثم retire. مع حساب التكلفة والـ rate limits وخطة rollback.
(Staff) pgvector ولا vector DB مخصص؟ دافع عن قرارك.
ابدأ من القيود: حجم الـ vectors، QPS، نوع الفلاتر، العزل، الفريق. pgvector بيكسب في البساطة والـ transactions مع الـ metadata و RLS وتقليل المكونات حتى مستوى معين؛ الـ DB المخصص بيكسب في الأحجام الضخمة والـ filtered search المتقدم والـ scaling المستقل. القرار في ADR مع benchmark على بياناتك وخطة خروج (abstraction للـ retriever).
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خريطة التغطية: 10 عنصر من الـ Roadmap ومكان شرحه في الدرس
New sectionRetrieval requirements and relevance judgments§13
New sectionChunking strategies and metadata design§13
New sectionDense sparse and hybrid retrieval§13
New sectionANN indexes and recall latency trade-offs§13
New sectionFiltering and tenant isolation§13
New sectionReranking and query transformation§13
New sectionRecall@k MRR and nDCG evaluation§13
New sectionIndex versioning and incremental updates§13
New sectionDeletion and data governance§13
New sectionRetrieval observability and failure analysis§13

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس