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

آخر این فصل میتوانی:
- یک سامانهٔ
RAGکامل را از صفر بنویسی - مدل را طوری از کدت جدا کنی که بدونِ آن هم قابلِ آزمایش باشد
- ابزارت را با یک مجموعهٔ ارزیابی بسنجی، نه با حس
- محدودیتهایش را صادقانه بنویسی
قبل از شروع#
از کلِ ترمِ ۴: مدلِ آماده (۱)، فراخوانیِ API (۳)، اعتبارسنجی (۴)، embedding (۵)، بازیابی و آستانه (۶)، cache (۷).
از ترمِ ۱: تابع و dict — هر دو را زیاد بهکار میبریم.
تنها چیزِ تازهٔ این فصل یک ایدهٔ پایتونی است، نه یک مفهومِ هوش مصنوعی: یک تابع میتواند تابعِ دیگری را بهعنوان ورودی بگیرد. بخشِ ۲ توضیحش میدهد.
📓 نوتبوک: نوتبوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و بهترتیب داخلش هست.
۱. اول مشخصات، بعد کد#
قبل از نوشتنِ یک خط، سه چیز را بنویس. این پنج دقیقه، بعداً ساعتها بحث را حذف میکند:
| ورودی | یک سؤالِ فارسی |
| خروجی | جواب + فهرستِ متنهایی که جواب از آنها آمده |
| وقتی نداند | «نمیدانم» — نه یک جوابِ حدسی |
| قلمرو | فقط متنهایی که خودت دادهای |
| آنچه انجام نمیدهد | دانشِ عمومی، حسابوکتاب، اطلاعاتِ روز |
آن ردیفِ آخر مهمترین است. ابزاری که مرزش را نگفته باشی، هر جوابِ غلطش تقصیرِ توست.
۲. تصمیمِ کلیدی: مدل را از کد جدا کن#
اگر تابعِ اصلیات مستقیم API را صدا بزند، هر بار که بخواهی چیزی را امتحان کنی به کلید، اینترنت و سهمیه نیاز داری — و هیچوقت نمیتوانی مطمئن شوی خطا از کدِ خودت بود یا از مدل.
راهِ حل: تولیدکنندهٔ جواب را بهعنوان یک parameter بگیر. آنوقت میتوانی یک تولیدکنندهٔ جعلی بدهی و کلِ مسیر را بدونِ هیچ فراخوانی بسنجی.
در پایتون تابع هم یک مقدار است، دقیقاً مثلِ عدد و رشته. اسمِ تابع بدونِ پرانتز، خودِ تابع را میدهد؛ با پرانتز، آن را صدا میزند:
def shout(text):
return text + "!"
def apply_twice(function, value):
"""function یک تابع است، نه نتیجهٔ یک تابع — به نبودِ پرانتز دقت کن."""
return function(function(value))
print(apply_twice(shout, "سلام"))
سلام!!
همین سه خط، تمامِ چیزی است که برای فهمِ ادامهٔ فصل لازم داری. apply_twice(shout, ...) تابعِ shout را میدهد، نه صدایش میزند؛ apply_twice(shout(), ...) یعنی چیزِ کاملاً دیگری و خطا میدهد.
و برای نگهداشتنِ وضعیتِ دستیار (متنها، ایندکس، cache، آمار) از همان dict ترمِ ۱ استفاده میکنیم: یک dict که همهچیزِ دستیار را نگه میدارد، و چند تابع که رویش کار میکنند.
pip install -q sentence-transformers
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)
تعداد متن: 20 | اندازه ایندکس: (20, 384)
💡 نکته: پایتون ابزارِ مخصوصی برای همین کار دارد — یک بستهٔ واحد از «داده + تابعهایی که رویش کار میکنند» — که اسمش
classاست. هنوز لازمش نداری و همینdictبههمراه چهار تابع دقیقاً همان کار را میکند. در ترمِ ۵ فصلِ ۲ که کد را از نوتبوک به فایلِ.pyمیبریم،classرا میبینی و آنوقت دلیلِ وجودش برایت روشن است، نه فقط دستورش.
ترتیبِ داخلِ ask عمدی است و جابهجا کردنش خطاست:
cacheقبل از بازیابی — وگرنه کارِ سنگین را برای سؤالی که جوابش را داری تکرار میکنی.- آستانه قبل از ساختنِ پرامپت — وگرنه برای سؤالی که جوابش را نداری هزینه میدهی.
- ذخیره در
cacheبعد از هر دو حالت — «نمیدانم» هم یک جواب است و ارزشِ کششدن دارد.
۳. تولیدکنندهٔ جعلی#
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"])
جواب : پیاز را با حرارت ملایم سرخ کن تا شیرینیاش دربیاید.
منابع : 3
جواب داد؟ True
📏 اندازه بگیر: این ایده اسم دارد و در مهندسیِ نرمافزار مرکزی است: جداکردنِ وابستگیها از منطق. ارزشش اینجا خیلی مشخص است — همهٔ منطقِ ابزارت (بازیابی، آستانه،
cache، شکلِ خروجی) بدونِ هیچ هزینهای و، بعد از دانلودِ مدلِembedding، بدونِ اینترنت قابلِ آزمایش شد. و وقتی جواب غلط بود، دقیقاً میدانی کجا را نگاه کنی، چون فقط یک قطعهٔ ناشناخته در مسیر باقی مانده.
۴. وقتی نمیداند#
missing = ask(bot, "قیمت دلار امروز چند است", echo_generator)
print("جواب :", missing["answer"], "| منابع:", len(missing["sources"]), "| جواب داد؟", missing["answered"])
ask(bot, "چطور غذا را خوشمزه کنم", echo_generator) # همان سؤال، بار دوم
print("آمار :", bot["stats"])
جواب : نمیدانم | منابع: 0 | جواب داد؟ False
آمار : {'asked': 3, 'cached': 1, 'refused': 1}
سه سؤال پرسیده شد، یکی از cache آمد، یکی رد شد. آن refused را جدی بگیر: نسبتش به asked یکی از مفیدترین عددهای یک سامانهٔ واقعی است. اگر خیلی بالا باشد، یا پیکرهات ناقص است یا آستانهات سختگیر. اگر صفر باشد، احتمالاً آستانهات هیچکاره است.
۵. حالا بسنجش#
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)}")
✓ | انتظار: جواب | نتیجه: جواب | چطور غذا را خوشمزه کنم
✓ | انتظار: جواب | نتیجه: جواب | بلیت ارزانتر بخرم
✓ | انتظار: جواب | نتیجه: جواب | چطور بهتر بخوابم
✓ | انتظار: جواب | نتیجه: جواب | چطور ورزش کنم
✓ | انتظار: نمیدانم | نتیجه: نمیدانم | قیمت دلار امروز چند است
✓ | انتظار: نمیدانم | نتیجه: نمیدانم | پایتخت ژاپن کجاست
✗ | انتظار: نمیدانم | نتیجه: جواب | چطور وقتم را بهتر مدیریت کنم
درست: 6/7
۶ از ۷، و آن یکی خطا از هر شش موفقیت آموزندهتر است. ببینیم چه شد:
score, text = retrieve(bot, "چطور وقتم را بهتر مدیریت کنم")[0]
print("شباهت:", round(score, 2))
print("متن :", text)
شباهت: 0.41
متن : تست نوشتن وقت میگیرد؛ نداشتن تست وقت بیشتری میگیرد.
سؤال دربارهٔ مدیریتِ زمان بود؛ متنِ بازیابیشده دربارهٔ تستنویسی است و فقط کلمهٔ «وقت» را مشترک دارد. ۰٫۴۱ خیلی بالاتر از آستانهٔ ۰٫۳۰ است، پس سامانه با اطمینان جوابِ نامربوط میدهد.
سه راهِ حل داری و هیچکدام رایگان نیست:
| کار | چه چیزی بهتر میشود | چه چیزی بدتر میشود |
|---|---|---|
| آستانه را بالا ببر (مثلاً ۰٫۴۵) | ردِ سؤالهای بیربط | سؤالهای درست هم رد میشوند |
| به مدل بگو «اگر نبود بنویس نمیدانم» | مدل خودش فیلترِ دوم میشود | به رفتارِ مدل تکیه میکنی، نه به کدت |
| پیکره را بزرگتر کن | پوششِ واقعی بیشتر میشود | کارِ واقعی میخواهد |
⚠️ مواظب باش: وسوسه میشوی آستانه را ۰٫۴۵ کنی تا این یک مورد درست شود. نکن — دستِکم نه بر اساسِ یک نمونه. این همان نشتیِ فصلِ ۹ ترمِ ۳ است در لباسِ تازه: داری پارامتر را روی دادهای تنظیم میکنی که با آن میسنجی، و بعد نتیجهٔ همان سنجش را گزارش میکنی. آستانه را روی یک مجموعهٔ ارزیابی تنظیم کن و روی مجموعهٔ دیگری گزارش بده.
۶. وصل کردن به مدلِ واقعی#
حالا که همهٔ منطق سنجیده شده، وصل کردنِ مدل فقط عوض کردنِ یک تابع است:
def gemini_generator(prompt):
return ask_model(prompt) # همان تابع فصل ۳
bot["cache"].clear() # جوابهای echo_generator پاک میشوند
result = ask(bot, "چطور غذا را خوشمزه کنم", gemini_generator)
print(result["answer"])
print("منابع:", result["sources"])
به جز آن یک خطِ clear، هیچ خطِ دیگری از کد عوض نمیشود. همان bot، همان آستانه، همان آمار.
آن خط لازم است، چون کلیدِ cache فقط سؤال است. این سؤال از بخشِ ۳ در cache مانده، پس بدونِ clear مدل اصلاً صدا زده نمیشود و جوابِ echo_generator برمیگردد. با یک مدلِ جعلی که صدا زدنش را میشمارد ببین:
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))
بدون clear: پیاز را با حرارت ملایم سرخ کن تا شیرینیاش دربیاید. | تعداد صدا زدن: 0
با clear : جواب مدل | تعداد صدا زدن: 1
همان هشدارِ فصلِ ۷ است: کلیدِ ناقص یعنی جوابِ یک مدل را به مدلِ دیگر نسبت میدهی.
✅ چک کن: بعد از وصل کردن، همان هفت سؤالِ بخشِ ۵ را دوباره بپرس.
answeredباید دقیقاً همان هفت مقدارِ قبلی باشد — چون بازیابی و آستانه به مدل ربطی ندارند. اگر فرق کرد، یعنی چیزی را عوض کردهای که نباید. متنِ جوابها البته فرق میکند و همان هدفِ کار است.
۷. کارتِ صداقت#
آخرین کارِ هر پروژه، نوشتنِ چیزی است که خودت میدانی و کاربر نمیداند:
| بر چه چیزی جواب میدهد | بیست جملهٔ فارسی در چهار موضوع |
| چطور میسنجد | ۷ سؤالِ آزمون، ۶ درست |
| آستانه | ۰٫۳۰ شباهتِ کسینوسی |
| مدلِ بازیابی | یک مدلِ embedding چندزبانهٔ کوچک |
| خطای شناختهشده | سؤالهایی که کلمهٔ مشترکِ بیربط دارند، جوابِ نامربوط میگیرند |
| بهکارش نبر برای | تصمیمِ پزشکی، حقوقی، مالی، یا هر جایی که جوابِ غلط هزینه دارد |
| دادهٔ کاربر | با تولیدکنندهٔ محلی جایی نمیرود؛ با API به سرورِ آن شرکت میرود |
این جدول در ترمِ ۵ اسمِ رسمیاش را میگیرد: model card. ولی ارزشش به اسمش نیست — به این است که تو مجبور شوی محدودیتها را بنویسی، نه اینکه امیدوار باشی کسی نپرسد.
🤖 از دستیارت بپرس: کلِ این چهار تابع را به دستیارت بده و بپرس: «این کد در چه حالتی خطا میدهد یا رفتارِ غیرمنتظره دارد؟» جوابش را یکییکی امتحان کن، نه اینکه باور کنی. (چند موردی که واقعاً هست: فهرستِ متنِ خالی، سؤالِ خالی،
kبزرگتر از تعدادِ متنها، متنِ تکراری در پیکره.) هر مورد که واقعاً خطا داد، یک تستِ آماده برای ترمِ ۵ است.
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
ترمِ ۴ اینجا تمام میشود. سه چیز را با خودت به ترمِ ۵ ببر:
- مدلِ آماده یک نامزد است، نه یک جواب — و مثلِ هر نامزدِ دیگری باید در برابرِ خطِ پایه ثابت کند که ارزشش را دارد.
- خروجیِ غیرقطعی باید اعتبارسنجی شود —
JSONمعتبر یعنی قالب درست است، نه اینکه محتوا معنا دارد. - بازیابی خاموش شکست میخورد — بدونِ آستانه و بدونِ مجموعهٔ ارزیابی، جوابِ غلط دقیقاً شکلِ جوابِ درست را دارد.
ترمِ ۵ سؤالِ آخر را جواب میدهد: این چیزی که ساختی، چطور از نوتبوکِ تو بیرون میآید و به دستِ کسی میرسد که تو را نمیشناسد؟
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.