بخش 3.4 · کش KV

پرامپت‌های سازگار با کش پیشوند

Prefix-friendly prompts

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

کش پیشوند (prefix cache) توکن‌ها را از همان توکنِ اول تطبیق می‌دهد؛ بنابراین حتی یک توکنِ متغیر در نزدیکی ابتدای پرامپت می‌تواند هزینه‌ای روی دستتان بگذارد که با هیچ تنظیمی در سمت سرور جبران نشود.

تیمی DeepSeek-V4 را برای نشست‌های طولانی ایجنت (agent sessions) روی 8 پردازنده‌ی گرافیکی اجرا می‌کند و کش سلسله‌مراتبی (hierarchical caching) را هم روشن کرده است. با این حال، داشبوردهای آن‌ها برای درخواست‌هایی که 100,000 توکن از تاریخچه را تکرار می‌کنند، مقدار #cached-token: 0 را نشان می‌دهد. آن‌ها لایه‌های کش و سیاست نوشتن را بازتنظیم می‌کنند، اما نرخ اصابت (hit rate) تکان چندانی نمی‌خورد. تا اینکه سرانجام متوجه می‌شوند رله‌شان در پیام سیستمی (system prompt) هر درخواست، یک هش تصادفی قرار می‌داده است.

پس از پایان این بخش، می‌توانید پیش از ارسال پرامپت‌ها پیش‌بینی کنید که کدام‌یک به کش پیشوند اصابت می‌کنند. همچنین می‌توانید نرخ اصابت را با cached_tokens، لاگ‌های اسکژولر (scheduler) و اندپوینت /metrics اثبات کنید.

آزمایش: یک شناسه، سه جایگاه مختلف

کیت تست، یک پیام سیستمی 2,999 توکنی و یک پرسش کوتاه را ارسال می‌کند؛ هر کدام را پنج بار و در سه حالت مختلف. سرور با پرچم --enable-cache-report اجرا می‌شود تا هر پاسخ تعداد توکن‌های کش‌شده‌اش را به کلاینت گزارش دهد. این کیت ابتدا دو درخواست برای گرم کردن سیستم (warm-up) می‌فرستد.

  • پایدار (Stable): پیام سیستمی در هر درخواست دقیقاً یکسان است.
  • شناسه در ابتدا (ID at start): پیام سیستمی با عبارت .Request id <random hex> آغاز می‌شود؛ مقداری تازه در هر درخواست.
  • شناسه در انتها (ID at end): همان شناسه‌ی تصادفی در انتهای پیام سیستمی قرار می‌گیرد.
خلاصهٔ آزمایش کش capture/out/cache-experiment.txt
…
{"summary": "stable-system-prompt", "median_ttft_ms": 45.1, "min_ttft_ms": 34.0, "max_ttft_ms": 62.5, "median_cached_tokens": 2998.0, "prompt_tokens": 2999}
{"summary": "id-at-start", "median_ttft_ms": 1255.3, "min_ttft_ms": 1102.6, "max_ttft_ms": 2197.3, "median_cached_tokens": 5, "prompt_tokens": 3034}
{"summary": "id-at-end", "median_ttft_ms": 88.2, "min_ttft_ms": 83.7, "max_ttft_ms": 118.1, "median_cached_tokens": 2985, "prompt_tokens": 3028}

سه خط خلاصه. پانزده خطِ به ازای هر درخواست در بالای آنها بریده شده است. در حالت پایدار، دور اول که کش را پر کرده بود حذف شده است.

وقتی شناسه در ابتدای پرامپت نشست، زمان انتظار برای اولین توکن 28 برابر بیشتر شد: 1,255 میلی‌ثانیه در برابر 45 میلی‌ثانیه. این آزمایش روی Mac ما با مدل Qwen3-0.6B در حالت 4-bit MLX انجام شد. این ضریب به سرعت پیش‌پرکنی (prefill) کارت گرافیک بستگی دارد، اما تعداد توکن‌های ازدست‌رفته ربطی به سخت‌افزار ندارد و ثابت است.

قرار دادن همان شناسه در انتها، تنها 43 میلی‌ثانیه بیشتر از پرامپت پایدار زمان برد. در هر سه حالت، توکن‌ها تقریباً یکسان هستند؛ فقط ترتیبشان فرق می‌کند.

تعداد توکن‌های کش‌شده دلیل این تفاوت زمانی را توضیح می‌دهد. پرامپت پایدار 2,998 توکن از 2,999 توکن را بازاستفاده کرد؛ یعنی بیشترین مقدار ممکن طبق بخش 3.3. اما شناسه‌ی ابتدای پرامپت فقط 5 توکنِ اول را تطبیق داد؛ یعنی همان توکن‌هایی که قبل از ارقام تصادفیِ هگزادسیمال آمده بودند. هر توکنی که بعد از یک تغییر می‌آید، وارد branch متفاوتی از درخت می‌شود؛ حتی اگر ادامه‌ی پرامپت کاملاً یکسان باشد.

توکن‌های یکسان در سه چیدمان مختلفوجود یک شناسهٔ تصادفی در ابتدای پرامپت باعث از دست رفتن کش برای حدود 3,027 توکن شد، در حالی که همان شناسه در انتها تنها حدود 45 توکن هزینه داشت.
توکن‌های یکسان در سه چیدمان سه نوار توکن برای پرامپت‌هایی با حدود 3,000 توکن. پرامپت پایدار از 2,998 توکن مجدداً استفاده کرده و 1 توکن را با میانه زمان تا توکن اول 45 میلی‌ثانیه محاسبه می‌کند. با شناسهٔ تصادفی در ابتدا، تنها از 5 توکن مجدداً استفاده شده و حدود 3,029 توکن در 1,255 میلی‌ثانیه محاسبه می‌شوند. با همان شناسه در انتها، از 2,985 توکن مجدداً استفاده شده و حدود 45 توکن در 88 میلی‌ثانیه محاسبه می‌شوند. استفادهٔ مجدد از radix cache محاسبه‌شده در پیش‌پرکنی پرامپت سیستم ثابت 2,998 کش‌شده میانهٔ TTFT: 45 ms شناسهٔ تصادفی در ابتدا 5 کش‌شده میانهٔ TTFT: 1,255 ms شناسهٔ تصادفی در انتها 2,985 کش‌شده میانهٔ TTFT: 88 ms هر توکن بعد از اولین تفاوت، یک branch جدید از درخت است.
هر نوار را از چپ به راست به عنوان توکن‌های پرامپت بخوانید. رنگ سبز استفادهٔ مجدد از کش و رنگ شرابی محاسبه در مرحلهٔ پیش‌پرکنی (prefill) است. برگرفته از capture/out/cache-experiment.txt.

چرا ترتیب توکن‌ها اهمیت دارد؟

درخت مبنا (Radix Tree) توکن‌ها را از اولین توکن به بعد مقایسه می‌کند و به اولین اختلاف که برسد، متوقف می‌شود. هیچ توکنی بعد از نقطه‌ی اختلاف نمی‌تواند تطبیق بخورد، زیرا مقادیر اتنشن (attention) هر توکنِ بعدی به همه‌ی توکن‌های پیش از آن وابسته است. کِشی که توکن‌های بعدی را دوباره استفاده کند، پاسخ‌های اشتباه برمی‌گرداند. بنابراین کش پیشوند ذاتاً دقیق طراحی شده و با همان منطق، کوچک‌ترین خطایی را برنمی‌تابد.

همین قاعده روی هر بخش از یک درخواست چت هم صدق می‌کند. الگوی چت (chat template) پیام‌ها را با ترتیبی ثابت به یک دنباله‌ی توکن تبدیل می‌کند: پیام سیستمی، فهرست ابزارها، نوبت‌های قبلی گفت‌وگو (earlier turns) و پیام جدید. هر تغییری در پیام سیستمی همه‌چیز را باطل می‌کند؛ تغییری در جدیدترین پیام فقط همان پیام را از اعتبار می‌اندازد.

ماجرای رخ‌داده

گزارش مشکل شماره‌ی 35129 همان ماجرای ابتدای این بخش است {{issue #35129}}. گزارش‌دهنده متوجه سه دلیل شد که روی هم تلمبار شده بودند:

  1. رله برای هر نشست یک هش تصادفیِ cch= و یک پیام سیستمی چرخشی در هر درخواست قرار می‌داد. حذف آن‌ها نرخ اصابت موتور را از 66.8 درصد به 94.4 درصد رساند.
  2. کلاینت اسنپ‌شاتِ فهرست وظایف (task-list snapshot) خود را در انتهای پیام سیستمی می‌نوشت. هر به‌روزرسانیِ وظیفه، پیام سیستمی را تغییر می‌داد و در نتیجه، بیش از 100,000 توکن تاریخچه‌ی پس از آن را باطل می‌کرد.
  3. بازیابی کش سلسله‌مراتبی (hierarchical cache load-back) وقتی جا پیدا نمی‌کرد، پیشوندهای نشست‌های دیگر را بیرون می‌انداخت (evict می‌کرد). گزارش‌دهنده 250,000 فراخوانی خروج از کش (evict) را در برابر تنها 376 بازیابیِ کامل‌شده ثبت کرده بود.

اولین راه‌حل، اصلاح پرامپت بود. هیچ پرچم سروری در بخش 3.5 نمی‌توانست 27.6 درصدی را که آن هش سوزانده بود، برگرداند.

موضع ما: پیش از تنظیم سرور، پرامپت‌ها را اصلاح کنید

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

  • محتوایی را که هرگز تغییر نمی‌کند اول بگذارید: پیام سیستمی و سپس فهرست ابزارها با ترتیبی ثابت.
  • محتوایی را که در هر نشست تغییر می‌کند بعد از آن، و محتوایی را که با هر درخواست عوض می‌شود در آخر قرار دهید.
  • هرگز برچسب زمانی، شناسه‌ی درخواست، هش نشست یا سید تصادفی نمونه‌برداری را در پیام سیستمی نگذارید. آن‌ها را در متادیتای درخواست بفرستید، یا در انتها.
  • تعاریف ابزارها و توابع را در ترتیبی پایدار نگه دارید. یک شیء JSON که ترتیب کلیدهایش عوض شود، دنباله‌ی توکن متفاوتی می‌سازد.
  • به ادامه‌ی گفت‌وگو اضافه کنید. نوبت‌های قبلی را بازنویسی نکنید (مثلاً برای خلاصه‌سازی)، مگر اینکه پیش‌پرکنی کامل را بپذیرید.

دو تنظیم در سمت سرور نیز استفاده‌ی مجدد را طوری مختل می‌کنند که شبیه به اشکال در پرامپت به نظر می‌رسد. درخواست احتمالات لگاریتمی پرامپت از موقعیت k، فقط می‌تواند k توکن اول را بازاستفاده کند {{code}}. تطبیق‌دهنده‌های (adapters) مختلف LoRA هم هرگز گره‌های درخت را به اشتراک نمی‌گذارند، حتی برای توکن‌های کاملاً یکسان؛ چون خود تطبیق‌دهنده بخشی از کلید درخت است {{code}}.

مسیریابی (routing) هم می‌تواند استفاده‌ی مجدد را بشکند. وقتی چند سرور دارید، درخواستی که به سروری بدون پیشوندِ آن برود، کش را از دست می‌دهد؛ پرامپت هر شکلی هم که داشته باشد. Jarvislabs گزارش داد که مسیریابی هر گفت‌وگو به همان سرور، نرخ اصابتشان را از 64.7 درصد به 92.1 درصد رساند {{field Jarvislabs 2026-08}}. بخش 6.4 نشان می‌دهد که گیت‌وی چگونه بر اساس پیشوند مسیریابی می‌کند.

چطور یک اصابت را اثبات کنیم؟

از سه سنجه استفاده کنید؛ از نزدیک‌ترین سطح به درخواست تا عمومی‌ترین:

  1. در پاسخ. سرور را با --enable-cache-report بالا بیاورید که به‌طور پیش‌فرض خاموش است {{code}}. در این صورت، بلوک usage مقدار cached_tokens را گزارش می‌دهد. API بومیِ /generate بدون نیاز به پرچم، cached_tokens را در meta_info برمی‌گرداند.
  2. در لاگ اسکژولر. هر خطِ Prefill batch مقادیر #new-token و #cached-token را گزارش می‌دهد.
  3. در متریک‌ها. اندپوینت /metrics سنجه‌ی sglang:cache_hit_rate را بیرون می‌دهد که معیاری از دسته‌های (batches) پیش‌پرکنی اخیر است. پس از اجرای بنچ‌مارک پیشوند مشترک در بخش 3.3، سرور ما مقدار 0.94 را گزارش داد. سروری که با --disable-radix-cache اجرا شده بود مقدار 0.0 را نشان داد.
دیدگاه اسکژولر نسبت به سه ساختار پرامپت capture/out/server-default.log
[2026-10-16 13:58:12] Prefill batch, #new-seq: 1, #new-token: 1, #cached-token: 2998, token usage: 0.02, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 7.09
…
[2026-10-16 13:58:14] Prefill batch, #new-seq: 1, #new-token: 3031, #cached-token: 3, token usage: 0.02, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 1937.91
…
[2026-10-16 13:58:20] Prefill batch, #new-seq: 1, #new-token: 45, #cached-token: 2983, token usage: 0.02, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 225.19

یک خط برای هر ساختار، به همان ترتیبی که کیت ارسال کرده است. دوازده خط دیگر حذف شده‌اند.

درس‌های کش کردن پرامپت و کش و هزینه همین قاعده را برای API مدل‌های میزبانی‌شده نشان می‌دهند. آن APIها توکن‌های ورودیِ کش‌شده را با قیمت کمتری فاکتور می‌کنند.

منابع: python/sglang/srt/mem_cache/radix_cache.py (RadixKey, match_prefix)، python/sglang/srt/managers/schedule_batch.py (_compute_max_prefix_len)، python/sglang/srt/arg_groups/fields/serving.py (enable_cache_report)، python/sglang/srt/entrypoints/openai/serving_chat.py در نسخه‌ی v0.5.22، capture/out/cache-experiment.txt، capture/out/server-default.log، capture/out/generate.txt، capture/out/metrics.txt، capture/out/no-radix-cache-metrics.txt، ایشوی شماره‌ی 35129 و گزارش Jarvislabs در تاریخ 2026-08-26.

ترجمه‌ی فارسی Prefix-friendly prompts از راهنمای SGLang 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما