بخش 4.7 · ایجنت، خروجی ساختاریافته و میان‌افزار

تلاش‌های مجدد، مدل‌های پشتیبان، محدودیت‌های نرخ درخواست و کش‌گذاری

Retries, backup models, rate limits, and caching

فهرست مطالب
  1. دو لایه برای مدل، یک لایه برای ابزارها
  2. دامنه‌ی شمول خطاها در هر لایه
  3. تنظیمات امن
  4. مدل‌های پشتیبان
  5. محدودیت‌های نرخ درخواست و کش‌گذاری

لایه‌های تلاش مجدد (retry layers) در یکدیگر ضرب می‌شوند؛ ToolRetryMiddleware ابزاری را که مهلت زمانی‌اش تمام شده ولی درخواستش پیش‌تر به سرویس رسیده دوباره اجرا می‌کند؛ و مدل پشتیبان هم بدون تفکیک، در برابر هر خطایی فعال می‌شود.

ایجنت شما ابزاری را برای پرداخت فراخوانی می‌کند، پاسخ بعد از 1 ثانیه با پایان مهلت زمانی (timeout) روبه‌رو می‌شود، و میدل‌ویرِ تلاش مجدد آن را دوباره فرا می‌خواند. درخواست اول در واقع به مقصد رسیده بود. حالا حساب مشتری دو بار شارژ شده است، در حالی که گزارش اجرای برنامه وضعیت را موفق نشان می‌دهد.

پس از پایان این بخش، می‌توانید تعداد تلاش‌های هر لایه‌ی تلاش مجدد را بشمارید و مشخص کنید هر لایه کدام شکست‌ها را دوباره امتحان می‌کند. می‌توانید تلاش‌های مجدد را طوری تنظیم کنید که اثری جانبی (side effect) تکرار نشود. همچنین می‌توانید مدل پشتیبان اضافه کنید و بگویید محدودکننده‌ی نرخ درخواست (rate limiter) و کش در نسخه‌ی قفل‌شده دقیقاً چه کار می‌کنند.

دو لایه برای مدل، یک لایه برای ابزارها

لایه‌ی تلاش مجدد: قطعه‌کدی مشخص که پس از بروز خطا، مدل یا ابزار را دوباره فراخوانی می‌کند.

فراخوانی مدل دو لایه‌ی تلاش مجدد دارد: ابتدا کلاینتِ درون پکیج ارائه‌دهنده دوباره تلاش می‌کند، و سپس ModelRetryMiddleware که در لایه‌ی بیرونی قرار گرفته این کار را تکرار می‌کند. در بخش 3.2 این لایه‌ها را با ChatOpenAI شمردیم: کلاینت 3 بار تلاش کرد، میدل‌ویر هم 3 بار، و در مجموع 9 تلاش ثبت شد. تصویر هر اجرا را نشان می‌دهد. در مقابل، ChatOllama فقط 1 بار تلاش کرد، چون کلاینت آن تلاشی برای اجرای مجدد نمی‌کند.

تعریف RetryPolicy روی نود گراف هم دقیقاً اثر ضربی دارد: 9 تلاش پیرامون رفتار پیش‌فرض کلاینت، و 27 تلاش پیرامون ایجنتی که میدل‌ویر را درون خود دارد. 6 تلاش مجددی که در صفحه‌ی مدل‌ها ذکر شده بود، برای ChatOpenAI در نسخه‌ی قفل‌شده برقرار نبود.

فراخوانی ابزار تنها یک لایه دارد: ToolRetryMiddleware. ابزاری که بدون این میدل‌ویر با خطا متوقف شود، همان‌طور که در بخش 3.4 دیدیم، اجرای کل فرایند را پایان می‌دهد. هر دو میدل‌ویر پارامترهای یکسانی می‌پذیرند و مقادیر پیش‌فرض آن‌ها به این شرح است {{code libs/langchain_v1/langchain/agents/middleware/tool_retry.py}}:

گزینه مقدار پیش‌فرض مفهوم
max_retries 2 تلاش‌های مجدد پس از اولین بار؛ یعنی در مجموع 3 تلاش
retry_on default_retry_on تعیین استثناهایی (exceptions) که باید برایشان تلاش مجدد انجام شود
on_failure "continue" برگرداندن یک پیام به جای توقف با خطا، پس از آخرین تلاش ناموفق
initial_delay، backoff_factor، max_delay 1.0، 2.0، 60.0 ثانیه‌های مکث پیش از هر تلاش مجدد؛ در هر نوبت دو برابر می‌شود
jitter True اعمال نوسان تصادفی روی تأخیرها
tools None فقط در ToolRetryMiddleware: تعیین ابزارهای مشمول تلاش مجدد، یا همه‌ی آن‌ها

محیط آزمایشی ابزاری را اجرا می‌کند که دو بار شکست می‌خورد و بار سوم موفق می‌شود. با تنظیم max_retries=2، ابزار سه بار با آرگومانی یکسان اجرا شد:

سه بار تلاش برای یک فراخوانی ابزار capture/out/12-mw-retries.txt
tool attempts:
[
  "http://svc.local/a",
  "http://svc.local/a",
  "http://svc.local/a"
]

تلاش‌های ثبت‌شده توسط ابزار در بخش اول فایل.

با تنظیم max_retries=1، وقتی فرصت تلاش‌ها ذیل رفتار on_failure="continue" تمام شود، مدل یک ToolMessage حاوی خطا دریافت می‌کند و اجرا ادامه می‌یابد:

پیام ToolMessage پس از پایان تلاش‌های مجدد capture/out/12-mw-retries.txt
    "content": "Tool 'flaky_fetch' failed after 2 attempts with ConnectionError: attempt 2 refused. Please try again.",
    "name": "flaky_fetch",

اما با انتخاب on_failure="error"، برنامه خطای ConnectionError: attempt 2 refused صادر کرد.

وظیفه‌ی ModelRetryMiddleware تلاش دوباره برای فراخوانی مدل است. در سناریوی آزمایشی، ChatOllama به یک بازپخش‌کننده (relay) هدایت شد؛ سیستمی که دو اتصال اول را قطع می‌کرد و سومی را به Ollama می‌رساند. با max_retries=2، سه فراخوانی به مدل رسید و در بار سوم پاسخ داد: 2 + 3 = 5..

اگر max_retries=1 و حالت continue فعال باشد، میدل‌ویر به جای توقف با خطا، یک AIMessage حاوی متن خطا برمی‌گرداند. در تست انجام‌شده، مدل را به پورتی بدون شنونده متصل کردیم؛ در نتیجه، شکست فراخوانی مدل شبیه یک پاسخ عادی به نظر رسید: Model call failed after 2 attempts with ConnectError: [Errno 111] Connection refused.

دامنه‌ی شمول خطاها در هر لایه

default_retry_on: مقدار پیش‌فرض retry_on در هر دو میدل‌ویر است. این رفتار برای تمام نمونه‌های Exception تلاش مجدد می‌کند، مگر استثنای ModelError در LangChain که مقدار is_retryable آن false باشد {{code libs/langchain_v1/langchain/agents/middleware/_retry.py}}.

بنابراین اگر پکیج ارائه‌دهنده خطایی از جنس ModelError صادر کند که نتواند رفع شود، تلاشی برایش صورت نمی‌گیرد. به همین دلیل خطای واقعی 404 در Ollama از مسیر ChatOpenAI تنها 1 بار تلاش شد. اما ChatOllama خطای ResponseError کلاینت ollama را برمی‌گرداند که ModelError محسوب نمی‌شود؛ در نتیجه با وجود ModelRetryMiddleware، خطای 404 آن 3 بار امتحان شد. خطاهای ابزار هم استثناهای معمولی هستند (مثل خطاهای کتابخانه‌ی httpx)، بنابراین حالت پیش‌فرض همه‌ی آن‌ها را دوباره امتحان می‌کند. میدل‌ویر نمی‌تواند بداند آیا درخواست ناموفق ابزار به سرویس رسیده است یا خیر.

ما رفتار ToolRetryMiddleware() را با مقادیر پیش‌فرض روی سیستم‌عامل مهمانِ سرور x86 اندازه گرفتیم؛ به این صورت که برای هر خانه 3 بار اجرا ثبت شد. مدل Qwen3 4B روی Ollama فراخوانی ابزار را انتخاب کرد. ابزار داده‌ها را در PostgreSQL می‌نوشت. برای پایان مهلت زمانی، ابزار ابتدا سطری به جدول حسابداری اضافه می‌کرد و سپس تابع pg_sleep(3) را با سقف زمانی statement_timeout معادل 1 ثانیه اجرا می‌کرد. نتایج شمارش در هر 3 اجرای هر خانه کاملاً یکسان بود:

نوع خطای ابزار بدون میدل‌ویر ToolRetryMiddleware() سطرهای جدول حسابداری با میدل‌ویر
رد اتصال (connection refused) برای یک بار توقف با خطا، 1 بار اجرا 2 بار اجرا، سپس موفقیت‌آمیز 1
رد اتصال در تمام فراخوانی‌ها توقف با خطا، 1 بار اجرا 3 بار اجرا، سپس ثبت خطای ToolMessage 0
نبود جدول در تمام فراخوانی‌ها توقف با خطا، 1 بار اجرا 3 بار اجرا، سپس ثبت خطای ToolMessage 0
پایان مهلت زمانی برای یک بار توقف با خطا، 1 بار اجرا 2 بار اجرا، سپس موفقیت‌آمیز 2
پایان مهلت زمانی در تمام فراخوانی‌ها توقف با خطا، 1 بار اجرا 3 بار اجرا، سپس ثبت خطای ToolMessage 3

در سناریوی پایان مهلت زمانی، هر تلاش مجدد سطر خود را پیش از پایان مهلت در جدول ثبت کرده بود. بنابراین ابزاری که پاسخش گم شده بود، عملیات خود را تا 3 بار تکرار کرد. ایشوی langchain#40688 نیز دقیقاً همین مشکل را برای ابزارهایی گزارش می‌کند که بی‌اثر در تکرار (idempotent) نیستند {{issue langchain#40688}}. این ایشو در نسخه‌ی قفل‌شده همچنان باز است و آزمایش‌های ما با یک پایگاه داده‌ی واقعی آن را بازتولید کرد. رفتار پیش‌فرض حتی برای خطای نبود جدول نیز دوباره تلاش کرد؛ در حالی که هیچ تلاش مجددی نمی‌تواند آن را رفع کند.

پس از دریافت ToolMessage حاوی خطا، مدل در هر 9 اجرا ابزار را دوباره صدا نزد؛ پیام پایانی مدل واژه‌ی done یا متنی با شروع Try again بود، و به همین دلیل شبیه یک اجرای موفق خوانده می‌شد. تصویر حالت پایان مهلت زمانی را ترسیم می‌کند.

فراخوانی ابزاری که سه بار با تایم‌اوت مواجه می‌شودهر یک از 3 تلاش، ردیف دفترکل خود را پیش از پایان مهلت زمانی ثبت کرد؛ بنابراین عملیاتی که پاسخ آن گم شده بود، 3 بار اجرا شد قبل از آنکه مدل خطایی دریافت کند.
فراخوانی ابزاری که سه بار دچار تایم‌اوت می‌شود یک توالی با چهار خط حیات: گره ابزارها، ToolRetryMiddleware، ابزار remote_action و جدول دفترکل در PostgreSQL. ابزار یک ردیف درج می‌کند و سپس pg_sleep(3) را تحت مهلت زمانی 1 ثانیه‌ای دستور اجرا می‌نماید. هر یک از 3 تلاش سطر خود را می‌نویسد و هرکدام با QueryCanceled پایان می‌یابد. میان‌افزار بین تلاش‌ها 1 ثانیه و سپس 2 ثانیه منتظر می‌ماند. پس از آخرین تلاش، یک ToolMessage خطا برمی‌گرداند و دفترکل در هر 3 اجرا با Qwen3 4B روی سرور مهمان x86، حاوی 3 ردیف است. گره ابزارها فراخوانی ابزار ToolRetry Middleware() remote_action ابزار دفترکل PostgreSQL INSERT, pg_sleep(3) 1 remote_action(item) 2 تلاش 1 3 INSERT 1 4 QueryCanceled بعد از 1 ثانیه انتظار 1 ثانیه 5 تلاش 2 6 INSERT 2 7 QueryCanceled بعد از 1 ثانیه انتظار 2 ثانیه 8 تلاش 3 9 INSERT 3 10 QueryCanceled بعد از 1 ثانیه 11 ToolMessage خطا 3 سطر دفترکل
ردیف‌ها را از بالا به پایین بخوانید. هر پیکان خط‌چین زیتونی یک INSERT است که سطر خود را ثبت کرده و هر پیکان خط‌چین صورتی یک QueryCanceled پس از 1 ثانیه است. دفترکل در هر یک از 3 اجرا شامل 3 سطر بود. برگرفته از capture/lab/summary/retries-x86.json.

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

تنظیمات امن

برای هر نوع فراخوانی فقط یک لایه‌ی تلاش مجدد انتخاب کنید، و تنها مواردی را دوباره امتحان کنید که تکرارشان امن است:

  1. برای مدل، تلاش‌های کلاینت را نگه دارید و ModelRetryMiddleware را کنار بگذارید، یا پارامتر max_retries=0 را در مدل تنظیم کنید و میدل‌ویر را بیفزایید.
  2. برای ابزارها، در گزینه‌ی tools مربوط به ToolRetryMiddleware فقط ابزارهایی را فهرست کنید که بی‌اثر در تکرار هستند.
  3. در پارامتر retry_on خطاهایی را مشخص کنید که از امن بودنشان مطمئنید؛ مثل رد اتصال یا خطای 503.
  4. برای هر اثر جانبی، یک کلید یکتایی تراکنش (idempotency key) تعریف کنید که سرویس آن را بررسی کند. بخش 5.3 نشان می‌دهد که چرا پس از توقف ناگهانی سیستم (crash) نیز به این سازوکار نیاز داریم.
  5. سقف زمانی خود را بر اساس تعداد تلاش‌ها تنظیم کنید. سه بار تلاش با مهلت 1 ثانیه‌ای و تأخیرهای 1 و 2 ثانیه‌ای، برای یک فراخوانی ابزار 6 ثانیه زمان می‌برد.

در آزمایشگاه، لایه‌ی کلاینت برای اجرای تست‌های میدل‌ویر به این شکل غیرفعال شد:

یک لایه تلاش مجدد برای مدل capture/lab/T05-retries-x86/t05_real.py
    kw = {"timeout": to}
    if config in ("openai_mw_only",):
        kw["max_retries"] = 0
    return chat_openai(model=name, port=port, **kw)
…
def build(config, model, tl):
    mw = []
    if config in ("openai_mw_only", "openai_stacked", "ollama_mw", "openai_both_mw"):
        mw.append(ModelRetryMiddleware())

بخش‌هایی از توابع model و build در اسکریپت آزمایشگاه. خطوط میان آن‌ها در محل علامت برش خورده است.

تعریف یک تاپل در retry_on تلاش مجدد را به همان نوع استثناها محدود می‌کند. در محیط آزمایشی، خطای رد اتصال باعث صادر شدن httpx.ConnectError شد که در دسته‌ی TimeoutError قرار نمی‌گیرد؛ بنابراین هیچ تلاشی صورت نگرفت و بلافاصله استثنا پرتاب شد:

یک فیلتر retry_on capture/s_middleware.py
        tools=[], middleware=[ModelRetryMiddleware(max_retries=2, retry_on=(TimeoutError,), on_failure="error", **fast)])

مدل‌های پشتیبان

ModelFallbackMiddleware: میدل‌ویری که در صورت بروز استثنا در فراخوانی مدل، مدل بعدی موجود در فهرستش را فرا می‌خواند.

کیت آزمایشی یک مدل اصلی ChatOllama روی پورتی بدون شنونده و یک مدل پشتیبان روی Ollama به آن می‌دهد. مدل اصلی با یک فراخوانی با خطای httpx.ConnectError روبه‌رو شد و مدل پشتیبان پاسخ داد:

پاسخ پس از بروز خطای مدل اولیه capture/out/13-mw-fallback-refusal.txt
    "type": "AIMessage",
    "content": "2 + 3 = 5.",

پیام این اجرا.

این میدل‌ویر مدل‌ها را به ترتیب امتحان می‌کند و در برابر هرگونه Exception فعال می‌شود {{code libs/langchain_v1/langchain/agents/middleware/model_fallback.py}}. اگر تمام مدل‌ها خطا بدهند، اجرا آخرین خطا را صادر می‌کند. وقتی در کیت آزمایشی هر سه مدل را به پورت قطع‌شده متصل کردیم، اجرا خطای httpx.ConnectError: [Errno 111] Connection refused را صادر کرد. کدْ نوع خطا را بررسی نمی‌کند، بنابراین حتی خطای 400 ناشی از درخواست نادرست هم باعث رفتن سراغ مدل بعدی می‌شود. آزمایش این اجرا در ویرایش بعدی ارائه خواهد شد و بخش 8.8 آن را فهرست کرده است.

امتناع مدل (refusal) استثنا نیست. میدل‌ویر ModelRefusalMiddleware خطای ModelRefusalError را تنها زمانی صادر می‌کند که در پاسخْ بلوک محتوایی استاندارد refusal وجود داشته باشد، و متن را نمی‌خواند {{code libs/langchain_v1/langchain/agents/middleware/model_refusal.py}}. ابتدا ModelFallbackMiddleware و سپس ModelRefusalMiddleware را در فهرست قرار دهید تا بلوک امتناع به مدل پشتیبان ارجاع داده شود.

کیت آزمایشی از Qwen3 4B پرسید که چگونه می‌توان قفل در همسایه را باز کرد. مدل در قالب متنی ساده امتناع کرد و نوشت: I'm sorry, but I can't assist with that.. از آنجا که Ollama بلوک امتناع ارسال نمی‌کند، این متن در هر سه اجرا پاسخی عادی در نظر گرفته شد. این وضعیت چه بدون میدل‌ویر، چه با ModelRefusalMiddleware و چه با هر دو میدل‌ویر برقرار بود و مدل پشتیبان هیچ فراخوانی‌ای دریافت نکرد. بنابراین امتناع در قالب متن معمولی نیازمند بررسی اختصاصی خود شماست.

محدودیت‌های نرخ درخواست و کش‌گذاری

مدل چت پارامتر rate_limiter می‌پذیرد. کلاس InMemoryRateLimiter یک سطل توکن (token bucket) با مقادیر پیش‌فرض requests_per_second=1 و max_bucket_size=1 در یک فرایند است {{code libs/core/langchain_core/rate_limiters.py}}. صفحه‌ی مدل‌ها هشدار می‌دهد که این ابزار فقط تعداد درخواست‌ها را می‌شمارد نه حجم آن‌ها را {{docs oss/python/langchain/models}}. دو فرایند هر کدام سطل مستقل خود را خواهند داشت.

دو کش وجود دارد: set_llm_cache پاسخ‌های مدل را در LangChain کش می‌کند، و آرگومان cache در تابع create_agent یک کش برای نودهای LangGraph است. ما هیچ‌کدام از این دو روش یا محدودکننده‌ی نرخ درخواست را در برابر یک مدل اجرا نکردیم. این آزمایش‌ها در ویرایش بعدی ارائه می‌شوند و بخش 8.8 آن‌ها را فهرست کرده است.

منابع: capture/out/12-mw-retries.txt، capture/out/13-mw-fallback-refusal.txt، capture/s_middleware.py، capture/common.py، libs/langchain_v1/langchain/agents/middleware/model_refusal.py در langchain==1.5.0؛ capture/lab/summary/retries-x86.json، capture/lab/T05-retries-x86/01-model-faults.jsonl، capture/lab/T05-retries-x86/02-tool-faults.jsonl، capture/lab/T05-retries-x86/03-both-faults.jsonl، capture/lab/T05-retries-x86/t05_real.py، capture/lab/T05-retries-x86/lr_common.py؛ ایشوی langchain#40688؛ docs.langchain.com در docs commit 04d4d4a (oss/python/langchain/models، oss/python/langchain/middleware/built-in)؛ libs/langchain_v1/langchain/agents/middleware/tool_retry.py، model_retry.py، _retry.py، و model_fallback.py در langchain==1.5.0؛ libs/core/langchain_core/rate_limiters.py در langchain-core 1.8.0.