بخش 8.7 · بهره‌برداری و نگهداری

مانور خرابی‌ها

A failure drill

فهرست مطالب
  1. مانور دقیقاً چه کار می‌کند
  2. خروجی اجرای ضبط‌شده
  3. آن‌چه مانور به بخش‌های پیشین اضافه می‌کند
  4. محدودیت‌های مانور

یک اسکریپت با مدل Qwen3 4B روی Ollama محلی، هفت خرابی مختلف را ایجاد می‌کند و نشانه، وضعیت، راه‌حل و مدت‌زمان هر کدام را در حدود 100 ثانیه نمایش می‌دهد.

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

وقتی این بخش را تمام کنید، می‌توانید هفت خرابی مستندشده را روی سیستم خود اجرا کنید. همچنین می‌توانید نشانه‌های هر کدام را بخوانید و راه‌حل رفع آن را پیاده کنید.

مانور دقیقاً چه کار می‌کند

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

مدل Qwen3 4B روی Ollama نقش مدل را بازی می‌کند. یک رله جلوی Ollama قرار دارد که تمام اتصالات مربوط به حالت تلاش مجدد (retry) را قطع می‌کند. هیچ درخواستی از سیستم خارج نمی‌شود. دو مورد از سناریوها فرایندهای فرعی (child processes) اجرا می‌کنند؛ یکی برای بستن اجباری با kill و دیگری برای زیر نظر گرفتن رفتار برنامه هنگام خروج (exit).

cd capture/demos/failure-drill
./run.sh

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

مورد خرابی بخش
1 انباشته شدن لایه‌های تلاش مجدد روی یک فراخوانی مدل 4.7
2 کرش بین یک اثر جانبی و ثبت چک‌پوینت آن 5.3
3 دور زدن تأییدیه با میدل‌وری که مستقیماً به ابزارها می‌پرد 6.5
4 اجرایی که بدون پاسخی ساختاریافته به پایان می‌رسد 4.2
5 از دسترس خارج شدن اندپوینت ردگیری محاسبات (tracing endpoint) 7.6
6 دو ابزار با نام یکسان 3.4
7 مدلی که تا ابد یک ابزار را فراخوانی می‌کند 6.8

هر سناریو یک تابع کوتاه است. کد زیر میدل‌ور سناریوی 3 را نشان می‌دهد که پس از هر پیام مدل حاوی فراخوانی ابزار، مقدار jump_to="tools" را برمی‌گرداند:

میان‌افزاری که بازبینی را دور می‌زند capture/demos/failure-drill/drill.py
class JumpToTools(AgentMiddleware):
    @hook_config(can_jump_to=["tools"])
    def after_model(self, state, runtime):
        if getattr(state["messages"][-1], "tool_calls", None):
            return {"jump_to": "tools"}
        return None

سناریوی 2 این ابزار را در یک فرایند فرعی روی SqliteSaver اجرا می‌کند. در فرایند اول، تراکنش مالی ثبت می‌شود، فایل با دیسک همگام (sync) می‌شود و فرایند خودش را می‌کشد. فرایند دوم اجرای رشته‌ی گفت‌وگو (thread) را با invoke(None) از سر می‌گیرد. وقتی حالت keyed فعال باشد، ابزار ابتدا شناسه فراخوانی ابزار (tool_call_id) خود را بررسی می‌کند:

ابزار شارژ در حالت 2 capture/demos/failure-drill/drill.py
    def charge_card(amount: int, runtime: ToolRuntime) -> str:
        """Charge the card of the customer."""
        key = runtime.tool_call_id
        lines = Path(sink).read_text().splitlines() if Path(sink).exists() else []
        if keyed and any(line.startswith(f"{key}\t") for line in lines):
            return f"already charged under key {key}"
        with open(sink, "a") as handle:
            handle.write(f"{key}\t{amount}\t{phase}\n")
            handle.flush()
            os.fsync(handle.fileno())
        if phase == "start":
            os.kill(os.getpid(), signal.SIGKILL)
        return f"charged {amount}"

خروجی اجرای ضبط‌شده

ما نتایج را در سه بار اجرا روی ماشین مهمان سرور x86 اندازه‌گیری کردیم (n=3 برای هر سناریو). هر بار اجرا بین 101 تا 103 ثانیه طول کشید که بیشتر آن صرف فراخوانی‌های مدل روی CPU شد. سناریوی ردگیری محاسبات طولانی‌ترین زمان را برد (حدود 27 ثانیه)، چون منتظر خروج ماند.

خروجی این مانور شماره بخش‌ها را بر اساس ساختار قبلی این راهنما چاپ می‌کند. بخش‌های 3.5، 4.3، 5.5، 3.2، 6.4، 2.4 و 5.8 در خروجی را به‌ترتیب همان بخش‌های 4.7، 5.3، 6.5، 4.2، 7.6، 3.4 و 6.8 بخوانید.

دو سناریوی اول بی‌صدا رخ می‌دهند؛ هیچ خطایی صادر نشده و خسارت فقط در تعداد دفعات تکرار پیداست:

لایه‌های تلاش مجدد و کرش پس از اثر جانبی capture/lab/failure-drill-x86/drill-run1.log
== 1 retry layers stack on one model call (section 3.5)
  symptom   one model call sent 9 requests to a relay in front of Ollama that drops every connection, in 6.8 s
  state     the run ended without an exception, last AIMessage: Model call failed after 3 attempts with OpenAIConnectionError: Connection error.
  fix       ChatOpenAI(max_retries=0), so ModelRetryMiddleware is the only retry layer
  after     3 requests in 2.3 s
  time      9.59 s

== 2 a crash between a side effect and its checkpoint (section 4.3)
  symptom   the first process exited with -9 inside charge_card, the resume ran charge_card again: 4 charges
  state     after the resume: next [], 5 messages, charges ['start', 'start', 'resume', 'resume'], last 'Charged'
  fix       check runtime.tool_call_id against the charges before the charge, with durability sync
  after     exit -9, then the resume: 2 charge, next [], last 'Charged'
  time      14.32 s

اولین اجرا از سه اجرا.

در سناریوی 1، کلاس ChatOpenAI درون هر یک از 3 تلاش ModelRetryMiddleware، تعداد 3 تلاش انجام داد. سپس اجرا با خطایی که در قالب متن یک AIMessage قرار گرفته بود به پایان رسید؛ بنابراین فراخوانی‌کننده‌ای که فقط آخرین پیام را می‌خواند، پاسخی عادی می‌بیند. در سناریوی 2، کد خروج 9- همان سیگنال SIGKILL است. مدل در یک پاسخ درخواست دو تراکنش مالی را داده بود و کلید نمی‌تواند جلوی فراخوانی دوم را بگیرد. پیش از کسر هزینه، سفارش را بررسی کنید.

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

دو سناریوی بعدی رفتار اجرا را بدون صادر کردن هیچ خطایی تغییر می‌دهند:

تأییدیهٔ ردشده و پاسخ ساختاریافتهٔ گم‌شده capture/lab/failure-drill-x86/drill-run1.log
== 3 an approval skipped by a middleware that jumps to tools (section 5.5)
  symptom   send_email ran 1 time before any decision, with 0 interrupts, to ['all-staff@example.org']
  state     batched mode, middleware=[HumanInTheLoopMiddleware, JumpToTools], next []
  fix       interrupt_mode="per_call", which pauses inside the tool call
  after     send_email ran 0 times, 1 interrupt waits, next ['tools']
  time      7.06 s

== 4 a run that ends with no structured response (section 3.2)
  symptom   3 of 5 prompts ended with no exception and structured_response None: ['Hello! How are you today?', 'Tell me a one-line joke.', 'What is the total of an empty order?']
  state     bound tools ['add', 'Answer']; last messages of the None runs: …
  fix       check structured_response for None after each run, and treat None as a failure
  after     the check raised on 3 of 5 runs
  time      15.56 s

اولین اجرا از سه اجرا. آخرین پیام‌های سه اجرای None در محل علامت بریده شده‌اند.

در سناریوی 4، دو پرامپت محاسباتی پاسخی ساختاریافته دادند. اما سه پرامپت دیگر در هر 3 بار اجرا، با متنی ساده و بدون هیچ خطایی تمام شدند. در سفارش خالی، مدل به‌جای فراخوانی ابزار Answer، عبارت Answer(total=0) را صرفاً به‌شکل متن نوشت.

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

اندپوینت غیرفعال ردگیری، نام ابزار تکراری، و حد بازگشت capture/lab/failure-drill-x86/drill-run1.log
== 5 a tracing endpoint that is down (section 6.4)
  symptom   the agent run took 4436.9 ms, and the process exited 16.9 s after it (22.0 s in all)
  state     LANGSMITH_TRACING=true, nothing listens on the endpoint port, 3 lines of upload errors on stderr
  fix       probe GET /info with a 1 s timeout at start, and run inside tracing_context(enabled=False) when it fails
  after     tracing False, exit 0.3 s after the run (5.0 s in all), 0 lines of upload errors
  time      26.97 s

== 6 two tools with the same name (section 2.4)
  symptom   create_agent raised nothing, the model saw 1 tool named ['lookup']
  state     the call to lookup ran: ['from the refunds table']; final answer "I'm sorry, but I couldn't find any information about order 7 in the refunds tabl"
  fix       check that tool names are unique before create_agent
  after     the check found duplicate names ['lookup']
  time      5.92 s

== 7 a model that calls a tool forever (section 5.8)
  symptom   GraphRecursionError: Recursion limit of 10 reached without hitting a stop condition. …
  state     the model was called 5 times before the limit
  fix       ModelCallLimitMiddleware(run_limit=3, exit_behavior="end"), first with the same recursion_limit of 10
  after     recursion_limit 10: 3 model calls, GraphRecursionError: Recursion limit of 10 reached without hi …
  after     recursion_limit 25: 3 model calls, no exception, last message 'Model call limits exceeded: run limit (3/3)'
  time      23.61 s

اولین اجرا از سه اجرا. بقیه پیام GraphRecursionError در محل علامت بریده شده است.

سناریوی 6 خرابی‌ای را نشان می‌دهد که در بخش‌های قبلی نیامده است. نود ابزار در create_agent ابزارهای خود را در یک دیکشنری بر اساس نام نگه می‌دارد؛ در نتیجه تابع دوم lookup جایگزین تابع اول شد {{code libs/prebuilt/langgraph/prebuilt/tool_node.py}}. مدل فقط یک ابزار را دید، ایجنت هیچ خطایی صادر نکرد و همه‌ی فراخوانی‌ها به تابع بازپرداخت‌ها (refunds) هدایت شدند. بنابراین پاسخ گفت که هیچ اطلاعاتی درباره‌ی سفارش 7 در جدول بازپرداخت‌ها پیدا نکرده است. همان‌طور که بخش 4.5 نشان می‌دهد، دو نمونه از یک میدل‌ور خطای AssertionError می‌دهند؛ اما دو ابزار با یک نام هیچ خطایی صادر نمی‌کنند.

سناریوی 7 راه‌حلی را نشان می‌دهد که خودش به تغییر دوم نیاز دارد. میدل‌ور ModelCallLimitMiddleware نود اختصاصی خود را به هر حلقه‌ی ایجنت اضافه می‌کند؛ به همین دلیل سه فراخوانی مدل به بیش از 10 گام نیاز داشتند. با recursion_limit برابر 10، اجرا همچنان خطا صادر کرد. با مقدار 25، بعد از سومین فراخوانی خودبه‌خود پایان یافت. تصویر هر نشانه را در کنار نتیجه‌اش پس از اعمال راه‌حل قرار می‌دهد.

هفت شکست در تمرین ارزیابی، قبل و بعد از هر اصلاحشش مورد از هفت شکست هیچ خطایی ایجاد نکردند، و هر اصلاح در ستون سمت راست برگرفته از بخشی است که آن شکست را مستند می‌کند.
هفت شکست در تمرین، قبل و بعد از هر اصلاح جدولی با هفت ردیف، هر ردیف مربوط به یک حالت از تمرین سناریوهای شکست با Qwen3 4B روی ماشین مهمان سرور x86، همراه با نشانه در سمت چپ و نتیجه پس از اصلاح در سمت راست. لایه‌های تلاش مجدد: 9 درخواست در برابر 3 درخواست. کرش پس از شارژ: 4 بار شارژ در برابر 2 بار با کلید، زیرا مدل دو بار درخواست شارژ داده بود. میان‌افزاری که بازبینی را دور می‌زند: ابزار قبل از هر تصمیمی اجرا شد و حالت مبتنی بر فراخوانی جلوی آن را گرفت. عدم وجود خروجی ساختاریافته: دریافت None بدون هیچ استثنایی در 3 مورد از 5 پرامپت، و بررسی‌ای که خطا صادر می‌کند. اندپوینت ردگیری که قطع است: خروج پس از 16.9 ثانیه در برابر 0.3 ثانیه. نام ابزار تکراری: متصل شدن یک ابزار بدون خطا. فراخوانی‌های بی‌پایان ابزار: خطای GraphRecursionError در حد 10، و اعمال سقف 3 فراخوانی مدل که اجرا را بعد از 3 بار متوقف می‌کند، همراه با افزایش حد بازگشت به 25. علامت و نشانه پس از اصلاح لایه‌های تلاش مجدد 9 درخواست، 6.83 ثانیه همهٔ اتصال‌ها قطع شدند 3 درخواست، 2.32 ثانیه max_retries=0 on the model کرش پس از شارژ 4 بار شارژ SIGKILL، سپس ازسرگیری 2 بار با کلید یک بار به ازای هر call id مدل دور زدن بازبینی 1 بار اجرا، بدون تصمیم حالت دسته‌ای 0 بار اجرا، 1 وقفه interrupt_mode per_call بدون خروجی ساختاریافته None در 3 از 5 پرامپت ToolStrategy و یک ابزار بررسی شما خطا می‌دهد بررسی برای None اندپوینت ردگیری قطع است خروج 16.9 ثانیه پس از اجرا یک اجرا، بدون شنونده خروج 0.3 ثانیه پس از اجرا آزمون ارزیابی، سپس قطع ردگیری دو ابزار با نام یکسان 1 ابزار متصل، بدون خطا تابع refunds اجرا شد مورد تکراری پیدا شد ابتدا نام‌ها چک شوند فراخوانی بی‌پایان ابزار خطا در 5 فراخوانی مدل recursion_limit 10 پایان در 3 فراخوانی حد فراخوانی 3، بازگشت 25 اولین اجرا از سه اجرای drill.py با Qwen3 4B روی Ollama، روی ماشین مهمان سرور x86.
هر ردیف را از نشانه در سمت چپ تا نتیجه پس از اصلاح در سمت راست بخوانید. خانه‌های صورتی نشان‌دهنده شکست و خانه‌های سبزآبی نتیجه به همراه اصلاح هستند. از capture/lab/summary/failure-drill-x86.json.

آن‌چه مانور به بخش‌های پیشین اضافه می‌کند

سه سناریو نتیجه‌ی اندازه‌گیری‌شده‌ی بخش‌های قبل را در مقیاسی کوچک‌تر تکرار می‌کنند. تعدادها را مقایسه کنید نه ثانیه‌ها را، چون حجم اجراها و سیستم‌ها تفاوت دارند.

مورد نتیجه قبلی نتیجه در مانور
لایه‌های تلاش مجدد 9 درخواست به مدل برای اتصال قطع‌شده در هر فراخوانی، 3 بار اجرا، بخش 3.2 9 درخواست، 3 بار اجرا
کرش پس از اعمال اثر جانبی اثر جانبی در 80 مورد از 150 آزمون گراف دو بار اجرا شد، بخش 5.3 3 یا 4 تراکنش بدون کلید، 2 تراکنش با کلید، 3 آزمون
قطعی اندپوینت ردگیری محاسبات خروج به مدت 9.9 ثانیه پس از 50 بار اجرا معطل ماند، بخش 7.6 خروج به مدت 16.9 تا 17.3 ثانیه پس از 1 بار اجرا معطل ماند

اعداد ردگیری محاسبات از فرایندهایی با اندازه‌های متفاوت می‌آیند (350 اجرای ردگیری‌شده در برابر 7 اجرا)؛ پس مدت‌زمان آن‌ها را با هم مقایسه نکنید. هر دو نشانه‌ی یکسانی دارند: فرایندی با ردگیری فعال در زمان خروج، معطل اندپوینتی می‌ماند که جواب نمی‌دهد. آزمون ارزیابی (probe) در سناریوی 5 راه‌حل اختصاصی خود ماست. بخش 7.6 دو راه‌حل دیگر ارائه می‌دهد: wait_for_all_tracers() را در نقطه‌ای دلخواه فراخوانی کنید، و روی تسک یک سقف زمانی (timeout) بگذارید.

محدودیت‌های مانور

  • پیام ذخیره‌شده‌ی هوش مصنوعی شناسه‌های فراخوانی‌اش را نگه می‌دارد، بنابراین کلید در زمان ازسرگیری مطابقت پیدا می‌کند. اما یک مدل واقعی همچنان ممکن است در یک پاسخ، دو بار تقاضای همان تراکنش را بکند.
  • سناریوی تلاش مجدد از ChatOpenAI روی رله‌ای استفاده می‌کند که اتصالات را قطع می‌کند. پکیج‌های ارائه‌دهندگان دیگر، تلاش‌های مجدد کلاینت خاص خود را دارند. پکیج ChatOllama فقط 1 تلاش انجام می‌دهد.
  • مانور فقط خرابی‌هایی را پوشش می‌دهد که تنها به Ollama نیاز دارند. خرابی‌های MCP، Postgres و Agent Server در بخش‌های 7 و 8 نیازمند سرویس‌های خودشان هستند. بخش 9 خرابی‌های Postgres را در قالب یک سرویس اجرا می‌کند: کرش پس از بازپرداخت، سیگنال SIGTERM و یک ابزار معلق.
  • سه بار اجرا نشان می‌دهد که سناریوها تکرارپذیرند، نه این‌که روی مدل‌های دیگر با چه تواتری رخ می‌دهند.

منابع: capture/demos/failure-drill/drill.py، capture/demos/failure-drill/real.py، capture/demos/failure-drill/run.sh، capture/demos/failure-drill/README.md؛ capture/lab/failure-drill-x86/drill-run1.log، capture/lab/failure-drill-x86/drill-run1.jsonl، capture/lab/failure-drill-x86/drill-run2.jsonl، capture/lab/failure-drill-x86/drill-run3.jsonl، capture/lab/summary/failure-drill-x86.json، capture/lab/summary/retries-x86.json، capture/lab/summary/crash-resume-mac.json، capture/lab/summary/tracing-mac-real.json؛ libs/prebuilt/langgraph/prebuilt/tool_node.py در langgraph 1.2.22؛ libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0.

ترجمه‌ی فارسی A failure drill از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما