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

توابع ()interrupt و Command(resume): اندیس resume و شناسه‌های وقفه

interrupt() and Command(resume): the resume index and interrupt ids

فهرست مطالب
  1. تابع ()interrupt در هر فراخوانی چه کار می‌کند؟
  2. ثبت سه فراخوانی روی یک نخ گفت‌وگو
  3. هزینه‌ی بازپخش
  4. عدم ایجاد چک‌پوینت جدید درون یک سوپراستپ
  5. چه باید کرد؟

ازسرگیری (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}}:

  1. اگر لیست resume این وظیفه در این اندیس پاسخی داشته باشد، همان را برمی‌گرداند. این کار همان بازپخش (replay) سوال قبلی است.
  2. در غیر این صورت، اگر دستور resume فقط یک پاسخ سراسری برای کل گراف فرستاده باشد، آن پاسخ را به انتهای لیست اضافه می‌کند، لیست را ذخیره می‌نماید و آن را برمی‌گرداند.
  3. در غیر این صورت، خطای 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های آن ذخیره شدند:

اجرای 1، دو وقفه و شناسه‌های محاسبه‌شده‌ی مجدد capture/lab/internals/04-interrupt/trace.txt
  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}}:

اجرای 2a، یک پاسخ برای دو سؤال capture/lab/internals/04-interrupt/trace.txt
## 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های ذخیره‌شده‌ی قبلی آن را مجدداً اعمال کرد:

اجرای 2b، نگاشتی از پاسخ‌ها بر اساس شناسه capture/lab/internals/04-interrupt/trace.txt
## 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 را از خود دستور گرفت. شکل این سه فراخوانی را رسم کرده است.

سه فراخوانی که به سه سؤال در دو نود موازی پاسخ می‌دهندهر فراخوانی نودهای منتظر و فراخوانی‌های مدل آن‌ها را از خط اول بازاجرا کرد، پاسخ‌های ذخیره‌شده را بر اساس اندیس بازپخش نمود، و نود پایان‌یافته‌ی other را هرگز دوباره اجرا نکرد.
سه فراخوانی که به سه سؤال در دو نود موازی پاسخ می‌دهند یک شبکه از چهار نود در برابر چهار فراخوانی روی یک thread با InMemorySaver و Qwen3 4B روی سرور میزبان x86. نودهای ask، approve و other پس از START به‌صورت موازی اجرا می‌شوند، و after در آخر اجرا می‌شود. ask و approve هر کدام قبل از فراخوانی interrupt از مدل یک سؤال می‌پرسند. فراخوانی 1 اجرا را آغاز می‌کند: ask در اولین وقفه‌اش با شناسه 462dc352 متوقف می‌شود، approve با شناسه 11314d20 متوقف می‌شود، و other پایان می‌یابد. فراخوانی 2a با یک مقدار ساده ادامه می‌یابد و به دلیل انتظار دو وقفه، خطای RuntimeError می‌دهد و هیچ فراخوانی مدلی انجام نمی‌دهد. فراخوانی 2b با نگاشتی از شناسه به پاسخ ادامه می‌یابد: approve دوباره از مدل می‌پرسد، OK دریافت می‌کند و پایان می‌یابد. ask دوباره از مدل می‌پرسد، اولین پاسخ خود را بازپخش می‌کند، سؤال دوم خود را می‌پرسد و با شناسه 177b6fc6 متوقف می‌شود. نود other اجرا نمی‌شود، زیرا نوشتن‌های ذخیره‌شده‌ی آن دوباره اعمال می‌گردند. فراخوانی 3 با A2 ادامه می‌یابد: ask برای بار سوم با دو فراخوانی مدل اجرا می‌شود و پایان می‌یابد، و after اجرا می‌شود. فراخوانی‌ها به ترتیب 3، 0، 3 و 3 فراخوانی مدل انجام دادند؛ مجموعاً 9 فراخوانی برای پنج پرامپت. این ترد شامل 4 چک‌پوینت است، گام‌های -1، 0، 1، 2. CALL مقدار resume اجرای 1 invoke(input) اجرای 2a 'yes' اجرای 2b {id: answer} اجرای 3 'A2' ask approve other after enter, list [] 1 فراخوانی مدل توقف در تماس 0# id 462dc352 enter, list [] 1 فراخوانی مدل توقف در تماس 0# id 11314d20 یک بار اجرا شد 1 فراخوانی مدل پایان نوشتن‌ها ذخیره شد - enter, list [A1] 2 فراخوانی مدل 0# مقدار A1 می‌دهد 1# توقف در 177b6fc6 enter, list [OK] 1 فراخوانی مدل 0# مقدار OK می‌دهد پایان اجرا نشد 0 فراخوانی مدل نوشتن‌های ذخیره‌شده اعمال مجدد - enter, list [A1] 2 فراخوانی مدل 0# بازپخش A1 1# دریافت A2، پایان - - اجرا شد 1 فراخوانی مدل پایان Runtime Error 2 منتظر هیچ نودی اجرا نشد فراخوانی‌های مدل چک‌پوینت‌ها 3 step -1، step 0 0 هیچ 3 هیچ 3 step 1، step 2 پاسخ‌های ذخیره‌شده به عنوان نوشتن روی چک‌پوینت گام 0 در یک وقفه متوقف می‌شود به پایان می‌رسد نوشتن‌ها بازاعمال شد، بدون اجرا لیست: لیست resume در ورود، 9 فراخوانی مدل برای پنج پرامپت در کل
ستون‌ها فراخوانی‌ها به ترتیب هستند و سطرها چهار نود را نشان می‌دهند. خانه‌های کهربایی در یک وقفه با شناسه آن متوقف می‌شوند، خانه‌های فیروزه‌ای به پایان می‌رسند و خانه‌ی خط‌چین‌دار نوشتن‌های ذخیره‌شده را دوباره اعمال کرده است. لیست درون هر خانه، لیست resume است که نود در سطر اول خود دیده است. سطرهای پایین فراخوانی‌های مدل را می‌شمارند و چک‌پوینت‌های ذخیره‌شده توسط هر فراخوانی را نام می‌برند. برگرفته از capture/lab/internals/04-interrupt/trace.txt.

هزینه‌ی بازپخش

این گراف پنج پرامپت مدل دارد: دو تا در ask، و یکی در هر یک از گره‌های approve، other و after. اما آن سه فراخوانی در عمل 9 بار مدل را صدا زدند:

فراخوانی‌های مدل به ازای هر فراخوانی گراف capture/lab/internals/04-interrupt/trace.txt
## model calls per invocation: {'run 1': 3, 'run 2a': 0, 'run 2b': 3, 'run 3': 3}

سوال اول ask سه بار به مدل فرستاده شد؛ سوال دوم آن و سوال گره‌ی approve هم هرکدام دو بار. با دمای 0، سوال‌های بازپخش‌شده کلمه‌به‌کلمه یکسان برگشتند. اما اگر مدل نمونه‌برداری تصادفی (sampling) انجام دهد، ممکن است هنگام بازپخش سوال متفاوتی بنویسد. با این حال پاسخ همچنان به همان اندیس تحویل داده می‌شود؛ در نتیجه ممکن است کاربر به یک سوال پاسخ دهد، ولی گره در ادامه‌ی کار سوال دیگری را ببیند.

عدم ایجاد چک‌پوینت جدید درون یک سوپراستپ

سه فراخوانی روی نخ گفت‌وگو به جای شش چک‌پوینت، چهار چک‌پوینت ساختند:

تاریخچه‌ی چک‌پوینت‌ها پس از سه فراخوانی capture/lab/internals/04-interrupt/trace.txt
## 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.