# فصل ۰۴ — `RAG` از صفر، بدونِ framework

<div dir="rtl">

# فصل ۰۴ — `RAG` از صفر، بدونِ framework

## در این فصل چه یاد می‌گیری

سه فصل است که کلِ پیکره را داخلِ پرامپت می‌چسبانیم. **برای دوازده سند می‌شود؛ برای دوازده هزار تا نه** — نه در حافظهٔ مدل جا می‌شود، نه پولش را می‌دهی، و همان‌طور که خواهی دید **نه حتی جوابِ بهتری می‌گیری**.

در این فصل سامانه‌ای می‌سازیم که **فقط تکه‌های مربوط را** پیدا می‌کند و همان‌ها را می‌فرستد. اسمش `RAG` است. نتیجه: **پرامپتی که به‌طورِ میانگین روی ۲۴ پرسش حدودِ شش برابر کوچک‌تر است، و دقتِ بالاتر** — ۱۶ از ۲۴ می‌شود ۱۸ از ۲۴. و آخرِ فصل دو عدد کنارِ هم می‌گذاریم که کلِ فصلِ ۵ از دلِ فاصله‌شان درمی‌آید.

![قفسه‌ای بزرگ از پرونده‌ها که فقط سه پوشه از آن بیرون کشیده شده](/lesson-assets/t5-s04-rag-from-scratch/prompt/01-image-pull-three-folders.png)

آخر این فصل می‌توانی:

- سند را با هم‌پوشانی به تکه بشکنی و بگویی چرا هم‌پوشانی لازم است
- یک فهرستِ برداری بسازی و جست‌وجوی شباهت بزنی
- `context` و پرامپتِ نهایی را درست سرِ هم کنی
- **بازیابی** را از **تولید** جدا اندازه بگیری

## قبل از شروع

**از ترمِ ۴ فصل ۸:** بار کردنِ مدلِ آمادهٔ چندزبانه، `attention_mask` و `masked mean`. همان کد را اینجا دوباره می‌نویسیم چون قلبِ بازیابی است.

**از سرنخ ترمِ ۴ فصل ۵ و ۶:** شباهتِ کسینوسی، و جست‌وجوی معنایی که رویش ساخته شد. آنجا اسمش را نگفتیم؛ **این همان است، در مقیاسِ یک سامانه.**

**از فصل ۱ همین ترم:** `chat` و اینکه پرسش آخرین سطرِ پیامِ کاربر است.

> 💡 **نکته:** **زمانِ تخمینی روی CPU: کمتر از یک دقیقه**، بیشترش صرفِ دانلودِ مدل در اولین اجرا. ارزیابی‌های این فصل روی ۲۴ پرسش‌اند و هر کدام یک بار `embed` می‌خواهند.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/zharfa/term-5-llm-engineering/session-04-rag-from-scratch.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

## ۱. اول ببین مسئله چقدر بزرگ است

</div>

```python
CORPUS = "\n\n".join(d["text"] for d in DOCS)
print("کلِ پیکره:", len(CORPUS), "نویسه در", len(DOCS), "سند")
print("اگر پیکره هزار برابر شود:", len(CORPUS) * 1000, "نویسه در یک پرامپت")
print("طولانی‌ترین سند:", max(len(d["text"]) for d in DOCS), "نویسه")
```

<div dir="rtl">

</div>

```text
کلِ پیکره: 3519 نویسه در 12 سند
اگر پیکره هزار برابر شود: 3519000 نویسه در یک پرامپت
طولانی‌ترین سند: 423 نویسه
```

<div dir="rtl">

**سه‌ونیم میلیون نویسه در یک پرامپت.** هیچ مدلی این را نمی‌گیرد، و اگر می‌گرفت هم **برای هر پرسش کلِ آن را حساب می‌کردی و پولش را می‌دادی.**

**و کتابخانهٔ نوردانه پیکرهٔ کوچکی است.** مستنداتِ یک شرکت، بایگانیِ ایمیل‌ها، تاریخچهٔ تیکت‌های پشتیبانی — هزار برابر که هیچ، صد هزار برابر.

**ایدهٔ `RAG` یک جمله است: قبل از پرسیدن، بگرد.**

## ۲. تکه کردن

</div>

```python
def chunk_doc(doc, size=3, overlap=1):
    """سند را به تکه‌های هم‌پوشان می‌شکند؛ مرزِ تکه، مرزِ جمله است."""
    parts = sentences(doc["text"])
    step = size - overlap
    out = []
    start = 0
    while start < len(parts):
        out.append({"doc": doc["id"], "title": doc["title"],
                    "text": " ".join(parts[start:start + size])})
        if start + size >= len(parts):
            break
        start += step
    return out


CHUNKS = [c for d in DOCS for c in chunk_doc(d)]
print("تعدادِ تکه‌ها:", len(CHUNKS))
print("میانگینِ طول:", round(sum(len(c["text"]) for c in CHUNKS) / len(CHUNKS)), "نویسه")
print()
for c in CHUNKS[3:5]:
    print(f"  [{c['doc']}] {c['text'][:78]}…")
```

<div dir="rtl">

</div>

```text
تعدادِ تکه‌ها: 30
میانگینِ طول: 142 نویسه

  [loans] عضو عادی هم‌زمان تا ۳ جلد کتاب امانت می‌گیرد. عضو دانشجویی هم‌زمان تا ۵ جلد کت…
  [loans] عضو پژوهشی هم‌زمان تا ۸ جلد کتاب امانت می‌گیرد. مدت امانت برای عضو عادی ۱۴ روز…
```

<div dir="rtl">

**سه تصمیم در این تابع هست و هر سه بعداً به تو ضربه می‌زنند اگر بد انتخاب کنی:**

**۱) مرزِ تکه کجاست؟** ما روی **جمله** بریدیم. **هرگز وسطِ جمله نبر** — نه فقط چون زشت است، بلکه چون `embedding`ِ نصفِ جمله معنای نصفه دارد و بازیابی را خراب می‌کند.

**۲) هر تکه چقدر باشد؟** تکهٔ کوچک دقیق است ولی زمینه ندارد؛ تکهٔ بزرگ زمینه دارد ولی `embedding`ش رقیق می‌شود — **بردارِ یک تکهٔ ده‌جمله‌ای میانگینِ ده موضوع است و به هیچ‌کدام نزدیک نیست.**

**۳) چرا هم‌پوشانی؟** به آن دو تکهٔ چاپ‌شده نگاه کن: **«عضو پژوهشی … تا ۸ جلد» در هر دو آمده.** بدونِ `overlap=1`، حقیقتی که سرِ مرز می‌افتد **هیچ‌وقت** با زمینه‌اش در یک تکه نمی‌نشیند. **اثرش را هم اندازه گرفته‌ایم:** روی این پیکره، `overlap=1` در برابرِ `overlap=0` بازیابی را عوض نمی‌کند (۱۶ از ۱۹ در هر دو) و نمرهٔ نهایی را از ۱۷ به ۱۸ می‌برد. پس مفید است، ولی معجزه نیست.

> ✅ **چک کن:** اگر `overlap` را برابرِ `size` بگذاری، `step` صفر می‌شود و حلقه **هرگز تمام نمی‌شود**. همیشه `overlap < size`. یک `assert` سه‌کلمه‌ای اول تابع، ساعتِ خوبی می‌خرد.

## ۳. فهرستِ برداری

</div>

```python
import torch
from transformers import AutoModel, AutoTokenizer

NAME = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
tokenizer = AutoTokenizer.from_pretrained(NAME)
encoder = AutoModel.from_pretrained(NAME)
encoder.eval()


@torch.no_grad()
def embed(texts, batch=32):
    out = []
    for i in range(0, len(texts), batch):
        b = tokenizer(texts[i:i + batch], padding=True, truncation=True,
                      max_length=128, return_tensors="pt")
        hidden = encoder(**b).last_hidden_state
        mask = b["attention_mask"].unsqueeze(-1).float()
        out.append((hidden * mask).sum(1) / mask.sum(1))
    return torch.nn.functional.normalize(torch.cat(out), dim=1)


INDEX = embed([c["text"] for c in CHUNKS])
print("شکلِ فهرست:", tuple(INDEX.shape))
```

<div dir="rtl">

</div>

```text
شکلِ فهرست: (30, 384)
```

<div dir="rtl">

**سی تکه، هر کدام یک بردارِ ۳۸۴بعدی. کلِ «پایگاه دادهٔ برداری» ما همین ماتریس است.**

**دو ریزه‌کاری که اگر جا بیندازی همه‌چیز بی‌صدا بد می‌شود:**

- **`attention_mask` در میانگین‌گیری** — همان چیزی که در ترمِ ۴ فصلِ ۸ دیدی. بدونش طولِ تکه به یک ویژگیِ ناخواسته تبدیل می‌شود.
- **`normalize`** — بردارها را به طولِ ۱ می‌رساند. **بعد از این، ضربِ داخلی دقیقاً همان شباهتِ کسینوسی است** و لازم نیست هر بار بر طول‌ها تقسیم کنی.

> 🌱 **ریشه‌اش کجاست:** اینکه ضربِ داخلیِ دو بردارِ **یکه** همان کسینوسِ زاویه‌شان است، در [ریشه ترمِ ۷ فصل ۳](/courses/risheh/lessons/term-7-linear-algebra/session-03-dot-product) با شکل و عدد آمده. **نرمال کردن یعنی طول را از معادله بیرون بیندازی تا فقط جهت بماند** — و جهت همان چیزی است که معنا را حمل می‌کند.

> 💡 **نکته:** برای سی تکه یک ماتریسِ ساده کافی است و **همین را هم بنویس**. کتابخانه‌های جست‌وجوی برداری از میلیون‌ها بردار به بعد ارزششان معلوم می‌شود — قبلش فقط یک وابستگیِ اضافه‌اند که بینِ تو و فهمِ ماجرا می‌ایستد.

## ۴. جست‌وجو

</div>

```python
def retrieve(question, k=3):
    scores = embed([question])[0] @ INDEX.T
    order = scores.topk(k).indices.tolist()
    return [(round(float(scores[i]), 3), CHUNKS[i]) for i in order]


for score, chunk in retrieve("کارتم را گم کرده‌ام، چه کار کنم؟"):
    print(f"  {score}  [{chunk['doc']:<10}] {chunk['text'][:56]}…")
```

<div dir="rtl">

</div>

```text
  0.671  [faq       ] کارتم را گم کرده‌ام، چه کنم؟ فوراً به باجهٔ امانت خبر بد…
  0.579  [faq       ] چند بار می‌توانم تمدید کنم؟ تا سه بار. کارتم را گم کرده‌…
  0.404  [lostcard  ] گم‌شدن کارت باید فوراً به باجهٔ امانت اعلام شود. تا لحظه…
```

<div dir="rtl">

**سه چیز در همین سه سطر پیداست:**

- **بالاترین امتیاز مالِ `faq` است، نه `lostcard`** — چون پرسشِ کاربر تقریباً کلمه‌به‌کلمه در `faq` تکرار شده. **بازیابیِ معنایی «مربوط‌ترین» را می‌آورد، نه لزوماً «معتبرترین».**
- **دو تکهٔ اولِ نتیجه از یک سندند** و بخشِ زیادی از متنشان مشترک است. **بودجهٔ زمینه‌ات را داری خرجِ تکرار می‌کنی.** فصلِ ۵ اسمش را می‌گذارد و درستش می‌کند.
- **امتیازها مطلق نیستند.** ۰٫۶۷ برای این پرسش خوب است؛ برای پرسشی دیگر ممکن است ۰٫۴ بهترین موجود باشد. **یک آستانهٔ ثابت مثلِ «کمتر از ۰٫۵ را دور بریز» تقریباً همیشه اشتباه است.**

## ۵. پرامپتِ نهایی

</div>

```python
SYSTEM = ("تو دستیارِ کتابخانهٔ نوردانه‌ای. فقط از متنِ زیر جواب بده. "
          "اگر جواب در متن نیست بنویس: در سند نیست")


def build_prompt(question, k=3):
    found = retrieve(question, k)
    context = "\n\n".join(f"[{c['title']}]\n{c['text']}" for _, c in found)
    return [{"role": "system", "content": SYSTEM},
            {"role": "user", "content": context + "\n\n" + question}]


def rag(question, k=3):
    return chat(build_prompt(question, k))["text"]


reset_calls()
question = "کارتِ المثنی پس از چند روزِ کاری صادر می‌شود؟"
print("پرامپتِ RAG   :", len(build_prompt(question)[1]["content"]), "نویسه")
print("پرامپتِ کلِ پیکره:", len(CORPUS) + len(question), "نویسه")
print("جواب:", rag(question))
```

<div dir="rtl">

</div>

```text
پرامپتِ RAG   : 475 نویسه
پرامپتِ کلِ پیکره: 3564 نویسه
جواب: کارتِ المثنی پس از ۳ روزِ کاری صادر می‌شود.
```

<div dir="rtl">

**۴۷۵ در برابرِ ۳۵۶۴ — حدودِ یک‌هفتم.** و جوابْ درست.

**سه انتخاب در `build_prompt` هست که هر کدام دلیل دارند:**

- **عنوانِ سند بالای هر تکه.** بدونش مدل نمی‌داند این جمله از کجا آمده، و **تو هم در جوابش نمی‌توانی منبع بدهی.** منبع‌دادن گران نیست و اعتماد می‌سازد.
- **پرسش در انتها.** قاعدهٔ فصلِ ۱.
- **دستورِ «اگر جواب در متن نیست بنویس: در سند نیست» در `system`.** بخشِ بعد نشان می‌دهد این یک جمله چقدر می‌ارزد.

> 🔧 **اگر کار نکرد:** اگر جواب‌ها ربطی به پرسش ندارند، **قبل از هر کاری `context` را چاپ کن.** نُه بار از ده بار مشکل در بازیابی است نه در تولید — و این را با چشمِ خودت در دو ثانیه می‌بینی. اگر `IndexError: list index out of range` گرفتی، `INDEX` را با تکه‌های قدیمی ساخته‌ای و بعد `CHUNKS` را کوتاه کرده‌ای. اگر `CHUNKS` را بلندتر کرده باشی هیچ خطایی نمی‌گیری و تکه‌های تازه بی‌صدا جست‌وجو نمی‌شوند؛ **هر بار که تکه‌ها عوض می‌شوند، فهرست باید از نو ساخته شود.**

## ۶. حالا اندازه بگیریم — سه سامانه، یک معیار

</div>

```python
def score_answer(item, text):
    return (REFUSAL in text) if item["a"] is None else (item["a"] in text)


def evaluate(answer_fn):
    per = {"ساده": [0, 0], "چندسندی": [0, 0], "بی‌جواب": [0, 0]}
    for item in GOLD:
        good = score_answer(item, answer_fn(item["q"]))
        per[item["kind"]][0] += good
        per[item["kind"]][1] += 1
    total = sum(v[0] for v in per.values())
    return total, per


def no_context(question):
    return chat([{"role": "system", "content": SYSTEM},
                 {"role": "user", "content": question}])["text"]


def full_corpus(question):
    return chat([{"role": "system", "content": SYSTEM},
                 {"role": "user", "content": CORPUS + "\n\n" + question}])["text"]


reset_calls()
for name, fn in [("بدونِ متن", no_context), ("کلِ پیکره", full_corpus), ("RAG با k=3", rag)]:
    total, per = evaluate(fn)
    detail = " · ".join(f"{k}: {v[0]}/{v[1]}" for k, v in per.items())
    print(f"{name:<12} {total:>2}/24   {detail}")
```

<div dir="rtl">

</div>

```text
بدونِ متن     5/24   ساده: 0/13 · چندسندی: 0/6 · بی‌جواب: 5/5
کلِ پیکره    16/24   ساده: 12/13 · چندسندی: 0/6 · بی‌جواب: 4/5
RAG با k=3   18/24   ساده: 13/13 · چندسندی: 0/6 · بی‌جواب: 5/5
```

<div dir="rtl">

**این جدول را سطر به سطر بخوان، چون هر سطرش یک درسِ جداست.**

**سطرِ اول — کفِ واقعی ۵ است، نه صفر.** سامانه‌ای که به **هر** پرسشی بگوید «در سند نیست»، ۵ از ۲۴ می‌گیرد؛ چون پنج پرسشِ ما واقعاً بی‌جواب‌اند و **اعتراف به ندانستن، جوابِ درست است**. اگر این را نمی‌دانستی، ۵ از ۲۴ به نظرت یک شروعِ ضعیف می‌آمد — در حالی که **کارِ مفیدِ صفر** است.

**سطرِ دوم — دادنِ همه‌چیز، دقیقاً بهترین کار نیست.** «کلِ پیکره» یک `ساده` را از دست داد و یک `بی‌جواب` را هم غلط جواب داد.

**سطرِ سوم — RAG هم دقیق‌تر است هم ارزان‌تر.** ۱۸ از ۲۴ با یک‌هفتمِ پرامپت. **ستونِ `ساده` کامل شد** و آن `بی‌جواب`ِ گمشده هم برگشت.

**و ستونِ `چندسندی` صفرِ صفر است، در هر سه سامانه.** این را پنهان نمی‌کنیم: **آن شش پرسش جوابشان در هیچ جمله‌ای نوشته نشده** و بازیابی هرگز حلشان نمی‌کند. **فصلِ ۳ راهش را نشان داد (ابزار) و فصلِ ۷ تا نیمه بازش می‌کند (عامل).**

## ۷. `k` چند باشد؟

</div>

```python
reset_calls()
for k in (1, 2, 3, 5, 8):
    total, _ = evaluate(lambda q, k=k: rag(q, k))
    size = sum(len(build_prompt(item["q"], k)[1]["content"]) for item in GOLD) // len(GOLD)
    print(f"  k={k}: {total:>2}/24   میانگینِ پرامپت {size:>4} نویسه")
```

<div dir="rtl">

</div>

```text
  k=1: 16/24   میانگینِ پرامپت  223 نویسه
  k=2: 17/24   میانگینِ پرامپت  389 نویسه
  k=3: 18/24   میانگینِ پرامپت  552 نویسه
  k=5: 17/24   میانگینِ پرامپت  887 نویسه
  k=8: 16/24   میانگینِ پرامپت 1390 نویسه
```

<div dir="rtl">

> 📏 **اندازه بگیر:** **منحنی بالا می‌رود، به قله می‌رسد، بعد پایین می‌آید.** از ۳ به ۸ پرامپت **دو و نیم برابر** شد و دقت **کمتر**. یعنی متنِ اضافه فقط بی‌فایده نیست — **مضر** است. تکه‌های بی‌ربط جملهٔ درست را در شلوغی گم می‌کنند، و تو دو برابر هم پولش را می‌دهی. **`k` یک ابرپارامتر است، مثلِ `learning_rate`، و باید مثلِ آن جاروب شود.** و قلهٔ ۳ مالِ همین پیکره است، نه یک عددِ جهانی.

## ۸. مهم‌ترین دو عدد این فصل

</div>

```python
found_doc = 0
for item in GOLD:
    if not item["doc"]:
        continue
    want = set(item["doc"].split("+"))
    got = {c["doc"] for _, c in retrieve(item["q"], 3)}
    found_doc += want.issubset(got)
print("بازیابی درست بود در:", found_doc, "از ۱۹ پرسشِ جواب‌دار")
print("جوابِ درست ولی:     ", evaluate(rag)[0] - 5, "از ۱۹")
```

<div dir="rtl">

</div>

```text
بازیابی درست بود در: 16 از ۱۹ پرسشِ جواب‌دار
جوابِ درست ولی:      13 از ۱۹
```

<div dir="rtl">

**۱۶ در برابرِ ۱۳. این فاصله، ارزشمندترین چیزی است که از یک سامانهٔ RAG می‌توانی بیرون بکشی.**

سامانهٔ تو دو نیمه دارد و **هر نیمه جداگانه خراب می‌شود:**

- **۳ پرسش را بازیابی گم کرد** — سندِ درست اصلاً به مدل نرسید. هرچقدر هم پرامپت را قشنگ‌تر بنویسی، این سه‌تا درست نمی‌شوند.
- **۳ پرسشِ دیگر سندشان رسید و باز جواب غلط شد** — اینجا بازیابی بی‌گناه است. مشکل در **استفاده** از متن است.

**و اگر فقط یک عدد داشته باشی — «۱۳ از ۱۹» — نمی‌دانی کدام نیمه را باید درست کنی، و احتمالاً روزها وقتت را صرفِ اشتباهی‌اش می‌کنی.**

**قاعده‌ای که بقیهٔ ترم رویش سوار است: بازیابی و تولید را همیشه جدا اندازه بگیر.**

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| RAG | آر-ای-جی | بازیابیِ متنِ مربوط، بعد پرسیدن از مدل با همان متن |
| chunk | چانک | تکه‌ای از سند که به‌عنوان واحدِ بازیابی نگه داشته می‌شود |
| overlap | اورلپ | جمله‌های مشترکِ دو تکهٔ پشتِ‌سرِ‌هم |
| vector index | وکتور ایندکس | مجموعهٔ بردارهای تکه‌ها که در آن جست‌وجو می‌کنی |
| top-k | تاپ-کِی | `k` تکهٔ نزدیک‌ترِ برگردانده‌شده |
| context | کانتکست | متنی که کنارِ پرسش به مدل می‌دهی |
| retrieval | ریتریول | نیمهٔ «پیدا کردن» از سامانه، جدا از نیمهٔ «جواب دادن» |

<div dir="rtl">

> 🤖 **از دستیارت بپرس:** «چه وقت `fine-tuning` به‌جای `RAG` انتخابِ درستی است؟» (پاسخِ درست حولِ این می‌چرخد: `RAG` برای **دانشی که عوض می‌شود** و باید منبع‌دار باشد؛ `fine-tuning` برای **رفتار و لحن و قالب**.) بعد این را بپرس: **«اگر مقرراتِ کتابخانه فردا عوض شود، در هر کدام چه کار باید بکنم؟»** — و جوابش تفاوت را برایت تمام می‌کند: در `RAG` یک فایل را عوض می‌کنی، در `fine-tuning` دوباره آموزش می‌دهی.

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا سامانه‌ای که همیشه می‌گوید «در سند نیست» صفر نمی‌گیرد؟

**تمرینِ اجباری:** `size` و `overlap` را جاروب کن — `(2,0)`، `(3,1)`، `(5,1)`، `(5,2)` — و برای هر کدام **سه ستون** بده: تعدادِ تکه، دقتِ بازیابی از ۱۹، و دقتِ نهایی از ۲۴. **کدام ترکیب بهترین است، و آیا همان است که بیشترین تکه را می‌سازد؟** جوابت نشان می‌دهد چرا «تکهٔ ریزتر = بهتر» یک افسانه است.

**تمرینِ ستاره‌دار ⭐:** یک سندِ سیزدهم به `DOCS` اضافه کن دربارهٔ چیزی که الان در پیکره نیست — مثلاً «خدماتِ چاپ و اسکن». بعد **بدونِ هیچ تغییرِ دیگری** فهرست را از نو بساز و همان ۲۴ پرسش را بزن. **دو پرسشِ `بی‌جواب` باید حالا جواب بگیرند.** بعد این را جواب بده: **در `fine-tuning` برای همین کار چه باید می‌کردی؟** — همین‌جا می‌فهمی چرا `RAG` برای دانشِ متغیر انتخابِ اول است.

## در فصل بعد

هجده از بیست‌وچهار خوب است، ولی **شش‌تا هنوز غلط‌اند** و ما دقیقاً می‌دانیم سه‌تایشان تقصیرِ بازیابی است. فصلِ بعد سراغِ همان‌ها می‌رود: **مرزِ بدِ تکه، تکه‌های تکراری، جملهٔ درستی که در شلوغی گم می‌شود، و پرسشی که کلمه‌اش در سند هست ولی معنایش نه.** برای هر کدام یک راهِ‌حل، و برای هر راهِ‌حل یک عدد.

</div>

---
Source: https://yaadestan.com/courses/zharfa/lessons/t5/s04-rag-from-scratch (یادستان, Yaadestan)
