چکپوینتر وضعیت گراف را بعد از هر گام ذخیره میکند؛ بنابراین نوبت گفتوگوی بعدی روی همان
thread_idاز آخرین چکپوینت شروع میشود، حتی پس از ریاستارت شدن برنامه.
فرض کنید چتی را بر پایهی create_agent میسازید و کاربر میپرسد: «من قبلاً چه سؤالی ازت پرسیدم؟». ایجنت اصلاً نمیداند کاربر چه میگوید، چون هر invoke با وضعیتی کاملاً خالی شروع شده است. مشکل از مدل نیست؛ ایجنت هیچ چیزی را بین اجراها نگه نمیدارد، مگر اینکه چیزی وضعیت را ذخیره کند.
با پایان این بخش، میتوانید به یک ایجنت حافظهی کوتاهمدت بدهید، یک چکپوینت را بخوانید و ظرفیت مناسب ذخیرهساز Postgres را برای چندین رشته تعیین کنید.
یک رشته در طول دو نوبت گفتوگو
چکپوینتر (Checkpointer): شیئی که وضعیت گراف را پس از هر گام ذخیره میکند و هنگام شروع اجرای بعدی، آخرین چکپوینت را بارگذاری میکند. InMemorySaver، SqliteSaver و PostgresSaver نمونههایی از چکپوینتر هستند.
رشته (Thread): توالی چکپوینتهایی است که با یک thread_id یکسان ذخیره میشوند. رشته همان گفتوگو است و هر بار اجرای invoke روی آن، یک نوبت گفتوگو محسوب میشود.
کیت دو نوبت گفتوگو را روی رشتهی memory-thread اجرا میکند:
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)در نوبت دوم فقط یک پیام جدید فرستاده شد. مدل کل نوبت اول را پیش از این پیام دریافت کرد:
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 نیاز دارد. بدون آن، ایجنت پیش از اجرا خطا میدهد:
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).
{
"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 اجرا میکند، اتصال را میبندد و سپس فایل را با یک ایجنت جدید دوباره باز میکند:
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:
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 سطر را نشان میدهد.
تمام سطرها 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 اتصال فعال داشت.
وقتی مدل روی 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).