# فصل ۰۸ — پروژه: یک دستیارِ پرسش‌وپاسخ روی متن‌های خودت

<div dir="rtl">

# فصل ۰۸ — پروژه: یک دستیارِ پرسش‌وپاسخ روی متن‌های خودت

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

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

![یک میزِ کارِ مرتب که چند ابزارِ جداگانه به یک دستگاهِ واحد وصل شده‌اند](/lesson-assets/t4-s08-project-ai-tool/prompt/01-image-assembled-tool.png)

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

- یک سامانهٔ `RAG` کامل را از صفر بنویسی
- مدل را طوری از کدت جدا کنی که بدونِ آن هم قابلِ آزمایش باشد
- ابزارت را با یک مجموعهٔ ارزیابی بسنجی، نه با حس
- محدودیت‌هایش را صادقانه بنویسی

## قبل از شروع

**از کلِ ترمِ ۴:** مدلِ آماده (۱)، فراخوانیِ API (۳)، اعتبارسنجی (۴)، `embedding` (۵)، بازیابی و آستانه (۶)، `cache` (۷).

**از ترمِ ۱:** تابع و `dict` — هر دو را زیاد به‌کار می‌بریم.

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

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-4-pretrained-models/session-08-project-ai-tool.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

## ۱. اول مشخصات، بعد کد

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

</div>

| | |
|---|---|
| **ورودی** | یک سؤالِ فارسی |
| **خروجی** | جواب + فهرستِ متن‌هایی که جواب از آن‌ها آمده |
| **وقتی نداند** | «نمی‌دانم» — **نه یک جوابِ حدسی** |
| **قلمرو** | فقط متن‌هایی که خودت داده‌ای |
| **آنچه انجام نمی‌دهد** | دانشِ عمومی، حساب‌وکتاب، اطلاعاتِ روز |

<div dir="rtl">

آن ردیفِ آخر مهم‌ترین است. **ابزاری که مرزش را نگفته باشی، هر جوابِ غلطش تقصیرِ توست.**

## ۲. تصمیمِ کلیدی: مدل را از کد جدا کن

اگر تابعِ اصلی‌ات مستقیم API را صدا بزند، هر بار که بخواهی چیزی را امتحان کنی به کلید، اینترنت و سهمیه نیاز داری — و هیچ‌وقت نمی‌توانی مطمئن شوی خطا از کدِ خودت بود یا از مدل.

راهِ حل: **تولیدکنندهٔ جواب را به‌عنوان یک `parameter` بگیر.** آن‌وقت می‌توانی یک تولیدکنندهٔ جعلی بدهی و کلِ مسیر را بدونِ هیچ فراخوانی بسنجی.

در پایتون **تابع هم یک مقدار است**، دقیقاً مثلِ عدد و رشته. اسمِ تابع بدونِ پرانتز، خودِ تابع را می‌دهد؛ با پرانتز، آن را صدا می‌زند:

</div>

```python
def shout(text):
    return text + "!"

def apply_twice(function, value):
    """function یک تابع است، نه نتیجهٔ یک تابع — به نبودِ پرانتز دقت کن."""
    return function(function(value))

print(apply_twice(shout, "سلام"))
```

<div dir="rtl">

</div>

```text
سلام!!
```

<div dir="rtl">

همین سه خط، تمامِ چیزی است که برای فهمِ ادامهٔ فصل لازم داری. `apply_twice(shout, ...)` تابعِ `shout` را **می‌دهد**، نه صدایش می‌زند؛ `apply_twice(shout(), ...)` یعنی چیزِ کاملاً دیگری و خطا می‌دهد.

و برای نگه‌داشتنِ وضعیتِ دستیار (متن‌ها، ایندکس، `cache`، آمار) از همان `dict` ترمِ ۱ استفاده می‌کنیم: **یک `dict` که همه‌چیزِ دستیار را نگه می‌دارد، و چند تابع که رویش کار می‌کنند.**

</div>

```bash
pip install -q sentence-transformers
```

<div dir="rtl">

</div>

```python
import numpy as np
import pandas as pd
from sentence_transformers import SentenceTransformer

MODEL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"


def build_assistant(texts, floor=0.30, k=3):
    """همهٔ چیزی که دستیار لازم دارد، در یک dict."""
    encoder = SentenceTransformer(MODEL)
    texts = list(texts)
    return {
        "texts": texts,
        "encoder": encoder,
        "index": encoder.encode(texts, normalize_embeddings=True),
        "floor": floor,
        "k": k,
        "cache": {},
        "stats": {"asked": 0, "cached": 0, "refused": 0},
    }


def retrieve(bot, question):
    """متن‌های مرتبط، فقط آن‌هایی که از آستانه بالاترند."""
    q = bot["encoder"].encode([question], normalize_embeddings=True)[0]
    scores = bot["index"] @ q
    best = np.argsort(-scores)[: bot["k"]]
    return [(float(scores[i]), bot["texts"][i]) for i in best if scores[i] >= bot["floor"]]


def build_prompt(question, found):
    context = "\n".join(f"- {t}" for _, t in found)
    return (
        "فقط با تکیه بر متن‌های زیر جواب بده. "
        "اگر جواب در متن‌ها نبود، بنویس «نمی‌دانم».\n\n"
        f"متن‌ها:\n{context}\n\nسؤال: {question}"
    )


def ask(bot, question, generate):
    """generate یک تابع است که پرامپت می‌گیرد و متن برمی‌گرداند."""
    bot["stats"]["asked"] += 1
    if question in bot["cache"]:
        bot["stats"]["cached"] += 1
        return bot["cache"][question]

    found = retrieve(bot, question)
    if not found:
        bot["stats"]["refused"] += 1
        result = {"answer": "نمی‌دانم", "sources": [], "answered": False}
    else:
        result = {
            "answer": generate(build_prompt(question, found)),
            "sources": [t for _, t in found],
            "answered": True,
        }
    bot["cache"][question] = result
    return result


docs = pd.read_csv("docs.csv")
bot = build_assistant(docs["text"])
print("تعداد متن:", len(bot["texts"]), "| اندازه ایندکس:", bot["index"].shape)
```

<div dir="rtl">

</div>

```text
تعداد متن: 20 | اندازه ایندکس: (20, 384)
```

<div dir="rtl">

> 💡 **نکته:** پایتون ابزارِ مخصوصی برای همین کار دارد — یک بستهٔ واحد از «داده + تابع‌هایی که رویش کار می‌کنند» — که اسمش `class` است. **هنوز لازمش نداری** و همین `dict` به‌همراه چهار تابع دقیقاً همان کار را می‌کند. در ترمِ ۵ فصلِ ۲ که کد را از نوت‌بوک به فایلِ `.py` می‌بریم، `class` را می‌بینی و آن‌وقت **دلیلِ وجودش** برایت روشن است، نه فقط دستورش.

**ترتیبِ داخلِ `ask` عمدی است و جابه‌جا کردنش خطاست:**

- `cache` **قبل از** بازیابی — وگرنه کارِ سنگین را برای سؤالی که جوابش را داری تکرار می‌کنی.
- آستانه **قبل از** ساختنِ پرامپت — وگرنه برای سؤالی که جوابش را نداری هزینه می‌دهی.
- ذخیره در `cache` **بعد از** هر دو حالت — «نمی‌دانم» هم یک جواب است و ارزشِ کش‌شدن دارد.

## ۳. تولیدکنندهٔ جعلی

</div>

```python
def echo_generator(prompt):
    """جای مدلِ واقعی: اولین متنِ بازیابی‌شده را برمی‌گرداند.

    کارِ هوشمندانه‌ای نمی‌کند و قرار هم نیست بکند — کارش این است که ثابت کند
    بازیابی، آستانه، cache و شکلِ خروجی همه درست کار می‌کنند.
    """
    block = prompt.split("متن‌ها:\n")[1].split("\n\nسؤال")[0]
    return block.split("\n")[0].lstrip("- ")


result = ask(bot, "چطور غذا را خوشمزه کنم", echo_generator)
print("جواب  :", result["answer"])
print("منابع :", len(result["sources"]))
print("جواب داد؟", result["answered"])
```

<div dir="rtl">

</div>

```text
جواب  : پیاز را با حرارت ملایم سرخ کن تا شیرینی‌اش دربیاید.
منابع : 3
جواب داد؟ True
```

<div dir="rtl">

> 📏 **اندازه بگیر:** این ایده اسم دارد و در مهندسیِ نرم‌افزار مرکزی است: **جداکردنِ وابستگی‌ها از منطق.** ارزشش اینجا خیلی مشخص است — همهٔ منطقِ ابزارت (بازیابی، آستانه، `cache`، شکلِ خروجی) بدونِ هیچ هزینه‌ای و، بعد از دانلودِ مدلِ `embedding`، بدونِ اینترنت قابلِ آزمایش شد. **و وقتی جواب غلط بود، دقیقاً می‌دانی کجا را نگاه کنی**، چون فقط یک قطعهٔ ناشناخته در مسیر باقی مانده.

## ۴. وقتی نمی‌داند

</div>

```python
missing = ask(bot, "قیمت دلار امروز چند است", echo_generator)
print("جواب  :", missing["answer"], "| منابع:", len(missing["sources"]), "| جواب داد؟", missing["answered"])

ask(bot, "چطور غذا را خوشمزه کنم", echo_generator)   # همان سؤال، بار دوم
print("آمار  :", bot["stats"])
```

<div dir="rtl">

</div>

```text
جواب  : نمی‌دانم | منابع: 0 | جواب داد؟ False
آمار  : {'asked': 3, 'cached': 1, 'refused': 1}
```

<div dir="rtl">

سه سؤال پرسیده شد، یکی از `cache` آمد، یکی رد شد. **آن `refused` را جدی بگیر: نسبتش به `asked` یکی از مفیدترین عددهای یک سامانهٔ واقعی است.** اگر خیلی بالا باشد، یا پیکره‌ات ناقص است یا آستانه‌ات سخت‌گیر. اگر صفر باشد، احتمالاً آستانه‌ات هیچ‌کاره است.

## ۵. حالا بسنجش

</div>

```python
TESTS = [
    ("چطور غذا را خوشمزه کنم", True),
    ("بلیت ارزان‌تر بخرم", True),
    ("چطور بهتر بخوابم", True),
    ("چطور ورزش کنم", True),
    ("قیمت دلار امروز چند است", False),
    ("پایتخت ژاپن کجاست", False),
    ("چطور وقتم را بهتر مدیریت کنم", False),
]

correct = 0
for question, should_answer in TESTS:
    answered = ask(bot, question, echo_generator)["answered"]
    good = answered == should_answer
    correct += good
    print(f"{'✓' if good else '✗'} | انتظار: {'جواب' if should_answer else 'نمی‌دانم':<8} "
          f"| نتیجه: {'جواب' if answered else 'نمی‌دانم':<8} | {question}")

print()
print(f"درست: {correct}/{len(TESTS)}")
```

<div dir="rtl">

</div>

```text
✓ | انتظار: جواب     | نتیجه: جواب     | چطور غذا را خوشمزه کنم
✓ | انتظار: جواب     | نتیجه: جواب     | بلیت ارزان‌تر بخرم
✓ | انتظار: جواب     | نتیجه: جواب     | چطور بهتر بخوابم
✓ | انتظار: جواب     | نتیجه: جواب     | چطور ورزش کنم
✓ | انتظار: نمی‌دانم | نتیجه: نمی‌دانم | قیمت دلار امروز چند است
✓ | انتظار: نمی‌دانم | نتیجه: نمی‌دانم | پایتخت ژاپن کجاست
✗ | انتظار: نمی‌دانم | نتیجه: جواب     | چطور وقتم را بهتر مدیریت کنم

درست: 6/7
```

<div dir="rtl">

**۶ از ۷، و آن یکی خطا از هر شش موفقیت آموزنده‌تر است.** ببینیم چه شد:

</div>

```python
score, text = retrieve(bot, "چطور وقتم را بهتر مدیریت کنم")[0]
print("شباهت:", round(score, 2))
print("متن  :", text)
```

<div dir="rtl">

</div>

```text
شباهت: 0.41
متن  : تست نوشتن وقت می‌گیرد؛ نداشتن تست وقت بیشتری می‌گیرد.
```

<div dir="rtl">

سؤال دربارهٔ مدیریتِ زمان بود؛ متنِ بازیابی‌شده دربارهٔ تست‌نویسی است و فقط کلمهٔ «وقت» را مشترک دارد. **۰٫۴۱ خیلی بالاتر از آستانهٔ ۰٫۳۰ است، پس سامانه با اطمینان جوابِ نامربوط می‌دهد.**

سه راهِ حل داری و هیچ‌کدام رایگان نیست:

</div>

| کار | چه چیزی بهتر می‌شود | چه چیزی بدتر می‌شود |
|---|---|---|
| آستانه را بالا ببر (مثلاً ۰٫۴۵) | ردِ سؤال‌های بی‌ربط | سؤال‌های درست هم رد می‌شوند |
| به مدل بگو «اگر نبود بنویس نمی‌دانم» | مدل خودش فیلترِ دوم می‌شود | به رفتارِ مدل تکیه می‌کنی، نه به کدت |
| پیکره را بزرگ‌تر کن | پوششِ واقعی بیشتر می‌شود | کارِ واقعی می‌خواهد |

<div dir="rtl">

> ⚠️ **مواظب باش:** وسوسه می‌شوی آستانه را ۰٫۴۵ کنی تا این یک مورد درست شود. **نکن — دستِ‌کم نه بر اساسِ یک نمونه.** این همان نشتیِ فصلِ ۹ ترمِ ۳ است در لباسِ تازه: داری پارامتر را روی داده‌ای تنظیم می‌کنی که با آن می‌سنجی، و بعد نتیجهٔ همان سنجش را گزارش می‌کنی. **آستانه را روی یک مجموعهٔ ارزیابی تنظیم کن و روی مجموعهٔ دیگری گزارش بده.**

## ۶. وصل کردن به مدلِ واقعی

حالا که همهٔ منطق سنجیده شده، **وصل کردنِ مدل فقط عوض کردنِ یک تابع است:**

</div>

```python-broken
def gemini_generator(prompt):
    return ask_model(prompt)          # همان تابع فصل ۳

bot["cache"].clear()                  # جواب‌های echo_generator پاک می‌شوند

result = ask(bot, "چطور غذا را خوشمزه کنم", gemini_generator)
print(result["answer"])
print("منابع:", result["sources"])
```

<div dir="rtl">

به جز آن یک خطِ `clear`، هیچ خطِ دیگری از کد عوض نمی‌شود. **همان `bot`، همان آستانه، همان آمار.**

آن خط لازم است، چون کلیدِ `cache` فقط سؤال است. این سؤال از بخشِ ۳ در `cache` مانده، پس بدونِ `clear` مدل اصلاً صدا زده نمی‌شود و جوابِ `echo_generator` برمی‌گردد. با یک مدلِ جعلی که صدا زدنش را می‌شمارد ببین:

</div>

```python
called = []

def fake_model(prompt):
    called.append(prompt)
    return "جواب مدل"

question = "چطور غذا را خوشمزه کنم"
print("بدون clear:", ask(bot, question, fake_model)["answer"], "| تعداد صدا زدن:", len(called))
bot["cache"].clear()
print("با clear  :", ask(bot, question, fake_model)["answer"], "| تعداد صدا زدن:", len(called))
```

<div dir="rtl">

</div>

```text
بدون clear: پیاز را با حرارت ملایم سرخ کن تا شیرینی‌اش دربیاید. | تعداد صدا زدن: 0
با clear  : جواب مدل | تعداد صدا زدن: 1
```

<div dir="rtl">

همان هشدارِ فصلِ ۷ است: کلیدِ ناقص یعنی جوابِ یک مدل را به مدلِ دیگر نسبت می‌دهی.

> ✅ **چک کن:** بعد از وصل کردن، همان هفت سؤالِ بخشِ ۵ را دوباره بپرس. **`answered` باید دقیقاً همان هفت مقدارِ قبلی باشد** — چون بازیابی و آستانه به مدل ربطی ندارند. اگر فرق کرد، یعنی چیزی را عوض کرده‌ای که نباید. متنِ جواب‌ها البته فرق می‌کند و همان هدفِ کار است.

## ۷. کارتِ صداقت

آخرین کارِ هر پروژه، نوشتنِ چیزی است که خودت می‌دانی و کاربر نمی‌داند:

</div>

| | |
|---|---|
| **بر چه چیزی جواب می‌دهد** | بیست جملهٔ فارسی در چهار موضوع |
| **چطور می‌سنجد** | ۷ سؤالِ آزمون، ۶ درست |
| **آستانه** | ۰٫۳۰ شباهتِ کسینوسی |
| **مدلِ بازیابی** | یک مدلِ `embedding` چندزبانهٔ کوچک |
| **خطای شناخته‌شده** | سؤال‌هایی که کلمهٔ مشترکِ بی‌ربط دارند، جوابِ نامربوط می‌گیرند |
| **به‌کارش نبر برای** | تصمیمِ پزشکی، حقوقی، مالی، یا هر جایی که جوابِ غلط هزینه دارد |
| **دادهٔ کاربر** | با تولیدکنندهٔ محلی جایی نمی‌رود؛ با API به سرورِ آن شرکت می‌رود |

<div dir="rtl">

این جدول در ترمِ ۵ اسمِ رسمی‌اش را می‌گیرد: `model card`. **ولی ارزشش به اسمش نیست — به این است که تو مجبور شوی محدودیت‌ها را بنویسی، نه اینکه امیدوار باشی کسی نپرسد.**

> 🤖 **از دستیارت بپرس:** کلِ این چهار تابع را به دستیارت بده و بپرس: «این کد در چه حالتی خطا می‌دهد یا رفتارِ غیرمنتظره دارد؟» جوابش را **یکی‌یکی امتحان کن**، نه اینکه باور کنی. (چند موردی که واقعاً هست: فهرستِ متنِ خالی، سؤالِ خالی، `k` بزرگ‌تر از تعدادِ متن‌ها، متنِ تکراری در پیکره.) **هر مورد که واقعاً خطا داد، یک تستِ آماده برای ترمِ ۵ است.**

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `cache` باید **قبل از** بازیابی چک شود و نه بعدش؟

**تمرینِ اجباری:** پیکرهٔ خودت را بگذار — دستِ‌کم سی متنِ واقعی از یک حوزهٔ آشنا (سؤال‌های پرتکرارِ یک کسب‌وکار، یادداشت‌های درسی‌ات، هر چیزی). ده سؤال بنویس که جوابشان در پیکره هست و پنج سؤال که نیست. دستیار را با `echo_generator` بساز و بسنج. **بعد آستانه را روی ۰٫۲۰، ۰٫۳۰، ۰٫۴۰ و ۰٫۵۰ امتحان کن و جدولِ نتیجه را بکش.** خواهی دید هیچ عددی هر دو ستون را با هم بهینه نمی‌کند — و همین جدول است که تصمیمت را توجیه می‌کند.

**تمرینِ ستاره‌دار ⭐:** به دستیارت قابلیتِ تاریخچه اضافه کن: هر سؤال و جواب و منابعش و شباهت‌ها در یک فهرست ذخیره شود و بشود آن را به `DataFrame` تبدیل کرد. حالا با ابزارهای ترمِ ۲ گزارش بگیر: توزیعِ شباهت‌ها چه شکلی است؟ آیا سؤال‌های ردشده و پذیرفته‌شده دو گروهِ جدا می‌سازند یا هم‌پوشانی دارند؟ **اگر هم‌پوشانی دارند، هیچ آستانه‌ای مسئله را حل نمی‌کند** — و آن‌وقت باید سراغِ مدلِ بهتر یا تکه‌کردنِ بهتر بروی. این تحلیل، دقیقاً همان کاری است که در یک تیمِ واقعی از تو می‌خواهند.

## در فصل بعد

ترمِ ۴ اینجا تمام می‌شود. سه چیز را با خودت به ترمِ ۵ ببر:

- **مدلِ آماده یک نامزد است، نه یک جواب** — و مثلِ هر نامزدِ دیگری باید در برابرِ خطِ پایه ثابت کند که ارزشش را دارد.
- **خروجیِ غیرقطعی باید اعتبارسنجی شود** — `JSON` معتبر یعنی قالب درست است، نه اینکه محتوا معنا دارد.
- **بازیابی خاموش شکست می‌خورد** — بدونِ آستانه و بدونِ مجموعهٔ ارزیابی، جوابِ غلط دقیقاً شکلِ جوابِ درست را دارد.

ترمِ ۵ سؤالِ آخر را جواب می‌دهد: **این چیزی که ساختی، چطور از نوت‌بوکِ تو بیرون می‌آید و به دستِ کسی می‌رسد که تو را نمی‌شناسد؟**

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t4/s08-project-ai-tool (یادستان, Yaadestan)
