بخش 3.1 · کش KV

استخر KV و بایت به ازای هر توکن

The KV pool and bytes per token

فهرست مطالب
  1. چرا به کش نیاز داریم؟
  2. فرمول و اولین اندازه‌گیری عملی ما
  3. دو جدول، یک استخر
  4. کش همان استخر است
  5. موضع ما: حساب توکن‌ها را داشته باشید، نه گیگابایت‌ها
  6. شاخص‌های کلیدی برای پایش

SGLang تمام توکن‌های هر درخواست در حال اجرا را در یک استخر واحد با جایگاه‌های (slots) اندازه‌ثابت ذخیره می‌کند؛ بنابراین بایت به ازای هر توکن در یک مدل تعیین می‌کند که یک GPU می‌تواند به چند کاربر سرویس بدهد.

یک GPU با 80 گیگابایت حافظه برای مدلی با 8 میلیارد پارامتر اجاره می‌کنید. وزن‌های مدل حدود 16 گیگابایت فضا می‌گیرند، بنابراین بیشتر افراد انتظار دارند فضا برای تعداد زیادی کاربر باز باشد. اما سرور در همان چند ده گفتگوی هم‌روند درخواست‌ها را صف‌بندی می‌کند؛ در حالی که GPU هنوز ظرفیت محاسباتی آزاد نشان می‌دهد. مشکل از وزن‌ها نبود که حافظه را پر کردند؛ مقادیر کلید و مقدار (keys and values) هر توکن این کار را کردند.

پس از پایان این بخش، می‌توانید هزینه‌ی کش کلید-مقدار (KV cache) یک مدل را از روی پیکربندی‌اش (config) محاسبه کنید. همین عدد را در لاگ راه‌اندازی پیدا خواهید کرد و متوجه می‌شوید چرا SGLang ظرفیت را بر حسب توکن می‌سنجد.

چرا به کش نیاز داریم؟

کش کلید-مقدار (KV cache): کلیدها و مقادیر ذخیره‌شده‌ی همه‌ی توکن‌های قبلی برای تمام لایه‌ها؛ تا در مرحله‌ی رمزگشایی (decode) نیازی به محاسبه‌ی دوباره‌ی آن‌ها نباشد. در هر گام رمزگشایی، یک توکن جدید تولید می‌شود. این توکن روی کلیدها و مقادیر تمام توکن‌های پیش از خود اتنشن (attention) می‌زند. اگر این کش نباشد، برای هر توکن جدید کل مرحله‌ی پیش‌پرکنی (prefill) گفتگو از اول تکرار خواهد شد.

پس این کش با دو متغیر رشد می‌کند: طول هر گفتگو و تعداد گفتگوهای هم‌زمان. بعد از وزن‌های مدل، کش بزرگ‌ترین مصرف‌کننده‌ی حافظه در موتور سرویس‌دهی است. تک‌تک تصمیم‌های اسکژولر (scheduler) در بخش 2 در واقع تصمیمی درباره‌ی همین حافظه‌اند.

فرمول و اولین اندازه‌گیری عملی ما

برای مدلی با اتنشن چندسر معمولی یا اتنشن پرس‌وجوی گروه‌بندی‌شده (Grouped-Query Attention)، هزینه‌ی هر توکن به بایت این‌طور حساب می‌شود:

2 × layers × KV heads × head dim × bytes per value

ضریب 2 برای کلید و مقدار است. اتنشن پرس‌وجوی گروه‌بندی‌شده: چند هد پرس‌وجو (query) در یک هد مشترک کلید و مقدار سهیم می‌شوند؛ به همین دلیل است که مدل‌های امروزی نسبت به هدهای اتنشن، هدهای KV بسیار کمتری دارند. SGLang هنگام راه‌اندازی این عدد را محاسبه می‌کند {{code}}. روی مک ما، بک‌اند MLX همان ابتدای لاگ این مقدار را چاپ کرد.

استخر KV، اندازه‌گیری‌شده در زمان راه‌اندازی capture/out/server-default.log
[2026-10-16 13:58:03] Auto-sized attention KV pool: sys_available=48.49 GB, mlx_limit=51.8 GB, mlx_used=0.31 GB, kv_budget=19.39 GB, bytes_per_slot=114688, pool_size=181574
…
[2026-10-16 13:58:08] MlxAttentionKVPool: 181575 slots x 28 layers x 8 heads x 128 dim, dtype=mlx.core.bfloat16, ~19859.8 MB

دو خط از لاگ راه‌اندازی پیکربندی پیش‌فرض کیت.

ما برای Qwen3-0.6B مقدار bytes_per_slot=114688 را ثبت کردیم. خط دوم تمام جمله‌ها را نشان می‌دهد: 28 لایه، 8 هد KV، بُعد هد (head dim) برابر با 128، و فرمت bfloat16 که 2 بایت است. در نتیجه هزینه برابر است با: 2 × 28 × 8 × 128 × 2، یعنی 114,688 بایت یا 112 کیبی‌بایت (KiB) به ازای هر توکن. فرمول دقیقاً و تا آخرین بایت با لاگ می‌خواند.

همین محاسبه روی کانفیگ مدل‌های عمومی این ارقام را به دست می‌دهد:

مدل اتنشن بایت به ازای توکن، bf16 به ازای هر GPU
Qwen3-0.6B (لاگ اندازه‌گیری ما) GQA، 28 لایه، 8 هد KV 112 KiB 112 KiB روی یک GPU
Llama-3.1-8B GQA، 32 لایه، 8 هد KV 128 KiB 128 KiB روی یک GPU
Llama-3.1-70B GQA، 80 لایه، 8 هد KV 320 KiB 40 KiB با موازی‌سازی تنسور 8 جهته
DeepSeek-V3 MLA، 61 لایه، متغیر نهفته‌ی 512 به اضافه‌ی 64 68.6 KiB 68.6 KiB روی تک‌تک GPUها

دو نتیجه بیشتر افراد را غافلگیر می‌کند: اول اینکه هزینه‌ی هر توکن یک مدل 0.6B تقریباً با مدل 8B برابری می‌کند. تعداد لایه‌ها و هدهای KV تعیین‌کننده‌ی هزینه‌اند، نه تعداد کل پارامترها. دوم اینکه یک گفتگوی 100,000 توکنی روی Llama-3.1-8B حدود 12.2 گیبی‌بایت (GiB) کش KV پر می‌کند؛ یعنی تقریباً نزدیک به حجم خود وزن‌های مدل.

اتنشن چندسر نهفته (Multi-head Latent Attention یا MLA): معماری اختصاصی اتنشن DeepSeek که به جای ذخیره‌ی کلیدها و مقادیر جداگانه برای هر هد، یک متغیر نهفته‌ی فشرده به ازای هر توکن نگه می‌دارد. حجم MLA به ازای هر توکن پایین است، اما هر رتبه‌ی (rank) موازی‌سازی تنسور (Tensor Parallelism) باید نسخه‌ی کامل این متغیر نهفته را ذخیره کند {{code}}. با اضافه کردن GPU از طریق موازی‌سازی تنسور ظرفیت توکن شما بیشتر نمی‌شود. بخش 6.1 نشان می‌دهد که اتنشن موازی داده چطور این گره را باز می‌کند.

هزینه‌ی حافظه برای یک توکن در Qwen3-0.6Bیک توکن در Qwen3-0.6B برابر با 114,688 بایت هزینه دارد؛ حاصل‌ضرب پنج عدد از تنظیمات مدل.
هزینه‌ی یک توکن در Qwen3-0.6B پنج فاکتور از پیکربندی Qwen3-0.6B با ضرب در یکدیگر 114,688 بایت به ازای هر توکن را تشکیل می‌دهند: 2 برای key و value، 28 لایه، 8 هد KV، بُعد هد 128، و 2 بایت برای bfloat16. لاگ راه‌اندازی همین عدد را با عنوان bytes_per_slot چاپ می‌کند، و 181,574 جایگاه با این اندازه، استخری به حجم 20.82 گیگابایت (معادل 19.39 گیبی‌بایت) می‌سازند. یک توکن، پنج فاکتور 2 K و V × 28 لایه‌ها × 8 هدهای KV × 128 بُعد هد × 2 B bfloat16 = 114,688 B 112 KiB همان عدد در لاگ راه‌اندازی استخر اتنشن KV با اندازه خودکار kv_budget=19.39 GB · bytes_per_slot=114688 · pool_size=181574 اندازه استخر 181,574 slots × 114,688 bytes = 20.82 GB, or 19.39 GiB, of KV
از چپ به راست بخوانید. هر جعبه یک فاکتور از مقدار bytes_per_slot در لاگ راه‌اندازی است. برگرفته از capture/out/server-default.log.

دو جدول، یک استخر

SGLang کش KV را در استخری از جایگاه‌های اندازه‌ثابت نگه می‌دارد؛ هر جایگاه برای یک توکن. دو جدول جلوی این استخر قرار گرفته‌اند که به دو سوال متفاوت جواب می‌دهند {{code}}.

ReqToTokenPool: جدولی با یک سطر به ازای هر درخواست در حال اجرا و یک ستون به ازای هر جایگاه توکن. در هر سلول، اندیسِ جایگاه مربوطه در استخر KV ذخیره می‌شود. سطر 0 برای پدینگ (padding) رزرو شده تا داده‌های دسته‌ای پدشده روی خانه‌ای بی‌خطر بازنویسی شوند.

TokenToKVPoolAllocator: لیست جایگاه‌های آزاد استخر KV. وقتی درخواستی جا بخواهد، اندیس جایگاه‌ها را تخصیص می‌دهد و وقتی درخواست تمام شد، آن‌ها را پس می‌گیرد. جایگاه 0 هم به همان دلیلِ پدینگ رزرو شده است. به همین علت است که لاگ ما بافر 181,575 جایگاهی را برای استخری به ظرفیت 181,574 گزارش می‌کند.

تنسورها در استخر فیزیکی قرار دارند. کرنل‌های اتنشن، کلیدها و مقادیر را از طریق سطر اختصاصیِ همان درخواست در ReqToTokenPool می‌خوانند. این طراحی یک مزیت بزرگ دارد: دو درخواستی که پیشوند مشترک دارند، سطرهایشان می‌تواند به جایگاه‌های یکسانی اشاره کند؛ یعنی توکن‌های مشترک فقط یک بار در حافظه می‌نشینند. بخش 3.3 ساختار درخت مبنا (Radix Tree) را که این جایگاه‌های مشترک را پیدا می‌کند، شرح می‌دهد.

اشاره‌ی سطرهای درخواست به یک استخر جایگاه مشترکدو درخواست با پرامپت سیستمی مشترک، سطرهای نخستین خود را به جایگاه‌های KV یکسانی ارجاع می‌دهند؛ بنابراین پیشوند فقط یک بار در حافظه ذخیره می‌شود.
اشاره‌ی سطرهای درخواست به یک استخر جایگاه مشترک دو سطر ReqToTokenPool، یعنی درخواست A و درخواست B، هرکدام اندیس‌های جایگاه‌های KV را فهرست می‌کنند. هر دو سطر با جایگاه‌های مشترک 1 تا 4 برای پرامپت سیستمی آغاز می‌شوند، سپس به جایگاه‌های اختصاصی خود برای توکن‌های پرسش اشاره می‌کنند. نوار استخر KV در پایین نشان می‌دهد که جایگاه‌های 1 تا 4 یک‌بار ذخیره شده و توسط هر دو سطر استفاده می‌شوند، و فهرست آزاد جایگاه‌های جدید را تحویل می‌دهد. سطرهای REQTOTOKENPOOL درخواست A 1 2 3 4 5 6 درخواست B 1 2 3 4 7 8 خانه‌ها اندیس جایگاه را دارند موقعیت‌های 0 تا 5 جایگاه‌های استخر KV 0 1 2 3 4 5 6 7 8 9 جایگاه 0: پدینگ، هرگز واگذار نمی‌شود جایگاه‌های 1 تا 4: پرامپت سیستمی مشترک، یک‌بار ذخیره و توسط هر دو سطر خوانده می‌شود جایگاه‌های 5 تا 8: توکن‌های پرسش اختصاصی هر درخواست جایگاه 9: در فهرست آزاد TokenToKVPoolAllocator
از بالا به پایین بخوانید. هر سطر یک ورودی ReqToTokenPool است و نوار پایین، استخر KV را نشان می‌دهد. سازوکار برگرفته از کد v0.5.22 است و اندازه‌ها جنبه‌ی توضیحی دارند.

کش همان استخر است

SGLang تنظیمات جداگانه‌ای برای حجم کش ندارد. مقاله‌ی SGLang این رویکرد را یک تصمیم معماری می‌داند: توکن‌های کش‌شده و درخواست‌های در حال اجرا هر دو از یک استخر حافظه‌ی مشترک استفاده می‌کنند {{paper}}. پیشوند کش‌شده در اصل دیتای KV است که فعلاً هیچ درخواست در حال اجرایی آن را قفل نکرده است. وقتی درخواست جدیدی به فضا نیاز داشته باشد، SGLang پیشوندهای قفل‌نشده را از همین استخر پاکسازی (evict) می‌کند.

به همین دلیل لاگ راه‌اندازی فقط یک عدد به عنوان max_total_num_tokens گزارش می‌دهد، نه دو عدد جداگانه. روی مک ما با فلگ --mem-fraction-static 0.4، این عدد 181,574 توکن بود. با توجه به اینکه مدل از طول زمینه‌ی (context length) 40,960 توکنی پشتیبانی می‌کند، این استخر گنجایش چهار گفتگوی کامل با حداکثر طول، یا حدود 180 گفتگوی 1,000 توکنی را دارد. درخواست‌های زنده و پیشوندهای کش‌شده دائماً بر سر تصاحب همین جایگاه‌ها با هم رقابت می‌کنند.

موضع ما: حساب توکن‌ها را داشته باشید، نه گیگابایت‌ها

ابعاد دیپلوی خود را بر اساس max_total_num_tokens تعیین کنید، نه حافظه‌ی خالی GPU. طول زمینه‌ی معمول خود را در میزان هم‌روندی مورد نیاز ضرب کرده و حاصل را با این عدد مقایسه کنید. اگر عدد به دست آمده بزرگ‌تر باشد، اسکژولر درخواست‌ها را پس می‌زند (retract) یا به صف می‌فرستد؛ هزینه‌ی این تأخیرها را در بخش 2.3 بررسی کرده‌ایم.

دو اهرمی که این عدد را تغییر می‌دهند، سهم حافظه در بخش 3.2 و نوع داده‌ی KV است. فلگ --kv-cache-dtype به طور پیش‌فرض روی auto تنظیم شده که نوع داده‌ی خود مدل را حفظ می‌کند، مگر اینکه چک‌پوینت (checkpoint) فرمت FP8 خواسته باشد {{code}}. استفاده از FP8 حجم هر بایت به ازای توکن را نصف می‌کند.

یک گزارش عملیاتی، قدرت این اهرم را به خوبی نشان می‌دهد: کلودفلر گزارش داد که تبدیل فرمت KV به FP8 در مدل Kimi K2.6 طول زمینه‌ی قابل نگه‌داری در حافظه را از حدود 686,000 به حدود 1.37 میلیون توکن رساند {{field Cloudflare 2026-08}}. همین گزارش اشاره کرد که در هم‌روندی پایین، نرخ پردازش (throughput) به ازای هر درخواست چند درصد افت کرد؛ اما در هم‌روندی 64، پیکربندی BF16 با کمبود حافظه (OOM) کرش کرد، در حالی که پیکربندی FP8 به نرخ 2,192 توکن در ثانیه رسید. در این سناریو، کش KV با فرمت FP8 کمی از سرعت به ازای توکن را فدا کرد تا ظرفیت کاربران را دو برابر کند.

در تست‌های FP8 خودمان، وزن‌ها و کش KV را هم‌زمان تغییر دادیم و سرعت به ازای هر کاربر حتی بیشتر شد. همان‌طور که در بخش 4.3 می‌بینید، روی پردازنده‌ی L4 برای 1 کاربر سرعت پردازش از 13.4 به 24.5 توکن در ثانیه رسید. البته قبل از پیاده‌سازی این تغییر، حتماً پست وبلاگ کلودفلر را درباره‌ی ارزیابی دقت خروجی مطالعه کنید.

شبیه‌ساز تعاملی Inside an LLM Serving GPU استخر KV را روی شش بسته‌ی تراشه‌ی GDDR6 یک پردازنده‌ی L4 شبیه‌سازی می‌کند. این لینک اجرای BF16 را در هم‌روندی 64 کاربر باز می‌کند: استخر 24,094 توکنی می‌تواند 37 درخواستِ 640 توکنی را جا دهد و 27 درخواست دیگر در صف انتظار می‌مانند. وزن‌ها و کش KV را روی FP8 بگذارید تا ببینید ظرفیت استخر چطور تا 142,369 توکن جهش می‌کند.

شاخص‌های کلیدی برای پایش

  • مقدار bytes_per_slot را بخوانید یا حساب کنید و تطابق این دو را بسنجید.
  • مقدار max_total_num_tokens را در لاگ شروع برنامه بخوانید و آن را بر طول زمینه‌ی متداول خود تقسیم کنید.
  • شاخص token usage را در لاگ اسکژولر زیر نظر بگیرید؛ این عدد در واقع کسری از ظرفیت استخر است که در تصاحب درخواست‌های جاری و پیشوندهای کش‌شده قرار دارد.

اگر کنجکاوید سازوکار درونی این فرایند را بدون وابستگی به SGLang بشناسید، در درس بهینه‌سازی استنتاج یک کش کلید-مقدار را از صفر پیاده‌سازی می‌کنیم.

منابع: python/sglang/srt/model_executor/pool_configurator.py (_compute_cell_size, calculate_pool_sizes)، python/sglang/srt/mem_cache/memory_pool.py (ReqToTokenPool)، python/sglang/srt/mem_cache/allocator/token.py (TokenToKVPoolAllocator)، python/sglang/srt/hardware_backend/mlx/model_runner.py (_compute_pool_size)، python/sglang/srt/arg_groups/fields/model.py (kv_cache_dtype) در نسخه‌ی v0.5.22، capture/out/server-default.log، مقاله‌ی SGLang (arXiv 2312.07104)، گزارش 2026-08-03 کلودفلر، capture/gpu/out-l4/server-load-default.log و capture/gpu/out-l4/server-load-fp8.log برای استخرهای حافظه‌ی پردازنده‌ی L4.

ترجمه‌ی فارسی The KV pool and bytes per token از راهنمای SGLang 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما