لایههای تلاش مجدد (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، ابزار سه بار با آرگومانی یکسان اجرا شد:
tool attempts:
[
"http://svc.local/a",
"http://svc.local/a",
"http://svc.local/a"
]تلاشهای ثبتشده توسط ابزار در بخش اول فایل.
با تنظیم max_retries=1، وقتی فرصت تلاشها ذیل رفتار on_failure="continue" تمام شود، مدل یک ToolMessage حاوی خطا دریافت میکند و اجرا ادامه مییابد:
"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 درخواست به مدل و 2 اجرای ابزار ثبت شد و فرایند با موفقیت پایان یافت. اما قطعی اتصال مدل در تمام دفعات، کار را به 9 بار ارسال درخواست به مدل کشاند و اصلاً به ابزار نرسید.
تنظیمات امن
برای هر نوع فراخوانی فقط یک لایهی تلاش مجدد انتخاب کنید، و تنها مواردی را دوباره امتحان کنید که تکرارشان امن است:
- برای مدل، تلاشهای کلاینت را نگه دارید و
ModelRetryMiddlewareرا کنار بگذارید، یا پارامترmax_retries=0را در مدل تنظیم کنید و میدلویر را بیفزایید. - برای ابزارها، در گزینهی
toolsمربوط بهToolRetryMiddlewareفقط ابزارهایی را فهرست کنید که بیاثر در تکرار هستند. - در پارامتر
retry_onخطاهایی را مشخص کنید که از امن بودنشان مطمئنید؛ مثل رد اتصال یا خطای 503. - برای هر اثر جانبی، یک کلید یکتایی تراکنش (idempotency key) تعریف کنید که سرویس آن را بررسی کند. بخش 5.3 نشان میدهد که چرا پس از توقف ناگهانی سیستم (crash) نیز به این سازوکار نیاز داریم.
- سقف زمانی خود را بر اساس تعداد تلاشها تنظیم کنید. سه بار تلاش با مهلت 1 ثانیهای و تأخیرهای 1 و 2 ثانیهای، برای یک فراخوانی ابزار 6 ثانیه زمان میبرد.
در آزمایشگاه، لایهی کلاینت برای اجرای تستهای میدلویر به این شکل غیرفعال شد:
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 قرار نمیگیرد؛ بنابراین هیچ تلاشی صورت نگرفت و بلافاصله استثنا پرتاب شد:
tools=[], middleware=[ModelRetryMiddleware(max_retries=2, retry_on=(TimeoutError,), on_failure="error", **fast)])مدلهای پشتیبان
ModelFallbackMiddleware: میدلویری که در صورت بروز استثنا در فراخوانی مدل، مدل بعدی موجود در فهرستش را فرا میخواند.
کیت آزمایشی یک مدل اصلی ChatOllama روی پورتی بدون شنونده و یک مدل پشتیبان روی Ollama به آن میدهد. مدل اصلی با یک فراخوانی با خطای httpx.ConnectError روبهرو شد و مدل پشتیبان پاسخ داد:
"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.