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