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

کانال‌ها و تداخل در نوشتن

Channels and colliding writes

فهرست مطالب
  1. هفت کانال، سه وضعیت
  2. تداخلی که یک ترد را از کار می‌اندازد
  3. ترمیم یک ترد آسیب‌دیده
  4. رقابت هم‌زمانی شناسه در add_messages

پیش از استقرار، برای هر کلیدی که دو گره در یک ابرگام (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}}.

یک کانال، سه به‌روزرسانی capture/lab/internals/02-channels/trace.txt
## 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}}:

خطای raise و نوشتن‌های ذخیره‌شده پیش از آن capture/lab/internals/02-channels/trace.txt
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 بار مدل را صدا زد:

چهار روش ترمیم یک رشته با تداخل LastValue capture/lab/internals/02-channels/repair.txt
## 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] بلافاصله ترد را خواند و اجرا را به پایان رساند. هیچ گره‌ای دوباره اجرا نشد و هزینه‌ی فراخوانی مجدد مدل تحمیل نگردید.

تصویر اجرای معیوب و روند ترمیم آن را نمایش می‌دهد.

تداخل LastValue، خواندن‌های ناموفق پس از آن و نحوه‌ی ترمیمهر دو عملیات نوشتن پیش از پرتاب خطا ذخیره می‌شوند؛ بنابراین هر بار خواندن، این تداخل را بازپخش می‌کند تا زمانی که اسکیمایی با یک کاهنده همان نوشتن‌های ذخیره‌شده را دوباره اعمال کند.
یک تداخل LastValue، خواندن‌های ناموفق پس از آن و ترمیم توالی روی چهار خط حیات: کد شما، حلقه Pregel، گره‌های a و b، و InMemorySaver. متد invoke اجرا را آغاز می‌کند. حلقه گره‌های a و b را اجرا می‌کند و نوشتن هر گره‌ی پایان‌یافته روی x به عنوان یک نوشتن معلق در چک‌پوینت گام 0 ذخیره می‌شود: x=2 از b و x=1 از a. سپس apply_writes متد LastValue.update را با دو مقدار فراخوانی کرده و InvalidUpdateError را ایجاد می‌کند. یک get_state بعدی همان نوشتن‌های معلق را می‌خواند و دوباره از طریق ['main.py:1496', 'main.py:1331', '_algo.py:319', 'last_value.py:64'] خطا می‌دهد. متد invoke(None) دوباره نوشتن‌ها را اعمال می‌کند، هیچ گره‌ای را اجرا نمی‌کند و مجدداً خطا می‌دهد. در بلوک پایینی، همان saver توسط گراف بازکامپایل‌شده با x: Annotated[int, operator.add] باز می‌شود. فراخوانی get_state مقدار {'x': 3} را برمی‌گرداند و invoke(None) با همان وضعیت پایان می‌یابد و هیچ گره‌ای را اجرا نمی‌کند. کد شما حلقه Pregel گره‌های a و b InMemorySaver 1 invoke({'x': 0}) 2 اجرای a و b 3 b: x=2 a: x=1 4 apply_writes دریافت دو مقدار در LastValue خطای InvalidUpdateError 5 get_state خواندن مرحله 0 + معلق تکرار InvalidUpdateError 6 invoke(None) nodes run: [], writes reapplied تکرار InvalidUpdateError همان saver، بازکامپایل گراف with x: Annotated[int, operator.add] 7 get_state {'x': 3} 8 invoke(None) nodes run: [], saved writes reduced: 0 + 1 + 2 {'x': 3}
از بالا به پایین بخوانید. فلش‌های فیروزه‌ای نوشتن‌های معلقِ ذخیره‌شده در InMemorySaver هستند، فلش‌های صورتی خطاهای پرتاب‌شده (raise) می‌باشند و بلوک پایینی همان رشته تحت گراف اصلاح‌شده است. برگرفته از capture/lab/internals/02-channels/trace.txt و capture/lab/internals/02-channels/repair.txt.

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

گره مربوط به آزمون رقابت (race test) capture/lab/internals/02-channels/race.py
    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 عمل نوشتن بدون شناسه ذخیره شوند:

اجرای کنترلی که شناسه (id) را از دست داد capture/lab/internals/02-channels/race_control_sleep06.txt
  {"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.

ترجمه‌ی فارسی Channels and colliding writes از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما