ازسرگیری (resume)، گره را از همان خط اولش دوباره اجرا میکند؛ فراخوانیهای مدل را هم همینطور. تطبیق پاسخها هم بر اساس موقعیت ترتیبی است. بنابراین فراخوانیهای مدل را بیرون از گرههای دارای وقفه نگه دارید و پاسخها را با نگاشتی از شناسهها ازسر بگیرید.
گراف شما همزمان از دو نفر سوال میپرسد: مسافری در یک branch و تأییدکنندهای در branch دیگر. هر گره ابتدا از مدل میخواهد سوالش را بنویسد. هر دو سوال به رابط کاربری (UI) شما میرسند. تأییدکننده زودتر پاسخ میدهد و سرورتان دستور Command(resume="OK") را ارسال میکند. LangGraph خطای RuntimeError بالا میآورد و هیچچیز ازسر گرفته نمیشود. وقتی هر دو پاسخ را در قالب یک نگاشت (map) میفرستید، کار میکند؛ ولی صورتحسابتان نشان میدهد که مدل همان سوالها را دوباره نوشته است.
با پایان این بخش، میتوانید مسیر یک دستور resume را در تابع ()interrupt خطبهخط ردگیری کنید و پیشبینی کنید هر فراخوانی چه پاسخی میگیرد. همچنین میتوانید دو گرهی منتظر را با یک فراخوانی ازسر بگیرید و تعداد فراخوانیهای مدلی را که در هر resume تکرار میشوند بشمارید.
تابع ()interrupt در هر فراخوانی چه کار میکند؟
لیست Resume (Resume list): فهرست پاسخهایی است که یک وظیفه (task) تا الان دریافت کرده و بهصورت یک ثبت داده (write) روی کانال __resume__ ذخیره شده است.
تابع ()interrupt یک شمارنده در یادداشت موقت (scratchpad) وظیفهی خود نگه میدارد. در هر فراخوانی، اندیس بعدی را برمیدارد و سه منبع را به ترتیب بررسی میکند {{code libs/langgraph/langgraph/types.py:1029-1058}}:
- اگر لیست resume این وظیفه در این اندیس پاسخی داشته باشد، همان را برمیگرداند. این کار همان بازپخش (replay) سوال قبلی است.
- در غیر این صورت، اگر دستور resume فقط یک پاسخ سراسری برای کل گراف فرستاده باشد، آن پاسخ را به انتهای لیست اضافه میکند، لیست را ذخیره مینماید و آن را برمیگرداند.
- در غیر این صورت، خطای
GraphInterruptرا با یک وقفه (Interrupt) جدید بالا میآورد و گره متوقف میشود.
شناسهی وقفه (Interrupt id): شناسهی یکتای یک سوال است. این شناسه با درهمسازی (هش) xxh3 از فضای نام (namespace) وظیفه ساخته میشود و عبارت n| برای nاُمین سوالِ بیپاسخِ آن وظیفه به انتهایش اضافه میگردد {{code libs/langgraph/langgraph/types.py:583-589}}.
وقتی وظیفهای خطای GraphInterrupt بالا میآورد، اجراکننده (runner) سوال و لیست resume را بهعنوان writeهای آن وظیفه ذخیره میکند {{code libs/langgraph/langgraph/pregel/_runner.py:594-600}}. شناسه نیازی به ذخیرهسازی ندارد؛ حلقهی اجرا آن را از روی فضای نام و تعداد پاسخها دوباره محاسبه میکند. بخش ذخیرهساز (saver)، سوال را بهعنوان یک write روی کانال __interrupt__ با اندیس 3- و هر پاسخ را روی کانال __resume__ با اندیس 4- ذخیره میکند {{code libs/checkpoint/langgraph/checkpoint/base/init.py:824}}.
ثبت سه فراخوانی روی یک نخ گفتوگو
گراف نمونه پس از START، سه گرهی ask، approve و other را موازی اجرا میکند و سپس سراغ after میرود. این گراف از مدل Qwen3 4B روی سرور مهمان x86 با دمای 0 استفاده میکند. گرهی ask از مدل سوال میخواهد، ()interrupt را صدا میزند، سوال دوم را از مدل میخواهد و دوباره ()interrupt را فرامیخواند. گرهی approve یک سوال از مدل میخواهد و یکبار ()interrupt را فرامیخواند. گرهی other ابزار آبوهوا و مدل را فرامیخواند و هرگز متوقف نمیشود. هر گره خط اول خود را به همراه فضای نام و لیست resume لاگ میکند و فراخوانیهای مدل را هم به ثبت میرساند.
اولین invoke دو وقفه برگرداند. گرهی other اجرا شد و به پایان رسید، و writeهای آن ذخیره شدند:
returned interrupt id=462dc352bc169ed50a32e43c579712fb value={'q': 'Which city would you like to visit?'}
returned interrupt id=11314d20c136a4a3ec3a8a26c24243c9 value={'q': 'Could you please approve a travel budget of 900 EUR for the upcoming business trip to Berlin?'}
…
recompute id for ask: xxh3_128(task_checkpoint_ns='ask:db8df5fb-7f77-0ac1-61de-e4a38b97c8a0') = 462dc352bc16... matches=True
recompute id for approve: xxh3_128(task_checkpoint_ns='approve:56f9f439-6fe7-44ef-ec89-762fd2b36cf4') = 11314d20c136... matches=Trueازسرگیری با یک مقدار تکی و ساده خطا داد و هیچ گره یا فراخوانی مدلی اجرا نشد. حلقه تعداد وقفههای معلق را میشمارد و اگر بیش از یکی باشد، ارائهی یک نگاشت از شناسه به پاسخ را الزامی میکند {{code libs/langgraph/langgraph/pregel/_loop.py:1066-1075}}:
## run 2a: Command(resume='yes') without an id while 2 interrupts are pending
raises RuntimeError: When there are multiple pending interrupts, you must specify the interrupt id when resuming. Docs: https://docs.langchain.com/oss/python/lanشکل نگاشتی کار کرد. هر دو گره دوباره از خط اول خود اجرا شدند و هر دو قبل از رسیدن به ()interrupt، دوباره مدل را صدا زدند. گرهی approve مقدار OK را دریافت کرد و به پایان رسید. گرهی ask برای سوال اولش مقدار A1 را گرفت، سوال دوم را از مدل خواست و با یک شناسهی جدید همانجا متوقف شد. گرهی other دوباره اجرا نشد؛ حلقه writeهای ذخیرهشدهی قبلی آن را مجدداً اعمال کرد:
## run 2b: Command(resume={ask_id: 'A1', approve_id: 'OK'})
…
{"node": "ask", "event": "enter (first line)", "ns": "ask:db8df5fb-7f77-0ac1-61de-e4a38b97c8a0", "scratchpad.resume": ["A1"], "null_resume": null}
{"node": "ask", "event": "model call -> 'Which city would you like to visit?'", "model_s": 1.16}
{"node": "ask", "event": "interrupt #0 returned 'A1'"}
…
tick step=1 returns=True to_run=['approve', 'ask'] reapplied(no rerun)=['other']
returned interrupt id=177b6fc6979f90e1a13103fec68d96fb value={'q': 'How many nights will the traveller stay at A1?'}
second interrupt id expected = xxh3_128(ns + '|1') = 177b6fc6979f... matches=Trueفراخوانی سوم، Command(resume='A2')، نیازی به شناسه نداشت؛ چون فقط یک سوال باقی مانده بود. گرهی ask برای بار سوم اجرا شد. سوال اولش را دوباره از مدل خواست و A1 را از لیست بازپخش کرد. سپس سوال دومش را دوباره خواست و A2 را از خود دستور گرفت. شکل این سه فراخوانی را رسم کرده است.
هزینهی بازپخش
این گراف پنج پرامپت مدل دارد: دو تا در ask، و یکی در هر یک از گرههای approve، other و after. اما آن سه فراخوانی در عمل 9 بار مدل را صدا زدند:
## model calls per invocation: {'run 1': 3, 'run 2a': 0, 'run 2b': 3, 'run 3': 3}سوال اول ask سه بار به مدل فرستاده شد؛ سوال دوم آن و سوال گرهی approve هم هرکدام دو بار. با دمای 0، سوالهای بازپخششده کلمهبهکلمه یکسان برگشتند. اما اگر مدل نمونهبرداری تصادفی (sampling) انجام دهد، ممکن است هنگام بازپخش سوال متفاوتی بنویسد. با این حال پاسخ همچنان به همان اندیس تحویل داده میشود؛ در نتیجه ممکن است کاربر به یک سوال پاسخ دهد، ولی گره در ادامهی کار سوال دیگری را ببیند.
عدم ایجاد چکپوینت جدید درون یک سوپراستپ
سه فراخوانی روی نخ گفتوگو به جای شش چکپوینت، چهار چکپوینت ساختند:
## checkpoint history (newest first)
step=2 source=loop next=() id=..bc1c0b7b902f
step=1 source=loop next=('after',) id=..9a14716dbcea
step=0 source=loop next=('ask', 'approve', 'other') id=..1ca1bd022200
step=-1 source=input next=('__start__',) id=..88027e62558cاجرای 2b در شرایطی تمام شد که ask همچنان در انتظار بود؛ بنابراین سوپراستپِ گام 1 هنوز به پایان نرسیده بود. پاسخها و سوال جدید بهصورت writeهایی روی چکپوینت 1ca1bd022200 و در کنار writeهای other ذخیره شدند. یک چکپوینت فقط زمانی ایجاد میشود که تکتک وظایف آن سوپراستپ به پایان رسیده باشند. به همین دلیل، ابزاری مثل سفر در زمان (time-travel) که فهرست چکپوینتها را نشان میدهد، هیچ نقطهای بین دو پاسخ به یک گرهی یکسان ثبت نخواهد کرد.
چه باید کرد؟
وقفههای معلق را از get_state(config).tasks بخوانید و با Command(resume={id: value}) پاسخ دهید. اگر همهی کلیدها شناسههای هگزادسیمال xxh3 باشند، حلقه دیکشنری را بهعنوان نگاشت میخواند، فرقی هم نمیکند چند وقفهی معلق وجود داشته باشد {{code libs/langgraph/langgraph/pregel/_loop.py:1045-1064}}. ما شکل نگاشتی را با یک وقفه اجرا نکردیم، اما همیشه از همین قالب استفاده کنید تا اگر branch دومی با یک سوال اضافه شد، برنامهی سرورتان از کار نیفتد.
هر فراخوانی مدلی را که سوال مینویسد، به گرهی مجزایی قبل از گرهی فراخوان ()interrupt منتقل کنید. با این کار آن گره تمام میشود، writeهایش ذخیره میگردد و همانطور که رفتار other نشان داد، دستور resume دیگر آن را دوباره اجرا نمیکند. در نتیجه سوال در تمام بازپخشها ثابت میماند و هزینهی آن را هم فقط یک بار میپردازید.
ترتیب فراخوانیهای ()interrupt یک گره را در همهی اجراها ثابت نگه دارید و هیچکدام را بر اساس شرطی که ممکن است تغییر کند جا نیندازید. پاسخها بر اساس اندیس اختصاص مییابند، نه بر اساس متن سوال.
شناسهی وقفه، نامی پایدار برای هر سوال است. این شناسه فقط به فضای نام وظیفه وابسته است و در بخش 2.3 دیدیم که این فضای نام در صورت کرش و بالا آمدن یک فرایند (process) جدید هم ثابت میماند. از این شناسه بهعنوان کلید سوال در رابط کاربری و پایگاه دادهتان استفاده کنید.
منابع: capture/lab/internals/04-interrupt/trace.txt، capture/lab/internals/04-interrupt/run.py، capture/lab/internals/04-interrupt/run1.trace.jsonl، capture/lab/internals/04-interrupt/run2b.trace.jsonl، capture/lab/internals/common/real.py؛ فایلهای libs/langgraph/langgraph/types.py، libs/langgraph/langgraph/pregel/_loop.py، libs/langgraph/langgraph/pregel/_algo.py و libs/langgraph/langgraph/pregel/_runner.py در langgraph 1.2.22؛ فایل libs/checkpoint/langgraph/checkpoint/base/init.py در langgraph-checkpoint 4.3.2.