بخش 2.3 · درون محیط اجرا

مسیر نوشتن چک‌پوینت: put، put_writes و پایایی

The checkpoint write path: put, put_writes, and durability

فهرست مطالب
  1. دو بار نوشتن برای هر سوپراستپ
  2. ترتیب فراخوانی‌ها در عمل
  3. کرش میان وظایف پایان‌یافته و ثبت چک‌پوینت
  4. چرا ادامه‌ی اجرا وظایف درست را پیدا می‌کند؟
  5. فضای نام وظیفه در نقش کلید یکتایی تراکنش

کرش درست پس از بازگشت یک گره، در 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 از مرحله‌ی ابزارها تا پایان است:

فراخوانی‌های saver در گام ابزارها و آخرین گام مدل، پایداریِ sync capture/lab/internals/03-checkpoint/trace.txt
  [ 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 میلی‌ثانیه معطل ماندند تا آن فراخوانی کامل شود. تصویر روی پایان هر سوپراستپ بزرگ‌نمایی می‌کند.

مدت انتظار هر وظیفه پایان‌یافته برای put_writes در یک اجرای syncدر یک اجرای زیر بار، وظیفه پایان‌یافته 3.0 تا 4.4 میلی‌ثانیه ناپایدار بود و sync تنها منتظر put چک‌پوینت ماند.
مدت انتظار هر وظیفه پایان‌یافته برای put_writes در یک اجرای sync چهار قاب، هر کدام برای یک ابرگام از یک اجرای create_agent با Qwen3 4B، پایداری sync، روی SqliteSaver در سرور مهمان x86. هر قاب 7 میلی‌ثانیه پس از بازگشت نخستین وظیفه گام را پوشش می‌دهد. خط بالایی حلقه است: یک نقطه برای هر وظیفه بازگشته و یک خط کهربایی در محل شروع ابرگام بعدی. خط پایینی saver پس‌زمینه است: بلوک‌های توپر فراخوانی‌های put برای ذخیره چک‌پوینت و بلوک‌های توخالی فراخوانی‌های put_writes برای ذخیره نوشتن‌های یک وظیفه هستند. نوار صورتی از بازگشت هر وظیفه تا پایان put_writes آن امتداد دارد. این اسپن‌ها در یک اجرا روی سیستم مهمان زیر بار، بین 3.0 تا 4.4 میلی‌ثانیه بودند. در گام 3، فراخوانی put چک‌پوینت پیش از put_writes وظیفه 7f67758b پایان یافت. بین قاب‌ها، مدل برای چندین ثانیه اجرا شد. حلقه saver گام 0 0 2 4 6 شروع مدل 3.55 ثانیه گام 1 0 2 4 6 مدل ابزارها 0.01 ثانیه گام 2 0 2 4 6 ابزارها، ابزارها مدل 1.54 ثانیه گام 3 0 2 4 6 مدل ms 1 2 1 گام 3: put چک‌پوینت تمام شد، انتظار sync پایان یافت و گام 4 آغاز شد 2 the put_writes of 7f67758b ends 1.4 ms later وظیفه بازگشت put put_writes ناپایدار، 3.0 تا 4.4 میلی‌ثانیه شروع ابرگام بعدی میان قاب‌ها: وظیفه بعدی و ثانیه‌های آن
هر قاب پایان یک ابرگام است که تا میلی‌ثانیه‌های پس از بازگشت آخرین وظیفه‌اش بزرگ‌نمایی شده. خط بالایی حلقه و خط پایینی saver پس‌زمینه است. بلوک‌های فیروزه‌ای توپر putها، بلوک‌های توخالی فراخوانی‌های put_writes و نوارهای صورتی اسپن‌های پیش از پایداری وظیفه هستند. برچسب‌های بین قاب‌ها نام وظیفه بعدی و مدت زمان آن را نشان می‌دهند. برگرفته از capture/lab/internals/03-checkpoint/a_sync.trace.jsonl.

همین ردگیری محاسبات (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__ متوقف شد. تصویر تک‌تک این آزمون‌ها را رسم کرده است.

آنچه پس از کرش در میانه یک ابرگام توسط resume اجرا شدبدون انتظار، نود مدلی که در آخر بازگشته بود در 97 از 100 آزمایش sync و 95 از 100 آزمایش async مجدداً اجرا شد، و با 0.2 ثانیه در هیچ‌کدام.
آنچه پس از کرش در میانه یک ابرگام توسط resume اجرا شد ردیف‌های نقطه‌ای برای آزمون کرش روی SqliteSaver با Qwen3 4B روی سرور مهمان x86. نودهای a و b و c به‌صورت موازی اجرا می‌شوند: a از مدل یک میوه می‌خواهد، b یک ابزار آب‌وهوا را فراخوانی می‌کند، و c پس از بازگشت a و b و انتظار 0 یا 0.2 ثانیه‌ای، از فرایند خارج می‌شود. یک فرایند جدید thread را از سر می‌گیرد (resume). هر نقطه یک آزمایش است، 50 مورد در هر خانه، دو اجرا. بدون انتظار، sync نود مدل a را در 49 و 48 آزمایش (97 از 100) و async در 45 و 50 آزمایش (95 از 100) دوباره اجرا کرد. نود ابزار b هرگز دوباره اجرا نشد. با 0.2 ثانیه انتظار، همه آزمایش‌ها تنها c را دوباره اجرا کردند. در حالت exit، در تمام 100 آزمایش اجرای 1 هیچ چک‌پوینتی وجود نداشت. اجرای 2 شامل exit نبود. اجرای 1 اجرای 2 حالت، انتظار sync 0.0 s 49/50 48/50 async 0.0 s 45/50 50/50 sync 0.2 s 0/50 0/50 async 0.2 s 0/50 0/50 exit 0.0 s هیچ اجرا نشد exit 0.2 s هیچ اجرا نشد اجرای مجدد a و c اجرای مجدد فقط c چیزی برای resume نیست بدون انتظار، تجمیعی: sync نود a را در 97 از 100 و async در 95 از 100 دوباره اجرا کرد نود ابزار b هرگز دوباره اجرا نشد، و 0.2 ثانیه انتظار فقط c را برای اجرای مجدد باقی گذاشت
هر نقطه نمایانگر یک آزمایش است؛ 50 آزمایش در هر خانه، دو اجرا. نقاط صورتی نود مدل a و نود کرش‌کرده c را دوباره اجرا کردند، نقاط فیروزه‌ای تنها c را دوباره اجرا کردند، و نقاط خاکستری چیزی برای resume نداشتند. برگرفته از capture/lab/internals/03-checkpoint/crash.json و capture/lab/internals/03-checkpoint/taskns.json.

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

خواندن namespace وظیفه در یک نود capture/lab/internals/03-checkpoint/crash.py
        rec["ns"] = get_config()["configurable"]["checkpoint_ns"]
مقایسه namespace در اجرای کرش‌کرده در برابر resume capture/lab/internals/03-checkpoint/taskns.txt
  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.