پیش از استقرار، برای هر کلیدی که دو گره در یک ابرگام (superstep) روی آن مینویسند یک کاهنده (reducer) بگذارید: بروز تداخل، تمام خواندنهای بعدی آن ترد (thread) را از کار میاندازد و تنها یک کاهنده میتواند آن را ترمیم کند.
شما یک branch دوم به گرافی اضافه میکنید که درست کار میکرد. هر دو branch مقداری را از مدل میخواهند و x را مقداردهی میکنند. اولین اجرا با خطای InvalidUpdateError متوقف میشود. برای بررسی موضوع، ترد را در پنل ادمین خود باز میکنید؛ اما خواندن آن هم با همان خطا مواجه میشود، تلاش مجدد برای اجرا نیز همین سرنوشت را دارد و یک نوبت گفتوگوی جدید هم به همین شکل از کار میافتد.
با پایان این بخش، متوجه میشوید که هر نوع کانال در برابر صفر، یک یا دو عمل نوشتن در طول یک ابرگام چه رفتاری نشان میدهد. همچنین یاد میگیرید که چگونه یک ترد آسیبدیده از تداخل را ترمیم کنید و چه زمانی ممکن است شناسهی پیام پس از ادامهی اجرا (resume) تغییر کند.
هفت کانال، سه وضعیت
کانال (Channel): شیئی که یک کلید از وضعیت گراف، یا یک مقدار داخلی حلقه را در خود نگه میدارد. apply_writes در هر ابرگام یک بار متد update کانال را با تمام مقادیر نوشتهشده برای آن صدا میزند.
ردگیری محاسبات، هر کلاس کانال را مستقیماً با همان لیست نوشتههایی اجرا میکند که apply_writes تحویل میداد. این بخش مدلی را فراخوانی نمیکند، چون صرفاً کلاسهای کانال را بهتنهایی میآزماید. جدول زیر نتیجه را در langgraph نسخه 1.2.22 نشان میدهد:
| کانال | کاربرد | بدون نوشتن | یک نوشتن | دو نوشتن در یک ابرگام |
|---|---|---|---|---|
LastValue |
کلید وضعیتی بدون کاهنده | مقدار را نگه میدارد | جایگزینش میکند | خطای InvalidUpdateError صادر میکند |
BinaryOperatorAggregate |
کلیدی همراه با یک کاهنده، مانند add_messages |
مقدار را نگه میدارد | ادغامش میکند | هر دو را به ترتیب مسیر وظایف ادغام میکند |
Topic(accumulate=False) |
__pregel_tasks، صف Send |
صف را پاک میکند | نگهش میدارد | هر دو را نگه میدارد |
EphemeralValue(guard=True) |
__start__، ورودی گراف |
پاک میشود، با نسخهی جدید | نگهش میدارد | خطا صادر میکند |
EphemeralValue(guard=False) |
branch:to:<node>، jump_to |
پاک میشود، با نسخهی جدید | نگهش میدارد | آخرین مقدار را حفظ میکند |
NamedBarrierValue |
join:a+b:c، یالی که منتظر چند گره میماند |
نامهای دیدهشده را نگه میدارد | نام را اضافه میکند | هر دو نام را اضافه میکند |
DeltaChannel (بتا) |
فهرستی از پیامها که بهجای مقادیر، نوشتهها را ذخیره میکند | مقدار را نگه میدارد | یک بار فراخوانی کاهنده | یک بار فراخوانی کاهنده برای هر دو |
سطرها از سورسکد کلاسهای کانال استخراج شدهاند: LastValue در صورت دریافت بیش از یک مقدار خطا صادر میکند {{code libs/langgraph/langgraph/channels/last_value.py:56-64}}. BinaryOperatorAggregate تکتک مقادیر را ادغام میکند و دو مقدار از نوع Overwrite را نمیپذیرد {{code libs/langgraph/langgraph/channels/binop.py:127-148}}. دو کانال موقت (ephemeral) با بهروزرسانیِ خالی، پاک میشوند {{code libs/langgraph/langgraph/channels/ephemeral_value.py:55-68}}. یک Topic بدون آرگومان accumulate در هر بهروزرسانی ابتدا خودش را خالی میکند {{code libs/langgraph/langgraph/channels/topic.py:77-85}}. کانال سد (barrier) هر نامی را که میشناسد میافزاید {{code libs/langgraph/langgraph/channels/named_barrier_value.py:56-67}}. DeltaChannel کل لیست نوشتهها را طی یک فراخوانی به کاهندهی خود میدهد {{code libs/langgraph/langgraph/channels/delta.py:159-183}}.
## LastValue
update([1]) -> returns True; available=True get=1 checkpoint()=1
update([]) -> returns False; available=True get=1 checkpoint()=1
update([2, 3]) -> RAISES InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple values.; available=True get=1 checkpoint()=1تداخلی که یک ترد را از کار میاندازد
اصل خود خطا در بخش 6.1 مستند شده است، اما آنچه بعد از آن بر سر ترد میآید در اسناد نیست.
ردگیری محاسبات، مسیرهای START -> a و START -> b را روی InMemorySaver با مدل Qwen3 4B روی سیستم مهمان سرور x86 اجرا میکند. گره a رقم 1 را از مدل میخواهد و آن را در قالب x برمیگرداند، و گره b همین کار را برای 2 انجام میدهد. x هیچ کاهندهای ندارد. صدور خطا در فاز بهروزرسانی رخ میدهد؛ یعنی بعد از آنکه بدنهی هر دو گره و هر دو فراخوانی مدل اجرا شدند {{code libs/langgraph/langgraph/pregel/_loop.py:732}} {{code libs/langgraph/langgraph/pregel/_algo.py:319}}:
raised InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple values.
…
node bodies that ran before the raise: ['a', 'b']
loop.put_writes calls before the raise (writes already persisted as pending): [('__start__', [('x', 0), ('branch:to:a', None), ('branch:to:b', None)]), ('b', [('x', 2)]), ('a', [('x', 1)])]
get_state after the raise ALSO raises InvalidUpdateError via ['main.py:1496', 'main.py:1331', '_algo.py:319', 'last_value.py:64']
get_state_history: 2 snapshots
raw saver.get_tuple works: checkpoint step=0 pending_writes=[('26351ed0', 'x', 1), ('8f6a50fe', 'x', 2)]
…
invoke(None) resume raises again: InvalidUpdateError; node bodies re-run on resume: [] (empty means the saved writes were reapplied, not re-executed)فهرست فریمها و دامپ مربوط به هر چکپوینت خلاصه شدهاند.
هر دو عمل نوشتن بهعنوان نوشتههای معلق (pending writes) در چکپوینت گام 0 ذخیره شدند. متد get_state نوشتههای معلق را برای ساخت وضعیتی که برمیگرداند اعمال میکند {{code libs/langgraph/langgraph/pregel/main.py:1326-1333}}. بنابراین همان LastValue.update را با همان دو مقدار صدا میزند و با همان خطا متوقف میشود. اجرای invoke(None) هم دوباره همان نوشتهها را اعمال میکند و بدون اجرای گرهها یا مدل، خطا میدهد. در این وضعیت، تنها ذخیرهساز خام میتواند دادههای ترد را بخواند.
ترمیم یک ترد آسیبدیده
ما چهار راه برونرفت را اندازه گرفتیم؛ روی سیستم مهمان سرور x86 با مدل Qwen3 4B، هر کدام طی یک اجرا با همان گراف و InMemorySaver. این فایل در مجموع 14 بار مدل را صدا زد:
## 1. same graph, after the raise
get_state: raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v
update_state(cfg, {'x': 9}): ok -> {'configurable': {'thread_id': 't1', 'checkpoint_ns': '', …
invoke(None): raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v
node bodies run by invoke(None): ['a', 'b']; model calls so far 4
invoke({'x': 5}) as a new turn: raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v
## 2. same saver, graph recompiled with x: Annotated[int, operator.add]
get_state: ok -> {'x': 3}
invoke(None): ok -> {'x': 3}
node bodies run by invoke(None): []; model calls so far 8شناسه چکپوینت در نتیجهی update_state و همچنین بخشهای 3 و 4 حذف شدهاند.
دستور update_state یک چکپوینت جدید نوشت و اجرای invoke(None) بعدی، دوباره هر دو گره و هر دو فراخوانی مدل را اجرا کرد و باز هم با خطا متوقف شد. نوبت گفتوگوی جدید هم به خطا خورد، چون گراف هنوز نادرست است. ایجاد یک fork از چکپوینت ورودی هم هر دو گره را دوباره اجرا کرد و متوقف شد. تنها اصلاح شِما (schema) چارهساز بود. همان ذخیرهساز، این بار با x: Annotated[int, operator.add] بلافاصله ترد را خواند و اجرا را به پایان رساند. هیچ گرهای دوباره اجرا نشد و هزینهی فراخوانی مجدد مدل تحمیل نگردید.
تصویر اجرای معیوب و روند ترمیم آن را نمایش میدهد.
بنابراین رفع تداخل نیازی به ترمیم داده ندارد. کاهنده را مستقر کنید؛ تمام تردهای آسیبدیده با استفاده از نوشتههای ذخیرهشدهی خود به پایان میرسند. کاهندهای که انتخاب میکنید مقدار نهایی را تعیین میکند: در این مثال، operator.add به مقدار 3 رسید، که حاصل جمع ورودی 0 با 1 و 2 است. کاهنده را بر اساس معنای کلید انتخاب کنید و به یاد داشته باشید که مقادیر نوشتهشده به ترتیب مسیر وظایف به آن تحویل داده میشوند.
رقابت همزمانی شناسه در add_messages
add_messages: کاهندهی فهرستی از پیامها. پیامی با شناسهی یکسان را جایگزین میکند، پیامی را که RemoveMessage نام برده حذف میکند و بقیه را میافزاید.
پیامی که شناسه ندارد، در داخل add_messages یک uuid4 جدید میگیرد. کاهنده آن را روی خود شیء پیام تنظیم میکند {{code libs/langgraph/langgraph/graph/message.py:199-205}}. این اتفاق در فاز بهروزرسانی رخ میدهد. تا آن موقع، حلقه همان شیء را پیشتر به put_writes پسزمینهی چکپوینتر فرستاده است. از این رو، نوشتهی معلق ذخیرهشده تنها در صورتی شناسه دارد که سریالیسازی (serialization) بعد از کاهنده انجام شده باشد.
پاسخ مدل چت همیشه یک شناسه همراه دارد که LangChain بر اساس اجرا تنظیم میکند؛ بنابراین رقابت همزمانی اثری روی آن ندارد. گره آزمایشی، پاسخ مدل و پیام دومی را که خودش از متن پاسخ و بدون شناسه میسازد برمیگرداند:
def node(s):
r = MODEL.invoke("Say OK.")
…
return {"messages": [r, AIMessage(content="copied: " + r.text)]}ما این مورد را اندازه گرفتیم؛ روی سیستم مهمان سرور x86 با مدل Qwen3 4B، طی دو دور اجرای 200 تایی، روی InMemorySaver با تنظیم durability="async". تمام 400 پاسخ مدل هنگام خروج از گره شناسه داشتند. پیام ساختهشده نیز در هر دو بار، در 200 اجرا از 200 اجرا با شناسهاش ذخیره شد. یک نمونهی کنترل بدون مدل، که در آن گره بلافاصله پیام ساختهشده را برمیگرداند، باز هم در هر دو دور نتیجهی 200 از 200 را داد. اما همان نمونهی کنترل با 0.6 ثانیه تاخیر (sleep) در گره، باعث شد 4 مورد از 200 عمل نوشتن بدون شناسه ذخیره شوند:
{"with id": 196, "without id": 4}بنابراین این رقابت همزمانی نادر است و فقط پیامی را تهدید میکند که کد خودتان میسازد. وقتی نوشتهی ذخیرهشده شناسه نداشته باشد، با ادامهی اجرا دوباره اعمال میشود و add_messages یک شناسهی دوم و متفاوت به آن میدهد. در نتیجه کلاینتی که شناسهی اول را استریم کرده و بعداً بخواهد پیام را با آن شناسه ویرایش یا حذف کند، آن را پیدا نخواهد کرد. حلقه فقط به پیامهای داخل یک DeltaChannel شناسههای پایدار اختصاص میدهد {{code libs/langgraph/langgraph/pregel/_messages.py:516-547}}. روی هر پیامی که میسازید مقدار id=str(uuid4()) را خودتان بگذارید تا کاهنده هرگز مجبور به این کار نشود.
منابع: capture/lab/internals/02-channels/trace.txt، capture/lab/internals/02-channels/run.py، capture/lab/internals/02-channels/repair.txt، capture/lab/internals/02-channels/repair.py، capture/lab/internals/02-channels/race.py، capture/lab/internals/02-channels/race_run1.txt، capture/lab/internals/02-channels/race_run2.txt، capture/lab/internals/02-channels/race_control.py، capture/lab/internals/02-channels/race_control_nodelay_run1.txt، capture/lab/internals/02-channels/race_control_nodelay_run2.txt، capture/lab/internals/02-channels/race_control_sleep06.txt، capture/lab/internals/common/instrument.py، capture/lab/internals/common/real.py؛ libs/langgraph/langgraph/channels/last_value.py، libs/langgraph/langgraph/channels/binop.py، libs/langgraph/langgraph/channels/ephemeral_value.py، libs/langgraph/langgraph/channels/topic.py، libs/langgraph/langgraph/channels/named_barrier_value.py، libs/langgraph/langgraph/channels/delta.py، libs/langgraph/langgraph/graph/message.py، libs/langgraph/langgraph/pregel/_messages.py، libs/langgraph/langgraph/pregel/_loop.py، libs/langgraph/langgraph/pregel/_algo.py و libs/langgraph/langgraph/pregel/main.py در langgraph نسخه 1.2.22.