هیچ حالت پایاییای از وظیفهای که خروجیاش تازه برگشته محافظت نمیکند، و مدل هم ممکن است یک تراکنش مالی را دو بار بخواهد؛ پس برای هر اثر جانبی یک کلید بگذارید و اول سوابق خود را بررسی کنید.
ایجنت شما در یک ابزار کارتی را شارژ میکند و فرایند، لحظهای بعد کرش میکند و از بین میرود. دوباره آن را اجرا میکنید و رشته (thread) را از سر میگیرید. شما با durability="sync" اجرا کرده بودید، چون مستندات آن را پایاترین حالت معرفی کرده است. با این حال، دفتر کل مالی همچنان دو تراکنش برای آن سفارش ثبت کرده است.
پس از پایان این بخش، میتوانید بگویید هر حالت پایایی چه چیزهایی را ذخیره میکند و منتظر چه میماند. میتوانید پیشبینی کنید که ادامهی اجرا پس از یک کرش چه مواردی را دوباره اجرا میکند، و کاری کنید که اثر جانبی فقط یک بار اجرا شود.
سه حالت پایایی
حالت پایایی (Durability mode): آرگومان durability در invoke و stream که مشخص میکند چکپوینتهای یک اجرا چه زمانی نوشته شوند: sync، async، یا exit.
صفحهی چکپوینترها این حالتها را از کمترین تا بیشترین پایایی مرتب کرده است {{docs oss/python/langgraph/checkpointers}}. کد برنامهنویسی برای sync فقط و فقط یک انتظارِ اضافی در نظر میگیرد. بخش 2.3 تمام فراخوانیهای ذخیرهساز (saver) یک اجرا را ردگیری میکند. حلقه در تمام حالتها، خروجی هر وظیفهی پایانیافته را با put_writes در پسزمینه ذخیره میکند. حالت sync سپس در انتهای هر گام، قبل از اینکه برای گام بعدی برنامهریزی کند، منتظر put چکپوینت میماند.
| حالت | مواردی که حلقه حین اجرا ذخیره میکند | مواردی که منتظرشان میماند | مواردی که کرش در اجراهای ما تکرار کرد |
|---|---|---|---|
exit |
هیچچیز؛ تا زمانی که اجرا تمام شود، شکست بخورد، یا روی وقفه متوقف شود | هیچچیز | کل اجرا، از همان ورودی اولیه |
async |
هر چکپوینت و دادههای نوشتهشدهی هر وظیفه، در پسزمینه | هیچچیز | وظیفهای که تازه خروجی داده بود، و گامی پس از آخرین چکپوینت ذخیرهشده |
sync |
همانند async |
متد put هر چکپوینت، قبل از گام بعدی |
وظیفهای که تازه خروجی داده بود |
حالت پیشفرض در کد برنامه async است {{code libs/langgraph/langgraph/pregel/main.py}}. صفحهی چکپوینترها مشخص نکرده که کدام حالت پیشفرض است، اما صفحات Agent Server حالت async را ذکر کردهاند {{docs langsmith/agent-server}}. این راهنما این شکاف را با عنوان تعارض D119 ثبت میکند.
کیت آزمایشی ما یک گراف با دو گره را روی InMemorySaver در هر حالت اجرا و چکپوینتها را شمارش میکند:
durability=sync: result {'n': 2}, 4 checkpoints, steps [2, 1, 0, -1]
durability=async: result {'n': 2}, 4 checkpoints, steps [2, 1, 0, -1]
durability=exit: result {'n': 2}, 1 checkpoints, steps [2]حالت exit فقط آخرین چکپوینت را ذخیره میکند؛ بنابراین رشتهای که در حالت exit اجرا شده باشد، هیچ تاریخچهای برای بازگشت به عقب ندارد.
حالت sync بدون چکپوینتر
بدون چکپوینتر، تمام حالتها هشدار میدهند که هیچ اثری ندارند. سپس async و exit اجرا میشوند. اما sync، چه در invoke و چه در stream خطا ایجاد میکند:
durability=sync invoke: raised AttributeError: 'SyncPregelLoop' object has no attribute '_put_checkpoint_fut'
warning: `durability` has no effect when no checkpointer is present.حلقه منتظر نوشتن چکپوینتی میماند که هرگز آغاز نکرده است {{code libs/langgraph/langgraph/pregel/main.py}}. این مورد ایشوی #9267 است که در نسخهی پینشده باز است و این راهنما آن را با عنوان تعارض D6 ثبت میکند. آرگومان durability="sync" را تنها به گرافی پاس بدهید که چکپوینتر دارد. آرگومان قدیمی checkpoint_during هنوز کار میکند، ولی هشدار LangGraphDeprecatedSinceV10 میدهد.
وظیفهای که خروجیاش تازه برگشته است
اثر جانبی (Side effect): تغییری که یک گره یا ابزار در خارج از وضعیت گراف ایجاد میکند، مثل تراکنش مالی یا ارسال ایمیل. چکپوینت نمیتواند آن را به حالت قبل بازگرداند.
بخش محیط اجرا همان سناریویی را اجرا کرد که sync برای پوشش آن طراحی شده است. سه گره به صورت موازی روی SqliteSaver اجرا میشوند. گره a از Qwen3 4B میخواهد نام یک میوه را بگوید، و b یک ابزار هواشناسی را فراخوانی میکند. گره c صبر میکند تا هر دو نتیجه را برگردانند، سپس به مدت مشخصی منتظر میماند و از فرایند خارج میشود. یک فرایند جدید رشته را با invoke(None) از سر میگیرد.
ما این مورد را اندازه گرفتیم؛ روی سیستم مهمان سرور x86، با 50 آزمایش در هر خانه، در دو دور اجرا. بازهها، بازههای اطمینان 95 درصدی ویلسون هستند:
| حالت | انتظار قبل از کرش | تکرار اجرای a، دور 1 و دور 2 |
مجموع |
|---|---|---|---|
sync |
0 ثانیه | 49 از 50، 48 از 50 | 97 از 100، 0.915 تا 0.990 |
async |
0 ثانیه | 45 از 50، 50 از 50 | 95 از 100، 0.888 تا 0.978 |
sync و async |
0.2 ثانیه | 0 از 50 در هر دور | 0 از 200 |
exit |
0 ثانیه و 0.2 ثانیه | بدون چکپوینت، 100 از 100 |
بازهها همپوشانی دارند، پس در اینجا sync هیچ محافظت اضافهتری نسبت به async ایجاد نکرد. گره a چند میلیثانیه قبل از کرش خروجی داد و فراخوانی put_writes آن هنوز تمام نشده بود. هر دو حالت فقط در انتهای گام منتظر میمانند، در حالی که کرش زودتر رخ داد. پس از 0.2 ثانیه انتظار، نوشتنها در تمام آزمایشها ذخیره شدند. تمام آزمایشهای exit هیچ چکپوینتی باقی نگذاشتند و invoke(None) خطای EmptyInputError داد.
کرش در پنج نقطهی مختلف از یک ایجنت
ایجنت آزمایشگاهی ما از نوع create_agent با مدل Qwen3 4B روی Ollama و یک ابزار به نام charge(order_id, amount_usd) است. این ابزار با ویژگی autocommit یک سطر در جدول دفتر کل PostgreSQL درج میکند. یک برنامهی راهانداز، ایجنت را در فرایندی جدید اجرا کرد و در یکی از پنج نقطه آن را با سیگنال SIGKILL متوقف کرد. فرایند جدید دیگری سپس اجرای رشته را با invoke(None) ادامه داد، یا اگر چکپوینتی وجود نداشت، ورودی را از اول اجرا کرد. تصویر این پنج نقطه را در یک گام نشان میدهد.
before_tool: ابزار شروع به کار کرده و هنوز تراکنش مالی انجام نشده است.inside_tool: تراکنش مالی commit شده، اما ابزار هنوز خروجی را برنگردانده است.before_put_writes: ابزار خروجی را برگردانده، اما دادههای نوشتهشدهی آن هنوز ذخیره نشدهاند.before_put: دادههای نوشتهشده به ذخیرهساز تحویل داده شدهاند، اما چکپوینتِ گام هنوز ذخیره نشده است.after_tool: فراخوانی بعدی مدل در آستانهی شروع است.
ما این مورد را اندازه گرفتیم؛ روی سیستم مهمان سرور x86، با SqliteSaver و با PostgresSaver روی PostgreSQL 16.15. هر خانهی ترکیبی از حالت، ذخیرهساز و نقطهی توقف، 20 بار بدون کلید آزمایش شد. از میان 560 آزمایش متوقفشده، 331 بار سفارش را دو بار شارژ کردند. وضعیت نهایی در تمام آنها درست بود. آمار به تفکیک حالت، برای هر دو ذخیرهساز در مجموع:
| نقطهی توقف | sync |
async |
exit |
|---|---|---|---|
before_tool |
0 از 40 | 0 از 40 | 0 از 40 |
inside_tool |
40 از 40 | 40 از 40 | 40 از 40 |
before_put_writes |
24 از 40 | 38 از 40 | هرگز نرسید، 10 آزمایش |
before_put |
20 از 40 | 11 از 40 | 40 از 40 |
after_tool |
0 از 40 | 38 از 40 | 40 از 40 |
جدول را بر اساس نقطهی توقف بخوانید:
- در نقطهی
inside_toolعملیات شارژ در تمام 120 آزمایش تکرار شد. هیچ نتیجهای از ابزار ذخیره نشده بود، بنابراین ادامهی اجرا آن را دوباره اجرا کرد. هیچ حالت پایاییای این وضعیت را تغییر نمیدهد. - نقطهی
before_put_writesهمان وظیفهای است که تازه خروجی داده است. حالتsyncآن را در 24 آزمایش از 40 آزمایش تکرار کرد؛ روی SQLite به میزان 8 از 20 و روی Postgres به میزان 16 از 20. حالتasyncدر 38 مورد از 40 مورد آن را تکرار کرد. - در نقطهی
before_putتحت حالتsync، اجرای مجدد روی هر دو ذخیرهساز رخ داد: 12 از 20 روی SQLite و 8 از 20 روی Postgres. فراخوانیput_writesابزار در پسزمینه اجرا میشود و ممکن است هنگام شروعputهنوز در حال اجرا باشد (بخش 2.3). - نقطهی
after_toolجایی است کهsyncبه کار میآید: 0 از 40 در برابر 38 از 40 تحتasync. چکپوینتِ گام مربوط به ابزار، قبل از شروع گام بعدی ذخیره شده بود. - حالت
exitحین اجرا هیچ نوشتن معوقهای ثبت نمیکند، بنابراین نقطهی توقفbefore_put_writesاصلاً پیش نیامد. هر توقف دیگری بعد از عملیات شارژ، هیچ چکپوینتی باقی نگذاشت و اجرای مجدد، تراکنش مالی را دوباره انجام داد.
ایشوی #8039 گزارش میدهد که sync ترتیب اجرای put_writes و put را تثبیت نمیکند، بنابراین بازیابی روی میزبانهای مختلف رفتار متفاوتی دارد {{issue 8039}}. این مورد در نسخهی پینشده همچنان باز است. وعدهی مستندات برای حالت sync در مرز بین گامها برقرار است و خانههای after_tool ما آن را تأیید میکنند؛ اما هیچ تعهدی دربارهی کرش در میانهی یک گام وجود ندارد.
روی سیستم Mac نیز همین پنج نقطه روی گرافی بررسی شد که گره آن فقط یک خط به یک فایل اضافه میکرد، بدون هیچ مدلی. آن خط در 80 مورد از 150 آزمایش دو بار نوشته شد، با همان الگوی رفتاری بر اساس نقطهی توقف. آن سطرها کماکان معتبرند. سطرهای مربوط به ایجنت در آن ماتریس از یک مدل اسکریپتشده استفاده میکردند و سطرهای x86 بالا جایگزین آنها شدهاند.
ادامهی اجرا فراخوانیهای مدل را هم تکرار میکند. هر اجرا به دو فراخوانی نیاز دارد. تحت حالت sync، تمام آزمایشها در کل دقیقاً 2 فراخوانی مدل داشتند. تحت async، در 77 آزمایش از 450 مورد، 3 فراخوانی انجام شد؛ زیرا پس از توقف در before_tool، اولین فراخوانی مدل دوباره اجرا شد. در حالت exit، تعداد 270 از 390 آزمایش 3 بار، و 90 آزمایش 4 بار مدل را فراخوانی کردند.
فیلد next خالی است، اما اجرا هنوز تمام نشده است
بعد از یک کرش، وضعیت رشته را میخوانید و تصمیم میگیرید که آیا به ادامهی اجرا نیاز دارد یا خیر. یک بررسی طبیعی، فیلد get_state(config).next است: یک تاپل خالی یعنی اجرا به پایان رسیده است. در نسخهی پینشده، این بررسی پس از یک کرش نادرست است.
ما این مورد را اندازه گرفتیم؛ روی همان ماتریس ایجنت در سیستم مهمان سرور x86. پس از توقف فرایند، فیلد next در 217 آزمایش از 1,260 آزمایش متوقفشده برابر با () بود، در حالی که هیچکدام از آن اجراها به پایان نرسیده بودند. در هر یک از آنها، فراخوانی invoke(None, config) باقیماندهی اجرا را انجام داد و وضعیت نهایی درستی تحویل داد. 177 مورد از آنها در حالت async بودند. 40 مورد دیگر در حالت sync در نقطهی before_put رخ دادند. ماتریس گراف روی Mac، بدون مدل، این موضوع را در 31 آزمایش از 140 موردِ متوقفشده نشان داد.
تصمیمگیری را صرفاً بر پایهی next انجام ندهید. در پایگاه دادهی خودتان شروع و پایان هر اجرا را ثبت کنید، و هر رشتهای را که شروع شده ولی تمام نشده، ادامه دهید. رشتهای که هیچ چکپوینتی ندارد چیزی برای ادامهی اجرا ندارد؛ بنابراین ورودی اولیه را در همان پایگاه داده نگه دارید و اجرا را از ابتدا شروع کنید.
تاریخچهی وضعیت پس از توقف در نقطهی before_tool نیز بسته به حالت پایایی متفاوت است. در حالت sync در تمام 90 آزمایش 3 چکپوینت ثبت شد، و در حالت async در تمام 90 آزمایش 2 چکپوینت. در حالت exit هیچ چکپوینتی ثبت نشد، بنابراین راهانداز مجبور شد اجرا را دوباره از ورودی اولیه آغاز کند. صفحهی چکپوینترها هشدار میدهد که یک رشتهی بدون چکپوینت پایدار، درست مثل رشتهای است که هرگز اجرا نشده است {{docs oss/python/langgraph/checkpointers}}.
راهحل: کلید روی اثر جانبی، و بررسی سوابق
کلید یکتایی تراکنش (Idempotency key): مقداری که یک اثر جانبی خاص را نامگذاری میکند، تا آن عملیات بتواند بررسی کند که آیا قبلاً انجام شده است یا نه و از اجرای مجدد خود صرفنظر کند.
صفحهی تابآوری در برابر خطا میگوید این کلید باید قبل از اجرای اثر جانبی پایدار شده باشد {{docs oss/python/langgraph/fault-tolerance}}. ابزار آزمایشگاهی ما یکی از دو کلید را میسازد و آن را در همان دستور ثبت تراکنش مینویسد. یک ستون با قید یکتا (UNIQUE) روی این کلید، از درج سطر دوم جلوگیری میکند:
@tool
def charge(order_id: str, amount_usd: int, runtime: ToolRuntime) -> str:
"""Charge an order. Returns a receipt."""
signal("before_tool")
call_id = runtime.tool_call_id
if A.key == "call_id":
key = f"{A.thread}:{call_id}"
elif A.key == "order":
key = f"{A.thread}:{order_id}"
else:
key = None
…
conn.execute("insert into t02r_ledger(trial, phase, call_id, order_id, amount, t, idem_key) values (%s,%s,%s,%s,%s,%s,%s) on conflict (idem_key) do nothing",
(A.trial, A.phase, call_id, str(order_id), amount_usd, time.time(), key))دستور درج در جدول attempts و branch بدون کلید حذف شدهاند.
ما هر دو کلید را اندازه گرفتیم؛ روی همان ماتریس در سیستم مهمان سرور x86:
| کلید | آزمایشهای متوقفشده با شارژ دوباره | در چه حالتی |
|---|---|---|
| بدون کلید | 331 از 560 | در همهی حالتها، به جدول بالا نگاه کنید |
رشته و tool_call_id |
120 از 560 | تمام 120 مورد در exit؛ 0 از 400 در sync و async |
| رشته و شناسه سفارش | 0 از 140 | هیچکدام، 5 آزمایش به ازای هر خانه |
کلیدِ مبتنی بر tool_call_id تنها در حالت exit شکست خورد. چون هیچ چکپوینتی وجود نداشت، اجرای مجدد دوباره مدل را فراخوانی کرد و ChatOllama به فراخوانی جدید یک شناسهی جدید داد. یکی از توسعهدهندگان در ایشوی #9185 کلیدِ مبتنی بر tool_call_id را پیشنهاد میکند {{issue 9185}}. این راهکار زمانی درست کار میکند که پیام مدل حاوی این شناسه درون یک چکپوینت ثبت شده باشد؛ چیزی که sync و async در تمام آزمایشهای اینجا فراهم کردند. در گراف روی Mac بدون مدل، کلیدی بر پایهی رشته و نام گره، در 150 آزمایش 0 بار تکرار داشت.
برای یک گره در گراف، فضای نام وظیفه (task namespace) همین نقش را ایفا میکند. یک گره آن را به عنوان checkpoint_ns و در قالب <node>:<task id> میخواند:
rec["ns"] = get_config()["configurable"]["checkpoint_ns"]در اجراهای همراه با کرش در بخش محیط اجرا، هر گرهی که دوباره اجرا شد، در هر دو حالت sync و async همان فضای نام اجرای اول خود را داشت. کلیدی که بر پایهی آن ساخته میشد، جلوی تمام 98 تکرار گره a را میگرفت. در حالت exit، کرش چیزی برای ادامه دادن باقی نمیگذارد، بنابراین شناسهها در آنجا هم جدید خواهند بود.
مدلی که دو بار درخواست میدهد
یک کلید روی فراخوانی، جلوی اجرای مجدد فراخوانیای را میگیرد که در چکپوینت ذخیره شده است؛ اما نمیتواند جلوی فراخوانی دومی را بگیرد که خود مدل خواسته است. مانور خرابی در بخش 8.7 از Qwen3 4B میخواهد یک کارت را یک بار شارژ کند (روی SqliteSaver با durability="sync") و فرایند را داخل ابزار متوقف میکند:
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'ما این مورد را اندازه گرفتیم؛ سه بار روی سیستم مهمان سرور x86. مدل در پاسخ اول خود برای همان یک تراکنش، در 3 دور از 3 اجرا دو فراخوانی charge_card فرستاد. بدون کلید یکتایی، اجراها به ترتیب 4، 4، و 3 بار کارت را شارژ کردند. با کلیدِ tool_call_id، آنها دقیقاً 2، 2، و 2 بار شارژ کردند. کلید جلوی هر اجرای مجددِ فراخوانی ذخیرهشده را گرفت، اما اجازهی عبور فراخوانی دوم را داد.
در ماتریس ایجنت، در پرامپت سیستم قید شده بود که ابزار فقط یک بار فراخوانی شود. در آنجا مدل در 1,290 آزمایش از 1,290 مورد دقیقاً یک فراخوانی درخواست کرد. پرامپت این نرخ خطا را کاهش میدهد، اما اثر جانبی همچنان نیازمند بررسی است.
بنابراین اثر جانبی را بر پایهی معنا و مفهوم واقعی آن کلیدگذاری کنید. از شناسهی سفارش یا شناسهی رکورد کسبوکاری که عملیات آن را تغییر میدهد استفاده کنید، و شناسهی رشته را در کلید نیاورید. همان سفارش در یک رشتهی دیگر هم باید دقیقاً همان کلید را تولید کند. قبل از اجرای اثر جانبی، سوابق خود را برای آن کلید بررسی کنید و اگر وجود داشت، نتیجهی ذخیرهشده را برگردانید. هنگام کار با یک سرویس بیرونی، کلید را همراه درخواست بفرستید تا خود سرویس درخواست دوم با همان کلید را رد کند.
بررسی AsyncSqliteSaver، AsyncPostgresSaver تحت کرش، و Agent Server تحت کرش همانطور که در بخش 8.8 آمده است، در ویرایش بعدی ارائه میشوند.
منابع: capture/s_persist.py, capture/out/31-durability.txt; capture/lab/internals/03-checkpoint/crash.py, capture/lab/internals/03-checkpoint/crash.txt, capture/lab/internals/03-checkpoint/crash.json, capture/lab/internals/03-checkpoint/taskns.txt, capture/lab/internals/03-checkpoint/taskns.json; capture/lab/summary/crash-resume-x86.json, capture/lab/T02-crash-resume-x86/01-agent-matrix.jsonl, capture/lab/T02-crash-resume-x86/02-agent-matrix-rep5-19.jsonl, capture/lab/T02-crash-resume-x86/09-summary-table.txt, capture/lab/T02-crash-resume-x86/10-summary.txt, capture/lab/T02-crash-resume-x86/t02r_child.py, capture/lab/T02-crash-resume-x86/t02r_drive.py; capture/lab/summary/failure-drill-x86.json, capture/lab/failure-drill-x86/drill-run1.log, capture/lab/failure-drill-x86/drill-run2.log, capture/lab/failure-drill-x86/drill-run3.log, capture/lab/failure-drill-x86/drill_real.py; capture/lab/summary/crash-resume-mac.json, capture/lab/summary/crash-next-mac.json, capture/lab/T02-crash-resume-mac/01-graph-matrix.jsonl, capture/lab/T02-crash-resume-mac/03-graph-idempotent.jsonl, capture/lab/T02-crash-resume-mac/t02_child.py; libs/langgraph/langgraph/pregel/main.py, libs/langgraph/langgraph/pregel/_loop.py, and libs/langgraph/langgraph/types.py at langgraph 1.2.22; docs.langchain.com at docs commit 04d4d4a (oss/python/langgraph/checkpointers, oss/python/langgraph/fault-tolerance, langsmith/agent-server); GitHub issues langchain-ai/langgraph#9267, #8039, #9185.