بخش 6.2 · جریان کنترل در LangGraph

یال‌ها، Send و Command

Edges, Send, and Command

فهرست مطالب
  1. گراف نمونه
  2. یال‌های ساده و شرطی
  3. ابزار Send: یک وظیفه برای هر آیتم
  4. ساختار Command: به‌روزرسانی و مسیریابی در یک گام

یال ساده همیشه اجرا می‌شود، یال شرطی مسیر را بر اساس وضعیت انتخاب می‌کند، Send برای هر آیتم یک وظیفه راه می‌اندازد و Command کار به‌روزرسانی و مسیریابی را در قالب یک مقدار بازگشتی انجام می‌دهد.

فهرستی از موضوعات دارید که تعدادشان را فقط در زمان اجرا می‌فهمید، و می‌خواهید برای هر موضوع یک بار مدل را فراخوانی کنید. بعد از آن‌ها، یک نود باید بین دو نقطه‌ی پایان تصمیم بگیرد و دلیلش را هم ثبت کند. در واقع در یک گراف به سه نوع مسیریابی (Routing) مختلف نیاز دارید.

پس از پایان این بخش، می‌توانید نودها را با یال‌های ساده و شرطی به هم متصل کنید. همچنین می‌توانید با Send تعداد متغیری وظیفه (Task) راه بیندازید و با Command مستقیماً از داخل یک نود مسیر بعدی را تعیین کنید.

گراف نمونه

گراف این کیت آموزشی در بخش 6.1 دارای 5 نود است. کد اتصال این نودها به یکدیگر به این صورت است:

گره‌ها و یال‌های گراف جوک capture/s_graph.py
    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) است:

یال‌های گراف کامپایل‌شده capture/out/34-stategraph-reducers-send-command.txt
	__start__ --> plan;
	pick -.-> publish;
	pick -.-> retry;
	plan -.-> write_joke;
	write_joke --> pick;
	publish --> __end__;
	retry --> __end__;

خطوط مربوط به یال‌ها در متن Mermaid. خطوط گره‌ها و استایل‌ها حذف شده‌اند.

هیچ فراخوانی مستقیمی با add_edge از نود pick خارج نمی‌شود، اما گراف دو یال خروجی از آن دارد. همان‌طور که در بخش بعد می‌بینید، این یال‌ها از نوع بازگشتی نود pick استخراج شده‌اند.

تصویر نمودار کامل Mermaid را از بالا به پایین نشان می‌دهد.

گراف جوک به همان شکلی که LangGraph رسم می‌کندمتن Mermaid دارای سه یال شرطی از plan و pick است، و هیچ فراخوانی add_edge آن‌ها را نساخته است.
گراف جوک به شکلی که LangGraph رسم می‌کند گراف جوکِ کامپایل‌شده که از خروجی draw_mermaid آن از بالا به پایین رسم شده است. دارای 7 گره و 7 یال است. 3 یال شرطی عبارتند از pick به publish، pick به retry، و plan به write_joke. یال خروجی از plan از add_conditional_edges به همراه Send حاصل می‌شود. دو یال خروجی از pick نیز از نوع بازگشتی Command در pick به دست می‌آیند، بدون هیچ فراخوانی add_edge. GET_GRAPH().DRAW_MERMAID() 4 یال ساده، 3 شرطی __start__ plan write_joke pick publish retry __end__ Send: one write_joke task for each subject تابع pick یک Command برمی‌گرداند یال ساده یال شرطی، انتخاب‌شده در زمان اجرا
از __start__ در بالا بخوانید. فلش‌های توپر فراخوانی‌های add_edge هستند. فلش‌های خط‌چین کهربایی از Send و نوع بازگشتی Command می‌آیند. از capture/out/50-draw-fanout.txt.

تصویر ساختار گراف و یک دور اجرای کامل آن را رسم کرده است.

گراف جوک و یک بار اجرای آندستور Send سه وظیفه write_joke را در یک گام آغاز می‌کند، و Command از pick مقدار best را به‌روزرسانی کرده و به publish می‌رود، بنابراین retry هرگز اجرا نمی‌شود.
گراف جوک و یک بار اجرای آن بخش بالایی نمودار حاصل از ثبت است: __start__ به plan، سپس سه فلش Send از plan به سه وظیفه write_joke برای cats، dogs و owls در یک گام، و سپس یال‌های ساده به pick. گره pick یک شیء Command برمی‌گرداند که best روی «a joke about cats» و goto روی publish تنظیم شده است، بنابراین publish اجرا شده و سپس به __end__ می‌رسد. گره retry، یعنی مقصد دیگر pick، اجرا نشد. بخش پایینی جدولی از مواردی است که هر گره در طول 4 گام در وضعیت نوشته است، خوانده‌شده از استریم updates: گره plan فیلد subjects را نوشت، هر write_joke یک جوک نوشت، operator.add این سه را در یک لیست 3تایی ادغام کرد، و pick فیلد best را نوشت. کلید log در انتها 6 ورودی دارد. __start__ plan گام 1 write_joke cats write_joke dogs write_joke owls Send x 3 pick Command publish اجرا شد retry اجرا نشد goto publish __end__ آنچه هر گام در وضعیت نوشت گام 1 گام 2 گام 3 گام 4 subjects cats, dogs, owls jokes جوکی درباره گربه‌ها جوکی درباره سگ‌ها جوکی درباره جغدها operator.add: 3 مورد یک لیست واحد در وضعیت best جوکی درباره گربه‌ها log plan write_joke(cats) write_joke(dogs) write_joke(owls) pick -> publish publish سه نوشتن در jokes در یک گام به یک لیست ادغام شدند. کلید log با 6 ورودی خاتمه می‌یابد. هر خانه فیروزه‌ای یک مقدار بازگردانده‌شده توسط گره است که از استریم updates خوانده شده است.
از __start__ در سمت چپ به سمت __end__ در راست بخوانید. فلش‌های توپر یال‌های ساده هستند، و فلش‌های خط‌چین کهربایی مسیرهای انتخاب‌شده در زمان اجرا هستند. گره خاکستری retry اجرا نشد. جدول زیر نشان می‌دهد هر گام چه چیزی در وضعیت نوشت. برگرفته از capture/out/34-stategraph-reducers-send-command.txt.

یال‌های ساده و شرطی

یال ساده: یالی از یک نود به نود دیگر که LangGraph با هر بار پایان کار نود اول، مسیر آن را پیش می‌گیرد.

یال شرطی: یالی همراه با یک تابع مسیریابی. پس از اجرای نود مبدأ، این تابع وضعیت را می‌خواند و نود بعدی، فهرستی از نودها یا مقدار END را برمی‌گرداند.

آرگومان سوم در add_conditional_edges فهرستی از نودهایی است که این تابع می‌تواند خروجی دهد. LangGraph از این فهرست برای رسم ساختار گراف استفاده می‌کند. بخش 1.3 یال‌های شرطی یک ایجنت (Agent) را نشان داد: پس از نود model، فراخوانی‌های ابزار (Tool calls) در آخرین پیام تعیین می‌کنند که مسیر به سمت tools برود یا __end__.

ابزار Send: یک وظیفه برای هر آیتم

مفهوم Send: مقداری که نام یک نود و ورودی اختصاصی برای یک بار اجرای آن را مشخص می‌کند. تابع مسیریابی با بازگرداندن فهرستی از این مقادیر، در همان گام اجرایی برای هر آیتم یک وظیفه راه می‌اندازد.

تابع fan_out همان تابع مسیریابی بعد از نود plan است. این تابع فیلد subjects را می‌خواند و به ازای هر موضوع، یک شیء Send برمی‌گرداند. هر وظیفه‌ی write_joke دیکشنری کوچک و اختصاصی خودش را به عنوان ورودی می‌گیرد و به کل وضعیت دسترسی ندارد:

تابع مسیریابی و گره‌ای که آغاز می‌کند capture/s_graph.py
    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 capture/out/34-stategraph-reducers-send-command.txt
  "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 می‌برد:

گره‌ای که یک Command برمی‌گرداند capture/s_graph.py
    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 اجرا نشد. دو تکه‌ی آخر استریم این موضوع را نشان می‌دهند:

دو چانک پایانی اجرا capture/out/34-stategraph-reducers-send-command.txt
{
  "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).

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