یک اسکریپت با مدل 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" را برمیگرداند:
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) خود را بررسی میکند:
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 بخوانید.
دو سناریوی اول بیصدا رخ میدهند؛ هیچ خطایی صادر نشده و خسارت فقط در تعداد دفعات تکرار پیداست:
== 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 تراکنش بر جای گذاشت: یکی برای هر شناسه فراخوانی. پیام ذخیرهشدهی هوش مصنوعی شناسههای فراخوانی خود را حفظ میکند، بنابراین کلید در زمان ازسرگیری با هر فراخوانی مطابقت داشت.
دو سناریوی بعدی رفتار اجرا را بدون صادر کردن هیچ خطایی تغییر میدهند:
== 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) را صرفاً بهشکل متن نوشت.
سه سناریوی آخر مربوط به خروج کند، ابزار از دست رفته و حلقهی بیپایان هستند:
== 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، بعد از سومین فراخوانی خودبهخود پایان یافت. تصویر هر نشانه را در کنار نتیجهاش پس از اعمال راهحل قرار میدهد.
آنچه مانور به بخشهای پیشین اضافه میکند
سه سناریو نتیجهی اندازهگیریشدهی بخشهای قبل را در مقیاسی کوچکتر تکرار میکنند. تعدادها را مقایسه کنید نه ثانیهها را، چون حجم اجراها و سیستمها تفاوت دارند.
| مورد | نتیجه قبلی | نتیجه در مانور |
|---|---|---|
| لایههای تلاش مجدد | 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.