بخش 5.2 · وضعیت، حافظه و پایایی

چک‌پوینترها و رشته‌ها: حافظه‌ی کوتاه‌مدت

Checkpointers and threads: short-term memory

فهرست مطالب
  1. یک رشته در طول دو نوبت گفت‌وگو
  2. درون یک چک‌پوینت چه می‌گذرد؟
  3. عملکرد SqliteSaver در صورت ری‌استارت برنامه
  4. اجرای چندین رشته روی یک ذخیره‌ساز Postgres

چک‌پوینتر وضعیت گراف را بعد از هر گام ذخیره می‌کند؛ بنابراین نوبت گفت‌وگوی بعدی روی همان thread_id از آخرین چک‌پوینت شروع می‌شود، حتی پس از ری‌استارت شدن برنامه.

فرض کنید چتی را بر پایه‌ی create_agent می‌سازید و کاربر می‌پرسد: «من قبلاً چه سؤالی ازت پرسیدم؟». ایجنت اصلاً نمی‌داند کاربر چه می‌گوید، چون هر invoke با وضعیتی کاملاً خالی شروع شده است. مشکل از مدل نیست؛ ایجنت هیچ چیزی را بین اجراها نگه نمی‌دارد، مگر این‌که چیزی وضعیت را ذخیره کند.

با پایان این بخش، می‌توانید به یک ایجنت حافظه‌ی کوتاه‌مدت بدهید، یک چک‌پوینت را بخوانید و ظرفیت مناسب ذخیره‌ساز Postgres را برای چندین رشته تعیین کنید.

یک رشته در طول دو نوبت گفت‌وگو

چک‌پوینتر (Checkpointer): شیئی که وضعیت گراف را پس از هر گام ذخیره می‌کند و هنگام شروع اجرای بعدی، آخرین چک‌پوینت را بارگذاری می‌کند. InMemorySaver، SqliteSaver و PostgresSaver نمونه‌هایی از چک‌پوینتر هستند.

رشته (Thread): توالی چک‌پوینت‌هایی است که با یک thread_id یکسان ذخیره می‌شوند. رشته همان گفت‌وگو است و هر بار اجرای invoke روی آن، یک نوبت گفت‌وگو محسوب می‌شود.

کیت دو نوبت گفت‌وگو را روی رشته‌ی memory-thread اجرا می‌کند:

دو نوبت گفت‌وگو در یک thread capture/s_persist.py
def two_turns(cap, checkpointer, name):
    m = llm(name)
    agent = create_agent(m, tools=[add], checkpointer=checkpointer)
    cfg = thread(name)
    agent.invoke(ask("What is 2 + 3?"), cfg)
    out = agent.invoke(ask("What did I ask you?"), cfg)

در نوبت دوم فقط یک پیام جدید فرستاده شد. مدل کل نوبت اول را پیش از این پیام دریافت کرد:

آنچه مدل در نوبت 2 دریافت کرد capture/out/28-checkpoint-memory.txt
what the model received on turn 2:
[
  "human: What is 2 + 3?",
  "ai: calls add",
  "tool: 5",
  "ai: 2 + 3 = 5.",
  "human: What did I ask you?"
]

مدل Qwen3 4B پاسخ داد: You asked what 2 + 3 is, and I calculated that it equals 5..

پس حافظه‌ی کوتاه‌مدت در واقع همان لیست پیام‌ها داخل چک‌پوینت است. کاهنده‌ی (Reducer) تابع add_messages پیام جدید کاربر را به این لیست اضافه می‌کند و در هر فراخوانی مدل، کل تاریخچه ارسال می‌شود. هزینه‌ی طولانی شدن رشته را در بخش 5.5 بررسی می‌کنیم.

اجرا روی چک‌پوینتر به thread_id نیاز دارد. بدون آن، ایجنت پیش از اجرا خطا می‌دهد:

یک چک‌پوینتر بدون thread_id capture/out/28-checkpoint-memory.txt
raised builtins.ValueError: Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id

یک thread_id جدید کارش را با وضعیت خالی شروع می‌کند. در این کیت، ایجنت دوم روی همان ذخیره‌ساز با رشته‌ی other-thread فقط سؤال خودش را دید. وقتی از آن پرسیده شد What did I ask you?، مدل پاسخ داد که این اولین گفت‌وگوی آن‌هاست. متد delete_thread("memory-thread") همه‌ی 8 چک‌پوینت رشته‌ی اول را پاک کرد.

لازم نیست رشته را از قبل بسازید؛ اولین چک‌پوینت خودش آن را ایجاد می‌کند. در صفحه‌ی checkpointers مستندات آمده است که رشته باید پیش از اجرا ایجاد شود، اما این قاعده متعلق به Agent Server API است {{docs oss/python/langgraph/checkpointers}}. این راهنما آن را به عنوان تعارض D118 ثبت کرده است.

درون یک چک‌پوینت چه می‌گذرد؟

تاپل چک‌پوینت (Checkpoint tuple): خروجی چک‌پوینتر برای یک چک‌پوینت است: پیکربندی (config)، فراداده‌ی آن (metadata)، خود checkpoint، پیکربندی والد آن، و عملیات‌های نوشتنِ معلق (pending writes).

آخرین چک‌پوینت این thread capture/out/28-checkpoint-memory.txt
{
  "config": {
    "configurable": {
      "thread_id": "memory-thread",
      "checkpoint_ns": "",
      "checkpoint_id": "<uuid-1>"
    }
  },
  "metadata": {
    "source": "loop",
    "step": 6,
    "parents": {},
    "ls_integration": "langchain_create_agent"
  },
  "checkpoint keys": [
    "channel_values",
    "channel_versions",
    "id",
    "ts",
    "updated_channels",
    "v",
    "versions_seen"
  ],
  "channel_values keys": [
    "__pregel_tasks",
    "messages"
  ],
…
  "v": 4
}

نسخه‌های کانال حذف شده‌اند.

فیلد channel_values وضعیت را نگه می‌دارد: در این‌جا همان لیست messages. فیلدهای channel_versions و versions_seen به حلقه نشان می‌دهند کدام گره‌ها ورودی جدید دارند، تا در صورت ادامه‌ی اجرا، گره‌ی درست بعدی اجرا شود. مقدار checkpoint_ns برای گراف اصلی خالی است و درون ساب‌گراف، نام گره‌ی والد را مشخص می‌کند.

عملکرد SqliteSaver در صورت ری‌استارت برنامه

کلاس InMemorySaver چک‌پوینت‌هایش را داخل فرایند (Process) نگه می‌دارد. صفحه‌ی پایداری داده‌ها (persistence) در مستندات می‌گوید با ری‌استارت شدن فرایند، تمام آن‌ها از بین می‌روند {{docs oss/python/langgraph/persistence}}. از این کلاس فقط برای تست‌ها استفاده کنید. یک فایل یا پایگاه داده رشته را در طول ری‌استارت حفظ می‌کند. کیت دو نوبت گفت‌وگو را روی SqliteSaver اجرا می‌کند، اتصال را می‌بندد و سپس فایل را با یک ایجنت جدید دوباره باز می‌کند:

باز کردن مجدد فایل و ادامه‌ی thread capture/s_persist.py
    with SqliteSaver.from_conn_string(path) as saver:
        agent = create_agent(llm("after-restart"), tools=[add], checkpointer=saver)
        out = agent.invoke(ask("Remind me what my first question was."), thread("sqlite-thread"))

نوبت سوم به هر شش پیام قبلی دسترسی داشت و مدل پاسخ داد: Your first question was, "What is 2 + 3?". این فایل شامل دو جدول است: checkpoints و writes:

دو جدول پس از سه نوبت گفت‌وگو capture/out/29-checkpoint-sqlite.txt
checkpoints: 11 rows, columns ['thread_id', 'checkpoint_ns', 'checkpoint_id', 'parent_checkpoint_id', 'type', 'checkpoint', 'metadata']

writes: 13 rows, columns ['thread_id', 'checkpoint_ns', 'checkpoint_id', 'task_id', 'task_path', 'idx', 'channel', 'type', 'value']

نوشتن معلق (Pending write): مقداری است که یک وظیفه (Task) حین یک گام نوشته و در جدول writes ذیل چک‌پوینتی که گام از آن شروع شده، ذخیره می‌شود. هنگام ادامه‌ی کار، LangGraph عملیات‌های نوشتن معلقِ آخرین چک‌پوینت را اعمال می‌کند و آن وظایف را دوباره اجرا نمی‌کند.

حلقه، هر نوشتن معلق را پس از پایان کارِ وظیفه در پس‌زمینه ذخیره می‌کند و منتظر آن فراخوانی نمی‌ماند {{code libs/langgraph/langgraph/pregel/_loop.py:523-551}}. بنابراین ممکن است یک نوشتن معلق، پس از چک‌پوینتِ گام خود به ذخیره‌ساز برسد. یک ردگیری محاسبات (Trace) در بخش 2.3 نشان می‌دهد که روی SqliteSaver با تنظیم durability="sync"، ذخیره‌ی حاصل از مدل پس از آن چک‌پوینت ثبت شده است. این تقدم و تأخر خطری ندارد، چون چک‌پوینت از قبل حاوی آن مقدار است. بازه‌ی زمانی حساس در ابتدای یک گام رخ می‌دهد و بخش 5.3 آن را اندازه می‌گیرد.

هر نوبت گفت‌وگو با چک‌پوینتی شروع می‌شود که منبع (source) آن input است و شمارنده‌ی گام‌ها نیز در طول نوبت‌ها جلو می‌رود. تصویر این 11 سطر را نشان می‌دهد.

سه نوبت گفت‌وگو از یک thread در فایل SQLiteهر نوبت یک چک‌پوینت ورودی و سپس یک چک‌پوینت حلقه به ازای هر گام اضافه می‌کند و شمارش گام‌ها در طول نوبت‌ها و راه‌اندازی مجدد ادامه می‌یابد.
سه نوبت گفت‌وگو از یک thread در فایل SQLite 11 سطر از جدول چک‌پوینت‌های SqliteSaver برای thread به نام sqlite-thread، در یک محور گام از -1 تا 9. نوبت 1، «2 + 3 چند می‌شود؟»، دارای یک چک‌پوینت ورودی در گام -1 و چک‌پوینت‌های حلقه در گام‌های 0، 1، 2، 3 است و 4 پیام در وضعیت باقی می‌گذارد. نوبت 2، «چه چیزی ازت پرسیدم؟»، یک چک‌پوینت ورودی در گام 4 و چک‌پوینت‌های حلقه در گام‌های 5 و 6 دارد و 6 پیام در وضعیت باقی می‌گذارد. نوبت 3، «یادم بنداز اولین سوالم چی بود.»، یک چک‌پوینت ورودی در گام 7 و چک‌پوینت‌های حلقه در گام‌های 8 و 9 دارد و 8 پیام در وضعیت به جا می‌گذارد. بین نوبت 2 و نوبت 3، اتصال بسته شد و فرایند جدیدی همان فایل را باز کرد. این فایل شامل 11 سطر چک‌پوینت و 13 سطر از نوشتن‌های معلق است. THREAD SQLITE-THREAD، یک سطر برای هر چک‌پوینت نوبت 1 2 + 3 چند می‌شود؟ ورودی حلقه حلقه حلقه حلقه 4 پیام در وضعیت پس از نوبت 2 چه چیزی ازت پرسیدم؟ ورودی حلقه حلقه 6 پیام در وضعیت پس از نوبت 3 یادم بنداز اولین سوالم چی بود. ورودی حلقه حلقه 8 پیام در وضعیت پس از -1 0 1 2 3 4 5 6 7 8 9 metadata.step اتصال بسته شد، فرایند جدید همان فایل را باز می‌کند checkpoints.db 11 چک‌پوینت 13 نوشتن ورودی پیام جدید در حلقه ذخیره بعد از گام
از چپ به راست در امتداد محور گام بخوانید. هر علامت نشان‌دهنده یک سطر از جدول چک‌پوینت‌ها است. نشانه‌های کهربایی چک‌پوینت‌های ورودی و نشانه‌های سبزآبی چک‌پوینت‌های حلقه هستند. برگرفته از capture/out/29-checkpoint-sqlite.txt.

تمام سطرها type برابر با msgpack دارند. این فرمت در واقع سریال‌ساز چک‌پوینت است و بخش 5.6 نشان می‌دهد چه چیزهایی را نگه می‌دارد.

اجرای چندین رشته روی یک ذخیره‌ساز Postgres

یک سرور چندین رشته را هم‌زمان روی یک چک‌پوینتر اجرا می‌کند. سؤال اصلی این است که به چند اتصال نیاز دارد.

ما این مورد را روی سرور مهمان x86 با 32 هسته‌ی مجازی (vCPU) و 48 گیگابایت حافظه، با AsyncPostgresSaver روی PostgreSQL 16.15 و مدل Qwen3 4B روی Ollama با CPU اندازه گرفتیم. یک فرایند asyncio تعداد 1، 4، 16 و 64 رشته را هم‌زمان اجرا کرد؛ دو اجرا برای هر حالت آزمون، یک بار با یک اتصال و بار دیگر با استخری از 20 اتصال. هر رشته دو بار اجرای ایجنت داشت که هر کدام شامل دو فراخوانی مدل و یک فراخوانی ابزار (Tool call) بود. تمام 680 اجرا بدون هیچ خطایی پاسخ درست دادند. مدل تعیین‌کننده‌ی سرعت بود و در همه‌ی حالت‌ها از 4 رشته به بالا، بین 0.42 تا 0.44 فراخوانی مدل در ثانیه ثبت کرد. به همین دلیل اجرای 64 رشته در دو اجرا، چه با یک اتصال و چه با استخر اتصالات، بین 587 تا 589 ثانیه طول کشید.

ذخیره‌ساز در مقادیر میانه (Median) سریع باقی ماند: aput بین 2.8 تا 4.5 میلی‌ثانیه و aput_writes بین 3.7 تا 5.8 میلی‌ثانیه در همه‌ی حالت‌ها زمان بردند. در 64 رشته، صدک 99 (p99) برای aput با یک اتصال 318 و 450 میلی‌ثانیه، و با استخر اتصالات 254 و 273 میلی‌ثانیه بود. این زمان‌ها سمت کلاینت اندازه‌گیری شده‌اند، در نتیجه زمان انتظار حلقه‌ی رویداد (Event loop) را هم شامل می‌شوند. این ارقام را به عنوان مقادیر p99 کلاینت در نظر بگیرید و اختلاف بین این دو حالت را اثر استخر اتصالات تلقی نکنید. این استخر تا 21 اتصال باز کرد، اما در نمونه‌برداری‌ها حداکثر 3 اتصال فعال داشت.

تعداد اجرا در ثانیه و صدک 99 نوشتن چک‌پوینت در یک AsyncPostgresSaver، برحسب threadهایک اتصال و یک استخر 20تایی هر دو در 64 thread با مدل Qwen3 4B نرخ 0.22 اجرا در ثانیه می‌دهند و p99 تابع aput نیز تفاوتی میان آن‌ها ایجاد نمی‌کند.
تعداد اجرا در ثانیه و صدک 99 نوشتن چک‌پوینت در یک AsyncPostgresSaver، برحسب threadها دو نمودار نقطه‌ای در برابر threadهای هم‌زمان (1، 4، 16 و 64) در مقیاس لگاریتمی، دو اجرا به ازای هر نقطه، روی سرور مهمان x86 با مدل Qwen3 4B روی CPU. چپ: اجرا در ثانیه. یک اتصال مقادیر 0.18 و 0.22 در 1 thread و 0.22 و 0.22 در 64 thread را می‌دهد. استخر 20تایی مقادیر 0.23 و 0.23 در 1 thread و 0.22 و 0.22 در 64 thread را ارائه می‌دهد. راست: p99 تابع aput بر حسب میلی‌ثانیه در مقیاس لگاریتمی. در 64 thread این مقدار با یک اتصال 450 و 318 میلی‌ثانیه و با استخر 273 و 254 میلی‌ثانیه است. 0 0.1 0.2 0.3 1 4 16 64 threadهای هم‌زمان اجرا در ثانیه 1 10 100 1k 1 4 16 64 threadهای هم‌زمان صدک 99 aput، میلی‌ثانیه یک اتصال استخر 20تایی هر نقطه یک اجرا است. تمام 680 اجرا از 680 مورد، با 0 خطا پاسخ درست دادند. مقدار p99 در کلاینت اندازه‌گیری شده، بنابراین شامل زمان انتظار event loop است.
هر نقطه نشان‌دهنده یک اجرا است، دو اجرا به ازای هر مقطع. هر خط میانگین‌های یک پیکربندی اتصال را به هم متصل می‌کند. نمودار سمت چپ نرخ اجرا در ثانیه و نمودار سمت راست p99 تابع aput را بر حسب میلی‌ثانیه در مقیاس لگاریتمی نشان می‌دهد. محور x تعداد threadهای هم‌زمان در مقیاس لگاریتمی است. برگرفته از capture/lab/summary/concurrency-x86-real.json.

وقتی مدل روی CPU اجرا می‌شود، خیلی زودتر از ذخیره‌ساز نرخ پردازش (Throughput) را محدود می‌کند. اندازه‌ی استخر اتصالات را متناسب با رشته‌هایی که هم‌زمان اجرا می‌شوند تنظیم کنید. مقادیر p99 ما نشان نمی‌دهد که استخر اتصالات دنباله‌ی تأخیر (Tail latency) در نوشتن چک‌پوینت‌ها را پایین بیاورد. اجرای دوباره روی رشته‌ای که هنوز در حال اجراست مسئله‌ی دیگری است؛ یعنی ارسال دو پیام پیاپی (Double texting) که در بخش 8.1 روی Agent Server به آن می‌پردازیم.

منابع: capture/s_persist.py، capture/common.py، capture/out/28-checkpoint-memory.txt، capture/out/29-checkpoint-sqlite.txt؛ capture/lab/summary/concurrency-x86-real.json، capture/lab/T16-concurrency-x86-real/01-levels.jsonl، capture/lab/T16-concurrency-x86-real/t16r_conc.py، capture/lab/internals/03-checkpoint/trace.txt؛ libs/langgraph/langgraph/pregel/_loop.py در langgraph 1.2.22؛ libs/checkpoint/langgraph/checkpoint/base/init.py، libs/checkpoint/langgraph/checkpoint/memory/init.py، و libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/init.py در langgraph 1.2.22؛ docs.langchain.com در docs commit 04d4d4a (oss/python/langgraph/persistence، oss/python/langgraph/checkpointers، oss/python/langchain/short-term-memory).

ترجمه‌ی فارسی Checkpointers and threads: short-term memory از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما