کش پیشوند (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): همان شناسهی تصادفی در انتهای پیام سیستمی قرار میگیرد.
…
{"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 متفاوتی از درخت میشود؛ حتی اگر ادامهی پرامپت کاملاً یکسان باشد.
چرا ترتیب توکنها اهمیت دارد؟
درخت مبنا (Radix Tree) توکنها را از اولین توکن به بعد مقایسه میکند و به اولین اختلاف که برسد، متوقف میشود. هیچ توکنی بعد از نقطهی اختلاف نمیتواند تطبیق بخورد، زیرا مقادیر اتنشن (attention) هر توکنِ بعدی به همهی توکنهای پیش از آن وابسته است. کِشی که توکنهای بعدی را دوباره استفاده کند، پاسخهای اشتباه برمیگرداند. بنابراین کش پیشوند ذاتاً دقیق طراحی شده و با همان منطق، کوچکترین خطایی را برنمیتابد.
همین قاعده روی هر بخش از یک درخواست چت هم صدق میکند. الگوی چت (chat template) پیامها را با ترتیبی ثابت به یک دنبالهی توکن تبدیل میکند: پیام سیستمی، فهرست ابزارها، نوبتهای قبلی گفتوگو (earlier turns) و پیام جدید. هر تغییری در پیام سیستمی همهچیز را باطل میکند؛ تغییری در جدیدترین پیام فقط همان پیام را از اعتبار میاندازد.
ماجرای رخداده
گزارش مشکل شمارهی 35129 همان ماجرای ابتدای این بخش است {{issue #35129}}. گزارشدهنده متوجه سه دلیل شد که روی هم تلمبار شده بودند:
- رله برای هر نشست یک هش تصادفیِ
cch=و یک پیام سیستمی چرخشی در هر درخواست قرار میداد. حذف آنها نرخ اصابت موتور را از 66.8 درصد به 94.4 درصد رساند. - کلاینت اسنپشاتِ فهرست وظایف (task-list snapshot) خود را در انتهای پیام سیستمی مینوشت. هر بهروزرسانیِ وظیفه، پیام سیستمی را تغییر میداد و در نتیجه، بیش از 100,000 توکن تاریخچهی پس از آن را باطل میکرد.
- بازیابی کش سلسلهمراتبی (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 نشان میدهد که گیتوی چگونه بر اساس پیشوند مسیریابی میکند.
چطور یک اصابت را اثبات کنیم؟
از سه سنجه استفاده کنید؛ از نزدیکترین سطح به درخواست تا عمومیترین:
- در پاسخ. سرور را با
--enable-cache-reportبالا بیاورید که بهطور پیشفرض خاموش است {{code}}. در این صورت، بلوک usage مقدارcached_tokensرا گزارش میدهد. API بومیِ/generateبدون نیاز به پرچم،cached_tokensرا درmeta_infoبرمیگرداند. - در لاگ اسکژولر. هر خطِ
Prefill batchمقادیر#new-tokenو#cached-tokenرا گزارش میدهد. - در متریکها. اندپوینت
/metricsسنجهیsglang:cache_hit_rateرا بیرون میدهد که معیاری از دستههای (batches) پیشپرکنی اخیر است. پس از اجرای بنچمارک پیشوند مشترک در بخش 3.3، سرور ما مقدار 0.94 را گزارش داد. سروری که با--disable-radix-cacheاجرا شده بود مقدار 0.0 را نشان داد.
[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.