بخش 2.6 · درون محیط اجرا

حجم چک‌پوینت، DeltaChannel و هزینه‌ی یک ابرگام

Checkpoint size, DeltaChannel, and the cost of a superstep

فهرست مطالب
  1. هر چک‌پوینت تمام لیست را در خود نگه می‌دارد
  2. ذخیره‌سازی تغییرات با DeltaChannel
  3. هزینه‌ی یک ابرگام چقدر است؟
  4. چه کار کنیم؟

فریم‌ورک کمتر از نیم درصد از زمان واقعی یک ایجنت واقعی را گرفت، در حالی که حجم چک‌پوینت‌های آن طی 100 فراخوانی ابزار (Tool call) به 10 مگابایت رسید؛ بنابراین وقت و تلاشتان را روی بایت‌ها بگذارید.

ایجنت شما سندی طولانی را صفحه به صفحه می‌خواند: 100 فراخوانی ابزار روی یک رشته‌ی گفت‌وگو (Thread). کل پیام‌های این گفت‌وگو حدود 110 کیلوبایت است، اما فایل SQLite برای همین یک رشته 10.1 مگابایت فضا گرفته است. هیچ‌کس 10 مگابایت محتوا ننوشته؛ ماجرا این است که ذخیره‌ساز (Saver) در هر ابرگام (Superstep)، تمام گفت‌وگو را دوباره از اول ذخیره کرده است.

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

هر چک‌پوینت تمام لیست را در خود نگه می‌دارد

متد SqliteSaver.put کل چک‌پوینت را با تمام مقادیر کانال‌ها در قالب یک سطر سریال‌سازی می‌کند {{code libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/init.py:433-449}}. این متد پارامتر new_versions (لیست کانال‌های تغییریافته) را تحویل می‌گیرد، اما از آن استفاده نمی‌کند.

در مقابل، InMemorySaver.put از آن استفاده می‌کند. این کلاس به ازای هر کانال تغییریافته یک شیء باینری (Blob) مجزا ذخیره می‌کند که کلید آن، کانال و نسخه‌ی آن است {{code libs/checkpoint/langgraph/checkpoint/memory/init.py:455-457}}. این کار مانع از بازنویسی کانال‌هایی می‌شود که تغییر نکرده‌اند. اما در یک ایجنت، کانال messages در هر ابرگام تغییر می‌کند؛ بنابراین هر Blob جدید، در واقع تکرار دوباره‌ی کل لیست است.

رشته‌ای با n ابرگام که در هر گام یک پیام دارد، به ترتیب 1، 2، 3 تا n پیام ذخیره می‌کند. مجموع این مقادیر با توان دوی n رشد می‌کند.

ما این مورد را آزمایش کردیم: یک بار اجرای create_agent به ازای هر ذخیره‌ساز روی ماشین مجازی سرور x86 با مدل Qwen3 4B و طول زمینه‌ی 16,384 توکن (Token). ابزار read_page صفحه‌ای را برمی‌گرداند که مکان‌نمای (Cursor) صفحه‌ی بعدی در آن آمده است؛ بنابراین مدل ناچار است در هر نوبت گفت‌وگو (Turn) فقط یک فراخوانی انجام دهد. هر اجرا شامل 100 رفت‌وبرگشت ابزار، 101 فراخوانی مدل و 203 ابرگام بود و با پیام DONE پایان یافت. بخش عمده‌ی زمان هر اجرا صرف مدل شد. از زمان‌ها صرف‌نظر می‌کنیم، چون هر ذخیره‌ساز تنها یک بار روی یک ماشین مجازی زیر بار اجرا شد:

حجم چک‌پوینت در طول 100 رفت‌وبرگشت واقعی ابزار capture/lab/internals/09-growth/trace.txt
   checkpoint rows=203 total bytes=10132489; row bytes at #1, #50, #100, #150, #200: [689, 25072, 49512, 74045, 98637]; largest 99390; mean 49914
   writes rows=403 bytes=111623 (messages channel 98824); checkpoints + writes = 10244112 bytes; checkpoints / writes = 90.8
…
   InMemorySaver: 203 checkpoints (118969 bytes without channel values); blobs 606 entries, 10002635 bytes, of which messages 9989570 bytes in 202 versions; messages blob at version #1, #50, #100: [861, 24630, 49074], last 98779; writes 111624 bytes

بلوک‌های SqliteSaver و InMemorySaver، محدود شده به خطوط اندازه.

حجم سطر از 689 بایت به 98,637 بایت رسید. مجموع این 203 سطر 10,132,489 بایت شد، در حالی که جدول writes که هر پیام را فقط یک بار نگه می‌دارد، تنها 111,623 بایت فضا گرفت. به این ترتیب، حجم چک‌پوینت‌ها 90.8 برابر بایت‌های جدول writes شد. حجم Blobها در InMemorySaver به 10,002,635 بایت رسید که 9,989,570 بایت از آن فقط مربوط به کانال messages بود.

ذخیره‌سازی تغییرات با DeltaChannel

کانال دلتا (DeltaChannel): نوعی کانال آزمایشی (Beta) است که در هر ابرگام فقط تغییرات (Writes) را ذخیره می‌کند و اسنپ‌شات (Snapshot) کامل را پس از تعداد مشخصی به‌روزرسانی نگه می‌دارد. در بخش 5.5 عملکرد آن را طی 5,000 گام اندازه می‌گیریم.

چک‌پوینت DeltaChannel در فاصله‌ی بین اسنپ‌شات‌ها هیچ مقداری نگه نمی‌دارد {{code libs/langgraph/langgraph/channels/delta.py:193-202}}. ثبت اسنپ‌شات هر snapshot_frequency به‌روزرسانی یک بار انجام می‌شود که مقدار پیش‌فرض آن 100 است {{code libs/langgraph/langgraph/channels/delta.py:74}}، یا پس از 5,000 ابرگام رخ می‌دهد {{code libs/langgraph/langgraph/_internal/_config.py:45-47}}. هنگام خواندن، لیست پیام‌ها بر اساس آخرین اسنپ‌شات و تغییراتِ پس از آن بازسازی می‌شود {{code libs/langgraph/langgraph/pregel/_checkpoint.py:458-499}}.

تابع create_agent کانال messages را در یک BinaryOperatorAggregate نگه می‌دارد. آرگومان state_schema در این تابع، زیرکلاسی از AgentState را می‌گیرد و در اجرای سوم از ساختاری استفاده کردیم که کانال را تغییر می‌دهد:

تابع create_agent با فهرست پیام‌های DeltaChannel capture/lab/internals/09-growth/run.py
class DState(AgentState):
    messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
…
    kw = {"state_schema": DState} if label == "sqlite-delta" else {}
همان 100 رفت‌وبرگشت با DeltaChannel capture/lab/internals/09-growth/trace.txt
   checkpoint rows=203 total bytes=286606; row bytes at #1, #50, #100, #150, #200: [470, 747, 49515, 750, 98638]; largest 98638; mean 1412
   writes rows=403 bytes=111777 (messages channel 98978); checkpoints + writes = 398383 bytes; checkpoints / writes = 2.6
   get_state at the end, 30 reads after 3 warmups: median 2.76 ms (p10 2.75, p90 2.8); 202 messages

بلوک sqlite-delta، محدود شده به خطوط اندازه و خواندن.

این اجرا همان کار را انجام داد: 100 رفت‌وبرگشت، 101 فراخوانی مدل و همان پاسخ نهایی. این بار حجم داده‌های رشته به جای 10,244,112 بایت به 398,383 بایت رسید؛ یعنی تقریباً یک‌بیست‌وششم. حجم سطرها به‌جز دو اسنپ‌شات در سطرهای 100 و 200، حوالی 750 بایت ماند. در پایان هر اجرا، داده‌های رشته را 30 بار خواندیم که از آن زمان‌ها صرف‌نظر می‌کنیم. تصویر وضعیت تک‌تک سطرهای هر دو اجرا را ترسیم کرده است.

بایت‌های هر ردیف چک‌پوینت: پیام‌های ساده در مقایسه با DeltaChannelردیف‌های ساده کل فهرست را نگه می‌دارند و تا 99 کیلوبایت رشد می‌کنند، اما ردیف‌های DeltaChannel به جز یک اسنپ‌شات در هر 100 به‌روزرسانی، نزدیک به 750 بایت می‌مانند.
بایت‌های هر ردیف چک‌پوینت، پیام‌های ساده در برابر DeltaChannel بایت‌های تمام ردیف‌های جدول checkpoints مربوط به SqliteSaver به ترتیب، برای یک اجرای create_agent با 100 رفت‌وبرگشت واقعی ابزار با Qwen3 4B روی سرور مهمان x86؛ یک بار با کانال ساده‌ی add_messages و یک بار با state_schema که پیام‌هایش از DeltaChannel استفاده می‌کنند. هر نقطه نشان‌دهنده‌ی یک ردیف است، 203 ردیف در هر اجرا. ردیف‌های ساده در یک خط مستقیم از 689 تا 99390 بایت رشد می‌کنند؛ در مجموع 10132489 بایت. ردیف‌های DeltaChannel به جز 2 ردیف اسنپ‌شات در موقعیت‌های 100 و 200 با اندازه‌های 49515 و 98638 بایت، نزدیک به 643 بایت باقی می‌مانند؛ در مجموع 286606 بایت. همراه با جدول writes، ترد ساده 25.7 برابر ترد DeltaChannel بایت اشغال می‌کند. 0 KB 20 KB 40 KB 60 KB 80 KB 100 KB 0 50 100 150 200 ردیف چک‌پوینت، به ترتیب بایت‌های ردیف پیام‌های ساده در مجموع 10.13 مگابایت DeltaChannel در مجموع 0.29 مگابایت ردیف‌های اسنپ‌شات DeltaChannel یکی در هر 100 به‌روزرسانی کل ترد با writes: ساده 10.24 مگابایت، با کانال دلتا 0.40 مگابایت، 25.7 برابر کمتر
هر نقطه نشان‌دهنده‌ی یک ردیف از جدول checkpoints در یک اجرای create_agent شامل 100 رفت‌وبرگشت واقعی ابزار است؛ به ترتیب، 203 ردیف در هر اجرا. رنگ سبزآبی کانال ساده است، نیلی DeltaChannel است، و دو حلقه ردیف‌های اسنپ‌شات آن هستند. برگرفته از capture/lab/internals/09-growth/growth.json.

کاهنده‌ی (Reducer) با نام _messages_delta_reducer یک نام خصوصی است و خود کانال هم هنوز در مرحله‌ی آزمایشی قرار دارد. بخش 5.5 قواعد تغییر کانال در رشته‌ای را که از قبل وجود دارد فهرست می‌کند.

هزینه‌ی یک ابرگام چقدر است؟

ما این مورد را آزمایش کردیم: زمان مربوط به هر بخش از یک اجرا روی ماشین مجازی سرور x86 با مدل Qwen3 4B اندازه گرفته شد. هر اجرا یک بار اجرای create_agent با 10 رفت‌وبرگشت ابزار و 22 ابرگام بود؛ این آزمایش پس از 2 بار گرم‌کردن (Warmup)، برای هر خانه 30 بار اجرا شد. زمان فریم‌ورک برابر است با زمان واقعی (Wall time) منهای زمان صرف‌شده داخل فراخوانی Ollama و داخل تابع ابزار:

ذخیره‌ساز و حالت سهم از زمان واقعی
بدون ذخیره‌ساز، async 0.144 %
InMemorySaver، حالت async 0.197 %
InMemorySaver، حالت sync 0.213 %
InMemorySaver، حالت exit 0.153 %
SqliteSaver، حالت async 0.245 %
SqliteSaver، حالت sync 0.449 %
SqliteSaver، حالت exit 0.190 %

ماشین مجازی زیر بار بود، بنابراین به سهم و ترتیب سطرها دقت کنید، نه میلی‌ثانیه‌ها.

مدل بیش از 99.5 درصد زمان هر اجرا را به خود اختصاص داد. توابع خود حلقه، یعنی برنامه‌ریزی، اعمال تغییرات و چک‌پوینت‌گیری (Checkpointing)، بخش بسیار ناچیزی از زمان فریم‌ورک بودند. تصویر این بخش‌ها را روی هم انباشته نشان می‌دهد.

زمان فریم‌ورک در هر سوپراستپ، بر حسب نوع saver و حالت پایاییسهم LangGraph و LangChain بین 0.14 تا 0.45 درصد از زمان واقعی بود، و حالت sync در SqliteSaver بیشترین هزینه را داشت.
زمان فریم‌ورک در هر سوپراستپ، بر حسب saver و حالت پایایی هفت نوار افقی، هر کدام برای یک saver و حالت پایایی، برای یک اجرای create_agent شامل 10 رفت‌وبرگشت ابزار با Qwen3 4B روی سرور مهمان x86، با 22 سوپراستپ، 30 اجرا در هر ردیف، میانه‌ها. ماشین مهمان زیر بار بود، بنابراین سهم و ترتیب میله‌ها ملاک است نه میلی‌ثانیه‌ها. زمان فریم‌ورک برابر است با زمان واقعی منهای زمان سپری‌شده درون فراخوانی Ollama و تابع ابزار. هر نوار میلی‌ثانیه بر سوپراستپ را نشان می‌دهد: بدون saver در حالت async برابر 1.70، InMemorySaver در حالت async برابر 2.33، InMemorySaver در حالت sync برابر 2.51، InMemorySaver در حالت exit برابر 1.79، SqliteSaver در حالت async برابر 2.89، SqliteSaver در حالت sync برابر 5.31، SqliteSaver در حالت exit برابر 2.24. بخش نیلی‌رنگ توابع حلقه است: برنامه‌ریزی، اعمال، ساخت چک‌پوینت، و ثبت خروجی‌های وظیفه. بخش خاکستری بقیه‌ی موارد است: پوشش‌های گره و کارهای saver که حلقه منتظرشان می‌ماند. ستون سمت راست سهم فریم‌ورک از زمان واقعی است، بین 0.144 تا 0.449 درصد، در اجراهایی حدود 25.9 ثانیه که عمدتاً توسط مدل پر شده است. SAVER، حالت میلی‌ثانیه فریم‌ورک بر سوپراستپ سهم از زمان واقعی 0 ms 2 ms 4 ms 6 ms بدون saver async 1.70 ms 0.144 % InMemorySaver async 2.33 ms 0.197 % InMemorySaver sync 2.51 ms 0.213 % InMemorySaver exit 1.79 ms 0.153 % SqliteSaver async 2.89 ms 0.245 % SqliteSaver sync 5.31 ms 0.449 % SqliteSaver exit 2.24 ms 0.190 % حلقه: برنامه‌ریزی، اعمال، چک‌پوینت، ثبت‌های وظیفه بقیه: پوشش‌های گره، انتظارهای saver روی حلقه مدل 99.55 درصد یا بیشتر از هر اجرای 25.9 ثانیه‌ای را پر کرد
هر میله نشان‌دهنده‌ی یک saver و حالت آن، بر حسب میلی‌ثانیه در هر سوپراستپ است (میانه‌ی 30 اجرا با 22 سوپراستپ). رنگ نیلی توابع حلقه است و رنگ خاکستری مابقی زمان فریم‌ورک است: پوشش‌های گره و انتظارهای saver در حلقه. ستون سمت راست سهم از زمان واقعی است. ماشین مهمان زیر بار بود، بنابراین به سهم و ترتیب میله‌ها توجه کنید، نه میلی‌ثانیه‌ها. برگرفته از capture/lab/internals/08-costs/breakdown.json.

بنابراین حلقه‌ی اجرا جایی نیست که ایجنت وقتش را در آن بگذراند. هزینه‌ای که بالا می‌رود حجم بایت‌های چک‌پوینت است، و در پایگاه‌داده‌ای با رشته‌های متعدد، این بایت‌ها یعنی فضای ذخیره‌سازی، بار I/O و فایل‌های پشتیبان.

چه کار کنیم؟

حجم بایت‌های یک رشته را با این فرمول تخمین بزنید: حجم بایت‌های یک پیام، ضرب‌در توان دوی تعداد ابرگام‌ها، تقسیم بر دو. برای اجرای بالا، این فرمول رقم 9.98 مگابایت را داد، در حالی که مقدار اندازه‌گیری‌شده 10.13 مگابایت بود. وقتی این عدد از آنچه پایگاه‌داده‌تان باید به ازای هر رشته نگه دارد فراتر رفت، پیام‌ها را کوتاه یا خلاصه‌سازی کنید (همان‌طور که در بخش 5.5 می‌بینید). یا به create_agent یک state_schema با لیست پیام از نوع DeltaChannel بدهید و آزمایشی بودن کانال را بپذیرید.

بهینه‌سازی را از حلقه شروع نکنید. پایداری داده (Durability) را با هدف درستی کار انتخاب کنید، همان‌طور که بخش 2.3 استدلال می‌کند. پرهزینه‌ترین پیکربندی در آزمایش‌های ما، یعنی حالت sync روی SQLite، کلاً 0.449 % از زمان واقعی سیستم را گرفت.

منابع: capture/lab/internals/09-growth/trace.txt، capture/lab/internals/09-growth/growth.json، capture/lab/internals/09-growth/run.py، capture/lab/internals/08-costs/trace.txt، capture/lab/internals/08-costs/breakdown.json، capture/lab/internals/08-costs/runs.json، capture/lab/internals/08-costs/run.py، capture/lab/internals/common/real.py، capture/lab/internals/common/pager.py؛ کتابخانه‌ی libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/init.py در نسخه‌ی langgraph-checkpoint-sqlite 3.1.3؛ کتابخانه‌ی libs/checkpoint/langgraph/checkpoint/memory/init.py در نسخه‌ی langgraph-checkpoint 4.3.2؛ کتابخانه‌های libs/langgraph/langgraph/channels/delta.py، libs/langgraph/langgraph/_internal/_config.py و libs/langgraph/langgraph/pregel/_checkpoint.py در نسخه‌ی langgraph 1.2.22؛ کتابخانه‌ی libs/langchain_v1/langchain/agents/factory.py در نسخه‌ی langchain==1.5.0.