یال ساده همیشه اجرا میشود، یال شرطی مسیر را بر اساس وضعیت انتخاب میکند،
Sendبرای هر آیتم یک وظیفه راه میاندازد وCommandکار بهروزرسانی و مسیریابی را در قالب یک مقدار بازگشتی انجام میدهد.
فهرستی از موضوعات دارید که تعدادشان را فقط در زمان اجرا میفهمید، و میخواهید برای هر موضوع یک بار مدل را فراخوانی کنید. بعد از آنها، یک نود باید بین دو نقطهی پایان تصمیم بگیرد و دلیلش را هم ثبت کند. در واقع در یک گراف به سه نوع مسیریابی (Routing) مختلف نیاز دارید.
پس از پایان این بخش، میتوانید نودها را با یالهای ساده و شرطی به هم متصل کنید. همچنین میتوانید با Send تعداد متغیری وظیفه (Task) راه بیندازید و با Command مستقیماً از داخل یک نود مسیر بعدی را تعیین کنید.
گراف نمونه
گراف این کیت آموزشی در بخش 6.1 دارای 5 نود است. کد اتصال این نودها به یکدیگر به این صورت است:
graph = StateGraph(Fanout)
graph.add_node("plan", plan)
graph.add_node("write_joke", write_joke)
graph.add_node("pick", pick)
graph.add_node("publish", publish)
graph.add_node("retry", retry)
graph.add_edge(START, "plan")
graph.add_conditional_edges("plan", fan_out, ["write_joke"])
graph.add_edge("write_joke", "pick")
graph.add_edge("publish", END)
graph.add_edge("retry", END)
app = graph.compile()متد compile گراف را بررسی میکند و شیئی را برمیگرداند که قابلیت اجرا دارد. در صفحهی مستندات رابط برنامهنویسی گراف (Graph API) آمده است که پیش از فراخوانی (invoke) یا استریم کردن، حتماً باید گراف را کامپایل کنید {{docs oss/python/langgraph/graph-api}}. متن Mermaid حاصل از گراف کامپایلشده همهی یالها را نشان میدهد. پیکان توپر --> نشاندهندهی یال ساده و پیکان خطچین -.-> نشاندهندهی یال شرطی (Conditional Edge) است:
__start__ --> plan;
pick -.-> publish;
pick -.-> retry;
plan -.-> write_joke;
write_joke --> pick;
publish --> __end__;
retry --> __end__;خطوط مربوط به یالها در متن Mermaid. خطوط گرهها و استایلها حذف شدهاند.
هیچ فراخوانی مستقیمی با add_edge از نود pick خارج نمیشود، اما گراف دو یال خروجی از آن دارد. همانطور که در بخش بعد میبینید، این یالها از نوع بازگشتی نود pick استخراج شدهاند.
تصویر نمودار کامل Mermaid را از بالا به پایین نشان میدهد.
تصویر ساختار گراف و یک دور اجرای کامل آن را رسم کرده است.
یالهای ساده و شرطی
یال ساده: یالی از یک نود به نود دیگر که LangGraph با هر بار پایان کار نود اول، مسیر آن را پیش میگیرد.
یال شرطی: یالی همراه با یک تابع مسیریابی. پس از اجرای نود مبدأ، این تابع وضعیت را میخواند و نود بعدی، فهرستی از نودها یا مقدار END را برمیگرداند.
آرگومان سوم در add_conditional_edges فهرستی از نودهایی است که این تابع میتواند خروجی دهد. LangGraph از این فهرست برای رسم ساختار گراف استفاده میکند. بخش 1.3 یالهای شرطی یک ایجنت (Agent) را نشان داد: پس از نود model، فراخوانیهای ابزار (Tool calls) در آخرین پیام تعیین میکنند که مسیر به سمت tools برود یا __end__.
ابزار Send: یک وظیفه برای هر آیتم
مفهوم Send: مقداری که نام یک نود و ورودی اختصاصی برای یک بار اجرای آن را مشخص میکند. تابع مسیریابی با بازگرداندن فهرستی از این مقادیر، در همان گام اجرایی برای هر آیتم یک وظیفه راه میاندازد.
تابع fan_out همان تابع مسیریابی بعد از نود plan است. این تابع فیلد subjects را میخواند و به ازای هر موضوع، یک شیء Send برمیگرداند. هر وظیفهی write_joke دیکشنری کوچک و اختصاصی خودش را به عنوان ورودی میگیرد و به کل وضعیت دسترسی ندارد:
def fan_out(state):
return [Send("write_joke", {"subject": s}) for s in state["subjects"]]
def write_joke(arg):
return {"jokes": [f"a joke about {arg['subject']}"], "log": [f"write_joke({arg['subject']})"]}استریم updates به ازای هر وظیفه یک تکه داده (chunk) تولید میکند. تکههای مربوط به سه وظیفهی write_joke دقیقاً بین خروجی plan و خروجی pick قرار میگیرند:
"write_joke": {
"jokes": [
"a joke about cats"
],
…
"write_joke": {
"jokes": [
"a joke about dogs"
],
…
"write_joke": {
"jokes": [
"a joke about owls"
],سه چانک از شش چانک استریم updates، محدودشده به کلید jokes.
از آنجا که هر سه وظیفه در یک گام همزمان روی کلید jokes مینویسند، این کلید به کاهندهی (Reducer) معرفیشده در بخش 6.1 نیاز دارد. صفحهی مستندات Send و Command این الگو را نگاشت-کاهش (Map-Reduce) مینامد {{docs oss/python/langgraph/graph-api-send-command}}.
کلاس Send را از مسیر langgraph.types ایمپورت کنید. ایمپورت کردن آن از langgraph.constants در نسخهی پینشده همچنان کار میکند، اما هشداری مبنی بر منسوخ شدن این مسیر میدهد {{code libs/langgraph/langgraph/constants.py}}.
ساختار Command: بهروزرسانی و مسیریابی در یک گام
مفهوم Command: مقداری که یک نود برمیگرداند تا بهروزرسانی وضعیت و نامگذاری نود بعدی را در یک مرحله انجام دهد. فیلدهای آن عبارتند از update، goto، graph و resume.
نود pick اولین جوک را بر اساس ترتیب الفبایی انتخاب میکند. سپس یک شیء Command بازمیگرداند که فیلد best را مقداردهی میکند، خطی به log میافزاید و مسیر را به سمت publish یا retry میبرد:
def pick(state) -> Command[Literal["publish", "retry"]]:
best = sorted(state["jokes"])[0]
target = "publish" if "cats" in best else "retry"
return Command(update={"best": best, "log": [f"pick -> {target}"]}, goto=target)نوع دادهی Literal در نوع بازگشتی تابع، دو مقصد احتمالی را مشخص میکند. LangGraph با خواندن این شناسه، دو یال خطچین خروجی از pick را رسم میکند و بر اساس مستندات، وجود این تایپهینت برای رسم الزامی است {{docs oss/python/langgraph/graph-api-send-command}}. در این اجرا مسیر به سمت publish رفت و نود retry اجرا نشد. دو تکهی آخر استریم این موضوع را نشان میدهند:
{
"pick": {
"best": "a joke about cats",
"log": [
"pick -> publish"
]
}
}
{
"publish": {
"log": [
"publish"
]
}
}وقتی تصمیمگیری مسیر فقط به وضعیت وابسته است، از یال شرطی استفاده کنید. هرگاه همان نودی که مقدار بهروزرسانی را حساب میکند مقصد بعدی را هم میداند (مثل نود pick)، از Command استفاده کنید.
دستور Command دو کاربرد دیگر هم دارد. با فیلد resume، نقش ورودیِ پاسخ به یک وقفه (Interrupt) را بازی میکند که در بخش 6.4 به آن میپردازیم. با مقدار graph=Command.PARENT، نودی در یک زیرگراف میتواند مسیر را به نودی در گراف والد هدایت کند {{docs oss/python/langgraph/graph-api-send-command}}. در این کیت هنوز Command.PARENT اجرا نشده است. بررسی و ثبت عملکرد آن همراه با سایر موارد باز در بخش 8.8 در ویرایش بعدی ارائه خواهد شد.
منابع: capture/s_graph.py، capture/out/34-stategraph-reducers-send-command.txt، capture/out/50-draw-fanout.txt؛ فایلهای libs/langgraph/langgraph/types.py، libs/langgraph/langgraph/constants.py و libs/langgraph/langgraph/graph/state.py در نسخه langgraph 1.2.22؛ docs.langchain.com در docs commit 04d4d4a (بخشهای oss/python/langgraph/graph-api و oss/python/langgraph/graph-api-send-command).