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

مقیاس کش کلید-مقدار FP8 بی‌سروصدا روی 1.0 می‌ماند

FP8 KV scales silently at 1.0

  • سطح ۳: ارشد
  • سناریوی رخداد
  • ۲۰ دقیقه

وضعیت

تیمی مدل Qwen/Qwen3-8B را روی یک کارت گرافیک L4 سرو می‌کند. درخواست‌ها به دلیل پر شدن استخر کش کلید-مقدار (KV pool) در صف می‌مانند؛ بنابراین آن‌ها فلگ --kv-cache-dtype fp8 را اضافه می‌کنند تا هر مقدار کش‌شده به‌جای دو بایت، در یک بایت ذخیره شود. اولین اجرای سرور با خطای کامپایلر از طرف یک کتابخانه‌ی کرنل (kernel) متوقف می‌شود. یکی از همکاران فلگ مربوط به بک‌اند (backend) را اضافه می‌کند، سرور بالا می‌آید و یک بنچمارک سریع نشان می‌دهد که زمان پردازش هر توکن نسبت به قبل کمی کمتر شده است.

تیم پیش از rollout، بنچمارک GSM8K را روی 500 سوال اول آن در دو حالت BF16 و FP8 اجرا می‌کند و می‌بیند که دقت هر دو در بازه‌ی خطای آماری یکسان است. آن‌ها تغییرات را روانه‌ی محیط عملیاتی (production) می‌کنند. در جلسه‌ی بازنگری، مهندس ارشد یک سوال می‌پرسد: «کش از چه مقیاسی (scale) استفاده کرد؟» هیچ‌کس نمی‌داند. مدل اصلی محیط عملیاتی این مدل نیست، بلکه از خانواده‌ای جدیدتر است که چک‌پوینت (checkpoint) آن مقیاس‌های کالیبره‌شده دارد.

نسخه
vLLM 0.31.0
مدل
Qwen/Qwen3-8B
سخت‌افزار
one L4 with 24 GB of memory

شواهد

accuracy-check.txt
title: GSM8K accuracy of the four configs on both engines
source: manuals/vllm-101/capture/gpu/out-l4/gsm8k-fp8-accuracy.txt
lines: 5-19
lang: text
note: Read the sentence about the scales before the table, then the width of each interval.
---
Eval: the first 500 GSM8K test questions, 8-shot, greedy, one run per config. The prefix cache was flushed before each run.
Neither checkpoint carries KV scales, so the FP8 KV runs used a scale of 1.0.
vLLM FP8 KV runs used --attention-backend TRITON_ATTN, because the FlashInfer FP8 prefill kernel does not build on this host.

engine   config                     correct   accuracy   Wilson 95% interval
SGLang   BF16                       458/500   91.6%      88.8 to 93.7
SGLang   FP8 weights                456/500   91.2%      88.4 to 93.4
SGLang   FP8 KV cache               458/500   91.6%      88.8 to 93.7
SGLang   FP8 weights + FP8 KV       460/500   92.0%      89.3 to 94.1
vLLM     BF16                       459/500   91.8%      89.1 to 93.9
vLLM     FP8 weights                453/500   90.6%      87.7 to 92.9
vLLM     FP8 KV cache               454/500   90.8%      87.9 to 93.0
vLLM     FP8 weights + FP8 KV       453/500   90.6%      87.7 to 92.9

Every interval overlaps every other interval, so this run did not show a difference between the configs. With 500 questions, it cannot rule out a loss of a few points.
first-start-fails.txt
title: the first start with an FP8 KV cache on the L4
source: manuals/vllm-101/capture/gpu/incidents/l4-vllm-kv-fp8-flashinfer-attention-jit.txt
lines: 1-5
lang: text
note: Read the backend that the second line picks, then the error in the fourth line.
---
(APIServer pid=813100) INFO 10-22 09:10:51 [api_utils.py:286] non-default args: {'model_tag': 'Qwen/Qwen3-8B', 'host': '127.0.0.1', 'port': 30000, 'model': 'Qwen/Qwen3-8B', 'max_model_len': 8192, 'gpu_memory_utilization': 0.9, 'kv_cache_dtype': 'fp8', 'num_gpu_blocks_override': 1506}
(EngineCore pid=814129) INFO 10-22 09:11:03 [cuda.py:526] Using FLASHINFER attention backend out of potential backends: ['FLASHINFER', 'TRITON_ATTN'].
(EngineCore pid=814129) ERROR 10-22 09:11:53 [core.py:1433] subprocess.CalledProcessError: Command '['ninja', '-v', '-C', '/root/.cache/flashinfer/0.7.0.post1/89/cached_ops/batch_prefill_with_kv_cache_dtype_q_bf16_dtype_kv_e4m3_dtype_o_bf16_dtype_idx_i32_head_dim_qk_128_head_dim_vo_128_posenc_0_use_swa_False_use_logits_cap_False_f16qk_False_kv_stride_equal', '-f', '/root/.cache/flashinfer/0.7.0.post1/89/cached_ops/ba
(EngineCore pid=814129) ERROR 10-22 09:11:53 [core.py:1433] /data/vllm/.venv/lib/python3.12/site-packages/flashinfer/data/cccl/libcudacxx/include/cuda/std/__cccl/cuda_toolkit.h:41:8: error: #error "CUDA compiler and CUDA toolkit headers are incompatible, please check your include paths"
RuntimeError: Engine core initialization failed. See root cause above. Failed core proc(s): {}
known-loader-bugs.txt
title: three rows of the incident index at 0.31.0
source: manuals/vllm-101/sections/r-3-incident-index.md
lines: 16-18
lang: text
note: The first and the third row name a loader that drops scales, and both issues are open.
---
| 54623 | the Qwen3.5 family never loads checkpoint KV scales, so an FP8 KV cache runs at scale 1.0 | open | [FP8 KV cache](#s-fit-more-users-with-an-fp8-kv-cache) |
| 57853 | a weight update sent while the engine sleeps segfaults the engine core | open | [RL rollouts](#s-use-vllm-as-an-rl-rollout-engine) |
| 60333 | one MTP draft loader drops FP8 KV scales, and the draft layers use scale 1.0 | open | [FP8 KV cache](#s-fit-more-users-with-an-fp8-kv-cache) |
speed-at-a-fixed-pool.txt
title: the FP8 KV cache with the Triton backend against the BF16 default, pool held fixed
source: manuals/vllm-101/sections/2-4-fit-more-users-with-an-fp8-kv-cache.md
lines: 69-72
lang: text
note: Compare the clock and the seed count of each row before you read the time per token.
---
| Users, L4 throttled session | Median TPOT, BF16 / FP8 | Output tok/s, BF16 / FP8 | Median SM clock, BF16 / FP8 | Seeds, BF16 / FP8 |
|---|---|---|---|---|
| 1 | 104.1 / 101.8 ms | 10.59 / 10.75 | 210 / 210 MHz | 3 / 2 |
| 32 | 142.7 / 138.0 ms | 186.68 / 192.00 | 450 / 480 MHz | 3 / 2 |
the-check.txt
title: the manual's check for scales in the checkpoint and in the startup log
source: manuals/vllm-101/sections/2-4-fit-more-users-with-an-fp8-kv-cache.md
lines: 110-114
lang: text
note: The last line names the warning to search for in the log.
---
No output means that the checkpoint has no scales.

A checkpoint with one weight file has no index. For it, list the tensor names with the `safetensors` Python package.

Then read the startup log. The warning `Using KV cache scaling factor 1.0` means that vLLM uses a scale of 1.0. If the checkpoint has scales and the log still shows the warning, the loader dropped them.

سؤال‌ها

  1. سرور با تغییر نوع داده‌ی کلید-مقدار، بک‌اند اتنشن (attention) متفاوتی را انتخاب کرد. چرا نوع داده تعیین‌کننده‌ی بک‌اند است و چرا آن بک‌اند روی این میزبان خطا داد؟
  2. در جدول سرعت، میان دو اجرای BF16 و FP8 دو پارامتر تغییر کردند. بر اساس این جدول، در چه تعداد کاربری چه ادعایی می‌توانید داشته باشید و چه ادعایی نمی‌توانید بکنید؟
  3. مقیاس کلید-مقدار چیست، مقیاس 1.0 چه اثری روی مقدار FP8 می‌گذارد و برای کدام چک‌پوینت‌ها عدد 1.0 تنها گزینه‌ی ممکن است؟
  4. تمام بازه‌ها در جدول دقت با یکدیگر همپوشانی دارند. این موضوع چه چیزی را اثبات می‌کند و با 500 سوال چه چیزی را نمی‌توان رد کرد؟
  5. چک‌پوینت محیط عملیاتی حاوی مقیاس‌های کالیبره‌شده است. سه مرحله‌ی بررسی را به ترتیب بگویید که ثابت کند سرورِ در حال اجرا از آن‌ها استفاده می‌کند.

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

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

از راه‌اندازی ناموفق شروع کنید. خط دوم لاگ انتخاب بک‌اند را نشان می‌دهد: FLASHINFER از میان دو گزینه‌ی کاندید یعنی FLASHINFER و TRITON_ATTN. نام FlashAttention در این فهرست دیده نمی‌شود. روی کارت L4، فریم‌ورک vLLM ابتدا FlashAttention را امتحان می‌کند؛ اما در نسخه‌ی 0.31.0 FlashAttention کش کلید-مقدار FP8 را فقط روی پردازنده‌های گرافیکی دیتاسنتری معماری Hopper و Blackwell می‌خواند، در حالی که L4 یک پردازنده‌ی گرافیکی معماری Ada با قابلیت محاسباتی SM 8.9 است. بنابراین vLLM به سراغ گزینه‌ی بعدی در فهرست خود رفت. FlashInfer کرنل‌هایش را در اولین اجرا بیلد می‌کند و خط چهارم نشان می‌دهد این فرایند به دلیل ناسازگاری نسخه‌ی کامپایلر CUDA با هدرهای CUDA شکست خورده است. راه‌حل استفاده از --attention-backend TRITON_ATTN است که بدون نیاز به بیلد، کش کلید-مقدار FP8 را می‌خواند؛ به همراه VLLM_USE_FLASHINFER_SAMPLER=0 چون ماژول نمونه‌گیر (sampler) هم با خطای بیلد مشابهی روبه‌رو می‌شود.

جدول سرعت، حجم استخر را در هر دو اجرا روی 24,096 توکن ثابت نگه داشته است؛ بنابراین استخر بزرگ‌تر را به هیچ وجه نشان نمی‌دهد، بلکه تغییر سرعت را نشان می‌دهد. در حالت یک کاربر، FP8 به ازای هر توکن 2.3 درصد سریع‌تر بود (101.8 در برابر 104.1 میلی‌ثانیه)، آن هم در فرکانس کاری یکسان 210 مگاهرتز، و بازه‌ی نتایج تکرارها هیچ همپوشانی نداشتند. در حالت 32 کاربر، بازه‌ی نتایج تکرارها همپوشانی داشتند و اجرای FP8 فرکانس بالاتری ثبت کرد (480 در برابر 450 مگاهرتز)؛ بنابراین در این نقطه نمی‌توان ادعایی مطرح کرد. چون دو متغیر با هم تغییر کردند (نوع داده‌ی کلید-مقدار و بک‌اند)، حتی بهبود سرعت در حالت یک کاربر را هم نمی‌توان صرفاً به نوع داده نسبت داد.

جدول دقت با همان جمله‌ای آغاز می‌شود که پاسخ مهندس ارشد است: هیچ‌کدام از چک‌پوینت‌ها مقیاس کلید-مقدار ندارند، بنابراین اجراهای FP8 از مقیاس 1.0 استفاده کرده‌اند. یک مقدار FP8 بیت‌های کمی دارد و مقیاس تعیین می‌کند که دامنه‌ی مقادیر واقعی کلیدها و مقدارها چگونه روی این دامنه‌ی محدود نگاشت شوند. سرور بدون مقیاس کالیبره‌شده، مقادیر را همان‌طور که هستند ذخیره می‌کند. نتیجه برای این مدل 454 پاسخ درست از 500 سوال در مقایسه با 459 پاسخ در حالت BF16 بود؛ یعنی 90.8 درصد در برابر 91.8 درصد، با بازه‌های اطمینان 87.9 تا 93.0 و 89.1 تا 93.9. هر بازه با بازه‌ی دیگر همپوشانی دارد. این یعنی آزمون تفاوتی را نشان نداد؛ اما به این معنی نیست که هیچ تفاوتی وجود ندارد. با 500 سوال نمی‌توان افت در حد چند نمره را رد کرد، ضمن این‌که آزمون فقط یک مدل و یک بنچمارک را سنجیده است.

فهرست رخدادها همان بخشی است که سوال را حساس و پرریسک می‌کند. گزارش خطای 54623 نشان می‌دهد که خانواده‌ی مدل‌های Qwen3.5 اصلاً مقیاس‌های کلید-مقدار موجود در چک‌پوینت خود را بارگذاری نمی‌کنند؛ در نتیجه کش کلید-مقدار FP8 حتی در صورت وجود مقیاس‌های کالیبره‌شده در چک‌پوینت، با مقیاس 1.0 اجرا می‌شود. گزارش 60333 نیز رفتار مشابهی را برای لودر پیش‌نویس MTP نشان می‌دهد. هر دو مورد در نسخه‌ی 0.31.0 همچنان باز هستند. بنابراین، وجود مقیاس‌ها در چک‌پوینت ثابت نمی‌کند که سرور واقعاً از آن‌ها استفاده می‌کند.

بخش آخر شواهد، نحوه‌ی بررسی را مشخص می‌کند. در نمایه یا ایندکس وزن‌ها نام تنسورهایی (tensor) را جست‌وجو کنید که به k_scale یا v_scale ختم می‌شوند. اگر خروجی خالی بود یعنی چک‌پوینت مقیاسی ندارد. سپس لاگ راه‌اندازی را بخوانید و به دنبال هشدار Using KV cache scaling factor 1.0 بگردید. اگر چک‌پوینت مقیاس دارد ولی هشدار در لاگ دیده می‌شود، لودر آن‌ها را نادیده گرفته است. در پایان، پرامپت‌های (prompt) خودتان را با و بدون FP8 اجرا کنید و خروجی‌ها را با هم بسنجید.

نتیجه

این رخداد ناشی از کرش سیستم نبود، بلکه از نپرسیدن یک سوال مهم نشئت گرفت. برای مدل Qwen/Qwen3-8B مقیاس 1.0 تنها گزینه‌ی ممکن بود و بررسی دقت روی 500 سوال نیز تفاوتی میان دو پیکربندی نشان نداد. اما تیم برای مدل محیط عملیاتی باید سه مورد را پیش از rollout اثبات می‌کرد: این‌که چک‌پوینت تنسورهای k_scale و v_scale را دارد، این‌که در لاگ راه‌اندازی هشدار مقیاس 1.0 چاپ نمی‌شود، و این‌که نمونه‌ای از پرامپت‌های خودشان با و بدون FP8 خروجی‌های یکسانی تولید می‌کند.

آن‌ها همچنین باید بعد از هر بار تغییر نوع داده‌ی کلید-مقدار، خط مربوط به بک‌اند را در لاگ می‌خواندند. روی این کارت L4، این تغییر باعث شد سرور از FlashAttention به Triton جابه‌جا شود، و جدول سرعت بیش از آن‌که نوع داده را بسنجد، این جابه‌جایی را اندازه گرفته بود. همواره در کنار نتیجه، نوع بک‌اند، مقیاس و بازه‌ی دقت را بنویسید و ارزیابی دقت را روی وظیفه‌ی (task) واقعی خودتان انجام دهید؛ چرا که مدلی با ساختار اتنشن متفاوت می‌تواند افت بسیار بیشتری نشان دهد.

مسیرهای اشتباه رایج
  • «چون دقت یکسان بود، پس FP8 برای هر مدلی امن است.» این بررسی فقط یک مدل بدون مقیاس، یک بنچمارک و 500 سوال را پوشش داد. این ارزیابی نمی‌تواند افت در حد چند نمره را رد کند، و مدلی دیگر ممکن است افت بیشتری داشته باشد.
  • «چک‌پوینت مقیاس دارد، پس سرور از آن‌ها استفاده می‌کند.» در نسخه‌ی 0.31.0 دو issue باز وجود دارد که لودرها در آن‌ها مقیاس‌ها را نادیده می‌گیرند و با 1.0 اجرا می‌شوند. تنها لاگ راه‌اندازی ثابت می‌کند که سرور واقعاً از چه چیزی استفاده کرده است.
  • «کوانتیزه‌سازی FP8 سرعت هر توکن را 2.3 درصد بیشتر کرد، پس این نوع داده ارزشش را داشت.» در همان اجرا بک‌اند هم تغییر کرد و این برتری فقط در حالت یک کاربر برقرار بود. جدول نمی‌تواند بگوید کدام تغییر این نتیجه را داده است.
  • «خطای کامپایلر را رفع کنید تا FlashInfer بیلد شود.» این کار تعمیر میزبان است، نه تصمیم فنی برای سرو مدل. بک‌اند Triton کش FP8 را بدون نیاز به بیلد می‌خواند و خط بک‌اند در لاگ می‌گوید کدام‌یک در حال اجراست.
درس کلی

حافظه‌ی کوانتیزه‌شده به مقیاس نیاز دارد و مقیاس پیش‌فرض 1.0 انتخابی بی‌صداست که سرور به‌جای شما انجام می‌دهد. هر بار که نوع داده را تغییر می‌دهید، پیامدهای آن را در این سه خط ارزیابی کنید: اکنون کدام کرنل اجرا می‌شود، از چه مقیاسی استفاده می‌کند، و تست کیفیت با این حجم نمونه چه چیزهایی را می‌تواند یا نمی‌تواند تشخیص دهد. تستی که تفاوتی نشان نمی‌دهد، صرفاً سقف افت را محدود می‌کند، نه این‌که احتمال افت را به کلی از بین ببرد.

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

راهنمای جامع vLLM فعال‌سازی کش کلید-مقدار FP8 و بررسی مقیاس‌ها را در صفحه‌ی کش کلید-مقدار FP8، توضیح انتخاب بک‌اند را در صفحه‌ی بک‌اند اتنشن و فهرست باگ‌های باز لودر را در فهرست رخدادها پوشش می‌دهد؛ همچنین راهنمای SGLang ارزیابی مشابهی برای دقت را در صفحه‌ی کوانتیزه‌سازی پیاده می‌کند.