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

سفر در زمان: بازپخش، update_state و forkها

Time travel: replay, update_state, and forks

فهرست مطالب
  1. تاریخچه‌ی یک thread
  2. بازپخش
  3. ایجاد fork با update_state
  4. ثبت وضعیت به جای گره با as_node
  5. آدرس باید کامل باشد
  6. یافته‌های آزمایشگاه

بازپخش (replay) از یک چک‌پوینت قبلی، تمام گره‌های بعدی را دوباره اجرا می‌کند؛ update_state نیز شاخه‌ای جدید در کنار شاخه‌ی قبلی می‌سازد. بنابراین هیچ‌کدام نتایج ذخیره‌شده را بازخوانی نمی‌کنند و تاریخچه را هم پاک نمی‌کنند.

فرض کنید ایجنتی کارتی را شارژ کرده است و می‌خواهید ببینید اگر دستور دیگری به آن می‌دادید چه می‌کرد. یکی از چک‌پوینت‌های قبلی تاریخچه را برمی‌دارید و اجرا را از همان‌جا آغاز می‌کنید. کارت برای بار دوم شارژ می‌شود؛ چون بازپخش، نتیجه‌ی قبلی ابزار را نمی‌خواند، بلکه ابزار را دوباره فراخوانی می‌کند.

پس از پایان این بخش، می‌توانید تاریخچه‌ی یک thread را فهرست کنید، اجرا را از هر چک‌پوینتی بازپخش کنید و با update_state یک fork بسازید. همچنین می‌توانید مشخص کنید دقیقاً کدام گره‌ها از نو اجرا می‌شوند.

تاریخچه‌ی یک thread

تاریخچه‌ی وضعیت (State history): فهرستی از چک‌پوینت‌های یک thread به ترتیب از جدیدترین به قدیمی‌ترین، که از خروجی get_state_history(config) به دست می‌آید.

ایجنت این کیت آموزشی یک ابزار دارد: charge، که مبالغ شارژشده را ثبت می‌کند. یک نوبت گفت‌وگو با دستور .Charge 10 پنج چک‌پوینت ذخیره کرد. هر چک‌پوینت نام والد خود را نگه می‌دارد و جدیدترین آن‌ها گره بعدی ندارد:

تاریخچه‌ی یک نوبت گفت‌وگو capture/out/30-state-history-forks.txt
  "step": 3,
  "source": "loop",
  "next": [],
  "checkpoint_id": "<uuid-1>",
  "parent_checkpoint_id": "<uuid-2>",
…
  "step": 2,
  "source": "loop",
  "next": [
    "model"
  ],
  "checkpoint_id": "<uuid-2>",
  "parent_checkpoint_id": "<uuid-3>",

خلاصه‌شده به گام، منبع، گره‌های بعدی و شناسه‌های دو چک‌پوینت اول. پیام‌ها حذف شده‌اند.

فیلد config در هر ورودی شامل thread_id ،checkpoint_ns و checkpoint_id است. این کانفیگ در واقع آدرس دقیق چک‌پوینت برای تمام فراخوانی‌های بعدی به شمار می‌رود.

بازپخش

بازپخش (Replay): یعنی فراخوانیِ invoke(None, config) در شرایطی که config به یک چک‌پوینت در گذشته اشاره کند. اجرا از همان چک‌پوینت شروع می‌شود و گره‌های موجود در فیلد next آن را دوباره اجرا می‌کند.

کیت، اجرا را از چک‌پوینتی بازپخش می‌کند که مقدار next آن برابر با tools است. ابزار برای بار دوم اجرا شد و تعداد چک‌پوینت‌های این thread از 5 به 8 رسید:

یک بازپخش از چک‌پوینت پیش از ابزارها capture/out/30-state-history-forks.txt
charge calls so far (the tool ran again on replay):
[
  10,
  10
]

checkpoints on the thread now: 8

مدل دقیقاً همان پیام‌های دور اول را دریافت کرد. با دمای 0 (temperature 0) همان پاسخ قبلی را داد: .The card has been successfully charged with 10 units، و کارت دو بار شارژ شد. مدلی که نمونه‌برداری (sampling) آن روشن باشد، ممکن است در بازپخش پاسخ متفاوتی بدهد. مستندات سفر در زمان (Time-travel) هم به همین نکته اشاره می‌کند: بازپخش، گره‌ها را همراه با فراخوانی‌های مدل، درخواست‌های API و وقفه‌ها دوباره اجرا می‌کند {{docs oss/python/langgraph/use-time-travel}}.

ایجاد fork با update_state

انشعاب (Fork): چک‌پوینت جدیدی که والد آن یکی از چک‌پوینت‌های گذشته است. اجراهای بعدی از این نقطه، شاخه‌ای در کنار شاخه‌ی قبلی می‌سازند و چک‌پوینت‌های قدیمی دست‌نخورده باقی می‌مانند.

متد update_state(config, values) مقادیر values را در چک‌پوینت جدیدی پس از چک‌پوینتِ مشخص‌شده در config می‌نویسد. این به‌روزرسانی درست مانند خروجی یک گره، از کاهنده‌ها (reducers) عبور می‌کند. کیت، یک پیام کاربر به اولین چک‌پوینت model اضافه می‌کند:

یک fork با یک پیام کاربر بیشتر capture/s_persist.py
    first_model = next(s for s in reversed(states) if s.next == ("model",))
    forked = agent.update_state(first_model.config, {"messages": [{"role": "user", "content": "Actually, charge 99."}]})

چک‌پوینت جدید منبعی از نوع update و شماره گام 1 دارد و والد آن چک‌پوینتِ گام 0 است. مقدار next آن همچنان model باقی مانده است. اجرای مجدد از این نقطه، کارت را به مبلغ 99 واحد شارژ کرد و تراکنش‌های شاخه‌ی اول نیز در فهرست باقی ماندند:

عملیات fork و اجرای حاصل از آن capture/out/30-state-history-forks.txt
  "step": 1,
  "source": "update",
  "next": [
    "model"
  ],
  "checkpoint_id": "<uuid-6>",
  "parent_checkpoint_id": "<uuid-4>",
…
charge calls:
[
  10,
  10,
  99
]

مورد fork خلاصه‌شده به گام، منبع، بعدی و والد آن، و سپس هزینه‌ها پس از اجرا.

صفحه‌ی مستندات سفر در زمان هشدار می‌دهد که update_state وضعیت یک thread را به عقب برنمی‌گرداند (roll back نمی‌کند) {{docs oss/python/langgraph/use-time-travel}}. این thread اکنون سه شاخه دارد: اجرای اول، بازپخش و fork.

ثبت وضعیت به جای گره با as_node

متد update_state آرگومانی به نام as_node می‌پذیرد؛ یعنی گره‌ای که این به‌روزرسانی به حساب آن گذاشته می‌شود. سپس LangGraph گره بعدی را طوری انتخاب می‌کند که گویی همان گره واقعاً اجرا شده است. ایجنت کیت با دستور interrupt_before=["tools"] پیش از گره tools متوقف می‌شود. سپس نتیجه‌ی ابزار را دستی و در قالب گره tools می‌نویسد و روند اجرا به سمت model ادامه پیدا می‌کند:

نتیجه‌ی دستی نوشته‌شده برای یک ابزار capture/out/30-state-history-forks.txt
[
  "human: Charge 5.",
  "ai: ",
  "tool: charged 5 by hand",
  "ai: It seems there was a misunderstanding. I cannot perform actions like charging a card manually. If you'd like, I can assist you with other tasks or help guide you through the correct process. Let me know how I can assist!"
]

charge calls (unchanged):
[
  10,
  10,
  99
]

در این سناریو ابزار اجرا نشد. سپس مدل پاسخ داد که نمی‌تواند کارت را دستی شارژ کند؛ در واقع نتیجه‌ای را که دستی نوشته شده بود اشتباه برداشت کرد. چنین نتیجه‌ای را دقیقاً با همان کلماتی بنویسید که خود ابزار استفاده می‌کرد، مثلاً charged 5. این قابلیت زمانی به کار می‌آید که فردی خارج از ایجنت کار ابزار را انجام داده باشد. پیام ToolMessage حتماً باید tool_call_id فراخوانیِ منتظر را به همراه داشته باشد.

آدرس باید کامل باشد

متد update_state به آدرس کامل یک چک‌پوینت نیاز دارد. در آزمایشگاه وقتی این متد با کانفیگی فراخوانی شد که فقط thread_id و checkpoint_id داشت، خطای 'KeyError: 'checkpoint_ns رخ داد. یا باید config یکی از ورودی‌های حاصل از get_state_history را ارسال کنید، یا برای گرافی که زیرگراف (subgraph) ندارد، مقدار "" :checkpoint_ns" را به آن بیفزایید.

یافته‌های آزمایشگاه

ما اندازه‌گیری کردیم: بازپخش‌ها و forkها را روی سیستم Mac، یک دور در هر سناریو و با استفاده از InMemorySaver اندازه گرفتیم. گرافی سه گره b ،a و c را پشت سر هم اجرا کرد و هر کدام یک واحد به x افزودند. اجرای اول 5 چک‌پوینت ذخیره کرد. بازپخش از چک‌پوینت قبل از b گره b را یک بار و c را هم یک بار اجرا کرد، a را صفر بار اجرا کرد و 3 چک‌پوینت جدید ساخت. منبع یکی از این سه چک‌پوینت، fork بود.

اجرای update_state روی همان چک‌پوینت، مقدار x را برابر با 100 قرار داد. این کار هیچ گره‌ای را اجرا نکرد، یک چک‌پوینت با منبع update افزود و همه‌ی چک‌پوینت‌های قبلی را نگه داشت. اجرای گراف از این نقطه، b و c را هر کدام یک بار اجرا کرد و مقدار x در نهایت به 102 رسید. در این لحظه، thread شامل 11 چک‌پوینت در سه شاخه بود. تصویر آن‌ها را رسم کرده است.

سه branch از یک threadیک بازپخش و یک update_state از چک‌پوینت قبل از b هر کدام یک branch در کنار اجرای اول باز می‌کنند و تمام چک‌پوینت‌های قدیمی باقی می‌مانند.
سه branch از یک thread درختی از 11 چک‌پوینت یک thread. اجرای اول گام‌های 1- تا 3 را با مقدار x از none تا 3 ذخیره کرد. از چک‌پوینت گام 1، که گره بعدی آن b است، یک بازپخش یک چک‌پوینت fork در گام 2 با مقدار x برابر 1 و دو چک‌پوینت حلقه اضافه کرد که به x برابر 3 ختم می‌شوند. تابع update_state روی همان چک‌پوینت، یک چک‌پوینت به‌روزرسانی در گام 2 با x برابر 100 اضافه کرد و اجرای حاصل از آن به x برابر 102 ختم شد. تمام چک‌پوینت‌های قدیمی باقی ماندند. گام 1-، ورودی x = none, next __start__ گام 0، حلقه x = 0, next a گام 1، حلقه x = 1, next b اجرای نخست گام 2، حلقه x = 2, next c گام 3، حلقه x = 3, next none بازپخش گام 2، fork x = 1, next b گام 3، حلقه x = 2, next c گام 4، حلقه x = 3, next none UPDATE_STATE گام 2، update x = 100, next b گام 3، حلقه x = 101, next c گام 4، حلقه x = 102, next none هر جعبه یک چک‌پوینت از یک اجرا روی مک است. چک‌پوینت‌های قدیمی هرگز حذف نمی‌شوند.
از چک‌پوینت ورودی در بالا بخوانید. هر جعبه یک چک‌پوینت به همراه گام و مقدار x است. جعبه‌ی کهربایی fork مربوط به بازپخش است و جعبه‌ی بنفش مربوط به به‌روزرسانی است. از capture/lab/summary/replay-fork-mac.json.

یک ایجنت با مدل Qwen3 4B و یک ابزار، در 3 بار اجرا روی سرور مهمان x86، در تمام دورها نتایج کاملاً یکسانی به دست داد. بازپخش از گام 0 که مقدار next آن model بود، 2 فراخوانی مدل و 1 فراخوانی ابزار انجام داد. بازپخش از گام 1 که مقدار next آن tools بود، 1 فراخوانی مدل و 1 فراخوانی ابزار انجام داد. بنابراین هزینه‌ی بازپخش برابر با هزینه‌ی اجرای اصلی از همان نقطه به بعد است. همیشه قبل از بازپخش، مطمئن شوید که اجرای مجدد تمام گره‌های بعد از آن چک‌پوینت خطری ندارد و ایمن است.

مستندات می‌گویند امکان سفر در زمان به نقطه‌ای میان گره‌های یک زیرگراف پیش‌فرض وجود ندارد {{docs oss/python/langgraph/use-time-travel}}. در آزمایشگاه، سفر در زمان داخل زیرگراف اجرا نشد. این موضوع در کنار سایر موارد بازِ بخش 8.8، در ویرایش بعدی بررسی خواهد شد.

منابع: capture/s_persist.py، capture/out/30-state-history-forks.txt؛ capture/lab/summary/replay-fork-mac.json، capture/lab/T17-claims-mac/02-replay-and-fork.jsonl، capture/lab/summary/replay-fork-x86.json، capture/lab/T17-claims-x86/01-claims.jsonl؛ فایل‌های libs/langgraph/langgraph/pregel/main.py و libs/checkpoint/langgraph/checkpoint/memory/init.py در نسخه langgraph 1.2.22؛ مستندات docs.langchain.com در commit شماره 04d4d4a (بخش oss/python/langgraph/use-time-travel).

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