stream و ابزارها

مدل فقط متن می‌نویسد و کار اصلی را ابزار انجام می‌دهد. اینجا می‌بینید این دو چطور در یک حلقه به هم وصل می‌شوند.

۶ دقیقهدرس ۳ از ۹۰ از ۳ قدم

دو چیز برنامهٔ شما را از یک تماس سادهٔ API جلوتر می‌برد: stream، تا کاربر برای دیدن جواب منتظر نماند، و ابزارها، تا مدل بتواند کاری هم انجام بدهد.

stream

با stream=true جواب تکه‌تکه می‌رسد و اولین کلمه‌ها زودتر دیده می‌شوند. برای هر رابط چت که کاربر جلویش منتظر است، همین حالت را بخواهید.

Python
resp = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash",
    messages=[{"role": "user", "content": "یک داستان کوتاه بنویس"}],
    stream=True,
)
for chunk in resp:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

آخرین تکه پیش از [DONE] فیلد usage را دارد و choices آن خالی است. برای همین در حلقه چک کرده‌ایم که choices خالی نباشد.

اگر جواب به‌جای تکه‌تکه یک‌جا می‌رسد، مشکل از buffer یک واسطه در سمت شماست، مثلاً nginx. ما هدر لازم را می‌فرستیم.

ابزارها

مدل نمی‌تواند خودش به پایگاه دادهٔ شما وصل شود، ولی می‌تواند بگوید کدام تابع را با چه ورودی صدا بزنید. به این می‌گویند function calling.

  1. درخواست را همراه تعریف ابزارها می‌فرستید.
  2. اگر مدل بخواهد ابزاری را صدا بزند، finish_reason برابر tool_calls می‌شود.
  3. تابع را خودتان اجرا می‌کنید.
  4. نتیجه را با نقش tool و همان tool_call_id به پیام‌ها اضافه می‌کنید و دوباره می‌فرستید.

schema ابزارها جزو پرامپت است و در هر درخواستِ همان گفت‌وگو، توکن ورودی حساب می‌شود.

ابزارهایی که خود ما اجرا می‌کنیم

سه ابزار با پیشوند iranrouter: را لازم نیست خودتان اجرا کنید. ما جست‌وجو یا خواندن را انجام می‌دهیم، نتیجه را به مدل می‌دهیم و یک جواب نهایی به شما می‌رسد.

نامچه می‌کند
iranrouter:web_searchجست‌وجوی وب عمومی
iranrouter:web_fetchخواندن متن یک صفحهٔ عمومی
iranrouter:datetimeتاریخ و ساعت تهران و UTC، با تاریخ شمسی
Python
resp = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash",
    messages=[{"role": "user", "content": "امروز چندم است؟"}],
    tools=[{"type": "function", "function": {"name": "iranrouter:datetime"}}],
)
print(resp.choices[0].message.content)

مدل باید function calling را پشتیبانی کند. هر دور از این حلقه یک درخواست کامل است، پس یک جواب ممکن است در «مصرف و لاگ‌ها» چند ردیف داشته باشد. حلقه سقف دارد تا از کنترل خارج نشود.

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

ابزار datetime را صدا بزنید۰ از ۳ قدم

  1. نمونهٔ بالا را با کلید خودتان اجرا کنید.
  2. ببینید تاریخ جواب درست است.
  3. در لاگ‌ها تعداد ردیف‌های این درخواست را بشمارید.

خلاصهٔ درس

  • با stream کاربر جواب را زودتر می‌بیند و usage در آخرین تکه می‌آید.
  • ابزارهای معمولی را شما اجرا می‌کنید و ابزارهای iranrouter: را ما.
  • درس بعد برنامه را در برابر قطعی مدل‌ها مقاوم می‌کنیم.
پایداری: مدل جایگزین و تلاش دوبارهمدل‌ها گاهی جواب نمی‌دهند. برنامهٔ شما نباید با آن‌ها بخوابد.تمام کردم، درس بعد