مرجع R.4

رابط برنامه‌نویسی چک‌پوینتر و Store

Checkpointer and store API

فهرست مطالب
  1. چک‌پوینترها
  2. جدول‌های روی دیسک
  3. رکوردها
  4. کلیدهای کانفیگ یک ترد
  5. متدهای مدیریت وضعیت در گراف کامپایل‌شده
  6. پایایی (Durability)
  7. چک‌پوینترهای زیرگراف
  8. Storeها
  9. سریالایزر

چک‌پوینتر یک ترد را گام‌به‌گام بر اساس 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.

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