یال شرطی چیست و چه تفاوتی با یال ایستا دارد؟
گراف لنگگراف دو نوع یال دارد. یال ایستا (Static Edge) با add_edge تعریف میشود و مقصدش از اول مشخص است: «بعد از A همیشه برو B». اما یال شرطی (Conditional Edge) یک تابع تصمیمگیر — تابع روتر — را بعد از گرهٔ مبدأ نصب میکند؛ این تابع state فعلی را میبیند و در لحظهٔ اجرا میگوید مسیر بعدی کدام گره است. به زبان مستندات رسمی: متد add_conditional_edges «بهصورت اختیاری به یک یا چند یال مسیریابی میکند یا اجرا را متوقف میکند» [S1].
امضای رسمی add_conditional_edges — هر پارامتر چه میکند؟
بر اساس سورس رسمی StateGraph، امضای متد این است: add_conditional_edges(source, path, path_map=None) و مقدار Self برمیگرداند تا بتوانید فراخوانیها را زنجیره کنید [S2]. ورودی path میتواند یک Callable معمولی، یک تابع async، یا حتی یک Runnable لنگچین باشد؛ path_map هم یا dict[Hashable, str] است یا list[str] یا None. سه سبک فراخوانی زیر را ببینید — هر سه در همین پروژه اجرا و تست شدهاند.
| پارامتر | نوع | نقش |
|---|---|---|
| source | str | نام گرهٔ مبدأ؛ این یال بلافاصله پس از اتمام اجرای این گره فعال میشود (میتواند START هم باشد — «ورود شرطی»). |
| path | Callable | Runnable | تابع روتر؛ state فعلی را میگیرد و مقصد (یا مقصدها) را برمیگرداند. اگر 'END' برگرداند، اجرای گراف متوقف میشود. [S2] |
| path_map | dict[Hashable, str] | list[str] | None | اختیاری؛ dict خروجی روتر را به نام گره ترجمه میکند و list فقط مقصدهای مجاز را مستند میکند. None یعنی خروجی روتر خودش نام گره است. |
| مقدار بازگشتی | Self | خود شیء گراف؛ برای زنجیرهکردن مثل builder.add_conditional_edges(...).add_edge(...) |
- نام یک گرهٔ موجود (str): آن گره در superstep بعدی اجرا میشود.
- فهرست نام گرهها: همهٔ آن گرهها بهصورت موازی در superstep بعدی اجرا میشوند [S1].
- END (که همان '__end__' است): اجرای گراف در همینجا تمام میشود [S2].
- با path_map دیکشنری: هر کلیدی که در دیکشنری تعریف کردهاید — کلید ناشناخته خطای KeyError میدهد (در همین پروژه تست شد).
- اشیاء Send (نسخههای جدید): برای map-reduce؛ به ازای هر آیتم یک state مستقل میسازد [S1].
چطور یک روتر واقعی با مدل APX24 بسازیم؟ (گامبهگام)
چطور چند گره را همزمان اجرا کنیم و خطاهای مسیریابی را مدیریت کنیم؟
یال شرطی فقط «اگر/وگرنه» نیست. طبق مستندات رسمی، اگر تابع روتر یک فهرست از نام گرهها برگرداند، همهٔ آن گرهها بهصورت موازی در superstep بعدی اجرا میشوند [S1]. این همان فناوت (fan-out) است: یک سؤال همزمان به بازیابیگر (retriever) و خلاصهساز میرود و هر دو نتیجه در state ادغام میشود. اما «ادغام» شرطی دارد: وقتی دو گرهٔ موازی به یک کلید state مینویسند، آن کلید باید reducer داشته باشد — وگرنه خطای InvalidUpdateError میگیرید؛ خطایی که در تست تحریریه دقیقاً همین پیام را داد: «Can receive only one value per step» [S7].
کدام مدل را به روتر و کدام را به پاسخدهنده بدهیم؟ (هزینه و انتخاب)
یال شرطی معماری را طوری میشکند که هر وظیفه مدل خودش را داشته باشد: دستهبندی یک وظیفهٔ «سهحالتهٔ» ساده است و نیازی به پرچمدار ندارد؛ پاسخ تخصصی و استدلال، بله. بر اساس تعرفهٔ رسمی اپکس۲۴ [S4]، ورودی/خروجی GPT-6 Luna دقیقاً ۱/۳۰ مدل Claude Sonnet 5 و ۱/۱۰۰ مدل GPT-6 Astra است — یعنی فرستادن مرحلهٔ مسیریابی به مدل درست، عملاً تفاوت بین ۴۰۵ هزار و ۴۰٫۵ میلیون تومان در ماه است. این انتخابپذیری فقط وقتی ممکن است که گراف شما مسیرها را جدا کرده باشد؛ همان کاری که یال شرطی میکند.
conditional edges، Command یا Send؟ کدام را کجا استفاده کنیم؟
| مورد | چه میکند | تغییر state | اجرای موازی | بهترین جا |
|---|---|---|---|---|
| add_conditional_edges | تعیین مقصد(ها) بعد از یک گره | خیر — فقط مسیر | بله — با فهرستِ خروجی | مسیریابی خالص بر اساس state؛ جدایی تصمیم از عمل |
| Command(goto, update) | آپدیت state + مسیر در خود گره | بله | بله — با فهرست در goto | وقتی تصمیم و آپدیت جدانشدنیاند؛ حذف روترهای میانی |
| Send | ساخت نمونهٔ state مستقل به ازای هر آیتم | بله — state جدید به ازای آیتم | ذاتی — به ازای هر Send | map-reduce روی فهرست ورودی (مثل پردازش دستهای تیکتها) |
| سازوکار | نوشتن با | دیاگرام | نمونهٔ کاربرد |
|---|---|---|---|
| add_conditional_edges | builder.add_conditional_edges("a", route) | نمایش داده میشود (با Literal دقیقتر) | ارجاع تیکت، پایان/ادامهٔ حلقه |
| Command | return Command(update={...}, goto="tools") | مسیر داخلی گره پنهان است | گارد حلقه + شمارنده در یک قدم |
| Send | return [Send("node", item) for item in items] | شاخههای داینامیک | پردازش موازی ۱۰۰ تیکت با state مستقل |
یک قانون مستندات را جدی بگیرید: برای هر گره فقط یک سازوکار مسیریابی انتخاب کنید — یال ایستا یا مسیریابی پویا، نه هر دو [S1]. در تست تحریریه، وقتی هم add_edge و هم add_conditional_edges را برای یک گره گذاشتیم، گراف کامپایل شد و هر دو مسیر اجرا شدند؛ خروجی درست به نظر میرسید اما رفتار مبهم بود و با تغییر نسخه ممکن است عوض شود. مبهمکاری در گراف = دیباگ شبزندهداری.
مرحلهٔ بعدی: تمرینها و مسیر یادگیری
شما حالا سه چیز را دارید که خیلی از پیادهسازیهای موجود ندارند: امضای دقیق add_conditional_edges از سورس رسمی، الگوی «روتر ارزان با مدل اقتصادی و پاسخدهندهٔ قوی» با تعرفهٔ واقعی، و سه خطای واقعیای که در محیط تست گرفتیم و رفع کردیم. دانشی که با خطای واقعی تست شود دیگر فرار نمیکند — برای همین سه تمرین زیر را با همان روحیه انجام دهید: اول اجرا، بعد تعمیم.
- تمرین P1 (آسان): روتر زوج/فرد بدون هیچ LLM — برای اینکه مکانیک گراف را لمس کنید.
- تمرین P2 (متوسط): همان روتر تیکت با path_map دیکشنری + کلید پیشفرض امن؛ بعد عمداً کلید ناشناخته برگردانید و KeyError را ببینید.
- تمرین P3 (سخت): حلقهٔ retry با گارد شمارنده؛ سقف را ۳ بگذارید و رفتار GraphRecursionError را با سقف صفر تجربه کنید.
- بعد از تمرینها: مقالهٔ Command را بخوانید تا آپدیت+مسیر را یکجا بنویسید؛ بعد Send برای map-reduce؛ بعد checkpointing برای حافظهٔ مکالمه.




