با هر ابرگام (superstep) مثل یک تراکنش رفتار کنید: نوشتنهای موازی همزمان و بر اساس ترتیب مسیر وظیفه پدیدار میشوند؛ بنابراین هرگز نگذارید وضعیت به این وابسته باشد که کدام گره زودتر تمام شده است.
دو گرهی موازی هرکدام از مدلی پاسخی میخواهند و آن را به یک لیست اضافه میکنند. در لاگهای شما، در بیشتر اجراها خروجی b قبل از a برمیگردد؛ اما وضعیت در تمام اجراها ابتدا a را ثبت میکند. ترتیبی که در وضعیت میبینید یک ترتیب مرتبسازیشده است و محیط اجرا (runtime) آن را پیش از اجرای گرهها تثبیت میکند.
با پایان این بخش، میتوانید ردگیری محاسبات (trace) یک ابرگام را خطبهخط بخوانید و از روی نسخهی کانالها پیشبینی کنید کدام گره در نوبت بعد اجرا میشود. همچنین میتوانید ترتیب ادغامِ (merge) نوشتنهای موازی را حدس بزنید و محدودیت بازگشت (recursion limit) را طوری تنظیم کنید که متغیر درستی را بشمارد.
سه فاز در یک حلقه
ابرگام: یک نوبت از حلقهی LangGraph. وظایف آماده را برنامهریزی میکند، آنها را اجرا میکند، و سپس همهی نوشتنهای آنها را یکجا اعمال مینماید.
حلقه کوتاه است: loop.tick() برنامهریزی میکند، runner.tick() هر وظیفهی برنامهریزیشدهای را که هنوز تغییری ثبت نکرده اجرا میکند، و loop.after_tick() نوشتنها را اعمال کرده و یک چکپوینت (checkpoint) ذخیره میکند {{code libs/langgraph/langgraph/pregel/main.py:3081-3105}}. یک گره هرگز تغییرات ثبتشده در ابرگام خودش را نمیبیند؛ مقادیری که میخواند، همان مقادیر انتهای ابرگام قبلی هستند.
برنامهریزی (Plan). تابع prepare_next_tasks دو نوع وظیفه (task) میسازد {{code libs/langgraph/langgraph/pregel/_algo.py:392}}. وظیفهی PULL گرهی است که کانال راهانداز آن مقداری در خود دارد و نسخهاش از آخرین نسخهای که گره دیده جدیدتر است {{code libs/langgraph/langgraph/pregel/_algo.py:1260-1277}}. وظیفهی PUSH یک Send در حال انتظار در کانال __pregel_tasks است {{code libs/langgraph/langgraph/pregel/_algo.py:441-466}}.
اجرا (Execute). اجراکننده (runner) وظایف را بهصورت موازی شروع میکند. با پایان هر وظیفه، حلقه تغییرات آن را ثبت کرده و در پسزمینه به چکپوینتر (checkpointer) میسپارد. بخش 2.3 همین مسیرِ نوشتن را پیگیری میکند.
بهروزرسانی (Update). پس از آخرین وظیفه، apply_writes وظایف را مرتب میکند، نوشتنهای آنها را بر اساس کانال دستهبندی مینماید، و هر کانال را یک بار با کل دستهی مربوط به خودش صدا میزند {{code libs/langgraph/langgraph/pregel/_loop.py:732-738}}. در نهایت _put_checkpoint نتیجه را ذخیره میکند {{code libs/langgraph/langgraph/pregel/_loop.py:774}}.
ثبت اجرای یک ایجنت واقعی
توابع حلقهی langgraph نسخهی 1.2.22 را پچ (patch) کردیم تا هر فراخوانی را ثبت کند. سپس create_agent را با مدل Qwen3 4B روی Ollama، در یک ماشین مهمان x86 و با دمای 0 اجرا کردیم. پرامپت این بود: Weather in Paris and Oslo?. مدل در اولین پاسخش دو فراخوانی get_weather درخواست کرد که 3.64 ثانیه طول کشید، و در پاسخ دومش جواب نهایی را داد که 1.59 ثانیه زمان برد. این زمانها مربوط به یک بار اجرا روی ماشین مهمان زیر بار هستند؛ پس ترتیبها و شمارشها را ملاک قرار دهید، نه ثانیهها را. این مراحل، گامهای 1 و 2 از این ردگیری محاسبات هستند:
[ 12] PLAN step=1 stop=9999 updated_channels=['branch:to:model', 'messages']
task __pregel_pull model id=c716c241 path=('__pregel_pull', 'model') triggers=['branch:to:model']
versions_seen(before)={'__input__': {}, '__start__': {'__start__': 1}}
[ 13] TICK step=1 returns=True status=pending run=['model']
channel_versions={'__start__': 2, 'branch:to:model': 2, 'messages': 2}
…
[ 15] UPDATE order=["model@('__pregel_pull', 'model')"]
…
versions_changed={'__pregel_tasks': [None, 3], 'branch:to:model': [2, 3], 'messages': [2, 3]}
versions_seen_updated={'model': {'branch:to:model': 2}}
updated_channels=['__pregel_tasks', 'messages']
…
[ 18] PLAN step=2 stop=9999 updated_channels=['__pregel_tasks', 'messages']
task __pregel_push tools id=7bd87c87 path=('__pregel_push', 0, False) triggers=['__pregel_push']
task __pregel_push tools id=81e79e5c path=('__pregel_push', 1, False) triggers=['__pregel_push']
…
[ 25] UPDATE order=["tools@('__pregel_push', 0, False)", "tools@('__pregel_push', 1, False)"]گامهای 1 و 2 اجرا. نوشتنهای مدل و خطوط ذخیرهساز میان فازها حذف شدهاند.
تابع create_agent هر فراخوانی ابزار (tool call) را به یک Send مستقل تبدیل میکند؛ در نتیجه دو فراخوانی ابزار تبدیل به دو وظیفهی PUSH از گره tools میشوند {{code libs/langchain_v1/langchain/agents/factory.py:2031-2032}}. به هرکدام یک شناسهی وظیفه و اندیس اختصاصی در مسیر تعلق میگیرد. شکل هر شش ابرگام اجرا را به همراه نسخهی هر کانال نمایش میدهد.
نسخهها تعیین میکنند چه چیزی در نوبت بعد اجرا شود
نسخهی کانال (Channel version): عددی که حلقه برای هر کانال در چکپوینت ذخیره میکند. کانالی که در یک ابرگام تغییر کند، نسخهی جدیدی میگیرد.
قاعده ساده و البته سراسری است. apply_writes بالاترین نسخهی موجود میان همهی کانالها را میگیرد و یک واحد به آن اضافه میکند {{code libs/langgraph/langgraph/pregel/_algo.py:271-282}}. تمام کانالهایی که در آن ابرگام تغییر میکنند دقیقاً همین عدد را دریافت خواهند کرد. در گام 1 بالا، کانالهای messages، __pregel_tasks و branch:to:model همگی به نسخهی 3 ارتقا یافتند.
versions_seen: نگاشتی در چکپوینت، از هر گره به نسخهی هریک از کانالهای راهانداز آن در زمان آخرین باری که آن گره اجرا شده است.
تابع apply_writes مقدار versions_seen را فقط برای کانالهایی بهروزرسانی میکند که وظیفه را فعال کردهاند {{code libs/langgraph/langgraph/pregel/_algo.py:262-269}}. پس از گام 1، گره model کانال branch:to:model را در نسخهی 2 دیده است. در گام 3 آن کانال روی نسخهی 4 قرار دارد؛ بنابراین model دوباره اجرا میشود. راهانداز وظیفهی PUSH برابر با __pregel_push است که یک کانال واقعی نیست؛ به همین دلیل در ردگیری محاسبات، مقدار versions_seen برای tools بهصورت {} خالی میماند.
یک نکتهی ظریف مشخص میکند چرا اجرا به پایان میرسد. کانال branch:to:model از نوع EphemeralValue است. وقتی model آن را میخواند، حلقه مقدار آن را پاک میکند، ولی همچنان یک نسخهی جدید به آن اختصاص میدهد {{code libs/langgraph/langgraph/pregel/_algo.py:284-292}}. در گام 4 نسخهی آن 5 است و model نسخهی 4 را دیده، اما کانال خالی است. مرحلهی برنامهریزی هم نسخهی جدیدتر میخواهد و هم وجود مقدار؛ در نتیجه وظیفهای اجرا نمیشود و حلقه متوقف میگردد.
ادغامِ نوشتنها بر اساس ترتیب مسیر وظیفه
تابع apply_writes وظایف را پیش از اعمال هر تغییری بر اساس مسیرشان مرتب میکند {{code libs/langgraph/langgraph/pregel/_algo.py:256}}. سپس کاهنده (reducer) فارغ از اینکه وظایف به چه ترتیبی تمام شدهاند، نوشتنها را با همان ترتیب دریافت میکند.
ما این رفتار را اندازهگیری کردیم؛ روی ماشین مهمان x86 با مدل Qwen3 4B، و 3 اجرا برای هر حالت. دو گرهی موازی، a و b، هرکدام از مدل پاسخی میخواهند و آن را با operator.add به یک لیست پیوست میکنند. یکی از گرهها متنی 60 کلمهای میخواهد و دیگری متنی تککلمهای:
slow node=a: finish order (node, model seconds)=[('a', 5.58), ('b', 5.75)] merged list=['a', 'b']
slow node=a: finish order (node, model seconds)=[('b', 0.6), ('a', 5.93)] merged list=['a', 'b']
slow node=a: finish order (node, model seconds)=[('b', 0.6), ('a', 5.85)] merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.48), ('a', 5.62)] merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.7), ('a', 5.83)] merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.67), ('a', 5.8)] merged list=['a', 'b']هر جفت شامل نود و ثانیههای فراخوانی مدل آن است، به ترتیبی که نودها بازگشتند.
فراخوانیهای مدل به اندازهی طول درخواستی زمان نبردند. یک سرور Ollama روی CPU به هر دو گره پاسخ میداد، در نتیجه پاسخ کوتاه ممکن بود پشت سر پاسخ بلند معطل شود. گره b در 5 بار از 6 اجرا زودتر بازگشت، اما در هر 6 بار لیست خروجی ['a', 'b'] بود.
مسیرهای PULL قبل از مسیرهای PUSH مرتب میشوند. نوشتنهای گرهی که Command(goto=...) با نام مشخص راهاندازی کرده، پیش از نوشتنهای وظایف Send در همان ابرگام اعمال میشوند. در دادههای ثبتشده، گره a نام یک شهر را از مدل پرسید و وظیفهی c را برای دیدن وضعیت هوای آن فرستاد. بخش برنامهریزی ابتدا c را در لیست آورد، و در بهروزرسانی ابتدا b اعمال شد:
PLAN step=2: push c path=('__pregel_push', 0, False) triggers=['__pregel_push'] id=5f91e09b; pull b path=('__pregel_pull', 'b') triggers=['branch:to:b'] id=5bbd9a1a
UPDATE order=["b@('__pregel_pull', 'b')", "c@('__pregel_push', 0, False)"] -> updated=['results'] versions={'__pregel_tasks': [3, 4], 'branch:to:b': [3, 4], 'results': [3, 4]}شکل این دو ترتیب را در کنار یکدیگر قرار میدهد. بنابراین، ترتیب لیست ادغامشده در طول اجراهای مختلف پایدار است و میتوانید آن را تست کنید. این نکته همچنین نشان میدهد کاهندهای که فقط آخرین مقدار را نگه میدارد، مقدار وظیفهای را حفظ میکند که مسیرش در آخرین جایگاهِ مرتبسازی قرار میگیرد؛ کندترین وظیفه هیچ تأثیری در این نتیجه ندارد.
محدودیت بازگشت دقیقاً چه چیزی را میشمارد؟
حلقه مقدار stop را برابر با گام فعلی بهاضافهی حد مجاز بهاضافهی یک قرار میدهد، و زمانی که گام از stop فراتر رود با خطا متوقف میشود {{code libs/langgraph/langgraph/pregel/_loop.py:1923}} {{code libs/langgraph/langgraph/pregel/_loop.py:666}}. پس این محدودیت ابرگامها را میشمارد، و گام پنهان __start__ هم یکی از آنهاست.
ما شمارش را اندازهگیری کردیم؛ روی سرور مهمان x86 با Qwen3 4B، با یک بار اجرا به ازای هر مقدار محدودیت. پرامپت به مدل میگوید در هر نوبت گفتوگو (turn) یک ابزار صدا بزند:
recursion_limit |
ابرگامهای اجراشده | فراخوانیهای مدل پیش از خطا |
|---|---|---|
| 1 | 2 | 1 |
| 4 | 5 | 2 |
| 5 | 6 | 3 |
| 10 | 11 | 5 |
| 25 | 26 | 13 |
محدودیت k به ازای ورودی جدید، k بهاضافهی یک ابرگام اجرا میکند، و مدل تقریباً k تقسیم بر 2 بار اجرا میشود. ازسرگیری یک نخ (thread) متوقفشده با وقفه (interrupt) که محدودیت 4 داشت، 6 ابرگام اجرا کرد: گامهای 2 تا 7. تابع create_agent این محدودیت را روی گراف خودش 9,999 میگذارد {{code libs/langchain_v1/langchain/agents/factory.py:1902}}. یک StateGraph ساده مقدار 10,007 دریافت میکند {{code libs/langgraph/langgraph/_internal/_config.py:42-44}}.
راهنمای عملیاتی
اگر ترتیب اهمیتی ندارد، کاهندههایی بنویسید که خروجیشان وابسته به ترتیب نباشد؛ مثل عملگر جمع یا مجموعهها (set). اگر ترتیب مهم است، به ترتیب مسیر تکیه کنید و برای آن تست بنویسید، چون کاملاً پایدار است. هرگز به لاگِ زمان پایان اجرای وظایف به عنوان ترتیب نهایی وضعیت نگاه نکنید.
برای کلیدی که دو گرهی موازی روی آن مینویسند یک کاهنده تعریف کنید، حتی اگر انتظار دارید فقط یک نویسنده داشته باشد. بخش 2.2 نشان میدهد نبود یک کاهنده چه بر سر یک نخ میآورد.
هنگام تنظیم محدودیت برای یک ایجنت، فراخوانیهای مدل را بشمارید نه گامها را. برای بودجهی n فراخوانی مدل، مقدار recursion_limit را برابر با 2 برابر n قرار دهید. هر گرهی قلاب (hook) before_model یا after_model به ازای هر فراخوانی مدل یک ابرگام اضافه میکند؛ بنابراین آنها را هم به حساب آورید.
منابع: capture/lab/internals/01-superstep/trace.txt, capture/lab/internals/01-superstep/trace.jsonl, capture/lab/internals/01-superstep/run.py, capture/lab/internals/02-channels/trace.txt, capture/lab/internals/06-send-command/trace.txt, capture/lab/internals/07-create-agent/trace.txt, capture/lab/internals/common/instrument.py, capture/lab/internals/common/real.py؛ فایلهای libs/langgraph/langgraph/pregel/main.py, libs/langgraph/langgraph/pregel/_loop.py, libs/langgraph/langgraph/pregel/_algo.py, و libs/langgraph/langgraph/_internal/_config.py در langgraph 1.2.22؛ libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0.