بخش 7.1 · عملیات و اشکال‌زدایی

عیب‌یابی بر اساس نشانه‌ها

Troubleshoot by symptom

فهرست مطالب
  1. سرور اجرا نمی‌شود
  2. اجرای سرور هنگام دانلود مدل متوقف می‌شود (hang می‌کند)
  3. اجرای سرور با پیامی مبنی بر پشتیبانی نشدن مدل متوقف می‌شود
  4. اجرای سرور با پیامی درباره‌ی درایور یا ابزارهای PTX متوقف می‌شود
  5. اجرای سرور با پیامی درباره‌ی کش KV و حداکثر طول زمینه متوقف می‌شود
  6. اجرای سرور با پیامی درباره‌ی حافظه‌ی آزاد و سهم حافظه متوقف می‌شود
  7. سرور هنگام شروع و پس از فعال‌سازی کش KV در فرمت FP8 کرش می‌کند
  8. اولین اجرای سرور با پیامی مبنی بر در دسترس نبودن nvcc متوقف می‌شود
  9. پس از تنظیم CUDA_HOME، نمونه‌گیر کامپایل نمی‌شود
  10. در DGX Spark خطای کمبود حافظه رخ می‌دهد، با اینکه سهم تعیین‌شده جا دارد
  11. اولین اجرای سرور روی DGX Spark چندین دقیقه طول می‌کشد
  12. اجرای سرور در مرحله‌ی کامپایل شکست می‌خورد
  13. سرورِ روی چند GPU در شروع کار گیر می‌کند
  14. پس از ارتقا، حداکثر طول زمینه کمتر شده است
  15. درخواست‌ها در حین اجرای سرور با خطا مواجه می‌شوند
  16. درخواست خطای HTTP 400 درباره‌ی حداکثر طول زمینه می‌دهد
  17. پس از بروز خطا در موتور، همه‌ی درخواست‌ها با شکست روبه‌رو می‌شوند
  18. سرور کند است
  19. تولید اولین توکن چند ثانیه طول می‌کشد، اما تولید ادامه‌ی متن سریع است
  20. هنگام فعالیت کاربران زیاد، جریان خروجی وقفه‌های طولانی دارد
  21. شمارنده‌ی پیش‌دستی بالا می‌رود
  22. دیکودینگ حدسی N-gram کمتر از حد انتظار نتیجه می‌دهد
  23. اولین درخواست‌ها بعد از شروع در حالت eager کند هستند
  24. رمزگشایی NVFP4 روی DGX Spark از نسخه‌های پیشین کندتر است
  25. خروجی اشتباه است
  26. پاسخ مدل با یک بلوک متنیِ طولانیِ تفکر شروع می‌شود
  27. بعد از هیت شدن کش پیشوند، مدل مدام یک توکن را تکرار می‌کند
  28. با فعال بودن دیکودینگ حدسی، خروجی JSON نامعتبر است
  29. خروجی در اجراهای پیاپی تغییر می‌کند
  30. نتایج بنچمارک نادرست است
  31. اجرای دوم بنچمارک سریع‌تر از اجرای اول ثبت می‌شود

بیشتر خرابی‌ها علت مشخصی دارند که با یک خط لاگ یا یک شاخص آماری نمایان می‌شود.

اوضاع درست پیش نمی‌رود و شما فقط نتیجه‌ی نامطلوب را می‌بینید، نه دلیلش را. با خواندن این بخش می‌توانید هر نشانه را به علت آن وصل کنید، یک بررسی مشخص انجام دهید و راهکار مربوطه را پیاده کنید.

نشانه‌ی مشکل خود را در این فهرست پیدا کنید. برای هر مورد، علت احتمالی، بررسی تأییدکننده و راه‌حل آن آمده است. شماره‌ی ایشوها به مخزن (repository) vLLM مربوط می‌شود و وضعیت آن‌ها در نسخه‌ی 0.31.0 درج شده است. مواردی که با عبارت «برگرفته از مستندات vLLM» مشخص شده‌اند، از راهنمای عیب‌یابی vLLM در نسخه‌ی 0.31.0 آمده‌اند و ما مستقیماً آن‌ها را بازتولید نکرده‌ایم.

از نشانه تا راه‌حلاز نشانه شروع کنید، یک عدد یا خط لاگ را بررسی کنید و سپس به صفحه‌ی رفع مشکل بروید.
هر مدخل عیب‌یابی: نشانه، اولین بررسی، و محل رفع مشکل بیست‌وچهار نشانه در پنج گروه: سرور شروع به کار نمی‌کند، درخواست‌ها ناموفق هستند، سرور کند است، خروجی نادرست است، و بنچمارک اشتباه است. هر سطر اولین خط لاگ یا متریک برای بررسی و بخش یا اقدام مربوط به رفع آن را ارائه می‌دهد. آنچه می‌بینید بررسی اولیه THEN سرور شروع به کار نمی‌کند توقف دانلود حجم پوشه کش hf download مدل پشتیبانی نمی‌شود معماری در خطا فهرست پشتیبانی خطای درایور یا PTX متن خطا به‌روزرسانی درایور کش KV و حداکثر طول طول در خطا 2.2 حافظه آزاد زیر سهم nvidia-smi 2.2 کرش با کش KV از نوع FP8 خط backend 2.4 کمبود حافظه DGX Spark free -g 2.3 شروع کند اولیه، GB10 Model loading took 2.3 خطا در مرحله کامپایل خطای torch.compile پاک‌سازی کش توقف اجرای چند-GPU NCCL_DEBUG=TRACE 6.1 حداکثر طول کوتاه‌تر طول مشتق‌شده 2.6 درخواست‌ها ناموفقند HTTP 400، طول زمینه تعداد در خطا درخواست کوتاه‌تر همه درخواست‌ها رد می‌شوند خطای EngineCore راه‌اندازی مجدد سرور کند است اولین توکن ثانیه‌ها طول می‌کشد در صف، مصرف KV 3.1 وقفه‌های طولانی، کاربران زیاد P99 در برابر میانه 3.3 افزایش پیش‌دستی‌ها num_preemptions 3.1 n-gram بازدهی کمتری دارد هشدار async 4.2 شروع کند در حالت eager درخواست‌های اول 4.3 NVFP4 کند روی GB10 TPOT در برابر 0.28 تثبیت نسخه خروجی نادرست است پاسخ با think شروع می‌شود فیلد محتوا 3.10 یک توکن تکرار می‌شود اصابت کش، spec خاموش کردن یکی JSON نامعتبر با spec اجرا بدون spec 3.5 خروجی در هر اجرا تغییر می‌کند همان درخواست به‌تنهایی 3.8 بنچمارک نادرست است اجرای دوم سریع‌تر است اصابت‌های کش پیشوند 5.1
هر سطر زیر به همان ترتیب یک مدخل است. نشانه، اولین بررسی و محل رفع مشکل را بخوانید؛ برگرفته از اجراهای ما، ایشوهای vLLM و مستندات vLLM.

سرور اجرا نمی‌شود

اجرای سرور هنگام دانلود مدل متوقف می‌شود (hang می‌کند)

  • علت: سرعت دانلود پایین است، یا مدل به توکن (token) پلتفرم Hugging Face نیاز دارد. برگرفته از مستندات vLLM.
  • بررسی: ثبت لاگ پیش از خط Model loading took متوقف می‌شود و حجم پوشه‌ی کش Hugging Face بسیار کند رشد می‌کند یا اصلاً تغییری نمی‌کند.
  • راه‌حل: ابتدا مدل را با دستور hf download دانلود کنید و اگر مدل دسترسی محدود دارد، متغیر محیطی HF_TOKEN را مقداردهی کنید. سپس HF_HUB_OFFLINE=1 را تنظیم کنید تا vLLM فقط از نسخه‌ی محلی استفاده کند.

اجرای سرور با پیامی مبنی بر پشتیبانی نشدن مدل متوقف می‌شود

  • علت: معماری این مدل در نسخه‌ی 0.31.0 vLLM پیاده‌سازی نشده است، یا نبودِ یک پکیج مانع از ایمپورت کد مدل توسط vLLM می‌شود. برگرفته از مستندات vLLM.
  • بررسی: خطا به نام معماری‌های ناموفق اشاره می‌کند؛ مانند Model architectures [...] are not supported for now یا failed to be inspected.
  • راه‌حل: فهرست مدل‌های پشتیبانی‌شده‌ی نسخه‌ی خود را بررسی کنید. اگر مدل در فهرست هست، خطوط لاگ بالاتر از خطا را برای خطای ایمپورت بخوانید.

اجرای سرور با پیامی درباره‌ی درایور یا ابزارهای PTX متوقف می‌شود

  • علت: نسخه‌ی ساخت CUDA در vLLM از درایور NVIDIA شما جدیدتر است. برگرفته از مستندات vLLM.
  • بررسی: متن خطا اعلام می‌کند The NVIDIA driver on your system is too old یا می‌گوید PTX با ابزارهایی پشتیبانی‌نشده کامپایل شده است.
  • راه‌حل: درایور را به‌روزرسانی کنید. در ایمیج رسمی و روی برخی پردازنده‌های گرافیکی دیتاسنتری، تنظیم متغیر محیطی -e VLLM_ENABLE_CUDA_COMPATIBILITY=1 کتابخانه‌های سازگاری CUDA را فعال می‌کند.

اجرای سرور با پیامی درباره‌ی کش KV و حداکثر طول زمینه متوقف می‌شود

  • علت: پردازش یک درخواست با طول --max-model-len به حجم کش کلید-مقدار (KV cache) بیشتری از حافظه‌ی باقی‌مانده پس از بارگذاری وزن‌ها نیاز دارد.
  • بررسی: خطا بیشترین طولی را که در حافظه جا می‌شود مشخص می‌کند.
  • راه‌حل: مقدار --max-model-len را برابر با طولانی‌ترین درخواست مدنظر خود بگذارید. جزئیات بیشتر در صفحه‌ی راه‌اندازی سرور آمده است.

اجرای سرور با پیامی درباره‌ی حافظه‌ی آزاد و سهم حافظه متوقف می‌شود

  • علت: فرایند (process) دیگری حافظه‌ی GPU را اشغال کرده است و سهم درخواستی شما آزاد نیست.
  • بررسی: دستور nvidia-smi را اجرا کنید و فرایندهای فعال روی GPU را ببینید.
  • راه‌حل: مقدار --gpu-memory-utilization را به کمتر از سهم آزاد فعلی کاهش دهید، یا فرایند دیگر را متوقف کنید.

سرور هنگام شروع و پس از فعال‌سازی کش KV در فرمت FP8 کرش می‌کند

  • علت: کش FP8 باعث شده vLLM از بک‌اند FlashInfer استفاده کند، و FlashInfer نتوانسته کرنل‌های (kernel) خود را کامپایل کند. این مشکل در ایشوی 60262 دنبال می‌شود و هنوز باز است.
  • بررسی: خطی را که نام بک‌اند اتنشن (attention) در آن آمده پیدا کنید و خطای FlashInfer بعد از آن را بخوانید.
  • راه‌حل: آرگومان --attention-backend TRITON_ATTN را اضافه کنید. صفحه‌ی کش KV در فرمت FP8 نمونه‌ی این مورد را نشان می‌دهد.

اولین اجرای سرور با پیامی مبنی بر در دسترس نبودن nvcc متوقف می‌شود

  • علت: FlashInfer کرنل‌های خود را در اولین اجرا کامپایل می‌کند، در حالی که هاست فقط درایور دارد و پکیج CUDA toolkit روی آن نصب نیست. ما در نود L4 خود پس از نصب تازه‌ی نسخه‌ی 0.31.0 با uv به این مشکل برخوردیم.
  • بررسی: خطا از سمت flashinfer/jit/cpp_ext.py صادر می‌شود و می‌گوید: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist.
  • راه‌حل: پکیج CUDA toolkit را نصب کنید، مسیر CUDA_HOME را به آن ارجاع دهید و سرور را دوباره اجرا کنید؛ یا از ایمیج رسمی که تول‌کیت را همراه خود دارد استفاده کنید.

پس از تنظیم CUDA_HOME، نمونه‌گیر کامپایل نمی‌شود

  • علت: نسخه‌ی تول‌کیت روی هاست با نسخه‌ی ساخت CUDA در PyTorch یکی نیست؛ در نتیجه نمونه‌گیر (sampler) در FlashInfer کامپایل نمی‌شود. ما در نود L4 با تول‌کیت nvcc 13.4 به این مشکل برخوردیم.
  • بررسی: متن خطا می‌گوید: CUDA compiler and CUDA toolkit headers are incompatible.
  • راه‌حل: نسخه‌ای از تول‌کیت را نصب کنید که با نسخه‌ی ساخت PyTorch همخوانی داشته باشد؛ یا مثل راهنمای صفحه‌ی کش KV در فرمت FP8، سرور را با متغیر محیطی VLLM_USE_FLASHINFER_SAMPLER=0 اجرا کنید.

در DGX Spark خطای کمبود حافظه رخ می‌دهد، با اینکه سهم تعیین‌شده جا دارد

  • علت: در حافظه‌ی یکپارچه (unified memory)، پارامتر --gpu-memory-utilization لزوماً حافظه‌ی اشغالی vLLM را محدود نمی‌کند. ایشوی 46307 گزارش داده که با سهم 0.70 حدود 112 GiB مصرف شده و بدون اصلاحیه بسته شده است. ایشوی 44740 نیز به بزرگ بودن بیش از حد کش KV در دیکودینگ حدسی MTP روی GB10 اشاره دارد و هنوز باز است.
  • بررسی: خط Available KV cache memory را با سهم موردانتظار خود مقایسه کنید و هنگام شروع کار، خروجی free -g را زیر نظر بگیرید.
  • راه‌حل: حجم کش را به بایت و با استفاده از فلگ --kv-cache-memory-bytes تعیین کنید. جزئیات بیشتر در صفحه‌ی DGX Spark آمده است.

اولین اجرای سرور روی DGX Spark چندین دقیقه طول می‌کشد

  • علت: بارگذاری وزن‌ها هر تنسور (tensor) را از نگاشت فایل کپی می‌کند و این کپی روی پردازنده‌ی GB10 کند است. ایشوی 58726 این مشکل را ثبت کرده و هنوز باز است.
  • بررسی: خط Model loading took را بخوانید. در تست ما، بارگذاری 57 GiB حدود 330 ثانیه زمان برد.
  • راه‌حل: وزن‌ها را روی درایو محلی نگه دارید و سرور را پیوسته در حال اجرا بگذارید. جزئیات در صفحه‌ی DGX Spark آمده است.

اجرای سرور در مرحله‌ی کامپایل شکست می‌خورد

  • علت: کش کامپایل خراب شده است، یا نسخه‌ی کتابخانه‌ی Triton با PyTorch همخوانی ندارد. برگرفته از مستندات vLLM.
  • بررسی: خطا از torch.compile یا از پوشه‌ی torch/_inductor می‌آید.
  • راه‌حل: یک بار سرور را با متغیر محیطی VLLM_DISABLE_COMPILE_CACHE=1 اجرا کنید. اگر درست شد، پوشه‌ی ~/.cache/vllm/torch_compile_cache را پاک کنید. هنگام عیب‌یابی می‌توانید با آرگومان -O0 سرور را بدون کامپایل بالا بیاورید.

سرورِ روی چند GPU در شروع کار گیر می‌کند

  • علت: پردازنده‌های گرافیکی به دلیل اشکالات شبکه، درایور یا مانت نشدن حافظه‌ی اشتراکی نمی‌توانند از طریق NCCL با یکدیگر ارتباط برقرار کنند. برگرفته از مستندات vLLM.
  • بررسی: سرور را با متغیر NCCL_DEBUG=TRACE دوباره اجرا کنید و ببینید لاگ در کدام نقطه متوقف می‌شود. آزمون NCCL شرح داده‌شده در صفحه‌ی موازی‌سازی را اجرا کنید.
  • راه‌حل: به کانتینر فلگ --ipc=host یا حجم زیادی از /dev/shm اختصاص دهید. در سیستم‌های متکی بر PCIe، مستندات vLLM برای خطای دسترسی به طرف ارتباط (peer access)، مقدار NCCL_CUMEM_HOST_ENABLE=0 یا به‌روزرسانی درایور را پیشنهاد می‌کند.

پس از ارتقا، حداکثر طول زمینه کمتر شده است

  • علت: انتشار نسخه‌ی 0.30.0 نحوه‌ی خواندن مقیاس‌بندی زمینه (مانند YaRN) را تغییر داد و اکنون طول محاسبه‌شده برای برخی مدل‌ها کوتاه‌تر می‌شود.
  • بررسی: طول محاسبه‌شده در لاگ شروع را با مقدار قبلی مقایسه کنید.
  • راه‌حل: پس از اطمینان از پشتیبانی مدل از آن طول زمینه، پارامتر --max-model-len را خودتان دستی تنظیم کنید.

درخواست‌ها در حین اجرای سرور با خطا مواجه می‌شوند

درخواست خطای HTTP 400 درباره‌ی حداکثر طول زمینه می‌دهد

  • علت: مجموع توکن‌های پرامپت (prompt) به‌اضافه‌ی max_tokens از مقدار تعیین‌شده در --max-model-len بیشتر است.
  • بررسی: متن خطا می‌گوید This model's maximum context length is و تعداد توکن‌ها را می‌نویسد. اگر فقط مقدار max_tokens به‌تنهایی از سقف فراتر برود، مانند تستی که روی نود L4 داشتیم، پیام خطا اعلام می‌کند که max_tokens نمی‌تواند بیشتر از max_model_len باشد.
  • راه‌حل: پرامپت کوتاه‌تری بفرستید، مقدار max_tokens را کم کنید، یا اگر استخر حافظه اجازه می‌دهد، سرور را با حداکثر طول بیشتری بالا بیاورید.

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

  • علت: فرایند هسته‌ی موتور (engine core) به دلیلی مثل خطای GPU متوقف شده است. وب‌سرور API روشن می‌ماند ولی امکان پاسخ‌دهی ندارد. برگرفته از سورس‌کد vLLM.
  • بررسی: لاگ عبارت EngineCore encountered an issue را نشان می‌دهد و دلیل اصلی خطا در سطرهای بالاتر آن آمده است.
  • راه‌حل: ریشه‌ی مشکل را از خط‌های بالاتر رفع و سپس سرور را ری‌استارت کنید. ری‌استارت را به هماهنگ‌کننده (orchestrator) بسپارید، چرا که سرور خودش به‌تنهایی بازیابی نمی‌شود.

سرور کند است

تولید اولین توکن چند ثانیه طول می‌کشد، اما تولید ادامه‌ی متن سریع است

  • علت: به دلیل پر بودن استخر حافظه یا دسته (batch)، درخواست‌ها در صف انتظار معطل می‌شوند.
  • بررسی: شاخص vllm:num_requests_waiting مقداری بیشتر از 0 دارد و vllm:kv_cache_usage_perc نزدیک به 1 است.
  • راه‌حل: تعداد کاربران هم‌زمان روی GPU را کم کنید، یا با کش KV در فرمت FP8 یا کاهش حداکثر طول، در استخر حافظه فضا باز کنید.

هنگام فعالیت کاربران زیاد، جریان خروجی وقفه‌های طولانی دارد

  • علت: پرامپت‌های تازه، گام‌های رمزگشایی (decode) را با درخواست‌های در حال اجرا سهیم می‌شوند و پرامپت‌های طولانی بخش بزرگی از هر گام را می‌گیرند.
  • بررسی: صدک P99 شاخص فاصله‌ی بین توکن‌ها (ITL) را با میانه‌ی آن مقایسه کنید. تفاوت چشمگیر نشانه‌ی معطلی است، نه کندیِ GPU.
  • راه‌حل: همان‌طور که در صفحه‌ی سهمیه‌ی توکن آمده، سهمیه‌ی توکن (token budget) را کاهش دهید. روی سیستم‌های ما این وقفه‌ها به طول پرامپت‌ها و خود موتور هم بستگی داشت، چنان‌که در صفحه‌ی انتخاب بین vLLM و SGLang آمده است.

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

  • علت: درخواستی در حال اجرا به یک بلاک حافظه‌ی جدید نیاز داشته و بلاک خالی وجود نداشته است. در نتیجه vLLM موقتاً درخواست را متوقف می‌کند (preemption) و محاسبات آن را بعداً از سر می‌گیرد.
  • بررسی: مقدار vllm:num_preemptions_total افزایش می‌یابد و لاگ‌های دوره‌ای آمار پیش‌دستی را نشان می‌دهند.
  • راه‌حل: پارامتر --gpu-memory-utilization را بالا ببرید، یا مقادیر --max-num-seqs یا --max-num-batched-tokens را کم کنید.

دیکودینگ حدسی N-gram کمتر از حد انتظار نتیجه می‌دهد

  • علت: در نسخه‌ی 0.31.0، روش n-gram باعث می‌شود vLLM از اجراکننده‌ی (runner) قدیمی‌تر استفاده کند و زمان‌بندی ناهمگام را از کار بیندازد.
  • بررسی: لاگ راه‌اندازی هشداری مبنی بر غیرفعال بودن زمان‌بندی ناهمگام ثبت می‌کند.
  • راه‌حل: بازدهی این روش را با حالتی که اصلاً دیکودینگ حدسی ندارید روی ترافیک خود بسنجید، به‌طوری که هر دو حالت از اجراکننده‌ی یکسانی استفاده کنند.

اولین درخواست‌ها بعد از شروع در حالت eager کند هستند

  • علت: از نسخه‌ی 0.31.0 به بعد، استفاده از --enforce-eager فرایند گرم‌کردن (warmup) را که در آغاز کار کرنل‌ها را کامپایل می‌کند خاموش می‌سازد؛ در نتیجه چند درخواست اول کار کامپایل را انجام می‌دهند.
  • بررسی: چند درخواست اول کندتر از درخواست‌های بعدی پردازش می‌شوند.
  • راه‌حل: پیش از پاسخ‌دهی به ترافیک واقعی، چند درخواست برای گرم‌کردن بفرستید، یا به‌جای آن از فلگ -O0 استفاده کنید.

رمزگشایی NVFP4 روی DGX Spark از نسخه‌های پیشین کندتر است

  • علت: ایشوی 59770 از کاهش سرعت رمزگشایی برای یک مدل NVFP4 خاص روی پردازنده‌ی GB10 از نسخه‌ی 0.29.0 به بعد گزارش داده است. این موضوع هنوز باز است.
  • بررسی: زمان لازم برای پردازش هر توکن را روی نسخه‌ی فعلی و نسخه‌ی 0.28 مقایسه کنید.
  • راه‌حل: تا زمان بسته شدن این ایشو، برای آن مدل روی نسخه‌ی سریع‌تر بمانید.

خروجی اشتباه است

پاسخ مدل با یک بلوک متنیِ طولانیِ تفکر شروع می‌شود

  • علت: یک مدل استدلالی (مانند Qwen3) بدون پارسر استدلال (reasoning parser) اجرا شده است.
  • بررسی: مقدار فیلد content با <think> شروع می‌شود.
  • راه‌حل: سرور را همراه با پارسر مناسب مدل اجرا کنید؛ مثلاً --reasoning-parser qwen3. جزئیات را در صفحه‌ی سرو مدل‌های استدلالی بخوانید.

بعد از هیت شدن کش پیشوند، مدل مدام یک توکن را تکرار می‌کند

  • علت: ایشوی 60174 وجود خروجی خراب را در نسخه‌های 0.30 و 0.31 هنگام اجرای دیکودینگ حدسی DFlash2 یا DSpark همراه با کش پیشوند گزارش می‌دهد. از درخواست سوم به بعد، پاسخ‌هایی که از بلاک‌های کش‌شده آغاز می‌شوند مرتباً یک توکن را پشت سر هم تکرار می‌کنند. این مشکل در تاریخ 2026-10-22 یعنی بعد از نسخه‌ی 0.31.0 بسته شد؛ بنابراین بررسی کنید که آیا نسخه‌ی شما این اصلاحیه را دارد یا نه.
  • بررسی: مشکل فقط بعد از اصابت به کش (cache hit) رخ می‌دهد و با اضافه کردن --no-enable-prefix-caching برطرف می‌شود.
  • راه‌حل: برای آن مدل، کش پیشوند یا روش دیکودینگ حدسی را خاموش کنید.

با فعال بودن دیکودینگ حدسی، خروجی JSON نامعتبر است

  • علت: اسکیمای JSON (JSON schema) و متد دیکودینگ حدسی ممکن است بر سر توکن‌های بعدی توافق نداشته باشند. ایشوی 60830 این مشکل را برای MTP روی یک مدل نشان داد و اکنون بسته شده است.
  • بررسی: همان درخواست‌ها را بدون --speculative-config بفرستید.
  • راه‌حل: سرور را به نسخه‌های جدیدتر ارتقا دهید یا دیکودینگ حدسی را برای ترافیک خروجی‌های JSON خاموش کنید.

خروجی در اجراهای پیاپی تغییر می‌کند

  • علت: vLLM به‌طور پیش‌فرض خروجی کاملاً یکسان را تضمین نمی‌کند. دسته‌ای که یک درخواست به آن ملحق می‌شود، ترتیب جمع‌ها را تغییر می‌دهد. هیت شدن کش پیشوند هم می‌تواند خروجی حریصانه (greedy) را تغییر دهد. در تست‌های ما روی Qwen3-0.6B با یک کاربر، یک کش گرم باعث تغییر 11 خروجی از 32 خروجی با استراتژی greedy شد. آن تست روی پردازنده‌ی L4 اشتراکی و بدون قفل فرکانس ثبت شد. تغییر نوع داده (dtype) هم، مانند تبدیل BF16 به FP16، بخش اعظم خروجی‌ها را عوض می‌کند.
  • بررسی: یک درخواست یکسان را دو بار به‌تنهایی بفرستید. اگر پاسخ‌ها یکی بودند، دسته‌ی پردازشی عامل تغییر است. اگر با هم تفاوت داشتند، درخواست دوم احتمالاً به کش پیشوند خورده است. آزمون را با --no-enable-prefix-caching تکرار کنید؛ اگر پاسخ‌ها کاملاً یکی شدند، عامل اصلی کش است.
  • راه‌حل: در حالت آفلاین، متغیر VLLM_ENABLE_V1_MULTIPROCESSING=0 را تنظیم کنید. در حالت آنلاین، حالت پایا نسبت به دسته (batch-invariant) کمک می‌کند، هرچند در نسخه‌ی 0.31.0 همه‌ی مسیرها را پوشش نمی‌دهد. بین اجراهایی که قصد مقایسه‌شان را دارید، کش پیشوند را ریست کنید. روش کامل در صفحه‌ی بازتولیدپذیری آمده است.

نتایج بنچمارک نادرست است

اجرای دوم بنچمارک سریع‌تر از اجرای اول ثبت می‌شود

  • علت: وقتی مقدار seed ثابت باشد، دیتاست تصادفی همان پرامپت‌های تکراری قبلی را ارسال می‌کند و کش پیشوند به آن‌ها پاسخ می‌دهد. در آزمون ما روی مدل Qwen3-0.6B با 16 کاربر، اجرای دوباره بدون ریست کردن کش باعث شد میانه‌ی TTFT حدود 6 برابر کمتر ثبت شود. آن آزمون هم روی یک L4 اشتراکی و بدون قفل فرکانس انجام شد.
  • بررسی: در جریان اجرای بار دوم، شاخص vllm:prefix_cache_hits_total رشد می‌کند.
  • راه‌حل: پیش از هر بار اجرای بنچمارک کش پیشوند را ریست کنید، از seed متفاوتی بهره ببرید و توکن‌های کش‌شده را ثبت کنید. شیوه‌ی استاندارد این کار در صفحه‌ی بنچمارک آورده شده است. مسیر POST /reset_prefix_cache فقط در صورتی وجود دارد که VLLM_SERVER_DEV_MODE=1 باشد؛ بنابراین صرفاً روی سروری که در دسترس عموم نیست از آن استفاده کنید.

منابع: ایشوهای 44740، 46307، 58726، 59770، 60174، 60262 و 60830 در vLLM؛ یادداشت‌های انتشار برای نسخه‌های v0.30.0 و v0.31.0 و v0.32.0؛ مستندات vLLM در نسخه‌ی v0.31.0 (شامل docs/usage/troubleshooting.md،‏ docs/design/torch_compile.md،‏ docs/configuration/optimization.md،‏ docs/usage/reproducibility.md،‏ docs/benchmarking/cli.md،‏ docs/features/reasoning_outputs.md)؛ کدهای منبع vLLM در نسخه‌ی v0.31.0 (فایل‌های vllm/config/vllm.py،‏ vllm/config/model.py،‏ vllm/renderers/params.py،‏ vllm/v1/engine/exceptions.py،‏ vllm/envs.py)؛ لاگ capture/gpu/out-gb10/server-load-vllm.log؛ مقاله‌ی Same Request, Different Answer: Quantization Amplifies Cache-Induced Divergence in LLM Serving (شناسه‌ی arXiv 2609.04748، سال 2026)؛ capture/gpu/out-l4/livecheck-2026-10-22.txt،‏ capture/gpu/out-l4/prefix-cache-flush.txt،‏ capture/gpu/out-l4/greedy-output-cache-batch-dtype.txt،‏ capture/gpu/out-l4/livecheck-2026-10-23.txt.

ترجمه‌ی فارسی Troubleshoot by symptom از راهنمای vLLM 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما