بخش 9.5 · محیط عملیاتی

ابزارهای ToolRetryMiddleware، ModelFallbackMiddleware و خاموش‌سازی

ToolRetryMiddleware, ModelFallbackMiddleware, and shutdown

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

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

جست‌وجو در مرکز راهنما یک‌بار با خطای اتصال روبه‌رو می‌شود؛ استعلام سفارش معلق می‌ماند؛ سیستم ثبت تیکت خطا می‌دهد و نمی‌دانید سطری در پایگاه داده نوشته شده یا نه؛ ارائه‌دهنده‌ی مدل اصلی از کار می‌افتد. هریک از این شرایط واکنش متفاوتی می‌طلبد، و پشته‌ی میان‌افزار (middleware stack) در create_agent دقیقاً همان جایی است که این رفتارها را تنظیم می‌کنید.

پس از پایان این بخش، می‌توانید میان‌افزارها را طوری بچینید که هر بار تلاش برای فراخوانی ابزار، محدودیت زمانی مستقل خودش را داشته باشد. همچنین یاد می‌گیرید کدام ابزارها را برای تلاش مجدد انتخاب کنید، یک مدل پشتیبان اضافه کنید و فرآیند کاری (worker) را بدون از دست رفتن اجرا متوقف کنید.

پشته‌ی میان‌افزار، از لایه‌ی بیرونی به درونی

پشته‌ی میان‌افزار سرویس capture/lab/prodapp-mac/code/app/agent.py
        middleware=[
            SummarizationMiddleware(model, trigger=("messages", settings.summarize_after), keep=("messages", 6)),
            ModelCallLimitMiddleware(run_limit=settings.model_calls_per_run, exit_behavior="end"),
            ModelFallbackMiddleware(backup),
            HumanInTheLoopMiddleware(
                {"refund_order": {"allowed_decisions": ["approve", "reject"], "description": refund_description}},
                interrupt_mode="per_call",
            ),
            ToolErrorMiddleware(tool_error_message),
            ToolRetryMiddleware(tools=IDEMPOTENT, max_retries=2, initial_delay=0.1, on_failure="error"),
            Tracing(),
            ToolTimeout(settings.tool_timeout, {"refund_order": settings.refund_timeout}),
            *extra,
        ],

اولین میان‌افزارِ فهرست، تمام موارد بعدی را در بر می‌گیرد. برای فراخوانی ابزار (Tool call)، ترتیب لایه‌ها از بیرون به درون به این صورت است: تاییدیه (approval)، متن خطا، تلاش مجدد، اسپن (span)، مهلت زمانی (timeout) و در نهایت خود ابزار. این چیدمان سه نتیجه به همراه دارد:

  • هر بار تلاش، محدودیت زمانی مستقل خودش را می‌گیرد؛ چون timeout درون retry قرار دارد.
  • هر بار تلاش، اسپن اختصاصی خودش را ثبت می‌کند؛ چون span هم داخل retry تعریف شده است.
  • مدل تنها یک پیام خطا را پس از اتمام آخرین تلاش می‌بیند؛ چون ToolErrorMiddleware بیرون لایه‌ی retry نشسته است.

ما ابزار ToolTimeout را خودمان نوشته‌ایم که در اصل چهار خط کد بر پایه‌ی asyncio.wait_for است. در نسخه‌ی 1.5.0 کتابخانه‌ی LangChain، فقط میان‌افزارهای shell و جست‌وجوی فایل محدودیت زمانی تعیین می‌کنند و فراخوانی‌های عادی ابزار هیچ محدودیت زمانی ندارند. ما مهلت زمانی ابزار refund_order را 15 ثانیه و بقیه‌ی ابزارها را 5 ثانیه گذاشته‌ایم؛ تست‌ها هم روی 0.5 ثانیه تنظیم شده‌اند.

اتمام مهلت زمانی، انتظار برای ابزار را لغو می‌کند، اما اثر ایجادشده را به عقب برنمی‌گرداند. ابزار بازپرداخت وجه ممکن است پیش از فعال شدن timeout، ردیف خود را commit کرده باشد. بنابراین پس از تمام شدن مهلت زمانی ابزاری که نقل‌وانتقال مالی انجام می‌دهد، پیش از آنکه به مشتری بگویید اتفاقی نیفتاده است، وضعیت سفارش را بخوانید.

ابزار بی‌اثر در تکرار (Idempotent tool): ابزاری است که اگر آن را دو بار با آرگومان‌های یکسان فراخوانی کنید، دقیقاً همان نتیجه و همان اثرات جانبی را تولید می‌کند. فقط ابزارهای read_order، search_faq و recall_notes در فهرست تلاش مجدد قرار دارند. ابزارهای create_ticket و save_note با هر بار فراخوانی، سطری با شناسه‌ی جدید می‌سازند؛ در نتیجه تلاش مجدد پس از پاسخی که دریافت نشده، دو سطر ثبت خواهد کرد. ابزار refund_order کلید اختصاصی خودش را دارد که بخش 9.3 آن را توضیح می‌دهد.

متن خطا به مدل می‌گوید هنگام بروز شکست چه‌کار کند.

متنی که مدل پس از شکست ابزار می‌خواند capture/lab/prodapp-mac/code/app/middleware.py
def tool_error_message(exc, request):
    event("tool.error", tool=request.tool_call["name"], error=type(exc).__name__)
    if isinstance(exc, TimeoutError):
        return f"{request.tool_call['name']} timed out. Tell the customer and do not guess."
    return f"{request.tool_call['name']} failed with {type(exc).__name__}. Tell the customer and do not guess."

سنجش پنج خطا روی سه مدل

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

خطا عملکرد سرویس، طبق اسپن‌ها Qwen3 4B Qwen3 14B Claude Haiku 5.5
یک‌بار خطای search_faq 2 تلاش، اولی اسپن خطا ابزار search_faq را صدا نزد 2 تلاش، سپس پاسخ درست 2 تلاش، سپس پاسخ درست
معلق ماندن read_order 3 تلاش، هر بار قطع در حدود 0.50 ثانیه 3 تلاش، سپس به مشتری گفت سفارش پیدا نشد 3 تلاش، سپس گفت در حال حاضر امکان استعلام سفارش وجود ندارد 3 تلاش، سپس گفت مهلت زمانی سیستم سفارش‌ها تمام شد
خطای create_ticket 1 تلاش، بدون تلاش مجدد، 0 سطر تیکت گفت نمی‌تواند تیکت باز کند گفت نمی‌تواند تیکت باز کند گفت نمی‌تواند تیکت باز کند
از کار افتادن مدل اصلی هر فراخوانی مدل اصلی یک اسپن خطا، سپس پاسخ مدل پشتیبان مدل پشتیبان Qwen3 8B، با 2 فراخوانی مدل پشتیبان Qwen3 4B، با 2 فراخوانی مدل پشتیبان Qwen3 4B، با 2 فراخوانی
درخواست بی‌پایان search_faq از طرف مدل توقف در 8 فراخوانی مدل و 8 فراخوانی ابزار اجرا 29.61 ثانیه طول کشید اجرا 151.34 ثانیه طول کشید اجرا 20.89 ثانیه طول کشید

شکل 9.5 همین اجراها را در قالب یک جدول تصمیم‌گیری نمایش می‌دهد.

پنج خطا، عملکرد میان‌افزار و پاسخ هر مدلمیان‌افزار با هر خطا در تمام مدل‌ها به یک شیوه برخورد کرد و فقط پاسخ به مشتری متفاوت بود.
پنج خطا، تلاش‌های ثبت‌شده در اسپن‌ها و پاسخ هر مدل به مشتری برای هر خطای تزریق‌شده، اسپن‌های ابزار و مدل در اولین اجرای آزمون روی Mac، و پاسخ‌های Qwen3 4B، Qwen3 14B و Claude Haiku 5.5. خطای یک‌باره‌ی search_faq: مدل Qwen3 4B ابزار را صدا نزد و گفت داده‌ای نیست (نامناسب)، Qwen3 14B پس از تلاش مجدد پاسخ داد (مناسب)، Claude Haiku 5.5 پس از تلاش مجدد پاسخ داد (مناسب). معلق ماندن read_order در هر تلاش: Qwen3 4B گفت سفارش پیدا نشد (نامناسب)، Qwen3 14B گفت اکنون قادر به جستجو نیست (مناسب)، Claude Haiku 5.5 گفت مهلت جستجو تمام شد (مناسب). خطای یک‌باره‌ی create_ticket: مدل Qwen3 4B گفت نتوانست تیکت ثبت کند (مناسب)، Qwen3 14B گفت نتوانست تیکت ثبت کند (مناسب)، Claude Haiku 5.5 گفت نتوانست تیکت ثبت کند (مناسب). خطای مدل اصلی: Qwen3 4B از مدل پشتیبان پاسخ داد (مناسب)، Qwen3 14B از مدل پشتیبان پاسخ داد (مناسب)، Claude Haiku 5.5 از مدل پشتیبان پاسخ داد (مناسب). درخواست بی‌پایان مدل برای search_faq: مدل Qwen3 4B پس از 8 فراخوانی پاسخ داد (مناسب)، Qwen3 14B پس از 8 فراخوانی پاسخ داد (مناسب)، Claude Haiku 5.5 پس از 8 فراخوانی پاسخ داد (مناسب). خطا اسپن‌های اجرا Qwen3 4B Qwen3 14B Haiku 5.5 ابزار موفق خطا فراخوانی مدل موفق search_faq fails یک‌بار 2 اسپن ابزار، Qwen3 14B بدون فراخوانی ابزار، گفت داده‌ای نیست پاسخ پس از تلاش مجدد پاسخ پس از تلاش مجدد read_order hangs در هر تلاش 3 اسپن ابزار، Qwen3 4B گفت سفارش یافت نشد گفت اکنون امکان جستجو وجود ندارد گفت جستجو مهلتش تمام شد create_ticket یک‌بار شکست 1 اسپن ابزار، Qwen3 4B گفت نتوانست موردی باز کند گفت نتوانست موردی باز کند گفت نتوانست موردی باز کند مدل اصلی خطا می‌دهد model.call: اصلی، پشتیبان پاسخ داد از پشتیبان پاسخ داد از پشتیبان پاسخ داد از پشتیبان مدل درخواست دارد search_faq forever 8 اسپن ابزار، Qwen3 4B پاسخ داد پس از 8 تماس پاسخ داد پس از 8 تماس پاسخ داد پس از 8 تماس
هر ردیف را از چپ به راست بخوانید: نوع خطا، تلاش‌های ثبت‌شده در اسپن‌ها و پاسخ هر مدل. پاسخ صورتی‌رنگ مشتری را گمراه کرده یا فراخوانی ابزار را نادیده گرفته است. برگرفته از capture/lab/prodapp-mac/summary/faults-mac.json.

سطری که باید به خاطر سپرد، گیر کردن استعلام سفارش در مدل Qwen3 4B است. متن پیام ابزار این بود: read_order timed out. Tell the customer and do not guess. اما مدل به مشتری پاسخ داد: I couldn't find your order. Please check the order ID and try again. این پاسخ نادرست است و مشتری را می‌فرستد تا شناسه‌ی سفارشی را اصلاح کند که از اول درست بوده است. هیچ میان‌افزاری نمی‌تواند جلوی این رفتار را بگیرد. حتماً در ارزیابی‌هایتان واکنش مدل به timeout را بررسی کنید و مدلی را انتخاب کنید که از این آزمون سربلند بیرون بیاید.

مدل پشتیبان

میان‌افزار ModelFallbackMiddleware هرگاه در فراخوانی خطایی رخ دهد، به سراغ مدل بعدی می‌رود. ما در آزمایش‌هایمان قطعی مدل اصلی را روی مک سنجیدیم: هر درخواست مدل اصلی خطای ConnectionError داد و یک اسپن خطا بر جا گذاشت، و در ادامه مدل پشتیبان فراخوانی را انجام داد. مدل پشتیبان در هر نوبت گفت‌وگو (Turn) به ازای هر درخواست مدل اجرا شد؛ بنابراین مدل اصلی دو بار امتحان شد و هر دو بار هم شکست خورد. هیچ بخشی از سیستم در حافظه‌اش نگه نمی‌دارد که مدل اصلی قطع است؛ برای اینکه درخواست‌ها مدتی به سرویس‌دهنده‌ی قطع‌شده ارسال نشوند، مدارشکن (Circuit Breaker) کدی است که خودتان باید اضافه کنید.

انتخاب مدل پشتیبان از یک ارائه‌دهنده‌ی دیگر هم گزینه‌ی پیش روی شماست. در اجراهای مربوط به Claude Haiku 5.5، مدل پشتیبان Qwen3 4B روی مک بود.

در همان اجرای مدل Haiku، خطایی پیش آمد که ما شبیه‌سازی نکرده بودیم: هنگام بارگذاری مدل پشتیبان، یکی از تلاش‌های read_order حدود 0.70 ثانیه زمان برد و به سقف 0.5 ثانیه‌ای تست‌ها برخورد کرد. تلاش بعدی در عرض 0.06 ثانیه به پایان رسید و وضعیت سفارش به دست مشتری رسید. بنابراین تلاش مجدد روی ابزارهای بی‌اثر در تکرار، کندی‌های مقطعی و معمولی سیستم را هم مدیریت کرد.

حلقه‌ای که تمام نمی‌شود

میان‌افزار ModelCallLimitMiddleware با تنظیمات run_limit=8 و exit_behavior="end"، جلوی اجراهای بی‌پایان را بعد از هشتمین فراخوانی مدل در تمام مدل‌ها گرفت. اجرا با وضعیت done و ارائه‌ی پیام نهایی مدل هوش مصنوعی بسته شد؛ در نتیجه کلاینت پایانی عادی را دید. این محدودیت، تعداد فراخوانی‌های مدل را در یک اجرا می‌شمارد؛ بنابراین مقدار آن را بر اساس طولانی‌ترین وظیفه‌ی (Task) واقعی در ارزیابی‌های خود تعیین کنید.

خاموش‌سازی

سرور Uvicorn پس از دریافت سیگنال SIGTERM، حداکثر تا سقف --timeout-graceful-shutdown منتظر اتصالات باز می‌ماند. سپس دوره‌ی حیات (lifespan) برنامه‌ی FastAPI به پایان می‌رسد، سرویس برای هر وظیفه‌ی در حال اجرا حداکثر تا DRAIN_SECONDS صبوری می‌کند و باقی‌مانده را لغو می‌کند. اجرای لغوشده، چک‌پوینت‌هایی (Checkpoint) را که پیش‌تر توسط durability="sync" ذخیره شده‌اند، نگه می‌دارد.

ما هر دو حالت را با مدل Qwen3 14B روی مک با پنج بار تکرار سنجیدیم. در هر بار، یک پرسش متداول مطرح شد، حین اجرا سیگنال SIGTERM به ورکر ارسال شد و ادامه‌ی ترد (thread) از ورکر جدیدی خوانده شد.

حالت تنظیمات کلاینت وضعیت ترد پس از راه‌اندازی مجدد
تکمیل (finish) ارسال SIGTERM در ثانیه‌ی 0.3، مهلت Uvicorn برابر 20 ثانیه، زمان تخلیه (drain) برابر 20 ثانیه اعلام وضعیت done در 8.28 تا 9.16 ثانیه در 4 آزمون از 5 آزمون در هر 5 آزمون پاسخ داده شد
لغو (cancel) ارسال SIGTERM در ثانیه‌ی 0.3، مهلت Uvicorn برابر 1 ثانیه، زمان تخلیه 0.05 ثانیه بسته‌شدن استریم با خطا در هر 5 آزمون فیلد next برابر با ["model"] و تنها حاوی پیام کاربر، در هر 5 آزمون

در اولین آزمونِ سناریوی تکمیل، نخستین فراخوانی مدل 14.96 ثانیه زمان برد؛ چون Qwen3 14B بعد از اجرای آزمون‌های نسخه‌ی 4B بارگذاری می‌شد. در ثانیه‌ی 20، سرور Uvicorn پیام Cancel 1 running task(s), timeout graceful shutdown exceeded را لاگ زد و استریم را بست. با این حال، وظیفه‌ی در حال اجرا ادامه پیدا کرد و در بازه‌ی تخلیه در ثانیه‌ی 21.58 کارش تمام شد. ترد به پاسخ خود رسید، اما کلاینت هرگز پیام done را ندید. این مجموعه‌ی آزمایشی با تعیین محدودیت زمانی 10 ثانیه‌ای، همین اتفاق را دو بار دیگر هم نشان داد.

در این آزمون‌ها بار پردازشی بالایی روی مک وجود داشت (میانگین بار 15.6 تا 28.7)؛ بنابراین زمان‌ها را به چشم حد بالا (Upper Bound) ببینید. یافته‌ی اصلی در شمارش تعداد رخدادهاست.

پس از هر بار لغو، یک ورکر جدید با فراخوانی /approve و بدون تصمیم جدید، کار روی ترد را از سر گرفت. اجرا در 7.27 تا 9.10 ثانیه به پایان رسید و در هر 5 آزمون، پاسخ از میان پرسش‌های متداول داده شد.

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

منابع: capture/lab/prodapp-mac/code/app/agent.py، capture/lab/prodapp-mac/code/app/middleware.py، capture/lab/prodapp-mac/code/app/tools.py، capture/lab/prodapp-mac/code/app/server.py، capture/lab/prodapp-mac/code/tests/conftest.py، capture/lab/prodapp-mac/code/tests/test_evals.py، capture/lab/prodapp-mac/code/scripts/drain_real.py، capture/lab/prodapp-mac/summary/faults-mac.json، capture/lab/prodapp-mac/summary/drain-mac.json، capture/lab/prodapp-mac/runs/drain/drain-trials.json، capture/lab/prodapp-mac/runs/drain/finish-01.server.log، capture/lab/prodapp-mac/runs/drain/finish-01.log.jsonl، capture/lab/prodapp-mac/runs/suite/qwen3-4b/rep-1/cases/14-hung_tool_times_out.json؛ و پرونده‌های libs/langchain_v1/langchain/agents/middleware/tool_retry.py، model_fallback.py، model_call_limit.py و tool_error.py در langchain==1.5.0.