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

سریال‌سازی وضعیت و داده‌هایی که بازگشت‌پذیر نیستند

Serialization of state, and what does not round-trip

فهرست مطالب
  1. کلاس JsonPlusSerializer
  2. چه چیزهایی دست‌خوش تغییر می‌شوند؟
  3. انواع داده‌ی اختصاصی شما و حالت سخت‌گیرانه‌ی msgpack

چک‌پوینتر وضعیت را با msgpack ذخیره می‌کند؛ بنابراین بیشتر مقادیر پایتون دقیقاً همان‌طور که ذخیره شده‌اند بازمی‌گردند، اما تاپل‌ها، مجموعه‌هایی از تاپل‌ها، زیرکلاس‌های dict و منطقه‌های زمانی دست‌خوش تغییر می‌شوند.

نود شما یک Counter را در وضعیت قرار می‌دهد و در گام بعدی به آن مقداری اضافه می‌کند. این کد روی یک ترد بدون مشکل اجرا می‌شود، اما در صورت ازسرگیری ترد با خطا متوقف خواهد شد؛ چراکه مقدار بازگشتی از چک‌پوینت، یک dict ساده است. وضعیتی که پس از چک‌پوینت می‌خوانید، همان وضعیتی است که سریالایزر (serializer) توانسته دوباره بسازد.

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

کلاس JsonPlusSerializer

سریالایزر: شیئی که مقادیر وضعیت را برای چک‌پوینتر به بایت تبدیل می‌کند و برعکس. گزینه‌ی پیش‌فرض، JsonPlusSerializer در مسیر langgraph.checkpoint.serde.jsonplus است.

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

کلاس JsonPlusSerializer بیشتر مقادیر را با msgpack می‌نویسد و نوع هر کدام را با برچسب‌هایی مانند msgpack، bytes یا null مشخص می‌کند. صفحه‌ی مستندات چک‌پوینترها اشاره می‌کند که این بخش از ormsgpack و JSON استفاده می‌کند و در صورت فعال‌سازی، حالت pickle نیز مجاز است {{docs oss/python/langgraph/checkpointers}}. تمام سطرهای فایل SQLite در بخش 5.2 دارای نوع msgpack بودند. انواع شناخته‌شده مانند پیام‌ها، مدل‌های Pydantic، دیتاکلاس‌ها و enumها نام ماژول و کلاس خود را به همراه دارند تا لودر بتواند دوباره آن‌ها را بسازد.

چه چیزهایی دست‌خوش تغییر می‌شوند؟

ما بررسی کردیم: 29 مقدار مختلف را روی سیستم مک، مدل Apple M1 Max با 10 هسته و 64 GiB رم، با نسخه‌ی langgraph-checkpoint 4.3.2 تست کردیم (هر کدام یک بار اجرا شدند). هر مقدار ابتدا از dumps_typed و loads_typed عبور کرد، سپس درون یک گراف تک‌نودی با SqliteSaver و get_state ارزیابی شد. هر دو مسیر برای تمام مقادیر نتیجه‌ی یکسانی داشتند. 20 مورد بازگشت‌پذیر بودند:

  • انواع str، int، float، bool، None، list و bytes
  • نوع dict با کلیدهای عدد صحیح، و set و frozenset از اعداد صحیح
  • انواع Decimal، UUID، Path، date، timedelta و datetime در استاندارد UTC
  • یک Enum، یک دیتاکلاس، یک مدل Pydantic و یک AIMessage

9 مقدار با تغییر برگشتند یا اصلاً ذخیره نشدند. شکل آن‌ها را دسته‌بندی کرده است.

آنچه یک چک‌پوینت برای 9 مقدار بازمی‌گرداندتاپل‌ها و مجموعه‌هایی از تاپل‌ها به صورت لیست، زیرکلاس‌های dict به صورت dict، مناطق زمانی به صورت آفست ثابت برمی‌گردند و یک کلاس معمولی ذخیره نمی‌شود.
آنچه یک چک‌پوینت برای 9 مقدار بازمی‌گرداند نه ردیف، هرکدام از مقداری که در وضعیت در سمت چپ قرار گرفته تا آنچه get_state در SqliteSaver در سمت راست بازگردانده است. یک tuple به شکل list برگشت. یک set و frozenset از تاپل‌ها به صورت لیستی از لیست‌ها برگشتند. defaultdict، Counter و OrderedDict به شکل dict معمولی برگشتند. یک datetime با منطقهٔ ZoneInfo با آفست ثابت برگشت، و مقداری با fold 1 فولد خود را از دست داد. نمونه‌ای از یک کلاس معمولی خطای TypeError داد و ذخیره نشد. در وضعیت قرار گرفت WHAT GET_STATE GAVE BACK tuple (1, 2) list [1, 2] set of tuples {(1, 2), (3, 4)} list of lists [[1, 2], [3, 4]] frozenset of tuples frozenset({(1, 2)}) list of lists [[1, 2]] defaultdict {'k': [1]} dict بدون default factory Counter Counter('abca') dict بدون متدهای Counter OrderedDict دو کلید dict همان کلیدها و ترتیب datetime, ZoneInfo Asia/Kolkata datetime, fixed offset +05:30، بدون قوانین منطقه datetime, fold=1 America/New_York datetime, fixed offset fold 0، نابرابر کلاس معمولی Plain(3) TypeError غیرقابل سریال‌سازی با msgpack بیست مقدار دیگر با نوع و مقدار یکسان برگشتند. روی مک، هرکدام یک اجرا.
هر ردیف یک مقدار از اجرای ماست. مقدار سمت چپ و سپس آنچه get_state بازگردانده را بخوانید. ردیف‌های کهربایی تغییر نوع دادند و ردیف صورتی قبل از هر چک‌پوینتی خطا داد. برگرفته از capture/lab/summary/serde-mac.json.
مقدار آن‌چه بازگشت برابری مقداری
(1, 2) [1, 2]، یعنی یک list خیر
{(1, 2), (3, 4)} [[1, 2], [3, 4]]، یعنی یک list خیر
frozenset({(1, 2)}) [[1, 2]]، یعنی یک list خیر
defaultdict(list, ...) یک dict بدون مقدار پیش‌فرض برابر
Counter("abca") یک dict برابر
OrderedDict(...) یک dict برابر
datetime در منطقه‌ی Asia/Kolkata همان زمان اما با آفست ثابت +05:30 برابر
datetime با fold=1 در America/New_York یک آفست ثابت با fold برابر 0 خیر
نمونه‌ای از یک کلاس ساده TypeError: Type is not msgpack serializable: Plain ذخیره نشد

بازسازی مجموعه‌ای از تاپل‌ها شکست خورد و لودر داده‌های خام آن را همراه با یک خط لاگ بازگرداند:

خطوط لاگ مربوط به بازگشت‌پذیری capture/lab/T13-serde-mac/04-round-trip-log.txt
Could not reconstruct builtins.set from checkpoint (TypeError); returning its serialized data instead.
Could not reconstruct builtins.frozenset from checkpoint (TypeError); returning its serialized data instead.
Deserializing unregistered type __main__.Color from checkpoint. This will be blocked in a future version. Set LANGGRAPH_STRICT_MSGPACK=true to block now, or add to allowed_msgpack_modules to allow explicitly: [('__main__', 'Color')]
…

خطوط مربوط به Point و Card بریده شده‌اند.

سه ایشوی باز این موارد را گزارش کرده‌اند. ایشوی 8388# گزارش می‌دهد که مجموعه‌ای از تاپل‌ها به صورت None بازمی‌گردد {{issue 8388}}. در این نسخه‌ی قفل‌شده، این مقدار به صورت لیستی از لیست‌ها برگشت. ایشوی 8184# به زیرکلاس‌های dict اشاره دارد و ایشوی 8826# به منطقه‌ی زمانی و fold مربوط است {{issue 8184}} {{issue 8826}}. هر دو مورد در این نسخه بازتولید می‌شوند.

زمانِ حاصل از ZoneInfo که با یک آفست ثابت بازمی‌گردد، در مقایسه‌ی اولیه همچنان برابر ارزیابی می‌شود؛ اما پس از تغییر ساعت تابستانی بعدی، زمان محلی آن نادرست خواهد بود.

وضعیت را با انواعی نگه دارید که بازگشت‌پذیر باشند. زمان را به صورت datetime در منطقه‌ی UTC و نام منطقه را به صورت رشته ذخیره کنید. مقادیر Counter یا defaultdict را در قالب dict ذخیره کنید و بازسازی آن‌ها را درون نود انجام دهید. به جای تاپل از لیست، و به جای مجموعه‌ای از تاپل‌ها از لیستِ لیست‌ها استفاده کنید. برای کلاس‌های سفارشی نیز از مدل‌های Pydantic یا دیتاکلاس کمک بگیرید.

انواع داده‌ی اختصاصی شما و حالت سخت‌گیرانه‌ی msgpack

در لاگ بالا هشدار دومی هم وجود دارد. اگر یک enum، دیتاکلاس یا مدل Pydantic متعلق به ماژول اختصاصی شما باشد، به عنوان یک نوع ثبت‌نشده شناخته می‌شود. لودر آن را می‌سازد اما هشدار می‌دهد که نسخه‌های بعدی جلوی آن را خواهند گرفت. اگر متغیر محیطی LANGGRAPH_STRICT_MSGPACK=true را تنظیم کنید، لودر اکنون مانع ساخت آن شده و فیلدهای خام را بازمی‌گرداند. متن هشدار راهکار را هم می‌گوید: نام ماژول و کلاس خود را در allowed_msgpack_modules از کلاس JsonPlusSerializer فهرست کنید.

همین قاعده از شما در برابر سطر تغییریافته‌ی چک‌پوینت محافظت می‌کند. یک سطر نام ماژول و کلاس را مشخص می‌کند و لودر با خواندن آن، کلاس مربوطه را ایمپورت کرده و می‌سازد.

ما بررسی کردیم: این‌که لودرها چه مواردی را روی مک می‌پذیرند بررسی شد (هر حالت یک بار اجرا شد). کلاس آزمایشی ما طوری طراحی شده بود که هنگام ساخته شدن، یک فایل نشانگر ایجاد می‌کرد. با تنظیمات پیش‌فرض، از 26 حالت، 5 حالت کلاس را ساختند. دو مورد گزینه‌های اختیاری allowed_json_modules=True و pickle_fallback=True بودند، و دو مورد مقادیر msgpack بودند که نام کلاس آزمایشی را مشخص می‌کردند. مورد پنجم یک سطر چک‌پوینت در SqliteSaver بود که آن را به صورت دستی تغییر دادیم تا نام این کلاس را صدا بزند، و get_state آن را ساخت. اما با فعال کردن LANGGRAPH_STRICT_MSGPACK=true، فقط همان دو حالت اختیاری کلاس را ساختند و سطر ویرایش‌شده صرفاً به شکل یک dict ساده برگشت.

بنابراین در نسخه‌ی قفل‌شده، هر کسی که بتواند سطری در چک‌پوینت بنویسد، می‌تواند فرایند شما را مجبور به ایمپورت و ساخت کلاس دلخواه خود کند. متن docstring در JsonPlusSerializer درباره‌ی این مسئله هشدار می‌دهد {{code libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py}}. حتماً LANGGRAPH_STRICT_MSGPACK=true را تنظیم کنید، ماژول‌های خود را ثبت کنید، و دسترسی نوشتن روی دیتابیسِ چک‌پوینت را فقط به همان سرویسی بدهید که گراف را اجرا می‌کند. بخش 8.4 به متد load() و هشدارهای امنیتی مربوط به این موارد می‌پردازد.

کلاس PostgresSaver هم از همین سریالایزر استفاده می‌کند و ما آن را اجرا نکردیم. EncryptedSerializer و ایشوی 8938#، پیرامون سطرهای متنیِ ساده‌ای که این ابزار می‌پذیرد، همان‌طور که در بخش 8.8 آمده است، در نسخه‌ی بعدی بررسی خواهند شد.

منابع: capture/out/29-checkpoint-sqlite.txt؛ capture/lab/summary/serde-mac.json، capture/lab/T13-serde-mac/01-serde-default.jsonl، capture/lab/T13-serde-mac/02-serde-strict-msgpack.jsonl، capture/lab/T13-serde-mac/03-round-trip.jsonl، capture/lab/T13-serde-mac/04-round-trip-log.txt، capture/lab/T13-serde-mac/t13_roundtrip.py؛ libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py و libs/checkpoint/langgraph/checkpoint/serde/_msgpack.py در langgraph 1.2.22؛ docs.langchain.com در commit مستندات 04d4d4a (بخش oss/python/langgraph/checkpointers)؛ ایشوهای گیت‌هاب langchain-ai/langgraph به شماره‌های 8388#، 8184#، 8826#، 8938# و هشدارهای امنیتی GHSA-g48c-2wqr-h844 و GHSA-fjqc-hq36-qh5p.