چکپوینتر وضعیت را با 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 مقدار با تغییر برگشتند یا اصلاً ذخیره نشدند. شکل آنها را دستهبندی کرده است.
| مقدار | آنچه بازگشت | برابری مقداری |
|---|---|---|
(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 |
ذخیره نشد |
بازسازی مجموعهای از تاپلها شکست خورد و لودر دادههای خام آن را همراه با یک خط لاگ بازگرداند:
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.