کرش درست پس از بازگشت یک گره، در 97 مورد از 100 آزمون sync و 95 مورد از 100 آزمون async باعث اجرای دوبارهی آن شد؛ بنابراین اثرات جانبی گره را بر پایهی فضای نام وظیفه کلیدگذاری کنید.
سه گره بهطور موازی اجرا میشوند. یکی از مدل سؤالی میپرسد، دومی ابزار آبوهوا را فراخوانی میکند، و سومی هنوز مشغول کار است که فرایند کرش میکند. شما از durability="sync" استفاده میکنید، چون مستندات آن را حالت امن مینامند. رشتهی گفتوگو را از سر میگیرید و گره مدل دوباره اجرا میشود. پاسخ مدل قبلاً دریافت شده بود و اگر اثر جانبی داشت، حالا دو بار رخ میداد.
پس از پایان این بخش، متوجه میشوید که کدام فراخوانیِ ذخیرهساز هر بخش از یک سوپراستپ (superstep) را پایا میکند و کرش چه بخشهایی را دوباره اجرا خواهد کرد. علاوه بر این، یاد میگیرید که چگونه بر اساس فضای نام وظیفه یک کلید یکتایی تراکنش (Idempotency key) بسازید.
دو بار نوشتن برای هر سوپراستپ
put_writes: فراخوانیِ ذخیرهساز که عملیات نوشتنِ یک وظیفهی پایانیافته را بهصورت سطرهایی در جدول writes ذخیره میکند. این سطرها به چکپوینتی وابسته هستند که سوپراستپ از آن شروع شده بود.
put: فراخوانیِ ذخیرهساز که یک چکپوینت—یعنی وضعیت پس از یک سوپراستپ—را بهصورت یک سطر در جدول checkpoints ذخیره میکند.
وقتی وظیفهای تمام میشود، حلقه خروجیهای آن را در حافظه ثبت میکند و فراخوانی put_writes را به یک مجری پسزمینه میسپارد {{code libs/langgraph/langgraph/pregel/_loop.py:523-551}}. بهطور پیشفرض، هیچ چیزی منتظر این فیوچر (future) نمیماند. عملیات نوشتن در DeltaChannel از این قاعده مستثنی است: _checkpointer_put_after_previous هم منتظر فیوچرهای نوشتنِ در حال انتظار میماند و هم منتظر put قبلی {{code libs/langgraph/langgraph/pregel/_loop.py:1748-1760}}. پس از فاز بهروزرسانی، تابع _put_checkpoint چکپوینت را میسازد و put را ارسال میکند {{code libs/langgraph/langgraph/pregel/_loop.py:1275-1420}}. با تنظیم durability="sync"، حلقه پیش از برنامهریزی سوپراستپ بعدی، منتظر تکمیل همین یک فیوچر میماند {{code libs/langgraph/langgraph/pregel/main.py:3103-3105}}. در حالت sync، حلقه فقط منتظر همین میماند و نه چیز دیگری.
با تنظیم durability="exit"، در طول اجرا هرگز put_writes فراخوانی نمیشود و فراخوانیهای میانیِ _put_checkpoint نیز ذخیرهساز را نادیده میگیرند {{code libs/langgraph/langgraph/pregel/_loop.py:1325-1351}}. تنها چکپوینت موجود، زمان خروج کامل اجرا ذخیره میشود {{code libs/langgraph/langgraph/pregel/_loop.py:1543-1553}}.
ترتیب فراخوانیها در عمل
ما تکتک فراخوانیهای ذخیرهساز را در یک اجرای create_agent روی SqliteSaver، با مدل Qwen3 4B روی ماشین مهمان سرور x86 ثبت کردیم. مدل ابتدا دو فراخوانی ابزار (Tool call) درخواست کرد و سپس پاسخ داد. این خروجیِ اجرای sync از مرحلهی ابزارها تا پایان است:
[ 21] tick step=2 run=['tools', 'tools']
[ 22] task done tools -> loop.put_writes ['messages', 'branch:to:model']
[ 23] task done tools -> loop.put_writes ['messages', 'branch:to:model']
[ 25] loop._put_checkpoint source=loop exiting=False
[ 27] SAVER.put_writes ckpt=..3a2745cf3dd2 task=9360c94c channels=['messages', 'branch:to:model']
[ 28] SAVER.put_writes ckpt=..3a2745cf3dd2 task=b0bb9318 channels=['messages', 'branch:to:model']
[ 29] SAVER.put id=..0f5fddfed5a3 parent=..3a2745cf3dd2 step=2 source=loop
[ 31] tick step=3 run=['model']
[ 32] task done model -> loop.put_writes ['messages']
[ 34] loop._put_checkpoint source=loop exiting=False
[ 36] SAVER.put id=..930ea1dbdfc0 parent=..0f5fddfed5a3 step=3 source=loop
[ 39] SAVER.put_writes ckpt=..0f5fddfed5a3 task=7f67758b channels=['messages']سطرهای 34 تا 39 را بخوانید. چکپوینت مرحلهی 3 در سطر 36 ذخیره شد و حلقه به کار خود ادامه داد. عملیات نوشتنِ وظیفهی مدل در آن گام (7f67758b)، در سطر 39 به ذخیرهساز رسید؛ یعنی پس از چکپوینتی که خودش این تغییرات را در بر دارد. اینجا این تقدم و تأخر آسیبی نزد، چون چکپوینت کل آن گام را پوشش میدهد. این موضوع نشان میدهد که حلقه حتی در حالت sync هم منتظر put_writes نمیماند.
آسیب اصلی زودتر از اینها و در طول یک سوپراستپ رخ میدهد. وظیفهای که کارش تمام شده در حالی که وظایف همتایش هنوز در حال اجرا هستند، تنها به put_writes خود متکی است تا خروجیاش حفظ شود. در یک اجرا روی ماشین مهمانِ تحت بار، هر یک از این پنج وظیفه 3.0 تا 4.4 میلیثانیه معطل ماندند تا آن فراخوانی کامل شود. تصویر روی پایان هر سوپراستپ بزرگنمایی میکند.
همین ردگیری محاسبات (Trace)، یک فاصلهی زمانی را در نقطهی شروع نشان میدهد. چکپوینت ورودی (مرحلهی 1-) در سطر 9 به ذخیرهساز رسید، یعنی پس از اینکه وظیفهی __start__ در سطر 5 به پایان رسیده بود. بنابراین، sync پیش از نخستین وظیفه منتظر چکپوینت ورودی نمیماند؛ بلکه این انتظار پیش از نخستین گرهی گراف شما رخ میدهد.
کرش میان وظایف پایانیافته و ثبت چکپوینت
گراف آزمایشی ما روی SqliteSaver، ابتدا گرههای a، b و c را بهصورت موازی اجرا میکند و سپس به سراغ d میرود. گره a از Qwen3 4B نام یک میوه را میخواهد و b ابزار get_weather را فراخوانی میکند. گره c صبر میکند تا هر دو به پایان برسند، سپس به مدت مشخصی مکث کرده و دستور os._exit(17) را اجرا میکند. پس از آن، یک فرایند جدید با فراخوانی invoke(None) ادامهی کار رشته را در دست میگیرد و هر گرهای را که اجرا شود ثبت میکند.
ما این آزمون را روی ماشین مهمان سرور x86 سنجیدیم؛ 50 بار تکرار برای هر حالت، در دو دور اجرای کامل. دور 1 ماتریس کرش را تشکیل میدهد. دور 2 حالتهای صفر و 0.2 ثانیه را تکرار میکند و علاوه بر آن، فضاهای نام وظایف را هم لاگ میاندازد. بازهها با روش 95 درصد ویلسون محاسبه شدهاند:
| حالت | زمان انتظار پیش از کرش | دور 1: اجرای دوبارهی a |
دور 2: اجرای دوبارهی a |
تجمیعشده، 95 درصد ویلسون |
|---|---|---|---|---|
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 |
0.2 ثانیه | 0 از 50 | 0 از 50 | 0 از 100 |
async |
0.2 ثانیه | 0 از 50 | 0 از 50 | 0 از 100 |
exit |
0 و 0.2 ثانیه | بدون چکپوینت، 100 از 100 | اجرا نشد |
گره b در هیچ تکراری دوباره اجرا نشد. ابزار در چند میلیثانیه کارش را تمام کرد، بنابراین put_writes آن خیلی قبل از کرش به پایان رسیده بود. گره a آخرین گرهی بود که خروجی داد، درست چند میلیثانیه پیش از خروج c؛ به همین دلیل دادههای نوشتن آن هنوز در راه بودند. در تمام آزمونهای حالت exit هیچ چکپوینتی به جا نماند و تلاش برای ادامهی اجرا با خطای EmptyInputError: Received no input for __start__ متوقف شد. تصویر تکتک این آزمونها را رسم کرده است.
در زمان انتظار صفر، حالت پایایی عملاً هیچ فرقی ایجاد نکرد. بازهها همپوشانی (Overlap) دارند و حتی در دور 2، حالت async تکرارهای بیشتری ثبت کرد. هر دو حالت در انتهای گام منتظر میمانند، در حالی که کرش پیش از پایان گام رخ داده بود. نقطهی آسیبپذیر، پنجرهی زمانیِ اجرای همان یک فراخوانی put_writes بعد از هر وظیفه است. روی SqliteSaver و در یک ماشین تحت بار، این فراخوانی بهطور میانگین 4.6 میلیثانیه در حالت sync و 4.2 میلیثانیه در حالت async طول کشید (بخش 2.6). در یک ایجنت (Agent)، گره مدل معمولاً در شرایطی کارش تمام میشود که گرههای همتای کندتر هنوز مشغول کارند؛ آسیبپذیری دقیقاً در همین بازه شکل میگیرد.
چرا ادامهی اجرا وظایف درست را پیدا میکند؟
شناسهی وظیفه (Task id): شناسهی یکتای یک وظیفه در یک سوپراستپ مشخص. حلقه این شناسه را بهصورت یک هش xxh3 محاسبه میکند {{code libs/langgraph/langgraph/pregel/_algo.py:616-623}} {{code libs/langgraph/langgraph/pregel/_algo.py:990-997}}. برای یک وظیفهی push شش مقدار، و برای یک وظیفهی PULL پنج مقدار ثابت بهعلاوهی محرکهای آن هش میشوند. این مقادیر عبارتند از: شناسهی چکپوینت، فضای نام، مرحله، نام گره، حالت PULL یا push، و در نهایت محرکها یا ایندکس Send.
دادههای نوشتنِ هر وظیفه ذیل همان چکپوینتی ذخیره میشود که سوپراستپ از آن آغاز شده بود، همراه با شناسهی همان وظیفه {{code libs/langgraph/langgraph/pregel/_loop.py:523-531}}. وقتی اجرای فرایند از سر گرفته میشود، همان چکپوینت را بارگذاری میکند، دقیقاً همان وظایف را میچیند و شناسههای یکسانی تولید میکند. هر وظیفهای که خروجی ذخیرهشده داشته باشد، دادههایش را پس میگیرد {{code libs/langgraph/langgraph/pregel/_loop.py:841-854}}، و اجراکننده (Runner) فقط سراغ وظایفی میرود که دادهی ذخیرهشدهای ندارند {{code libs/langgraph/langgraph/pregel/main.py:3085}}. وظیفهای که با خطا مواجه شده یا روی یک وقفه (Interrupt) متوقف مانده است، خروجی ذخیرهشدهای ندارد، پس دوباره اجرا میشود {{code libs/langgraph/langgraph/pregel/_task_status.py:99-129}}.
شناسهی خودِ چکپوینت هر بار یک uuid6 کاملاً جدید است {{code libs/langgraph/langgraph/pregel/_checkpoint.py:334}}. بنابراین، شناسههای وظیفه فقط زمانی تکرار میشوند که چکپوینت اولیه با موفقیت ذخیره شده باشد. اگر آن چکپوینت از بین برود، ادامهی اجرا از یک چکپوینت قدیمیتر کلید میخورد و شناسههای کاملاً تازهای میسازد. این اتفاق در هیچیک از 200 آزمونِ دور 2 رخ نداد؛ چرا که در این آزمونها فراخوانی مدل در a بیشتر از فراخوانی put برای چکپوینت پیش از آن طول کشید.
فضای نام وظیفه در نقش کلید یکتایی تراکنش
هر گره میتواند فضای نام وظیفهی خود را به فرمت <node>:<task id> از کانفیگ خود بخواند. در دور 2 ماتریس کرش، این مقدار در نخستین سطر هر گره ثبت شد:
rec["ns"] = get_config()["configurable"]["checkpoint_ns"] durability=sync wait=0.0s: {"n": 50, "categories": {"a and c": 48, "only c": 2}, … "ns": {"c ns same": 50, "a ns same when a rerun": 48, "a rerun": 48, "b ns same when b rerun": 0, "b rerun": 0}}
durability=async wait=0.0s: {"n": 50, "categories": {"a and c": 50}, … "ns": {"c ns same": 50, "a ns same when a rerun": 50, "a rerun": 50, "b ns same when b rerun": 0, "b rerun": 0}}خلاصه شده به تعداد namespaceهای هر خانه.
هر گرهی که دوباره اجرا شد، دقیقاً همان فضای نام اجرای اولش را داشت: c در 200 مورد از 200 آزمون، و a در 98 مورد از 98 تکرار. اگر اثر جانبی بر پایهی این فضای نام کلیدگذاری میشد، از تمام 98 بار اجرای مجدد a صرفنظر میکرد. این قاعده هم در حالت sync و هم در حالت async بدون تغییر برقرار بود.
بنابراین، اثرات جانبی هر گره را بر پایهی فضای نام آن کلیدگذاری کنید. همانطور که در بخش 5.3 نشان داده شده، این کلید را کنار همان اثر ذخیره کنید و اگر کلید از قبل وجود داشت، اثر جانبی را اجرا نکنید. با آغاز یک نوبت گفتوگو (Turn) جدید، وظایف تازه با شناسههای نو برنامهریزی میشوند، بنابراین همان درخواست در نوبت بعدی یک اثر کاملاً جدید بهشمار میرود. در حالت exit، در صورت وقوع کرش چیزی برای ادامهی اجرا باقی نمیماند، پس در آن حالت کلید یکتایی را بر اساس دادههای اختصاصی خودتان بسازید.
فضای نام وظیفه تنها تا زمانی معتبر است که چکپوینت اولیه ذخیره شده باشد. اگر آن چکپوینت از دست برود، بازپخش (Replay) شناسههای متفاوتی برای وظایف تولید خواهد کرد. در چنین شرایطی، تنها یک کلید تجاریِ اختصاصی که خودتان ذخیره کردهاید (مثل شناسهی سفارش)، جلوی اجرای تکراری یک اثر را میگیرد.
منابع: capture/lab/internals/03-checkpoint/trace.txt، capture/lab/internals/03-checkpoint/run.py، capture/lab/internals/03-checkpoint/a_sync.trace.jsonl، capture/lab/internals/03-checkpoint/a_async.trace.jsonl، capture/lab/internals/03-checkpoint/a_exit.trace.jsonl، 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/internals/08-costs/trace.txt؛ libs/langgraph/langgraph/pregel/_loop.py، libs/langgraph/langgraph/pregel/main.py، libs/langgraph/langgraph/pregel/_algo.py، libs/langgraph/langgraph/pregel/_task_status.py و libs/langgraph/langgraph/pregel/_checkpoint.py در نسخه langgraph 1.2.22.