سناریوی رخداد

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

A request ID that opens the prompt

  • سطح ۲: میانی
  • سناریوی رخداد
  • ۱۵ دقیقه

وضعیت

یک محصول مبتنی بر ایجنت (Agent)، تمام درخواست‌ها را از طریق یک رله (Relay) می‌فرستد. این رله برای ردگیری محاسبات (Tracing)، یک خط جدید به قالب .Request id <hex> در ابتدای پرامپت سیستم (System prompt) می‌گذارد که در هر فراخوانی مقدار متفاوتی دارد. خود پرامپت سیستم 2,999 توکن طول دارد و هرگز تغییر نمی‌کند. تیم فنی مدل Qwen/Qwen3-8B را با SGLang روی یک پردازنده‌ی گرافیکی L4 و با فعال بودن پرچم --enable-cache-report سرو می‌کند.

کاربران گزارش می‌دهند که تولید اولین توکن در هر نوبت گفت‌وگو (Turn) حدود 2 ثانیه طول می‌کشد؛ حتی وقتی سؤالی را تکرار می‌کنند. تیم سهم حافظه (Memory fraction) را دو برابر می‌کند، سیاست تخلیه‌ی حافظه (Eviction policy) متفاوتی را می‌آزماید و کش سلسله‌مراتبی (Hierarchical caching) را روشن می‌کند. اما زمان انتظار هیچ تکانی نمی‌خورد. اندپوینت (Endpoint) متریک‌ها نیز نرخ اصابت (Hit Rate) کش را نزدیک به صفر گزارش می‌دهد.

نسخه
SGLang 0.5.22
مدل
Qwen/Qwen3-8B
سخت‌افزار
one L4 with 24 GB of memory, and a GB10 as the second machine

شواهد

id-at-end.txt
title: the same request id moved to the end of the system prompt
source: manuals/sglang-101/capture/gpu/out-l4/cache-experiment.txt
lines: 11-15
lang: text
note: Compare cached_tokens with prompt_tokens on each line.
---
{"case": "id-at-end", "round": 1, "ttft_ms": 98.2, "prompt_tokens": 3033, "cached_tokens": 2983}
{"case": "id-at-end", "round": 2, "ttft_ms": 98.4, "prompt_tokens": 3032, "cached_tokens": 2987}
{"case": "id-at-end", "round": 3, "ttft_ms": 99.7, "prompt_tokens": 3033, "cached_tokens": 2986}
{"case": "id-at-end", "round": 4, "ttft_ms": 97.2, "prompt_tokens": 3030, "cached_tokens": 2985}
{"case": "id-at-end", "round": 5, "ttft_ms": 93.1, "prompt_tokens": 3032, "cached_tokens": 2987}
id-at-start.txt
title: five requests whose system prompt starts with a request id
source: manuals/sglang-101/capture/gpu/out-l4/cache-experiment.txt
lines: 6-10
lang: text
note: Read cached_tokens on every line, then ttft_ms.
---
{"case": "id-at-start", "round": 1, "ttft_ms": 2171.2, "prompt_tokens": 3032, "cached_tokens": 3}
{"case": "id-at-start", "round": 2, "ttft_ms": 2161.4, "prompt_tokens": 3034, "cached_tokens": 6}
{"case": "id-at-start", "round": 3, "ttft_ms": 2159.2, "prompt_tokens": 3031, "cached_tokens": 6}
{"case": "id-at-start", "round": 4, "ttft_ms": 2161.8, "prompt_tokens": 3031, "cached_tokens": 6}
{"case": "id-at-start", "round": 5, "ttft_ms": 2160.6, "prompt_tokens": 3033, "cached_tokens": 6}
scheduler-view.txt
title: the scheduler log while the three forms went through
source: manuals/sglang-101/capture/gpu/out-l4/server-default.log
lines: 62-79
lang: text
note: Follow the cached-token field through the stable prompt, the id at the start, and the id at the end.
---
[2026-10-17 14:43:50] Prefill batch, #new-seq: 1, #new-token: 1, #cached-token: 2998, token usage: 0.13, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 0.99
[2026-10-17 14:43:50] INFO:     127.0.0.1:59136 - "POST /v1/chat/completions HTTP/1.1" 200 OK
[2026-10-17 14:43:51] Decode batch, #running-req: 1, #token: 3010, token usage: 0.13, cuda graph: True, gen throughput (token/s): 14.48, #queue-req: 0
[2026-10-17 14:43:53] Prefill batch, #new-seq: 1, #new-token: 3029, #cached-token: 3, token usage: 0.13, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 972.29
[2026-10-17 14:43:53] INFO:     127.0.0.1:59142 - "POST /v1/chat/completions HTTP/1.1" 200 OK
[2026-10-17 14:43:57] Prefill batch, #new-seq: 1, #new-token: 3028, #cached-token: 6, token usage: 0.13, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 966.95
[2026-10-17 14:43:57] INFO:     127.0.0.1:51474 - "POST /v1/chat/completions HTTP/1.1" 200 OK
[2026-10-17 14:44:00] Prefill batch, #new-seq: 1, #new-token: 3025, #cached-token: 6, token usage: 0.13, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 966.73
[2026-10-17 14:44:00] INFO:     127.0.0.1:51480 - "POST /v1/chat/completions HTTP/1.1" 200 OK
[2026-10-17 14:44:00] Decode batch, #running-req: 1, #token: 3037, token usage: 0.13, cuda graph: True, gen throughput (token/s): 4.41, #queue-req: 0
[2026-10-17 14:44:03] Prefill batch, #new-seq: 1, #new-token: 3025, #cached-token: 6, token usage: 0.13, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 965.89
[2026-10-17 14:44:03] INFO:     127.0.0.1:51494 - "POST /v1/chat/completions HTTP/1.1" 200 OK
[2026-10-17 14:44:06] Prefill batch, #new-seq: 1, #new-token: 3027, #cached-token: 6, token usage: 0.13, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 966.89
[2026-10-17 14:44:06] INFO:     127.0.0.1:51506 - "POST /v1/chat/completions HTTP/1.1" 200 OK
[2026-10-17 14:44:07] Decode batch, #running-req: 1, #token: 0, token usage: 0.00, cuda graph: True, gen throughput (token/s): 5.79, #queue-req: 0
[2026-10-17 14:44:07] Prefill batch, #new-seq: 1, #new-token: 50, #cached-token: 2983, token usage: 0.13, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 46.77
[2026-10-17 14:44:07] INFO:     127.0.0.1:41460 - "POST /v1/chat/completions HTTP/1.1" 200 OK
[2026-10-17 14:44:08] Prefill batch, #new-seq: 1, #new-token: 45, #cached-token: 2987, token usage: 0.13, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 42.41
second-machine.txt
title: the summary of the same experiment on a GB10 with a larger model
source: manuals/sglang-101/capture/gpu/out-gb10/cache-experiment.txt
lines: 16-18
lang: text
note: The times differ from the L4, the cached-token counts do not.
---
{"summary": "stable-system-prompt", "median_ttft_ms": 44.75, "min_ttft_ms": 44.2, "max_ttft_ms": 48.4, "median_cached_tokens": 2998.0, "prompt_tokens": 2999}
{"summary": "id-at-start", "median_ttft_ms": 632.2, "min_ttft_ms": 631.0, "max_ttft_ms": 645.2, "median_cached_tokens": 6, "prompt_tokens": 3030}
{"summary": "id-at-end", "median_ttft_ms": 143.9, "min_ttft_ms": 139.5, "max_ttft_ms": 148.8, "median_cached_tokens": 2985, "prompt_tokens": 3032}
stable-prompt.txt
title: the same five requests with a stable system prompt
source: manuals/sglang-101/capture/gpu/out-l4/cache-experiment.txt
lines: 1-5
lang: text
note: The first round fills the cache, so read the four rounds after it.
---
{"case": "stable-system-prompt", "round": 1, "ttft_ms": 2143.9, "prompt_tokens": 2999, "cached_tokens": 3}
{"case": "stable-system-prompt", "round": 2, "ttft_ms": 82.8, "prompt_tokens": 2999, "cached_tokens": 2998}
{"case": "stable-system-prompt", "round": 3, "ttft_ms": 85.1, "prompt_tokens": 2999, "cached_tokens": 2998}
{"case": "stable-system-prompt", "round": 4, "ttft_ms": 82.2, "prompt_tokens": 2999, "cached_tokens": 2998}
{"case": "stable-system-prompt", "round": 5, "ttft_ms": 80.7, "prompt_tokens": 2999, "cached_tokens": 2998}

سؤال‌ها

  1. فهرست اول پنج درخواست را نشان می‌دهد. تعداد توکن‌های کش‌شده (Cached tokens) درباره‌ی نقطه‌ی توقف تطابق چه چیزی به شما می‌گوید؟
  2. درخت مبنا (Radix Tree) چگونه یک پرامپت را تطبیق می‌دهد، و چرا بعد از اولین تفاوت، هیچ چیز دیگری قابل تطبیق نیست؟
  3. در فهرست سوم، شناسه در انتهای پرامپت آمده است. پیش از خواندن ادامه، تعداد توکن‌های کش‌شده را پیش‌بینی کنید؛ سپس علت تفاوت را توضیح دهید.
  4. کدام سه نقطه در یک سرور در حال اجرا می‌توانند اصابت یا عدم‌اصابت کش را تأیید کنند؛ از نزدیک‌ترین نقطه به درخواست تا عمومی‌ترین آن‌ها؟
  5. تیم فنی ابتدا لایه‌های کش و سیاست تخلیه را تنظیم کرد. چرا هیچ‌کدام از این تنظیمات کمکی نکردند، و ترتیب درست برای تغییر پرامپت‌ها و پرچم‌های سرور چیست؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام

فهرست اول را فیلد به فیلد بخوانید. هر درخواست حدود 3,030 توکن پرامپت می‌فرستد و سرور مقدار cached_tokens را 3 یا 6 گزارش می‌دهد. تولید اولین توکن در هر دور بین 2,159.2 تا 2,171.2 میلی‌ثانیه زمان می‌برد. بنابراین هر درخواست تاوان پیش‌پرکنی (Prefill) کامل پرامپت سیستم را می‌دهد و تنها توکن‌هایی که کش پیدا کرده، همان چند توکن انگشت‌شماری هستند که پیش از ارقام تصادفی هگزادسیمال آمده‌اند.

فهرست دوم نقش نمونه‌ی کنترل را دارد. همان سؤال پس از یک پرامپت سیستمِ ثابت، از دور دوم به بعد، 2,998 توکن کش‌شده از 2,999 توکن را گزارش می‌دهد و اولین توکن در 80.7 تا 85.1 میلی‌ثانیه می‌رسد. دور اول 3 توکن کش‌شده و زمان 2,143.9 میلی‌ثانیه را ثبت می‌کند، چون در حال پر کردن کش بوده است. در نتیجه، سرور و مدل در صورت تطابق پرامپت می‌توانند حدود 25 برابر سریع‌تر پاسخ دهند.

فهرست سوم همان شناسه‌ی تصادفی را به انتهای پرامپت سیستم منتقل می‌کند. تعداد توکن‌های کش‌شده به 2,983 تا 2,987 توکن می‌رسد. رسیدن اولین توکن 93.1 تا 99.7 میلی‌ثانیه طول می‌کشد. توکن‌ها در هر سه حالت تقریباً یکسان هستند و فقط ترتیب آن‌ها فرق می‌کند. درخت مبنا توکن‌ها را از اولین توکن مقایسه می‌کند و با رسیدن به نخستین تفاوت متوقف می‌شود. هیچ چیز بعد از یک تفاوت نمی‌تواند تطبیق پیدا کند؛ زیرا مقادیر اتنشن (Attention) هر توکنِ بعدی به همه‌ی توکن‌های قبلی وابسته است. کشی که توکن‌های بعدی را دوباره مصرف کند، پاسخ‌های اشتباه تحویل خواهد داد.

لاگ اسکژولر هم همین ماجرا را از سمت سرور بازگو می‌کند. دورهای با پرامپت ثابت مقدار #cached-token: 2998 را با یک توکن جدید ثبت می‌کنند. سپس پنج دسته‌ی (Batch) پیش‌پرکنی لاگ می‌شوند که حدود 3,025 تا 3,029 توکن جدید دارند و فقط 3 یا 6 توکن کش‌شده به همراه دارند. پس از آن، دورهایی که شناسه در انتهای آن‌هاست، 45 تا 50 توکن جدید را با 2,983 تا 2,987 توکن کش‌شده ثبت می‌کنند. فهرست آخر، تکرار آزمایش روی یک ماشین GB10 با مدلی از نوع ترکیبی از متخصص‌ها (Mixture of Experts) است. زمان‌ها متفاوت‌اند؛ 632.2 میلی‌ثانیه در برابر 44.75 میلی‌ثانیه، ولی تعداد توکن‌های کش‌شده تفاوتی ندارد: 6 توکن در برابر 2,998 توکن.

نتیجه

رله مقداری متغیر را درست در ابتدای تنها بخشی از پرامپت نشانده بود که بین تمام درخواست‌ها مشترک است. مشکل با یک ویرایش حل شد: شناسه‌ی ردگیری محاسبات (Trace ID) را از پرامپت سیستم خارج کنید و در متادیتای درخواست بفرستید، یا آن را به انتها ببرید. در اندازه‌گیری ما روی پردازنده‌ی گرافیکی L4، میانه‌ی زمان تولید اولین توکن از 2,161.4 میلی‌ثانیه (با شناسه در ابتدا) به 98.2 میلی‌ثانیه (با شناسه در انتها) افت کرد و میانه‌ی تعداد توکن‌های کش‌شده از 6 به 2,986 توکن از مجموع حدود 3,030 توکن رسید.

این راهکار را از سه نقطه بررسی کنید: سرور را با پرچم --enable-cache-report بالا بیاورید و مقدار cached_tokens را در بلوک usage هر پاسخ بخوانید؛ خطوط Prefill batch را در لاگ اسکژولر ببینید و مقدار #cached-token را بررسی کنید؛ متریک sglang:cache_hit_rate را از اندپوینت /metrics بخوانید. در vLLM، متریک‌های vllm:prefix_cache_hits_total و vllm:prefix_cache_queries_total را بررسی کنید. تنظیمات کِشی که تیم فنی ابتدا سراغشان رفت مشکل اصلی نبودند؛ هیچ سیاست تخلیه یا لایه‌ی میزبانی (Host tier) نمی‌تواند توکن‌هایی را که از همان ابتدا تفاوت دارند تطبیق دهد.

مسیرهای اشتباه رایج
  • «سهم حافظه را بالا ببریم تا کش ظرفیت بیشتری داشته باشد.» مخزن حافظه پر نبود. عدم‌اصابت به دلیل ترتیب توکن‌ها در پرامپت رخ داد؛ افزایش ظرفیت فقط بلوک‌های بیشتری نگه می‌دارد که هیچ درخواستی با آن‌ها منطبق نمی‌شود.
  • «کش سلسله‌مراتبی را فعال کنیم.» لایه‌ی حافظه‌ی میزبان پیشوندهای تخلیه‌شده را نگه می‌دارد، در حالی که اصلاً چیزی تخلیه نشده بود. پیشوند از همان ابتدا تطبیق پیدا نمی‌کرد.
  • «نرخ اصابت پایین است چون سؤال‌ها فرق می‌کنند.» سؤال فقط حدود 30 توکن در انتهای یک پرامپت 2,999 توکنی است. یک سؤال متغیر حدود 30 توکن هزینه‌ی پیش‌پرکنی دارد، نه 2,999 توکن.
  • «پرامپت سیستم را هش کنیم و بر اساس آن درخواست‌ها را مسیریابی (Routing) کنیم.» مسیریابی زمانی مهم است که چند سرور بار ترافیک را تقسیم کنند، اما اینجا پای یک سرور در میان بود و پرامپت پیش از اینکه مسیریابی بتواند کمکی بکند، در تک‌تک درخواست‌ها تغییر می‌کرد.
درس کلی

چیدمان پرامپت را بخشی از سامانه‌ی سرو مدل در نظر بگیرید. محتوایی که هرگز تغییر نمی‌کند را در ابتدا، محتوایی که در سطح هر نشست (Session) تغییر می‌کند را پس از آن، و محتوایی را که با هر درخواست تغییر می‌کند در انتها قرار دهید. شناسه‌ها، برچسب‌های زمانی (Timestamps)، هش‌ها و مقادیر اولیه‌ی تصادفی (Random seeds) را وارد پرامپت سیستم نکنید، و تعریف ابزارها (Tool Definitions) و کلیدهای JSON را همیشه با ترتیبی ثابت نگه دارید. پیش از تغییر دادن هر پرچم مربوط به کش، تعداد توکن‌های کش‌شده را روی درخواست‌های واقعی خود بخوانید. اصلاح ساختار پرامپت می‌تواند نرخ اصابتی را احیا کند که هیچ پرچمی در سرور قادر به جبران آن نیست.

کجای دوره آموزش داده می‌شود

مستندات SGLang این سه شکل پرامپت را در صفحه‌ی پرامپت‌های سازگار با پیشوند اندازه‌گیری کرده و ساختار درختی را در صفحه‌ی RadixCache شرح می‌دهد. راهنمای vLLM نیز همین قاعده را در صفحه‌ی کش پیشوند خود آورده است، و درس توجه رادیکس (RadixAttention) این سازوکار را از صفر می‌سازد.