رادیکسکش (RadixCache) تمام توکنهای کششده را در قالب یک درخت نمایهگذاری میکند؛ بنابراین هر درخواست جدید طولانیترین پیشوند منطبق را دوباره به کار میگیرد و فقط توکنهای بعد از آن پیشپرکنی (prefill) میشوند.
یک محصول چت را در نظر بگیرید که همراه هر پرسش، یک پرامپت سیستمی ثابت 2000 توکنی میفرستد. سروری که از استفادهی مجدد از پیشوند (prefix reuse) بیبهره باشد، این 2000 توکن را برای تکتک درخواستها از نو محاسبه میکند و در نتیجه همهی کاربران دوباره معطل همان پردازش تکراری میشوند. روی سیستم Mac ما، همین محاسبات تکراری باعث شد بنچمارک پیشوند مشترک 129.7 ثانیه طول بکشد؛ اما با روشن بودن رادیکسکش، اجرای همان بنچمارک فقط 48.8 ثانیه زمان برد.
پس از پایان این بخش، میتوانید توضیح دهید که درخت چطور پیشوند را پیدا میکند و چرا درخواستهای در حال اجرا پیشوندشان را نگه میدارند. همچنین با نحوهی حذف توکنهای کششده توسط سازوکار بیروناندازی (eviction) آشنا میشوید و یاد میگیرید چطور خطوط لاگ اسکژولر (Scheduler) را که نشاندهندهی وقوع اصابت (hit) هستند بخوانید.
بار کاری یکسان با درخت و بدون آن
کیت بنچمارکگیری، آزمون پیشوند مشترکِ خود SGLang را دو بار اجرا میکند. در این آزمایش چهار گروه 16تایی از پرامپتها تعریف شدهاند که در هر گروه یک پرامپت سیستمی 2048 توکنی مشترک است و هر پرامپت یک پرسش 128 توکنی به آن اضافه میکند. سرور دوم با فلگ --disable-radix-cache اجرا میشود.
| نتیجه | رادیکسکش روشن | --disable-radix-cache |
|---|---|---|
| مدتزمان بنچمارک | 48.81 ثانیه | 129.68 ثانیه |
| میانهی زمان تا اولین توکن | 1358 میلیثانیه | 7222 میلیثانیه |
| صدک 99 زمان تا اولین توکن | 3277 میلیثانیه | 13548 میلیثانیه |
| توکن خروجی بر ثانیه | 83.91 | 31.59 |
اندازهگیریهای ما نشان داد مدتزمان اجرا 2.7 برابر کوتاهتر شد و میانهی زمان انتظار تا اولین توکن 5.3 برابر کاهش یافت. لاگهای اسکژولر نشان میدهند این زمان صرف چه کاری شده است.
[2026-10-16 14:01:00] Prefill batch, #new-seq: 7, #new-token: 955, #cached-token: 15102, token usage: 0.05, #running-req: 1, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 1472.94یک خط از بنچمارک پیشوند مشترک در پیکربندی پیشفرض.
[2026-10-16 14:02:34] Prefill batch, #new-seq: 3, #new-token: 4096, #cached-token: 0, token usage: 0.06, #running-req: 2, #queue-req: 3, #pending-token: 7883, cuda graph: False, input throughput (token/s): 2261.21
[2026-10-16 14:02:36] Prefill batch, #new-seq: 3, #new-token: 4096, #cached-token: 0, token usage: 0.08, #running-req: 4, #queue-req: 1, #pending-token: 3787, cuda graph: False, input throughput (token/s): 2245.89
[2026-10-16 14:02:38] Prefill batch, #new-seq: 2, #new-token: 3787, #cached-token: 0, token usage: 0.10, #running-req: 6, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 1626.02سه خط متوالی از همان بنچمارک با --disable-radix-cache.
در حالتی که درخت فعال بود، هفت درخواست جدید تنها به 955 توکن تازه نیاز داشتند و 15102 توکن مستقیماً از کش خوانده شد. اما بدون درخت، اسکژولر سه دسته (batch) تا سقف 4096 توکن برای هشت درخواست پر کرد که همگی از صفر محاسبه شدند. عدد 4096 همان اندازهی پیشپرکنی تکهای (Chunked Prefill) از بخش 2.2 است.
همان آزمایش روی یک پردازندهی گرافیکی 24 گیگابایتی L4
از آنجا که سیستم Mac فرآیند پیشپرکنی را بسیار کند انجام میدهد، آزمایش را روی یک کارت گرافیک NVIDIA L4 با مدل Qwen/Qwen3-8B تکرار کردیم. این بار طول پرامپت سیستمی مشترک را از 0 تا 4096 توکن تغییر دادیم. در هر بار اجرا چهار گروه 16تایی پرامپت، یک پرسش 128 توکنی، 64 توکن خروجی و سقف هشت درخواست همزمان در نظر گرفته شد. برای هر طول پرامپت، آزمایش را با سه سید (seed) مختلف اجرا کردیم.
… Prefill batch, #new-seq: 3, #new-token: 405, #cached-token: 12952, token usage: 0.58, #running-req: 1, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 1452.28
… Prefill batch, #new-seq: 4, #new-token: 546, #cached-token: 17269, token usage: 0.58, #running-req: 4, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 2532.09دو خط از اجرای دارای پرامپت مشترک 2,048 توکنی. برچسبهای زمانی حذف شدهاند.
… Prefill batch, #new-seq: 2, #new-token: 4096, #cached-token: 0, token usage: 0.68, #running-req: 1, #queue-req: 0, #pending-token: 5527, cuda graph: True, input throughput (token/s): 1632.42
… Prefill batch, #new-seq: 2, #new-token: 4096, #cached-token: 0, token usage: 0.74, #running-req: 2, #queue-req: 0, #pending-token: 1431, cuda graph: True, input throughput (token/s): 1634.70دو خط از اجرای دارای پرامپت مشترک 4,096 توکنی. برچسبهای زمانی حذف شدهاند.
در این دور، کارت L4 که دچار افت فرکانس حرارتی (throttling) شده بود، حدود 1600 توکن را در ثانیه پیشپرکنی کرد. پردازش هر دستهی 4096 توکنی حدود 2.5 ثانیه زمان برد و بدون درخت، تکتک درخواستها هزینهی پردازش پرامپت کامل خود را پرداختند.
| پرامپت مشترک | میانهی TTFT با کش روشن | میانهی TTFT با کش خاموش | توکن خروجی بر ثانیه با کش روشن | توکن خروجی بر ثانیه با کش خاموش |
|---|---|---|---|---|
| 0 | 349 میلیثانیه | 379 میلیثانیه | 113.56 | 113.33 |
| 1024 | 462 میلیثانیه | 2202 میلیثانیه | 105.76 | 70.15 |
| 4096 | 479 میلیثانیه | 14706 میلیثانیه | 88.87 | 20.80 |
در پرامپت مشترک 4096 توکنی، میانهی کلاک SM با کش روشن 1440 مگاهرتز و بدون کش 930 مگاهرتز ثبت شد. در اجرای بدون کش، تمام سیدها زیر کف فرکانسی 1000 مگاهرتزی ما باقی ماندند.
در پرامپت مشترک 4096 توکنی، اندازهگیری ما نشان داد میانهی زمان انتظار 30.7 برابر کمتر و نرخ پردازش (Throughput) 4.3 برابر بیشتر شد. البته هر دو ضریب را به عنوان حد بالا (Upper Bound) در نظر بگیرید؛ زیرا در اجرای بدون کش، در 62 درصد از نمونهها پرچم افت فرکانس حرارتی فعال بود و فرکانس کلاک 35 درصد کاهش داشت. اگر کارت خنک میماند این اختلاف کمتر میشد، ولی تفاوت 35 درصدی در کلاک پردازنده بهتنهایی نمیتواند اختلاف 30 برابری را توجیه کند. زمانی هم که پرامپت مشترکی وجود نداشت، میانهی TTFT فقط 8 درصد تفاوت داشت (که درون محدودهی پراکندگی بین سیدهاست) و نرخ پردازش خروجی تفاوتی نکرد.
اجرای همین بازه روی GB10 با مدل Qwen/Qwen3-30B-A3B-Instruct-2507 ضریب کمتری نشان داد. در 4096 توکن مشترک، میانهی TTFT با درخت 589 میلیثانیه و بدون آن 5208 میلیثانیه (8.8 برابر) بود. نرخ خروجی نیز 120.66 در برابر 49.73 توکن بر ثانیه اندازهگیری شد. سرور بدون درخت یک روز بعد از سرور دیگر راهاندازی شد و با میانهی کلاک 2376 مگاهرتز کار کرد، در حالی که در 37 درصد نمونهها پرچم افت حرارتی فعال بود. در مقابل، سرورِ مجهز به درخت با فرکانس 2496 مگاهرتز کار میکرد.
فرضیه (Hypothesis) ما دربارهی این دو کارت این است که پیشپرکنی روی GB10 ارزانتر تمام میشد. آن مدل به ازای هر توکن تقریباً 3 میلیارد پارامتر فعال میکند؛ به همین خاطر محاسبهی مجدد پرامپت تکراری هزینهی کمتری میبرد. با این حال دو متغیر مداخلهگر باقی میماند: افت فرکانس کارت L4 در حالت بدون کش باعث اغراق در ضریب L4 شد، و آزمایشهای GB10 نیز طی دو روز مختلف و با کلاکهای نابرابر انجام گرفتند.
ساختار درخت
رادیکسکش (RadixCache): یک درخت مبنا (Radix Tree) روی توالی توکنها است که گرههای آن اندیسهای جایگاه (slot) حافظهی KV مربوط به توکنهای روی یالهایشان را نگهداری میکنند. این ایده از مقالهی SGLang آمده که در آن نام این سازوکار را توجه رادیکس (RadixAttention) گذاشتهاند {{paper}}. یک درخت مبنا توالی توکنها را روی یالهای خود نگه میدارد؛ بنابراین یک گره میتواند به تنهایی یک پرامپت سیستمی کامل را درون خود ذخیره کند.
گره درخت (TreeNode): تکگرهی از درخت که فرزندان خود را (با کلید اولین توکنشان) و توالی توکنهای روی یالش را نگه میدارد {{code}}. همچنین حاوی اندیسهای جایگاههای KV برای آن توکنها، شمارندهی قفل، زمان آخرین دسترسی و تعداد اصابتها است.
کل کار با چهار عملیات انجام میگیرد:
- match_prefix: از ریشه حرکت میکند و فرزندی را دنبال میکند که توکن اولش همخوانی دارد. اگر تطابق وسط یک یال تمام شود، آن گره را میشکند تا مرز دقیقاً تنظیم شود. زمان دسترسی همهی گرههای این مسیر بهروزرسانی میشود.
- insert: با همان روش پیش میرود و برای توکنهایی که همخوانی نداشتند یک گره برگ اضافه میکند. اگر درخواست دیگری از قبل همان توکنها را اضافه کرده باشد، SGLang جایگاههای تکراری را آزاد میکند و ارجاع درخواست را به نسخهی موجود در درخت متصل میسازد.
- inc_lock_ref و dec_lock_ref: تعداد درخواستهای در حال اجرایی را که از یک گره استفاده میکنند میشمارند. عددی بالاتر از صفر، کل مسیر تا ریشه را محافظت میکند.
- evict: برگهایی را که هیچ درخواستی روی آنها قفل نگذاشته است، به ترتیب از قدیمیترینها آزاد میکند و با حذف برگها، به سمت بالای شاخه (branch) حرکت میکند.
یک قاعده در اینجا باعث شگفتی افراد میشود: تطابق پیشوند حداکثر میتواند به اندازهی طول پرامپت منهای یک باشد {{code}}. آخرین توکن پرامپت همیشه باید از مرحلهی پیشپرکنی عبور کند، زیرا مدل به لاجیتهای (Logits) آن نیاز دارد تا بتواند اولین توکن خروجی را نمونهبرداری کند. آزمایش کش ما این قاعده را نشان میدهد: برای یک پرامپت 2999 توکنی، گزارش شد که 2998 توکن از کش آمده و 1 توکن جدید پیشپرکنی شده است.
در نسخهی v0.5.22 کدام درخت اجرا میشود؟
نام این کلاس در پستهای وبلاگی و ایشوهای قدیمیتر RadixCache بود. اما در نسخهی v0.5.22 حالت پیشفرض UnifiedRadixCache است؛ درختی واحد که پنجرهی لغزان (Sliding-window) و وضعیت Mamba را هم مدیریت میکند {{code}}. از نسخهی v0.5.21 به بعد، پیمایشهای درخت بهصورت پیشفرض در یک هستهی Rust انجام میگیرد. لاگ سیستم Mac ما این استثنا را نشان میدهد:
[2026-10-16 13:58:06] Using the Python TreeCore: the Rust TreeCore supports Linux only
[2026-10-16 13:58:06] Init Unified Radix Cache. Components: (<ComponentType.FULL: 0>,). Tree Core: UnifiedTreeCore
[2026-10-16 13:58:06] Tree cache initialized: source=default impl=UnifiedRadixCache hybrid_swa=False hybrid_ssm=False hicache_attached=Falseسه خط از لاگ راهاندازی در پیکربندی پیشفرض.
سرور بدون کش نیز همین سه خط را چاپ کرد. آرگومان --disable-radix-cache همچنان ساختار UnifiedRadixCache را میسازد، اما در یک حالت غیرفعال که نه چیزی را تطبیق میدهد و نه چیزی را ثبت میکند. کلاس جداگانهی ChunkCache هم که نوشتههای قدیمیتر توصیفش میکردند، در تاریخ 2026-10-08 حذف شد {{issue #43201}}.
نحوهی استفادهی اسکژولر از درخت
سیاست پیشفرض برای زمانبندی (--schedule-policy) روش fcfs (ورود به ترتیب نوبت) است {{code}}. روش تطابق طولانیترین پیشوند (lpm) که در مقاله آمده، گزینهای است که خودتان باید انتخاب کنید. کد برنامه فقط تا زمانی درخواستها را بر اساس طول پیشوند مرتب میکند که حداکثر 128 درخواست در انتظار باشند؛ زیرا تطبیق دادن تکتک درخواستهای منتظر زمانبر است {{code}}. بالاتر از این تعداد، lpm به همان ترتیب FCFS برمیگردد.
اسکژولر جلوی هدررفت منابع در یک دور کاری را هم میگیرد. وقتی چند درخواستِ منتظر، پیشوندی مشترک دارند که هنوز کش نشده است، به یکی از آنها اجازه میدهد تا بخش مشترک را ابتدا پیشپرکنی کند. سایر درخواستها در دور بعد از آن استفادهی مجدد میکنند. بخش 2.2 این سیاستها را بهطور کامل پوشش میدهد.
دیدگاه ما: رادیکسکش را روشن بگذارید
در اجراهای ما بدون پرامپت مشترک روی L4 و GB10، هزینهی فعال بودن کش آنقدر ناچیز بود که اندازهگیری نمیشد. البته هزینهی آن را زیر بار سنگین بیروناندازی توکنها نسنجیدیم. توکنهای کششده در همان استخر مشترک با درخواستهای فعال نگهداری میشوند و بیروناندازی بنا به تقاضا آنها را آزاد میکند. تنها یک دلیل برای خاموش کردن آن میشناسیم: آزمایش اینکه آیا پاسخ نادرست از استفادهی مجدد از KV ناشی میشود یا خیر. حتی در این حالت هم ابتدا --kv-canary log را امتحان کنید که با قناری (Canary) سلامت جایگاههای KV را بررسی میکند، در حالی که کش همچنان روشن میماند {{code}}.
سپس نرخ اصابت (Hit Rate) را همراه با هر قابلیت جدیدی که اضافه میکنید اندازه بگیرید. ایشوی شماره 32459 این هشدار را میدهد {{issue #32459}}. تیمی که ترافیک بازپخش (Replay) یک ایجنت (Agent) چندنوبتی را اجرا میکرد، متوجه شد که نرخ اصابت پرامپتهای عمیق بدون دیکودینگ حدسی (Speculative Decoding) برابر 97 درصد بود، اما با EAGLE به 40 تا 53 درصد رسید. نرخ پردازش ورودی نیز بدون هیچ خطایی در لاگها، از 43981 به 12881 توکن در ثانیه افت کرد. علت احتمالی، حافظهی KV اضافهای بود که دیکودینگ حدسی رزرو میکرد و این مسئله درخت را ناچار میساخت پرامپتهای کششده را بیرون بیندازد.
گزارشهای عملی جایگاه این شنیدهها را مشخص میکنند. موتور vLLM هم از پیشوندها استفادهی مجدد میکند؛ بنابراین مقایسهی موتورها در واقع سنجش عملکرد دو کش در برابر یکدیگر است. در یک آزمایش مستقل روی 16 مدل با کارت A10G مشخص شد SGLang روی پیشوندهای تکراری برتری دارد {{field Varad More 2026-04}}. این بهبود در مدلهای 7B تا 9B بین 20 تا 40 میلیثانیه کاهش در زمان اولین توکن بود. در تست RunPod روی یک مدل 70B با زمینهی کششدهی 7000 توکنی، سرعت 35.0 در مقایسه با 32.8 توکن بر ثانیه به ازای هر استریم ثبت شد {{field RunPod 2025-06}}. مقالهی SGLang نیز تا 6.4 برابر نرخ پردازش بالاتر را گزارش میدهد {{paper}} که بهترین سناریوی نویسندگان در مقایسه با سیستمهای سال 2024 است.
منابع: python/sglang/srt/mem_cache/radix_cache.py (شامل TreeNode، match_prefix، insert، evict، inc_lock_ref)، فایلهای python/sglang/srt/mem_cache/unified_radix_cache.py، python/sglang/srt/mem_cache/unified_cache/tree_core_registry.py، python/sglang/srt/mem_cache/registry.py، متد python/sglang/srt/managers/schedule_batch.py (_compute_max_prefix_len)، فایلهای python/sglang/srt/managers/schedule_policy.py و python/sglang/srt/arg_groups/fields/schedule.py در نسخهی v0.5.22، capture/out/bench-shared-prefix.txt، capture/out/no-radix-cache-bench-shared-prefix.txt، capture/out/server-default.log، capture/out/server-no-radix-cache.log، capture/out/cache-experiment.txt، مقالهی SGLang با شناسه (arXiv 2312.07104)، ایشوهای شماره #32459 و #43201، گزارش RunPod مورخ 2025-06-15، بنچمارک Varad More مورخ 2026-04-22، لاگهای capture/gpu/out-l4/server-prefix-default.log، capture/gpu/out-l4/server-prefix-no-radix-cache.log، و خلاصهی capture/gpu/summary/l4.json و capture/gpu/summary/gb10.json.