چکپوینتر یک ترد را گامبهگام بر اساس
thread_idذخیره میکند؛ Store آیتمهای JSON را بر اساس فضای نام (namespace) در میان تمام تردها نگه میدارد؛ و هر دو در نسخهی پینشده سه بکاند دارند.
کلاسهای مورد بحث از مخزن langgraph نسخهی 1.2.22، در پکیجهای langgraph-checkpoint 4.3.2، langgraph-checkpoint-sqlite 3.1.3 و langgraph-checkpoint-postgres 3.2.1 قرار دارند. مسیرهای ارائهشده از پوشهی libs/ همین مخزن شروع میشوند. بخش 5.2 چکپوینترها را اجرا میکند و بخش 5.4 به اجرای Storeها میپردازد.
چکپوینترها
| کلاس | ایمپورت | خط | نکات |
|---|---|---|---|
InMemorySaver |
langgraph.checkpoint.memory |
checkpoint/.../memory/__init__.py:34 |
فقط درون یک فرایند. MemorySaver نام قدیمی همین کلاس در خط 634 است |
SqliteSaver |
langgraph.checkpoint.sqlite |
checkpoint-sqlite/.../sqlite/__init__.py:49 |
متد from_conn_string در خط 104، setup در خط 134 |
AsyncSqliteSaver |
langgraph.checkpoint.sqlite.aio |
checkpoint-sqlite/.../sqlite/aio.py:49 |
setup در خط 317 |
PostgresSaver |
langgraph.checkpoint.postgres |
checkpoint-postgres/.../postgres/__init__.py:45 |
متد from_conn_string در خط 69، setup در خط 90 |
AsyncPostgresSaver |
langgraph.checkpoint.postgres.aio |
checkpoint-postgres/.../postgres/aio.py:45 |
setup در خط 95 |
{{code checkpoint/langgraph/checkpoint/memory/init.py:34}} {{code checkpoint-sqlite/langgraph/checkpoint/sqlite/init.py:49-134}} {{code checkpoint-postgres/langgraph/checkpoint/postgres/init.py:45-90}}
تمام این کلاسها زیرکلاس BaseCheckpointSaver هستند {{code checkpoint/langgraph/checkpoint/base/init.py:199}}. هر متد یک همتای ناهمگام (async) نیز دارد که نامش با حرف a آغاز میشود.
| متد | عملکرد | خط |
|---|---|---|
get_tuple(config) |
CheckpointTuple مشخصشده در کانفیگ یا جدیدترین چکپوینت ترد را برمیگرداند |
262 |
list(config, ...) |
چکپوینتهای یک ترد را از جدیدترین به قدیمیترین برمیگرداند | 277 |
put(config, checkpoint, metadata, new_versions) |
یک چکپوینت را ذخیره میکند | 301 |
put_writes(config, writes, task_id) |
عملیات نوشتن معلقِ یک وظیفه را ذخیره میکند | 324 |
delete_thread(thread_id) |
تمام چکپوینتها و عملیات نوشتن یک ترد را حذف میکند | 344 |
get_next_version(current, channel) |
نسخهی بعدی یک کانال را برمیگرداند | 721 |
جدولهای روی دیسک
متد setup() جدولها را میسازد. قبل از اولین اجرا روی پایگاه دادهی جدید، باید این متد را یکبار صدا بزنید.
| Saver | جدولها |
|---|---|
SqliteSaver |
checkpoints، writes {{code checkpoint-sqlite/langgraph/checkpoint/sqlite/init.py:147-157}} |
PostgresSaver |
checkpoint_migrations، checkpoints، checkpoint_blobs، checkpoint_writes {{code checkpoint-postgres/langgraph/checkpoint/postgres/base.py:47-69}} |
رکوردها
| نوع | فیلدها | خط |
|---|---|---|
CheckpointTuple |
config، checkpoint، metadata، parent_config، pending_writes |
base/__init__.py:140 |
Checkpoint |
v، id، ts، channel_values، channel_versions، versions_seen، updated_channels |
base/__init__.py:93 |
CheckpointMetadata |
source، step، parents |
base/__init__.py:39 |
StateSnapshot |
values، next، config، metadata، created_at، parent_config، tasks، interrupts |
langgraph/langgraph/types.py:721 |
{{code checkpoint/langgraph/checkpoint/base/init.py:39-150}} {{code langgraph/langgraph/types.py:721-746}}
مقدار source یکی از موارد input، loop، update یا fork است. مقدار step برای چکپوینت ورودی -1 و برای اولین چکپوینتِ حلقه برابر با 0 است. فایل لاگ 30-state-history-forks.txt مقادیر input، loop و update را نشان میدهد، و بازپخش آزمایشگاهی در بخش 6.6 مقدار fork را به نمایش میگذارد.
کلیدهای کانفیگ یک ترد
کلید در configurable |
مفهوم |
|---|---|
thread_id |
ترد مورد نظر. مقدار جدید در اولین چکپوینت یک ترد تازه میسازد |
checkpoint_id |
یک چکپوینت خاص از ترد، برای بازپخش یا fork |
checkpoint_ns |
فضای نام زیرگراف. رشتهی خالی نشاندهندهی گراف ریشه (top graph) است |
اگر گراف چکپوینتر داشته باشد ولی کانفیگ اجرای آن اصلاً ورودی configurable نداشته باشد، خطای ValueError رخ میدهد {{code langgraph/langgraph/pregel/main.py:2701-2705}}. اما اگر دیکشنری configurable همراه با کلیدهای دیگری داده شود، از این بررسی عبور میکند و کمی بعد با خطاهایی مانند KeyError: 'checkpoint_ns' متوقف میشود. متن دقیق خطاها را در مرجع خطاها ببینید.
متدهای مدیریت وضعیت در گراف کامپایلشده
| متد | عملکرد | خط در pregel/main.py |
|---|---|---|
get_state(config) |
یک StateSnapshot از آخرین چکپوینت یا چکپوینت مشخصشده برمیگرداند |
1479 |
get_state_history(config) |
اسنپشاتهای یک ترد را از جدیدترین به قدیمیترین yield میکند | 1529 |
update_state(config, values, as_node=None) |
یک چکپوینت جدید ثبت میکند، طوری که انگار یک نود مقادیر values را برگردانده است |
2636 |
bulk_update_state(config, supersteps) |
چند بهروزرسانی را به ترتیب ذخیره میکند | 1634 |
{{code langgraph/langgraph/pregel/main.py:1479-2636}}
پایایی (Durability)
گزینههای Durability شامل sync، async یا exit هستند {{code langgraph/langgraph/types.py:99}}. حالت پیشفرض روی async تنظیم شده است {{code langgraph/langgraph/pregel/main.py:2715}}. آرگومان قدیمی checkpoint_during همچنان کار میکند، اما یک هشدار میدهد: مقدار True به async و False به exit تبدیل میشود {{code langgraph/langgraph/pregel/main.py:2837-2847}}. در بخش 5.3 بررسی شده که هر حالت پیش از کرش چه مواردی را ذخیره میکند.
چکپوینترهای زیرگراف
آرگومان checkpointer در تابع compile مقادیر None، True، False یا یک شیء saver میپذیرد {{code langgraph/langgraph/types.py:110}}. مقدار None saver را از والد به ارث میبرد، True وضعیت زیرگراف را در میان فراخوانیها نگه میدارد، و False ذخیرهی چکپوینت را کاملاً خاموش میکند. بخش 6.7 این سه حالت را شرح میدهد.
Storeها
| کلاس | ایمپورت | خط | نکات |
|---|---|---|---|
InMemoryStore |
langgraph.store.memory |
checkpoint/.../store/memory/__init__.py:136 |
مقدار index=None در خط 183 |
SqliteStore |
langgraph.store.sqlite |
checkpoint-sqlite/.../store/sqlite/base.py:789 |
متد from_conn_string در خط 1014، setup در خط 1064 |
PostgresStore |
langgraph.store.postgres |
checkpoint-postgres/.../store/postgres/base.py:668 |
متد from_conn_string در خط 784، setup در خط 1121. ساخت ایندکس به pgvector نیاز دارد |
{{code checkpoint/langgraph/store/memory/init.py:136-183}} {{code checkpoint-sqlite/langgraph/store/sqlite/base.py:789-1064}} {{code checkpoint-postgres/langgraph/store/postgres/base.py:668-1121}}
کلاس InMemoryStore موجود در langchain_core.stores کلاس متفاوتی است؛ یک مخزن کلید-مقدار بدون فضای نام. در فهرست مستندات، پیوند مربوط به آن با شناسهی D106 ثبت شده است.
تمام Storeها زیرکلاس BaseStore هستند {{code checkpoint/langgraph/store/base/init.py:708}}. هر متد یک همتای ناهمگام با پیشوند a دارد.
| متد | پارامترها و مقادیر پیشفرض | خط |
|---|---|---|
get |
namespace, key, refresh_ttl=None |
756 |
search |
namespace_prefix, سپس query=None, filter=None, limit=10, offset=0, refresh_ttl=None |
784 |
put |
namespace, key, value, index=None, ttl |
866 |
delete |
namespace, key |
952 |
list_namespaces |
prefix=None, suffix=None, max_depth=None, limit=100, offset=0 |
966 |
batch |
فهرستی از عملیاتها | 733 |
{{code checkpoint/langgraph/store/base/init.py:733-980}}
هر شیء Item فیلدهای value، key، namespace، created_at و updated_at را در بر دارد. شیء SearchItem فیلد score را هم اضافه میکند {{code checkpoint/langgraph/store/base/init.py:51-151}}. شیء IndexConfig مدل امبدینگ، ابعاد آن و فیلدهای مورد نظر برای تولید امبدینگ را تنظیم میکند، و TTLConfig زمان انقضا را مشخص میسازد {{code checkpoint/langgraph/store/base/init.py:545-578}}.
برچسب فضای نام نمیتواند خالی باشد و نباید شامل نقطه یا بایت NUL باشد. در صورت بروز هر یک از این موارد، خطای InvalidNamespaceError رخ میدهد {{code checkpoint/langgraph/store/base/init.py:1317-1341}}.
| Store | جدولها |
|---|---|
SqliteStore |
store، store_vectors، store_migrations، vector_migrations {{code checkpoint-sqlite/langgraph/store/sqlite/base.py:44-1106}} |
PostgresStore |
store، store_vectors، و جدولهای migration آن {{code checkpoint-postgres/langgraph/store/postgres/base.py:66-1132}} |
سریالایزر
هر دو saver بهطور پیشفرض از JsonPlusSerializer استفاده میکنند {{code checkpoint/langgraph/checkpoint/serde/jsonplus.py:104}}. کلاس EncryptedSerializer با استفاده از AES لایهای امنیتی روی آن میکشد و کلید رمزنگاری را از LANGGRAPH_AES_KEY میخواند {{code checkpoint/langgraph/checkpoint/serde/encrypted.py:54-59}}. بخش 5.6 نشان میدهد کدام مقادیر در بازگشتپذیری (round-trip) دچار تغییر میشوند.
منابع: libs/checkpoint/langgraph/checkpoint/base/init.py، libs/checkpoint/langgraph/checkpoint/memory/init.py، libs/checkpoint/langgraph/store/base/init.py، libs/checkpoint/langgraph/store/memory/init.py، libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py، libs/checkpoint/langgraph/checkpoint/serde/encrypted.py، libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/init.py، libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py، libs/checkpoint-sqlite/langgraph/store/sqlite/base.py، libs/checkpoint-postgres/langgraph/checkpoint/postgres/init.py، libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py، libs/checkpoint-postgres/langgraph/checkpoint/postgres/base.py، libs/checkpoint-postgres/langgraph/store/postgres/base.py، libs/langgraph/langgraph/types.py، و libs/langgraph/langgraph/pregel/main.py در langgraph 1.2.22؛ خروجی فایلهای capture/out/28-checkpoint-memory.txt، capture/out/29-checkpoint-sqlite.txt، capture/out/30-state-history-forks.txt، capture/out/33-store.txt.