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

رابط برنامه‌نویسی تابعی: ‎@entrypoint‎ و ‎@task‎

The functional API: @entrypoint and @task

فهرست مطالب
  1. نقطه‌ی ورود و وظایف آن
  2. توقف اجرای اول درون یک وظیفه
  3. ازسرگیری و بازیابی وظایف پایان‌یافته
  4. مقداری که روی رشته‌ی گفت‌وگو می‌ماند
  5. یک گره، نه گرافی از گره‌ها

هر تابع ‎@entrypoint‎ هنگام ازسرگیری، دوباره از ابتدا اجرا می‌شود؛ اما هر ‎@task‎ که پیش از توقف تمام شده باشد، به‌جای اجرای مجدد، نتیجه‌ی ذخیره‌شده‌ی خود را برمی‌گرداند.

فرض کنید یک تابع معمولی پایتون دارید که سه سرویس را پشت سر هم صدا می‌زند. حالا می‌خواهید این تابع برای تایید یک فرد متوقف شود و در برابر ری‌استارت شدن برنامه هم دوام بیاورد. اگر بخواهید آن را به‌صورت گره‌ها و یال‌ها بازنویسی کنید، کدی را که در حال حاضر کار می‌کند دستکاری کرده‌اید. رابط برنامه‌نویسی تابعی (functional API) ساختار تابع را دست‌نخورده نگه می‌دارد و فقط دور فراخوانی‌های آن چک‌پوینت می‌گذارد.

پس از پایان این بخش، می‌توانید یک تابع را به یک ‎@entrypoint‎ همراه با فراخوانی‌های ‎@task‎ تبدیل کنید. همچنین می‌توانید پیش‌بینی کنید که هنگام ازسرگیری کدام فراخوانی‌ها دوباره اجرا می‌شوند و چطور مقداری را بین دفعات مختلف اجرا نگه دارید.

نقطه‌ی ورود و وظایف آن

نقطه‌ی ورود (Entrypoint): تابعی که با ‎@entrypoint‎ دکوریت شده است. LangGraph آن را مانند گرافی با یک گره تکی اجرا می‌کند و وقتی چک‌پوینتری به آن بدهید، چک‌پوینت‌ها را روی رشته‌ی گفت‌وگویش (thread) ذخیره می‌سازد.

وظیفه (Task): تابعی مجهز به دکوراتور ‎@task‎. فراخوانی آن بلافاصله یک فیوچر (future) برمی‌گرداند و LangGraph به محض پایان کار وظیفه، نتیجه‌اش را ذخیره می‌کند.

جریان کاری کیت، سه عدد را در دل سه وظیفه دو برابر می‌کند، آن‌ها را با هم جمع می‌زند و از یک فرد می‌پرسد که مجموع نهایی را نگه دارد یا نه. این پرسش در قالب یک وقفه (interrupt) درون یک وظیفه قرار دارد:

یک entrypoint با سه وظیفه و یک سؤال capture/s_graph.py
    @task
    def double(x: int) -> int:
        runs.append(f"double({x})")
        return x * 2

    @task
    def ask_human(total: int) -> str:
        return interrupt({"total": total, "question": "Keep it?"})

    @entrypoint(checkpointer=InMemorySaver())
    def workflow(numbers: list[int]) -> dict:
        futures = [double(n) for n in numbers]
        total = sum(f.result() for f in futures)
        answer = ask_human(total).result()
        return {"total": total, "answer": answer}

هر سه فراخوانی double، هر سه وظیفه را پیش از رسیدن به اولین result() آغاز می‌کنند و هر result() منتظر پایان یکی از آن‌ها می‌ماند.

مستندات رابط تابعی سه قاعده برای این کد مشخص کرده است {{docs oss/python/langgraph/functional-api}}: نقطه‌ی ورود فقط یک آرگومان موضعی (positional argument) می‌گیرد؛ اگر چک‌پوینتر تنظیم شده باشد، ورودی و خروجی نقطه‌ی ورود و خروجی هر وظیفه باید قابلیت سریال‌سازی به JSON را داشته باشند؛ و وظیفه را فقط می‌توان از داخل یک نقطه‌ی ورود، وظیفه‌ای دیگر، یا گره‌ای از یک گراف صدا زد.

توقف اجرای اول درون یک وظیفه

اجرای اول، اعداد 1، 2 و 3 را دو برابر کرد، به عدد 12 رسید و روی پرسش متوقف شد. فراخوانی invoke با آرگومان version="v2" مقدار خروجی و وقفه‌ها را جدا از هم برمی‌گرداند:

اولین اجرای جریان کاری capture/out/35-functional-api.txt
{
  "value": {},
  "interrupts": [
    {
      "value": {
        "total": 12,
        "question": "Keep it?"
      },
      "id": "<hex-1>",
      "response_schema": null
    }
  ]
}

task runs:
[
  "double(1)",
  "double(2)",
  "double(3)"
]

مقدار خروجی خالی است، چون تابع چیزی برنگردانده و اجرای آن تمام نشده است.

ازسرگیری و بازیابی وظایف پایان‌یافته

ارسال Command(resume="yes") روی همان رشته‌ی گفت‌وگو، workflow را دوباره از خط اولش اجرا می‌کند. سه فراخوانی double نتایج ذخیره‌شده‌ی خود را برمی‌گردانند و بدنه‌ی double اصلاً اجرا نمی‌شود. تابع ask_human مقدار "yes" را از interrupt دریافت می‌کند و تابع به پایان می‌رسد:

ادامه‌ی اجرای جریان کاری (resume) capture/out/35-functional-api.txt
{
  "total": 12,
  "answer": "yes"
}

task runs:
[
  "double(1)",
  "double(2)",
  "double(3)"
]

فهرست دفعات اجرای وظایف همچنان سه مورد دارد؛ مستندات نیز همین را می‌گوید. ازسرگیری از بالاترین نقطه‌ی entrypoint شروع می‌شود و چک‌پوینتر نتایج وظایف پایان‌یافته را برمی‌گرداند {{docs oss/python/langgraph/functional-api}}. شکل هر دو اجرا را نشان می‌دهد.

دو بار اجرای یک entrypointادامه‌ی اجرا (resume) جریان کاری را از ابتدا اجرا می‌کند، سه وظیفه‌ی double نتایج ذخیره‌شده را بدون اجرا بازمی‌گردانند و فقط ask_human دوباره اجرا می‌شود.
دو بار اجرای یک entrypoint پنج خط حیات: کد شما، نقطه ورود جریان کاری، وظیفه double، وظیفه ask_human و چک‌پوینتر. ستون ششم لاگ بدنه‌های وظایف اجراشده است که از خروجی خوانده شده است. اجرای 1: با ورودی‌های 1، 2 و 3 فراخوانی می‌شود، بدنه‌های double(1)، double(2) و double(3) را اجرا می‌کند، نتایج 2، 4 و 6 را ذخیره کرده، ask_human را با 12 فراخوانی می‌کند و با وقفه "Keep it?" متوقف می‌شود. اجرای 2: دستور Command با مقدار resume="yes" جریان کاری را دوباره از بالا اجرا می‌کند. فراخوانی‌های double نتایج ذخیره‌شده را بازمی‌گردانند و لاگ هیچ ورودی جدیدی ثبت نمی‌کند. ask_human مقدار yes را دریافت می‌کند و جریان کاری مجموع 12 و پاسخ yes را برمی‌گرداند. کد شما invoke workflow @entrypoint double @task ask_human @task چک‌پوینتر InMemorySaver وظایف اجراشده لاگ، به‌ترتیب اجرای 1 1 invoke([1, 2, 3]) 2 double(1), (2), (3) double(1) double(2) double(3) 3 نتایج 2، 4، 6 4 ask_human(12) 5 وقفه: نگه‌داشته شود؟ اجرای 2، ادامه‌ی اجرا 6 Command(resume='yes') 7 double(1), (2), (3) 0 ورودی جدید 8 ذخیره‌شده: 2، 4، 6 9 2، 4، 6، بدون اجرا 10 ask_human(12) 11 'yes' 12 مجموع 12، پاسخ yes 3 ورودی پس از هر دو اجرا: هر double یک‌بار اجرا شد
اجرای 1 را در بالا و اجرای 2 را زیر آن بخوانید. فلش‌های فیروزه‌ای نتایج ذخیره‌شده هستند و ردیف کهربایی نشان‌دهنده‌ی وقفه است. ستون راست، لاگ بدنه‌های وظایفی است که اجرا شده‌اند. برگرفته از capture/out/35-functional-api.txt.

کدی که مستقیماً در خود نقطه‌ی ورود نوشته می‌شود وظیفه نیست؛ بنابراین همان‌طور که در مستندات آمده، در هر بار ازسرگیری دوباره اجرا خواهد شد. محاسبه‌ی مجموع در کیت از همین جنس کدهاست، و کیت فقط دفعات اجرای وظایف را ثبت می‌کند. هر عملیاتی را که اثر جانبی (side effect) دارد درون یک وظیفه بگذارید تا ازسرگیری از نتایج ذخیره‌شده پیش برود. کرش کردن برنامه پس از اعمال اثر و پیش از ذخیره شدن نتیجه می‌تواند باعث اجرای دوباره‌ی وظیفه شود. بنابراین اثر جانبی را هم بی‌اثر در تکرار (idempotent) طراحی کنید، همان‌طور که در بخش 5.3 نشان داده شده است.

استریم updates در یک اجرای جدید، برای هر وظیفه‌ی پایان‌یافته یک تکه‌داده (chunk) تولید می‌کند که کلید آن نام وظیفه است. اجرا با ورودی [5] ابتدا تکه‌داده‌ی {"double": 10} و سپس تکه‌داده‌ی __interrupt__ را تحویل داد.

مقداری که روی رشته‌ی گفت‌وگو می‌ماند

entrypoint.final: مقدار بازگشتی یک نقطه‌ی ورود که خروجی تحویل‌داده‌شده به فراخواننده را از آنچه روی رشته‌ی گفت‌وگو ذخیره می‌شود جدا می‌کند. مقدار ذخیره‌شده، در اجرای بعدی به‌عنوان آرگومان previous برمی‌گردد.

شمارنده‌ی موجود در کیت، هر ورودی را با مجموع ذخیره‌شده جمع می‌زند. این شمارنده یک جمله برمی‌گرداند و عدد را ذخیره می‌کند:

شمارنده‌ای که مقدار کل خود را حفظ می‌کند capture/s_graph.py
    @entrypoint(checkpointer=InMemorySaver())
    def counter(n: int, *, previous: int | None = None) -> entrypoint.final[int, int]:
        total = (previous or 0) + n
        return entrypoint.final(value=f"added {n} to {previous}, saved {total}", save=total)

سه بار فراخوانی روی یک رشته‌ی گفت‌وگو با مقادیر 3، 4 و 5 چنین مقادیری را برگرداند:

سه بار فراخوانی شمارنده capture/out/35-functional-api.txt
three calls:
[
  "added 3 to None, saved 3",
  "added 4 to 3, saved 7",
  "added 5 to 7, saved 12"
]

نخستین فراخوانی، مقدار previous را برابر با None دریافت کرد. هر فراخوانی بعدی، عددی را گرفت که فراخوانی قبل از آن ذخیره کرده بود. نوع بازگشتی entrypoint.final[int, int] در کیت با مقدار رشته‌ای هم‌خوانی ندارد، اما اجرا همچنان کار می‌کند؛ چون LangGraph آن را بررسی نمی‌کند.

یک گره، نه گرافی از گره‌ها

گراف این جریان کاری سه گره دارد: __start__، workflow و __end__. وظایف گره نیستند؛ بنابراین در رسم گراف هیچ‌کدام از آن‌ها دیده نمی‌شوند. مستندات رابط تابعی می‌گوید برای ایجنت‌ها و جریان‌های کاری جدید از رابط گرافی استفاده کنید. این مستندات، رابط تابعی را برای ایجنتی پیشنهاد می‌کند که از قبل در کدهای دیگر پیاده شده است و باید روی Agent Server اجرا شود {{docs oss/python/langgraph/functional-api}}.

شکل گراف را بر اساس متن Mermaid آن رسم می‌کند.

گرافِ یک entrypointیک entrypoint به صورت یک گره بین __start__ و __end__ کامپایل می‌شود و وظایف آن درون همان گره و بدون هیچ گره اختصاصی برای خود اجرا می‌شوند.
گرافِ یک entrypoint گراف نقطه ورود جریان کاری، برگرفته از خروجی draw_mermaid آن. این گراف 3 گره دارد: workflow، __start__ و __end__. یک یال ساده از __start__ به workflow می‌رود و یک یال شرطی از workflow به __end__ متصل است. وظایف double و ask_human درون گره workflow اجرا می‌شوند و در گراف وجود ندارند. GET_GRAPH() OF AN @ENTRYPOINT 3 گره، بدون گره وظیفه __start__ workflow __end__ double and ask_human run in here یال ساده یال شرطی، انتخابی در زمان اجرا
از بالا به پایین بخوانید. گره جریان کاری کل تابع را اجرا می‌کند و هر فراخوانی وظیفه درون آن اجرا می‌شود. برگرفته از capture/out/51-draw-functional.txt.

یک وظیفه همچنین می‌تواند retry_policy ،cache_policy و timeout بگیرد {{code libs/langgraph/langgraph/func/init.py}}. پارامتر timeout فقط روی وظایف ناهمگام (async) کار می‌کند و روی وظایف همگام (sync) خطای ValueError می‌دهد. کیت هنوز آن‌ها را روی یک وظیفه اجرا نکرده است. خروجی‌های ثبت‌شده‌ی آن‌ها در ویرایش بعدی، همراه با دیگر موضوعات بازِ بخش 8.8 ارائه می‌شوند.

منابع: capture/s_graph.py، capture/out/35-functional-api.txt، capture/out/51-draw-functional.txt؛ libs/langgraph/langgraph/func/init.py در langgraph 1.2.22؛ docs.langchain.com در commit مستندات 04d4d4a (oss/python/langgraph/functional-api).

ترجمه‌ی فارسی The functional API: @entrypoint and @task از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما