Software Engineer Encyclopedia
0%
Domain 10 · Python, Machine Learning & Data Engineering · Topic 10.6

Document Ingestion للـRAG

Document Ingestion for RAG

PDF/OCR, layout parsing, chunking, metadata, embeddings, incremental re-indexing and tenant isolation.

  • Intermediate
  • ~14 min read
  • 13 sections
  • 9 code examples
  • 1 diagrams
  • 6 questions
  • Priority L2 · Essential
  • Python · OCR · Embeddings · Vector indexes

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

  • تبني incremental indexing بـ content hashing على مستوى المستند والـ chunk.
  • تتعامل مع الحذف والتعديل والتغييرات الشكلية.
  • تكتشف الـ near-duplicates.

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

أساسيات البرمجة والـ complexity. مش محتاج خبرة Python سابقة.

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

PRACTICALتدرب | Ingestion يعيد فهرسة المتغير بس

01

Document Ingestion هو بداية جودة RAG

Build a traceable document pipeline
Deep dive

RAG لا يبدأ من vector database؛ يبدأ من document lifecycle. تحتاج تعرف مصدر الملف، owner، tenant، permissions، version، checksum، timestamps، classification، language، parser version، و status. كل chunk لازم يرجع إلى document/source span حتى تعرض citations وتطبق deletion.

Pipeline: discover → authorize → fetch → parse → normalize → classify/redact → chunk → enrich metadata → embed → index → verify → publish. اجعل ingestion async وقابلًا لإعادة المحاولة، ولا تجعل الملف يظهر للمستخدم قبل اكتمال فهرسته والتحقق من صلاحياته.

02

PDF Parsing و OCR و Layout-aware Extraction

Text is not always a flat string
Practical

PDF قد يحتوي text layer أو صور ممسوحة أو جداول أو أعمدة أو headers/footers. استخراج النص وحده قد يفسد ترتيب القراءة. استخدم parser يخرج blocks مع page number و bounding boxes و table structure عند الحاجة. OCR يضيف أخطاء مثل 0/O و1/l؛ قِس confidence واحتفظ بإمكانية مراجعة المصدر.

افصل parser output عن normalized document representation. احتفظ بالـ raw file checksum، parser version، page references، و warnings. تعامل مع ملفات مشفرة أو تالفة أو huge pages بحدود زمن وحجم، واعزل parser process للملفات غير الموثوقة.

PDF Parsing, Layout and OCR Quality Engineering

PDF ليس دائمًا نصًا متسلسلًا؛ قد يحتوي positioned glyphs، columns، tables، headers/footers، scanned pages، images، و mixed layouts. Text extraction البسيط قد يخلط ترتيب الأعمدة أو يفقد reading order. OCR يضيف recognition errors، خصوصًا مع Arabic ligatures، low resolution، skew، tables، و mixed scripts.

قيّم parser على gold set من documents ممثلة، مع metrics مثل character error rate/word error rate للـ OCR، table cell accuracy، reading-order correctness، page coverage، و metadata retention. احتفظ page number و bounding boxes و parser version. عند انخفاض confidence أرسل human review بدل اختراع نص نظيف.

PythonText extraction is a noisy perception pipeline
# A simple character error rate (CER) helper for OCR evaluation
def cer(reference: str, hypothesis: str) -> float:
    # Production implementation should use a tested edit-distance library.
    prev = list(range(len(hypothesis) + 1))
    for i, a in enumerate(reference, 1):
        cur = [i]
        for j, b in enumerate(hypothesis, 1):
            cur.append(min(cur[-1] + 1, prev[j] + 1, prev[j-1] + (a != b)))
        prev = cur
    return prev[-1] / max(1, len(reference))
print(round(cer('invoice total 120', 'invoice totaI 120'), 3))

Parsing Tables و Arabic/Multilingual Documents

الجداول ليست نصًا عاديًا؛ حافظ على headers وربط كل cell بعموده وصفه، وإلا قد يظهر رقم دون معنى. في المستندات العربية/ثنائية اللغة، حافظ على reading order و RTL text، ولا تخلط ترتيب الأعمدة. OCR قد ينتج حروفًا متشابهة؛ اختبر أسماء المنتجات والأرقام والتواريخ تحديدًا.

أضف language و document type و section path إلى metadata. عند embedding، اختبر multilingual model على queries عربية وإنجليزية ومختلطة. لا تترجم كل شيء تلقائيًا؛ الترجمة قد تغير المصطلحات القانونية أو الفنية.

03

Chunking Strategies

Preserve meaning and retrieval boundaries
Deep dive

Chunking يقسم المستند لوحدات retrieval. Fixed-size token chunks سهلة لكنها قد تقطع heading/table/code. Recursive splitting يحترم separators تدريجيًا. Structure-aware chunking يعتمد headings/paragraphs/tables. Semantic chunking يستخدم تغيّر المعنى لكنه أعلى تكلفة وأكثر حساسية.

Overlap يحافظ على سياق الحدود لكنه يكرر النص ويزيد index size. لا تختَر chunk size واحدًا لكل corpus؛ جرّب على أسئلة حقيقية، وقيّم retrieval recall و context precision. خزّن parent document و section path و chunk index و token count.

PythonPreserve meaning and retrieval boundaries
def make_chunks(text, max_chars=1800, overlap=200):
    if max_chars <= overlap:
        raise ValueError("max_chars must exceed overlap")
    chunks, start = [], 0
    while start < len(text):
        end = min(start + max_chars, len(text))
        if end < len(text):
            boundary = text.rfind("\n\n", start, end)
            if boundary > start + max_chars // 2:
                end = boundary
        piece = text[start:end].strip()
        if piece:
            chunks.append(piece)
        if end == len(text):
            break
        start = max(start + 1, end - overlap)
    return chunks

Chunking Lab: قياس بدل التخمين

قارن fixed 300/600/900 tokens مع recursive structure-aware chunking على golden question set. لكل سؤال خزّن relevant source spans. قِس Recall@5 و MRR و context precision، ثم answer faithfulness. راقب token count والتكرار والـ index size والـ embedding cost. لا تستخدم عدد الأحرف بدل tokens كقاعدة عامة دون قياس، لأن العربية والكود والجداول تختلف في tokenization.

حافظ على parent-child relation: استرجع child chunk دقيقًا، ثم وسّع إلى parent section عند الحاجة. أضف title/heading metadata إلى embedding input إذا ثبت أنه يحسن retrieval.

PythonCompare chunk policies empirically
experiment = [
  {"chunker": "fixed", "size_tokens": 400, "overlap": 60},
  {"chunker": "fixed", "size_tokens": 700, "overlap": 100},
  {"chunker": "recursive", "size_tokens": 600, "overlap": 80},
]
# Run the same golden queries and compare retrieval metrics + cost.

Chunking Algorithms and Boundary Preservation

Fixed-token chunking سهل وقابل للتكرار لكنه قد يقطع headings أو tables أو code blocks. Recursive/semantic chunking يحاول احترام boundaries، لكنه يعتمد على parser واللغة. Parent-child retrieval يخزن chunks صغيرة للبحث ويعيد parent section أوسع للسياق. Overlap يساعد عند الحدود لكنه يكرر النص ويرفع index size وقد يسبب duplicate evidence.

لا يوجد chunk size مثالي عالمي. اعمل experiment matrix عبر chunk size/overlap/strategy، وقس Recall@k و MRR و context precision و answer groundedness و latency/cost. احفظ chunk ID و document ID و page/section offsets و content hash حتى يمكن تحديثه أو حذفه بدقة.

PythonChunk size is a retrieval design variable
def fixed_chunks(tokens: list[str], size: int, overlap: int):
    if size <= 0 or not 0 <= overlap < size:
        raise ValueError('require size > 0 and 0 <= overlap < size')
    step = size - overlap
    return [tokens[i:i+size] for i in range(0, len(tokens), step)]

chunks = fixed_chunks([f't{i}' for i in range(11)], size=4, overlap=1)
print(chunks)
04

Metadata و Embeddings و Index Versioning

Make retrieval filterable and reproducible
Practical

Metadata أساسي للفلترة: tenant_id، document_id، source_uri، page، section، access tags، language، created_at، version، checksum. لا تعتمد على metadata من user-supplied file كحقيقة أمنية؛ derive ownership and ACL from trusted server-side records.

Embedding model له dimensions و normalization و version. لا تخلط vectors من model versions مختلفة في نفس index دون strategy. خزّن embedding_model_id و dimensions و chunker_version. عند تغيير النموذج، أنشئ index version جديدًا ثم swap alias بعد التحقق بدل كسر البحث أثناء reindex.

PythonMake retrieval filterable and reproducible
record = {
    "tenant_id": trusted_tenant_id,
    "document_id": document_id,
    "chunk_id": f"{document_id}:v{version}:c{index}",
    "source_version": version,
    "page": page_number,
    "section_path": ["Policy", "Refunds"],
    "parser_version": "pdf-parser-3",
    "chunker_version": "recursive-2",
    "embedding_model": "embedding-model-version",
    "text": chunk_text,
}
05

Incremental Re-indexing و Deletion

Update only what changed, delete what must disappear
Deep dive

احسب checksum للمصدر. لو لم يتغير، لا تعِد parsing/embedding بلا داعٍ. لو تغير، أنشئ version جديدة، ثم استبدل chunks القديمة ذريًا أو عبر alias swap. اجعل ingestion idempotent باستخدام document/version/chunk IDs. دعم deletion يجب أن يزيل النص والـ vectors والـ caches والـ derived artifacts وفق سياسة retention.

Multi-tenant isolation ليس مجرد filter اختياري يضيفه prompt. طبّق ACL server-side في كل retrieval، واختبر cross-tenant leakage. لو عندك document-level ACL، طبّقها قبل تسليم passages إلى model. سجل audit metadata دون تسريب محتوى حساس.

Incremental Indexing: عالج اللي اتغيّر بس، وامسح اللي اتشال

أول مرة بتعمل ingestion لكل المستندات. بعدها كل يوم 2% منها بيتغير. لو كل مرة بتعيد الـ embedding لكل حاجة، بتدفع 50 ضعف اللازم وبتاخد ساعات. ولو بتضيف بس، المستندات المحذوفة والنسخ القديمة بتفضل في الـ index والمساعد بيجاوب منها. الـ incremental indexing بيحل الاتنين بفكرة واحدة: hash للمحتوى.

Pythonincremental_index.py — three sync runs over a changing document set, counting embedding callsExecuted ✓
import hashlib, re

index = {}          # chunk_id -> {"doc": ..., "hash": ..., "text": ...}   (stands in for the vector store)
manifest = {}       # doc_id -> {"doc_hash": ..., "chunk_ids": [...]}       (what we indexed last time)
embedding_calls = 0

def h(text):
    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]

def normalise(text):
    """Hash the MEANING-bearing text, not incidental whitespace: avoids re-embedding on cosmetic edits."""
    return re.sub(r"\s+", " ", text).strip()

def chunks_of(text):
    return [normalise(p) for p in text.split("\n\n") if normalise(p)]

def embed(text):
    global embedding_calls
    embedding_calls += 1                                   # every call costs money and time
    return [len(text)]

def sync(docs):
    """docs: the COMPLETE current set {doc_id: text}. Returns counters for this run."""
    global embedding_calls
    before, stats = embedding_calls, dict(unchanged_docs=0, chunks_added=0, chunks_kept=0, chunks_removed=0, docs_deleted=0)
    for doc_id in list(manifest):                          # 1) deletions: anything indexed but no longer present
        if doc_id not in docs:
            for cid in manifest.pop(doc_id)["chunk_ids"]:
                index.pop(cid, None); stats["chunks_removed"] += 1
            stats["docs_deleted"] += 1
    for doc_id, text in docs.items():
        doc_hash = h(normalise(text))
        old = manifest.get(doc_id)
        if old and old["doc_hash"] == doc_hash:            # 2) fast path: whole document unchanged
            stats["unchanged_docs"] += 1; stats["chunks_kept"] += len(old["chunk_ids"]); continue
        new_ids = []
        for chunk in chunks_of(text):                      # 3) chunk-level diff: id = doc + content hash
            cid = f"{doc_id}:{h(chunk)}"
            new_ids.append(cid)
            if cid in index:
                stats["chunks_kept"] += 1
            else:
                index[cid] = {"doc": doc_id, "text": chunk, "vector": embed(chunk)}; stats["chunks_added"] += 1
        for cid in set(old["chunk_ids"] if old else []) - set(new_ids):
            index.pop(cid, None); stats["chunks_removed"] += 1   # stale chunks of an edited document
        manifest[doc_id] = {"doc_hash": doc_hash, "chunk_ids": new_ids}
    stats["embedding_calls"] = embedding_calls - before
    return stats

policy_v1 = "Returns are accepted within 30 days.\n\nRefunds take 5 business days.\n\nGift cards are final sale."
docs = {"returns": policy_v1,
        "shipping": "Standard shipping takes 3-7 days.\n\nExpress is next day.",
        "legacy-faq": "Fax us your order form.\n\nWe reply within two weeks."}

def report(label, stats):
    print(f"{label:<44} " + "  ".join(f"{k}={v}" for k, v in stats.items()) + f"  | index size={len(index)}")

report("run 1: initial load", sync(docs))
report("run 2: nothing changed", sync(docs))

docs["returns"] = policy_v1.replace("5 business days", "3 business days")      # one paragraph edited
docs["shipping"] = "Standard shipping takes 3-7 days.\n\n\n   Express is   next day."   # whitespace-only change
del docs["legacy-faq"]                                                              # document removed at the source
docs["warranty"] = "Electronics carry a 12 month warranty."
report("run 3: 1 edit, 1 cosmetic, 1 delete, 1 new", sync(docs))

print("\nstale content check:", "no chunk mentions '5 business days' or 'Fax'" if not any(
    "5 business days" in c["text"] or "Fax" in c["text"] for c in index.values()) else "STALE CHUNKS REMAIN")

# ---------- near-duplicates: the same paragraph copied into several documents ----------
def shingles(text, k=3):
    w = re.findall(r"\w+", text.lower())
    return {" ".join(w[i:i + k]) for i in range(len(w) - k + 1)}
def jaccard(a, b):
    A, B = shingles(a), shingles(b)
    return len(A & B) / len(A | B) if A | B else 0.0

a = "Refunds are issued to the original payment method within five business days of receiving the item."
b = "Refunds are issued to the original payment method within five business days after receiving the item!"
c = "Express shipping is delivered on the next business day for orders placed before noon."
print(f"\nnear-duplicate detection (Jaccard on 3-word shingles): a~b={jaccard(a, b):.2f}   a~c={jaccard(a, c):.2f}   exact hashes equal: {h(a) == h(b)}")
ConsoleOutput — captured from a real run
run 1: initial load                          unchanged_docs=0  chunks_added=7  chunks_kept=0  chunks_removed=0  docs_deleted=0  embedding_calls=7  | index size=7
run 2: nothing changed                       unchanged_docs=3  chunks_added=0  chunks_kept=7  chunks_removed=0  docs_deleted=0  embedding_calls=0  | index size=7
run 3: 1 edit, 1 cosmetic, 1 delete, 1 new   unchanged_docs=1  chunks_added=2  chunks_kept=4  chunks_removed=3  docs_deleted=1  embedding_calls=2  | index size=6

stale content check: no chunk mentions '5 business days' or 'Fax'

near-duplicate detection (Jaccard on 3-word shingles): a~b=0.65   a~c=0.00   exact hashes equal: False

Run 2 = صفر نداءات embedding. الـ doc hash اتقارن ولقاه زي ما هو فاتخطى المستند كله. ده اللي بيخلي الـ sync يتشغّل كل ساعة من غير تكلفة.

Run 3: نداءين embedding بس: واحد للفقرة المعدّلة وواحد للمستند الجديد. تعديل فقرة واحدة = إعادة embedding لـ chunk واحد بس (الـ chunk id مبني على hash المحتوى، فالفقرتين اللي ما اتغيروش اتعرفوا واتسابوا). والـ chunk القديم («5 business days») اتمسح — من غير الخطوة دي المساعد هيلاقي الرقمين ويختار أي واحد.

التغيير الشكلي ما كلّفش حاجة: الـ normalise قبل الـ hash خلّى المسافات والسطور الفاضية ما تتحسبش تغيير. من غيره، إعادة حفظ ملف من محرر مختلف بتعيد فهرسة كل حاجة.

الحذف محتاج القائمة الكاملة: الـ sync بياخد كل المستندات الحالية، مش التغييرات بس — دي الطريقة الوحيدة يعرف إن legacy-faq اتشال. لو المصدر بيدّيك تغييرات بس (webhooks)، لازم يبعت أحداث حذف صريحة، ولازم reconciliation دوري كامل يلقط اللي فات.

الـ near-duplicates: الـ hash الدقيق بيفشل مع أي فرق حرف (False). الـ Jaccard على الـ shingles بيلقط التشابه العالي. مهم لأن نفس الفقرة القانونية المنسوخة في 40 مستند هتملى الـ top-k كله بنفس المعلومة وتطرد النتايج المفيدة.

حذف = التزام أمني وقانوني

لما مستخدم يمسح مستند أو صلاحيته تتسحب، الـ chunks لازم تختفي من الـ index ومن أي cache للإجابات. الـ index اللي بيضيف وما بيمسحش بيخالف «حق المحو» وبيسرّب محتوى المفروض إنه اتشال. اكتب test: احذف مستند، شغّل الـ sync، واتأكد إن البحث عن جملة مميزة فيه بيرجّع صفر.

غيّرت الـ chunking strategy (الحجم من 300 لـ 500 token). إيه اللي لازم يحصل للـ index؟

Incremental Indexing, Deduplication and Deletion

Ingestion يجب أن تكون idempotent: نفس document version لا ينتج chunks مكررة عند retry. استخدم stable document ID + content hash + parser/chunker/embedding version لتحديد تغيّر فعلي. Upsert على chunk IDs، واحتفظ manifest يربط document بال chunks. عند document update، احذف/استبدل chunks القديمة ضمن transaction أو staged alias switch.

Deletion ليست مجرد حذف row من SQL؛ قد تحتاج حذف vectors، lexical index entries، cached answers، derived summaries، و backups حسب policy. احتفظ tombstone يمنع إعادة إدخال document من stale pipeline. Tenant-scoped authorization يجب تطبيقه في retrieval query نفسها، لا بعد إرسال كل النتائج إلى LLM.

PythonKeep the corpus consistent over time
import hashlib

def content_hash(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()

payload = b'policy version 3'
print(content_hash(payload))
# Stable IDs should combine tenant/document/version/chunk identity;
# never rely on a random ID if retries must be idempotent.
06

اختبار جودة Ingestion

Golden documents and parser regression
Practical

جهز corpus مرجعي: PDF نصي، scanned PDF، جدول، multi-column، عربي/إنجليزي، ملف كبير، corrupt file، document فيه prompt injection، ونسخة معدلة. قِس extraction coverage، page alignment، chunk count، duplicate rate، OCR confidence، permission correctness، و re-index behavior.

أضف tests تضمن أن كل chunk له source reference وأن metadata لا تختلط بين tenants. ingestion failure يجب ألا ينشر partial index للمستخدمين. احتفظ بعينة من parser output لمراجعة regressions عند ترقية المكتبة.

المخرجIngestion pipeline قابل للتكرار، incremental، auditable، permission-aware، وله test corpus قبل أن نضيف vector search.
07

Document Security و Deletion Propagation

Permissions and lifecycle are end-to-end
Pitfalls

عند إلغاء صلاحية مستند، يجب أن يتوقف ظهوره فورًا حتى لو vector deletion asynchronous. طبّق authoritative ACL check وقت retrieval، واستخدم tombstone/version state لمنع stale index من إعادة إظهاره. عند حذف tenant، تتبع raw object، parsed text، chunks، embeddings، caches، exports، backups وفق policy.

اختبر race condition: ingestion بدأ قبل revoke ثم اكتمل بعده. قبل publish، أعد التحقق من document version والـ ACL. لا تجعل ingestion worker يثق في tenant_id القادم من file metadata أو message دون تحقق من DB.

08

Ingestion Throughput و Backpressure

Scale document processing safely
Deep dive

قسّم ingestion إلى stages مع queue بين parsing و embedding/indexing إذا اختلفت معدلاتها. ضع per-tenant quotas، max file size/pages، concurrency limits، retry policy، و dead-letter handling. Embedding APIs لها rate limits؛ batch requests ضمن provider limits وراقب partial failures. لا تضع ملايين tasks في memory queue.

استخدم checkpoints على مستوى document/version، و persist stage status. إذا فشل embedding بعد parsing، أعد embedding فقط بدل إعادة OCR. قِس documents/hour و cost/document و p95 processing time و queue age.

09

الـ ingestion pipeline كامل في صورة واحدة

The RAG ingestion pipeline end to end
Deep dive

كل مشكلة جودة في RAG بتتتبّع لخطوة هنا. لو المستند ما اتقراش صح، أو اتقطع في مكان غلط، أو الـ metadata ناقصة، أحسن موديل في العالم مش هيصلحه.

Upload / URLSSRF guard, AV scanStore rawblob + sha256Parselayout, tables, OCRNormalizeArabic, whitespaceChunkstructure-awareEnrichtitle, ACL, langEmbedbatch, model vNIndexvector + keywordMark ready+ notify (SignalR)Delete / re-indexby doc_id + version → purge old chunks everywhereDead-letter per stage; metrics: docs/min, parse failures, chunks/doc
Ingestion: every stage is idempotent, versioned and observable; deletion travels the same path
المرحلةIdempotency keyالفشل الشائعالـ metric
Store rawsha256 للمحتوىنفس الملف اترفع مرتين ← chunks مكررةdedup rate
Parse(doc_id, parser_version)PDF ممسوح ضوئيًا ← نص فاضي؛ جداول ← نص متلخبط% صفحات بنص < 50 حرف
Chunk(doc_id, chunker_version)قطع في نص جدول/قائمةتوزيع أطوال الـ chunks
Embed(chunk_hash, embed_model)تغيير موديل الـ embeddings من غير re-index كامل ← vectors مش قابلة للمقارنةchunks بموديل قديم
Indexchunk_idصلاحيات (ACL) ما اتنقلتش ← تسريبchunks من غير tenant/acl

قاعدة الـ embedding model: الـ query والـ chunks لازم يتعملوا embed بنفس الموديل والنسخة. تغيير الموديل = index جديد بالتوازي (blue/green)، eval على الاتنين، وبعدين switch — مش تحديث تدريجي يخلط vectors من موديلين.

10

مقارنة الـ chunking strategies على مستند حقيقي

Chunking compared
Practical
الاستراتيجيةالفكرةتكسبتخسر
Fixed tokens + overlapكل 512 token مع 64 overlapبسيطة وثابتةبتقطع في نص جملة/جدول
Recursive (فقرات ← جمل)تقسيم على حدود طبيعية لحد ما الحجم يناسبchunks متماسكةأطوال متفاوتة
Structure-awareعناوين Markdown/HTML، أقسام PDF، صفوف جداولكل chunk معاها مسار العنوان («سياسة الإجازات › الإجازة المرضية»)محتاجة parser كويس
Parent-childتبحث بـ chunks صغيرة، وترجّع الـ parent الأكبر للموديلدقة بحث + سياق كافيtokens أكتر في الـ prompt
Contextual chunk headersتضيف للـ chunk جملة سياق (عنوان المستند والقسم) قبل الـ embedrecall أحسن للـ chunks الغامضة («المدة 14 يوم»)تكلفة إضافية لو السياق متولد بـ LLM
Pythonstructure-aware chunker with heading paths (illustrative)
import re

def chunk_markdown(text: str, max_chars: int = 1500):
    path, buf, out = [], [], []
    def flush():
        if buf:
            body = "\n".join(buf).strip()
            if body:
                out.append({"heading_path": " > ".join(path), "text": f"[{' > '.join(path)}]\n{body}"})
            buf.clear()
    for line in text.splitlines():
        m = re.match(r"^(#{1,6})\s+(.*)", line)
        if m:
            flush()
            level = len(m.group(1))
            path[:] = path[: level - 1] + [m.group(2).strip()]
            continue
        buf.append(line)
        if sum(len(x) for x in buf) > max_chars:      # split long sections at paragraph boundaries
            flush()
    flush()
    return out

القرار بالقياس: نفس الـ golden set، كل strategy، قِس recall@k و MRR للـ retrieval (مش جودة الإجابة النهائية بس). الـ Capstone فيه 400+ سؤال بشرائح عشان التجربة دي بالظبط.

11

الـ ingestion من ‎.NET: worker و queue و status

Running ingestion from ASP.NET Core
Practical
C#IngestionWorker.cs (shape)
public sealed class IngestionWorker(Channel<IngestJob> queue, IServiceScopeFactory scopes, ILogger<IngestionWorker> log) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stop)
    {
        await foreach (var job in queue.Reader.ReadAllAsync(stop))
        {
            using var scope = scopes.CreateScope();
            var p = scope.ServiceProvider.GetRequiredService<IngestionPipeline>();
            using var _ = log.BeginScope(new Dictionary<string, object> { ["tenant"] = job.TenantId, ["doc"] = job.DocumentId });
            try { await p.RunAsync(job, stop); }                     // parse → chunk → embed (batched) → index → ready
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                log.LogError(ex, "Ingestion failed at {Stage}", (ex as StageException)?.Stage);
                await p.MarkFailedAsync(job, ex, stop);              // visible to the user; retry button; dead-letter after N
            }
        }
    }
}

في الإنتاج، الـ Channel بيتبدل بـ queue durable (Service Bus/Pub/Sub/Hangfire) عشان الـ jobs ما تضيعش مع restart، وحالة كل مستند (queued/processing/ready/failed) في الـ DB. الـ SSRF guard للـ URLs وفحص الـ uploads جزء من أول مرحلة — مشروحين في Secure Coding ومنفذين في CAPSTONE/ingestion.

12

اختبر فهمك

Knowledge Check
Practical
هل metadata التي يرسلها PDF تحدد tenant ownership؟
لا. الملكية والصلاحيات يجب أن تأتي من مصدر موثوق في backend.
لماذا نستخدم checksum و document version؟
للكشف عن التغييرات وإعادة فهرسة المتغير فقط مع دعم incremental updates والـ rollback.

اختبار الإتقان المهني

لماذا لا يكفي قياس OCR character accuracy وحده؟
لأن reading order والجداول والصفحات والـ metadata والـ layout قد تكون خاطئة حتى مع character accuracy جيدة.
لماذا نستخدم content hash و stable IDs في ingestion؟
لتحقيق idempotency واكتشاف التغيير ومنع تكرار chunks عند retry.
لماذا يجب تطبيق ACL قبل تمرير evidence إلى LLM؟
لمنع كشف بيانات غير مصرح بها؛ لا ينبغي الاعتماد على prompt ليطلب من النموذج تجاهل evidence غير المسموح.
13

Multimodal RAG and Structured Evidence

Tables, images and page-level provenance
Deep dive

Multimodal RAG قد يحتاج text chunks و table representations و image captions أو visual embeddings. لا تحول table إلى prose عشوائيًا إذا كانت العلاقات بين headers/cells مهمة؛ خزّن table schema و row/column context. للصور احتفظ page number و region coordinates و caption provenance، وميّز OCR text عن original extracted text.

Evidence object يجب أن يحمل source ID، tenant/ACL، document version، page/section، extraction method، و confidence. عند الإجابة، citations يجب أن تشير إلى evidence IDs موجودة ومصرح بها، ويمكن للمستخدم فتح المصدر الأصلي. لا تجعل model يخترع page number أو source URL.

PythonTables, images and page-level provenance
evidence = {
  'evidence_id': 'doc-42:v3:p7:table-2',
  'tenant_id': 'tenant-17',
  'document_version': 3,
  'page': 7,
  'kind': 'table',
  'parser_version': 'layout-parser-2',
  'acl_checked': True,
}
assert evidence['acl_checked'] and evidence['page'] > 0
print(evidence['evidence_id'])
↗

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

References & further reading

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

خريطة التغطية: 17 عنصر من الـ Roadmap ومكان شرحه في الدرس
New sectionDocument Ingestion§01
New sectionPDF Parsing and OCR§01
New sectionChunking Strategies§01
New sectionMetadata Extraction§01
New sectionEmbedding Generation§01
SuggestedDocument Ingestion§01
SuggestedPDF Parsing and OCR§01
SuggestedChunking Strategies§01
SuggestedMetadata Extraction§01
SuggestedEmbedding Generation§01
SuggestedHybrid Search§02
SuggestedReranking§03
SuggestedRetrieval Evaluation§03
SuggestedIncremental Re-indexing§03
SuggestedMulti-Tenant Document Isolation§03
SuggestedLayout-aware Parsing§02
SuggestedKnowledge Graphs§03

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

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