در این فصل چه یاد میگیری#
به حسابِ مدل نمیشود تکیه کرد. این را دستِکم نگیر: «جریمهٔ ۵ ساعت تأخیرِ کتابِ مرجع چقدر است؟» جوابش در هیچ سندی نوشته نشده — باید ۵ را در ۶ ضرب کنی. و بدلِ ما که فقط استخراج میکند، حتی وقتی هر دو حقیقت جلوی چشمش است، صفر از چهار میگیرد. مدلِ واقعی این ضربِ ساده را احتمالاً درست میزند، ولی این را نمیشود بهش سپرد.
در این فصل به آن اجازه میدهیم کار بخواهد: تابعِ تو را نام ببرد و ورودیاش را پیشنهاد بدهد؛ اجرا با کدِ توست. همان چهار پرسش میشود چهار از چهار. و بعد سه راهِ خراب شدنِ این ماجرا را میبینیم که یکیشان را هیچ اعتبارسنجیای نمیگیرد.

آخر این فصل میتوانی:
- ابزار را با
schemaتعریف کنی و به مدل معرفی کنی - حلقهٔ «درخواست → اجرا → پاسخ» را کامل بنویسی
- ورودیِ پیشنهادیِ مدل را قبلِ اجرا از دروازه رد کنی
- بگویی چرا فهرستِ سفید تنها مرزِ امنیتیِ واقعی است
قبل از شروع#
از فصل ۲: pydantic، Literal، Field و ValidationError. اینجا همانها از داده به ورودیِ تابع میروند.
از فصل ۱: chat و نقشهای پیام. یک نقشِ چهارم هم اضافه میشود: tool.
📓 نوتبوک: نوتبوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و بهترتیب داخلش هست.
۱. یک ابزار یعنی چه#
سه تکه دارد و هر سه لازم است:
- تابعِ واقعیِ پایتون — چیزی که کار را میکند.
schemaی ورودیها — چه آرگومانهایی، از چه نوعی.- یک توضیح به زبانِ آدمیزاد — که مدل از رویش تصمیم میگیرد کِی به دردش میخورد.
تکهٔ سوم را دستِکم نگیر. آن توضیح، پرامپت است. بخشِ ۲ نشان میدهد چطور یک توضیحِ بد، ابزارِ سالم را عملاً نامرئی میکند.
from typing import Literal
from pydantic import BaseModel, Field, ValidationError
LIMITS = {"عادی": (3, 14), "دانشجویی": (5, 21), "پژوهشی": (8, 30)}
def fa(number):
"""عدد را با ارقامِ فارسی برمیگرداند — ترجمه، سرِ مرزِ خروجی."""
return str(number).translate(str.maketrans("0123456789", "۰۱۲۳۴۵۶۷۸۹"))
class LateBookArgs(BaseModel):
days: int = Field(ge=0, le=365)
class LateReferenceArgs(BaseModel):
hours: int = Field(ge=0, le=24)
class MaxLoanArgs(BaseModel):
tier: Literal["عادی", "دانشجویی", "پژوهشی"]
renewals: int = Field(ge=0, le=2)
class HoursArgs(BaseModel):
day: Literal["شنبه", "پنجشنبه", "جمعه"]
def fine_for_late_book(a):
return f"{fa(a.days)} روز تأخیرِ کتابِ عادی = {fa(2 * a.days)} امتیازِ منفی"
def fine_for_late_reference(a):
return f"{fa(a.hours)} ساعت تأخیرِ کتابِ مرجع = {fa(6 * a.hours)} امتیازِ منفی"
def max_loan_days(a):
total = LIMITS[a.tier][1] + 7 * a.renewals
return f"عضو {a.tier} با {fa(a.renewals)} بار تمدید: {fa(total)} روز"
def hours_lookup(a):
table = {"شنبه": "۸ تا ۲۰", "پنجشنبه": "۸ تا ۱۴", "جمعه": "تعطیل"}
return f"ساعتِ کارِ {a.day}: {table[a.day]}"
TOOLS = [
{"name": "fine_for_late_book", "run": fine_for_late_book, "args": LateBookArgs,
"description": "جریمهٔ دیرکردِ یک کتابِ عادی را بر حسبِ امتیازِ منفی حساب میکند؛ ورودی تعدادِ روزِ تأخیر است",
"parameters": {"type": "object", "properties": {
"days": {"type": "integer", "description": "تعدادِ روزِ تأخیر"}}, "required": ["days"]}},
{"name": "fine_for_late_reference", "run": fine_for_late_reference, "args": LateReferenceArgs,
"description": "جریمهٔ دیرکردِ یک کتابِ مرجع در امانتِ کوتاه؛ ورودی تعدادِ ساعتِ تأخیر است",
"parameters": {"type": "object", "properties": {
"hours": {"type": "integer", "description": "تعدادِ ساعتِ تأخیر"}}, "required": ["hours"]}},
{"name": "max_loan_days", "run": max_loan_days, "args": MaxLoanArgs,
"description": "حداکثر روزی که عضو میتواند کتاب را نگه دارد، با در نظر گرفتنِ تمدید",
"parameters": {"type": "object", "properties": {
"tier": {"type": "string", "enum": ["عادی", "دانشجویی", "پژوهشی"]},
"renewals": {"type": "integer", "description": "تعدادِ تمدید"}}, "required": ["tier", "renewals"]}},
{"name": "hours_lookup", "run": hours_lookup, "args": HoursArgs,
"description": "ساعتِ کارِ کتابخانه در یک روزِ هفته",
"parameters": {"type": "object", "properties": {
"day": {"type": "string", "enum": ["شنبه", "پنجشنبه", "جمعه"]}}, "required": ["day"]}},
]
BY_NAME = {t["name"]: t for t in TOOLS}
QUESTIONS = [
"جریمهٔ ۱۰ روز تأخیر در بازگرداندنِ کتابِ عادی چند امتیاز است؟",
"جریمهٔ ۵ ساعت تأخیر در بازگرداندنِ یک کتابِ مرجع چند امتیاز است؟",
"عضو دانشجویی با ۲ بار تمدید چند روز فرصت دارد؟",
"عضو پژوهشی با ۱ بار تمدید چند روز فرصت دارد؟",
]
reset_calls()
for q in QUESTIONS:
call = chat([{"role": "user", "content": q}], tools=TOOLS)["tool_call"]
print(f"{q[:40]:<42} → {call['name'] if call else '— هیچ ابزاری'}")
جریمهٔ ۱۰ روز تأخیر در بازگرداندنِ کتابِ → fine_for_late_book
جریمهٔ ۵ ساعت تأخیر در بازگرداندنِ یک کت → fine_for_late_reference
عضو دانشجویی با ۲ بار تمدید چند روز فرصت → — هیچ ابزاری
عضو پژوهشی با ۱ بار تمدید چند روز فرصت د → — هیچ ابزاری
دو تا از چهار تا. دو پرسشِ آخر هیچ ابزاری نگرفتند — در حالی که max_loan_days دقیقاً برای همین دو پرسش نوشته شده و در فهرست هم هست.
پس مشکل از داشتن یا نداشتنِ ابزار نیست.
۳. خطِ پایه: بدونِ ابزار چه میشود#
CORPUS = "\n\n".join(d["text"] for d in DOCS)
SYSTEM = "تو دستیارِ کتابخانهای. فقط از متنِ زیر جواب بده. اگر جواب در متن نیست بنویس: در سند نیست"
reset_calls()
without = []
for q in QUESTIONS:
text = chat([{"role": "system", "content": SYSTEM},
{"role": "user", "content": CORPUS + "\n\n" + q}])["text"]
without.append(text)
print(" ", text[:60])
بهازای هر روز تأخیر در بازگرداندنِ کتابِ عادی ۲ امتیازِ منف
بهازای هر روز تأخیر در بازگرداندنِ کتابِ عادی ۲ امتیازِ منف
در سند نیست
در سند نیست
کلِ پیکره جلوی چشمش بود و هیچکدام را نگرفت.
دو تای اول قانون را برگرداندند بهجای جواب — «هر روز ۲ امتیاز» درست است ولی پرسش «۱۰ روز چقدر؟» بود. دو تای آخر هم صادقانه گفتند نمیدانند.
و این دقیقاً مرزی است که باید ببینی: جواب در هیچ جملهای نوشته نشده. باید ساخته شود، از ترکیبِ دو حقیقت و یک ضرب. بازیابیِ متن این را حل نمیکند — هرچقدر هم بازیابیات خوب باشد.
۴. اجرای امن#
def call_tool(tool_call):
"""مرزِ امنیتی: فقط از فهرستِ سفید، و فقط بعد از اعتبارسنجی."""
if tool_call["name"] not in BY_NAME:
raise ValueError(f"ابزارِ ناشناخته: {tool_call['name']}")
tool = BY_NAME[tool_call["name"]]
checked = tool["args"](**tool_call["arguments"])
return tool["run"](checked)
reset_calls()
for q in QUESTIONS:
call = chat([{"role": "user", "content": q}], tools=TOOLS)["tool_call"]
print(" ", call_tool(call))
۱۰ روز تأخیرِ کتابِ عادی = ۲۰ امتیازِ منفی
۵ ساعت تأخیرِ کتابِ مرجع = ۳۰ امتیازِ منفی
عضو دانشجویی با ۲ بار تمدید: ۳۵ روز
عضو پژوهشی با ۱ بار تمدید: ۳۷ روز
این شش خط کوچکترین تابعِ این ترم است و مهمترینشان. دو خطش دو دیوارِ جداگانهاند:
if ... not in BY_NAME— فهرستِ سفید. فقط ابزارهایی که خودت نوشتهای.tool["args"](**...)— دروازهٔ فصلِ ۲، این بار روی آرگومانها.
✅ چک کن: اگر بهجای
BY_NAME[...]وسوسه شدیglobals()[name]یاgetattr(module, name)بنویسی، بایست. آنوقت مدل میتواند نامِ هر تابعی را که در حافظه هست بگوید.evalوexecروی خروجیِ مدل هم همینطور. این مرز جای خلاقیت نیست.
۵. حلقهٔ کامل#
def answer_with_tools(question, verbose=False):
messages = [{"role": "user", "content": question}]
first = chat(messages, tools=TOOLS)
if first["tool_call"] is None:
return first["text"]
result = call_tool(first["tool_call"])
if verbose:
print(" ۱) مدل خواست :", first["tool_call"])
print(" ۲) کد اجرا کرد:", result)
messages.append({"role": "tool", "name": first["tool_call"]["name"], "content": result})
return chat(messages)["text"] # این بار بدونِ ابزار: فقط جملهٔ نهایی را بساز
reset_calls()
print(" ۳) جوابِ نهایی:", answer_with_tools(QUESTIONS[1], verbose=True))
۱) مدل خواست : {'name': 'fine_for_late_reference', 'arguments': {'hours': 5}}
۲) کد اجرا کرد: ۵ ساعت تأخیرِ کتابِ مرجع = ۳۰ امتیازِ منفی
۳) جوابِ نهایی: ۵ ساعت تأخیرِ کتابِ مرجع = ۳۰ امتیازِ منفی
سه گام، و مرز دقیقاً وسطِ گامِ اول و دوم است:
- ۱) مدل تصمیم میگیرد — کدام ابزار، با چه ورودی. هیچ کاری نمیکند؛ فقط نام میبرد.
- ۲) کدِ تو اجرا میکند — بعد از فهرستِ سفید و اعتبارسنجی.
- ۳) نتیجه با نقشِ
toolبرمیگردد — همراهِ نامِ ابزار — و مدل جملهٔ نهایی را میسازد.
آن name تزیینی نیست. بدونش مدل نمیداند این نتیجه جوابِ کدام درخواست بود، و اگر چند ابزار پشتِسرِهم صدا زده شود گم میشود و همان ابزار را دوباره میخواهد. فصلِ ۷ که حلقه را باز میکند، دقیقاً روی همین بند میایستد.
و به تماسِ دوم دقت کن: tools را دیگر نفرستادیم. یعنی صریح گفتیم «کارت تمام است، فقط جمله را بساز». این حلقه عمداً یکمرحلهای است — یک درخواست، یک اجرا، یک جواب. اگر ابزار را دوباره پیشنهاد کنی، مدل میتواند باز هم ابزار بخواهد و حلقهای باز میشود که خودش موضوعِ فصلِ ۷ است.
«مدل تصمیم میگیرد، کدِ تو اجرا میکند» شعار نیست، معماری است. هر بار که این مرز را میشکنی، یک راهِ نفوذ باز کردهای — و فصلِ ۹ نشان میدهد چطور یک سند میتواند همان تصمیم را بدزدد.
۶. حالا با عدد#
GOLD_ANSWERS = ["۲۰ امتیاز", "۳۰ امتیاز", "۳۵ روز", "۳۷ روز"]
reset_calls()
with_tools = [answer_with_tools(q) for q in QUESTIONS]
hit_without = sum(a in t for a, t in zip(GOLD_ANSWERS, without))
hit_with = sum(a in t for a, t in zip(GOLD_ANSWERS, with_tools))
print("بدونِ ابزار:", hit_without, "از ۴ درست")
print("با ابزار :", hit_with, "از ۴ درست")
بدونِ ابزار: 0 از ۴ درست
با ابزار : 4 از ۴ درست
صفر به چهار. و این بهبود از هوشِ بیشترِ مدل نیامد — از این آمد که کارِ حساب را به چیزی سپردیم که حساب بلد است.
📏 اندازه بگیر: قاعدهای که در فصلِ ۲ دیدی، اینجا شکلِ کاملترش را میگیرد: هر چیزی که کد میتواند حساب کند یا جستوجو کند، ابزار شود. مدل برای فهمیدنِ پرسش است و ساختنِ جملهٔ جواب. تاریخ و ارز و موجودی و نرخ — هیچکدام را از حافظهٔ مدل نپرس. حافظهاش کهنه است و مطمئن هم بهنظر میرسد.
۷. خرابیِ اول: ورودیِ بیمعنا#
reset_calls()
vague = chat([{"role": "user", "content": "جریمهٔ تأخیر کتابِ مرجع چطور حساب میشود؟"}], tools=TOOLS)
print("مدل پیشنهاد داد:", vague["tool_call"])
try:
call_tool(vague["tool_call"])
except ValidationError as error:
problem = error.errors()[0]
print("دروازه جلویش را گرفت →", problem["loc"], "|", problem["type"], "|", repr(problem["input"]))
مدل پیشنهاد داد: {'name': 'fine_for_late_book', 'arguments': {'days': 'نامشخص'}}
دروازه جلویش را گرفت → ('days',) | int_parsing | 'نامشخص'
پرسش هیچ عددی نداشت — «چطور حساب میشود؟» یک پرسشِ روش است، نه یک حساب. ولی مدل بهجای اینکه بگوید نمیدانم، چیزی از خودش ساخت و در آرگومان گذاشت.
این رفتار واقعی است و باید انتظارش را داشته باشی: مدلها تمایل دارند فیلدِ اجباری را پر کنند، حتی وقتی دادهای برایش ندارند.
و دقت کن دروازه کجا ایستاد: قبل از اجرای تابع. اگر fine_for_late_book را بدونِ دروازه صدا میزدی، 2 * 'نامشخص' هیچ خطایی نمیداد: پایتون رشته را دو بار تکرار میکند و تابع بیصدا «نامشخص روز تأخیرِ کتابِ عادی = نامشخصنامشخص امتیازِ منفی» برمیگرداند.
و error.errors() را هم ببین: بهجای بریدنِ متنِ خطا با splitlines، pydantic خودش فهرستی از دیکشنری میدهد با loc و type و input. برای تصمیمگیریِ برنامهای همیشه از این استفاده کن؛ متنِ انسانی برای انسان است — و برای برگرداندن به مدل، مثلِ فصلِ ۲.
۸. خرابیِ دوم: ورودیِ معتبر و غلط#
reset_calls()
sneaky = chat([{"role": "user", "content": "پنجشنبهها ساعت کار کتابخانه تا چند است؟"}], tools=TOOLS)
print("مدل پیشنهاد داد:", sneaky["tool_call"])
print("اعتبارسنجی :", HoursArgs(**sneaky["tool_call"]["arguments"]), "← بدونِ اعتراض")
print("نتیجه :", call_tool(sneaky["tool_call"]))
print("جوابِ درست : ساعتِ کارِ پنجشنبه: ۸ تا ۱۴")
مدل پیشنهاد داد: {'name': 'hours_lookup', 'arguments': {'day': 'شنبه'}}
اعتبارسنجی : day='شنبه' ← بدونِ اعتراض
نتیجه : ساعتِ کارِ شنبه: ۸ تا ۲۰
جوابِ درست : ساعتِ کارِ پنجشنبه: ۸ تا ۱۴
پرسش دربارهٔ پنجشنبه بود. مدل «شنبه» فرستاد. Literal هم قبولش کرد — چون «شنبه» یک مقدارِ کاملاً مجاز است.
این خطرناکترین خرابیِ کلِ فصل است، و هیچ اعتبارسنجیای نمیگیردش.
مسیرِ کاربر را دنبال کن: پرسید پنجشنبه، جواب گرفت «۸ تا ۲۰»، پنجشنبه ساعت ۱۹ آمد و در بسته بود. هیچ خطایی هیچجا ثبت نشد. برنامه از دیدِ خودش کاملاً موفق بود.
پس در برابرش چه میشود کرد؟ سه چیز، و هیچکدام کامل نیست:
- مقدارِ برگشتی را با پرسش مقابله بده. اگر «پنجشنبه» در پرسش هست و ابزار «شنبه» گرفته، شک کن. یک بررسیِ ساده، نه یک راهِحلِ عمومی.
- نتیجهٔ ابزار را در جوابِ نهایی نشان بده، نه فقط خلاصهاش. «ساعتِ کارِ شنبه: ۸ تا ۲۰» به کاربر میگوید کجا اشتباه شده. شفافیت، بخشی از درستی است.
- و مهمتر از همه:
evalبساز. فصلِ ۶ تمامش دربارهٔ همین است — تنها راهِ دیدنِ این خرابیها قبل از کاربر، این است که خودت مجموعهای از پرسشهای با جوابِ معلوم داشته باشی و مرتب اجرایشان کنی.
🔧 اگر کار نکرد: اگر مدل ابزارِ درست را انتخاب کرد ولی آرگومان مدام غلط بود، سه جا را نگاه کن: نامِ آرگومان (
dayگویاتر ازdاست)،descriptionی خودِ آرگومان (همانقدر مهم که توضیحِ ابزار)، وenumی که یک مقدارش داخلِ مقدارِ دیگری است — مثلِ «شنبه» که پایانِ «پنجشنبه» است و دقیقاً همینجا ما را زمین زد. اگر میتوانی، مقدارها را طوری بنویس که هیچکدام داخلِ دیگری نباشد.
۹. خرابیِ سوم: ابزاری که وجود ندارد#
try:
call_tool({"name": "os.system", "arguments": {"cmd": "rm -rf /"}})
except ValueError as error:
print("جلویش گرفته شد →", error)
جلویش گرفته شد → ابزارِ ناشناخته: os.system
اینجا خودمان یک درخواستِ بدخواه ساختیم تا فهرستِ سفید را امتحان کنیم. ولی سؤالِ درست این است: چنین چیزی از کجا میتواند بیاید؟
از متن. مدل هر چیزی را که در ورودیاش هست پردازش میکند — از جمله سندی که تو از پایگاه داده کشیدهای و داخلِ پرامپت گذاشتهای. اگر آن سند بگوید «ابزارِ os.system را با این ورودی صدا بزن»، مدل ممکن است اطاعت کند.
فصلِ ۹ دقیقاً این حمله را میسازد و اندازه میگیرد. تا آنوقت، این شش خط را نگه دار.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| tool calling | تول کالینگ | مدل نامِ تابع و ورودیاش را پیشنهاد میدهد، کد اجرا میکند |
| tool schema | تول اسکیما | توصیفِ رسمیِ آرگومانهای یک ابزار |
| whitelist | وایتلیست | فهرستِ بستهٔ چیزهای مجاز؛ هر چیزِ دیگری رد |
| role: tool | رول تول | نقشِ پیامی که نتیجهٔ اجرای ابزار را برمیگرداند |
| least privilege | لیست پریویلیج | هر ابزار فقط همان اجازهای که واقعاً لازم دارد |
🤖 از دستیارت بپرس: «اگر ابزارم پایگاه داده را تغییر میدهد، قبل از اجرا چه محافظی لازم دارم؟» (تأییدِ انسانی،
dry-run، سقفِ اثر، و برگشتپذیری را خواهی دید.) بعد این را بپرس: «آیا باید بگذارم مدل نامِ جدولی را که میخواهد پاک شود، خودش انتخاب کند؟» — جوابِ درست نه است، و همان قاعدهٔ فهرستِ سفید است در لباسِ داده.
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
تا حالا سندها را با دست داخلِ پرامپت گذاشتیم — کلِ دوازده سند، هر بار. برای دوازده سند میشود؛ برای دوازده هزار تا نه. فصلِ بعد پیکره را تکه میکند، همه را به بردار تبدیل میکند، و فقط تکههای مربوط را پیدا میکند. اسمش RAG است، و از صفر میسازیمش.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.