راهنمای عملی

vLLM 101

سرویس‌دهی، ابعاددهی، تنظیم دقیق و اشکال‌زدایی مدل‌های متن‌باز با vLLM، به همراه پاسخ‌های مبتنی بر سنجش برای هر تصمیم

  • نسخه‌ی سنجیده‌شده: vLLM 0.31.0
  • ۵۲ بخش

روش نصب vLLM، گنجاندن مدل روی GPU، بهینه‌سازی آن برای ترافیک کاری و رفع اشکال بر اساس نشانه‌ها. سنجیده‌شده روی یک NVIDIA L4 و یک DGX Spark با vLLM 0.31.0.

شروع از بخش ۱٫۱

بعد از این راهنما می‌توانید

  • vLLM را نصب کنید، یک مدل را اجرا و سرویس‌دهی کنید و خطوط راه‌اندازی را که ظرفیت سرور را مشخص می‌کنند بخوانید.
  • پیش‌بینی کنید چه تعداد کاربر روی GPU شما جا می‌گیرند و خطای کمبود حافظه (OOM) را در زمان راه‌اندازی رفع کنید.
  • یک یا دو پرچمی را که برای ترافیک شما اهمیت دارند انتخاب کنید و بقیه را روی مقادیر پیش‌فرض بگذارید.
  • بر اساس اندازه‌گیری و سنجش تصمیم بگیرید که دیکودینگ حدسی، FP8، یا سطح کامپایل چه زمانی ارزش به‌کارگیری دارند.
  • یک سرور کند یا از کار افتاده را بر اساس نشانه‌ای که مشاهده می‌کنید اشکال‌زدایی کنید.
یک استخر بلوک روی یک پردازنده L4
One block pool on one L4 The vLLM 0.31.0 API server and EngineCore run on the host CPU and talk over ZMQ. The Scheduler inside EngineCore builds one step under a token budget of 2,048 tokens: requests A and B decode one token each, and request C adds a prefill chunk. The block table of the KVCacheManager maps each request to blocks that are not all next to each other. Below is one NVIDIA L4 with its SM array of 58 SMs and 24 GB of GDDR6, where the KV cache is a grid of 16-token blocks: 1,506 blocks hold 24,096 tokens, and the grid shows 40 of them: the blocks of A and B, some of the blocks of C, and free blocks. HOST CPU · VLLM 0.31.0 PROCESSES API server HTTP, tokenizer EngineCore Scheduler KVCacheManager block table A · 2, 13, 31 B · 7, 8, 26, 38 C · 17, 18, 27, 28, 35, more ZMQ allocate_slots x86_64 host ONE SCHEDULER STEP budget 2,048 tokens A decode, 1 token B decode, 1 token C prefill chunk, 2,046 tokens The decode slivers are drawn wider. Decodes go first, then a prompt chunk fills the rest. NVIDIA L4 · GPU MEMORY SM array 58 SMs, Ada KV cache · 16-token blocks 1,506 blocks, 24,096 tokens 24 GB GDDR6, six packages in use free · 40 of 1,506 shown With 8 users the log read: GPU KV cache usage 77.2%, prefix cache hit rate 87.2%. Block ids show the mapping only. Pool, block size, and budget are from our L4 runs.
اسکژولر یک مرحله را ذیل سهمیه‌ی 2048 توکنی پر می‌کند. جدول بلوک هر درخواست را به بلوک‌هایی که الزاماً پشت سر هم نیستند متصل می‌کند. روی پردازنده L4 ما، استخر شامل 1506 بلوک 16 توکنی بود. برگرفته از capture/gpu/summary/l4.json و capture/gpu/out-l4/server-h2h-prefix-vllm.log.

این کتابچه کمکتان می‌کند مدل‌های باز را با vLLM سرو کنید، منابع لازم را تخمین بزنید، آن را بهینه کنید و خطاهایش را رفع کنید؛ علاوه بر این، برای هر تصمیم فنی پاسخی مبتنی بر اندازه‌گیری واقعی به شما ارائه می‌دهد.

مستندات vLLM می‌گوید هر فلگ چه کاری انجام می‌دهد. این کتابچه نشانتان می‌دهد کدام فلگ‌ها متناسب با GPU و ترافیک شما اهمیت دارند و با تغییر دادن آن‌ها چه نتیجه‌ای گرفتیم.

از اینجا شروع کنید

این دستورها یک سرور را بالا می‌آورند:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm==0.31.0 --torch-backend=auto
vllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3 2>&1 | tee server.log
curl http://localhost:8000/v1/models

دستور curl را در ترمینال دوم اجرا کنید. در بخش 1 تمام این دستورها و خروجی‌هایی را که باید ببینید قدم‌به‌قدم بررسی می‌کنیم.

بعد از خواندن این کتابچه چه کارهایی می‌توانید بکنید

  • vLLM را نصب کنید، یک مدل سرو کنید و سطرهای ابتدایی راه‌اندازی (Startup) را بخوانید؛ سطرهایی که پاسخ بیشتر سؤالات شما در آن‌ها نهفته است.
  • پیش‌بینی کنید چند کاربر روی GPU شما جا می‌شوند، و خطای کمبود حافظه (Out-Of-Memory) را در همان زمان بالا آمدن برطرف کنید.
  • فقط یک یا دو فلگی را که برای ترافیکتان واقعاً اهمیت دارند انتخاب کنید و دست به بقیه‌ی فلگ‌ها نزنید تا روی پیش‌فرض بمانند.
  • بر اساس اندازه‌گیری واقعی تصمیم بگیرید چه زمانی دیکودینگ حدسی (Speculative Decoding)، قالب FP8 یا سطحی از کامپایل ارزش استفاده دارد.
  • بر اساس نشانه‌ای که می‌بینید، سرور کُند یا ازکارافتاده را خطایابی کنید.

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

پیش از این مدلی را از طریق API فراخوانی کرده‌اید و حالا می‌خواهید خودتان یک مدل باز را سرو کنید. می‌دانید توکن (Token) و GPU چیستند. کد منبع یک موتور سرو را هم نخوانده‌اید و نیازی هم نیست بخوانید.

بخش‌ها چطور مرتب شده‌اند

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

بخش 8 سازوکار درونی vLLM را توضیح می‌دهد؛ هر بار که یکی از رفتارهای پیش‌فرض غافلگیرتان کرد، سراغ این بخش بروید. در صفحات مرجع نیز جدول فلگ‌ها، معیارها، نمایه‌ی حوادث و یادداشت‌های آزمایشگاه قرار دارند.

روی چه سخت‌افزاری آزمایش کردیم

آزمایش‌ها را روی vLLM 0.31.0 با یک NVIDIA L4 و یک سرور DGX Spark انجام دادیم. کارت L4 مدل Qwen3-8B را سرو کرد و DGX Spark مدل Qwen3-30B-A3B را بالا آورد. کنار هر عددِ مبتنی بر اندازه‌گیری در این کتابچه، نام دستگاه مربوطه هم آمده است. در یادداشت‌های آزمایشگاه سیدها (Seeds)، فرکانس‌ها و جدول‌های کامل را آورده‌ایم.

چهار نشست کارت L4

کارت L4 با یک سرعت ثابت کار نکرد. فرکانس ریزپردازنده‌های چندمنظوره‌ی آن (SM clock) با تغییر دما و سایر پردازش‌های روی نود بالا و پایین می‌شد. بنابراین یک بار کاری یکسان روی Qwen3-8B در نشست‌های مختلف زمان‌های متفاوتی ثبت کرد. در این کتابچه، بالای هر جدول مربوط به L4 نام نشست آن آمده است؛ مقایسه‌ی دو عدد را فقط درون یک نشست انجام دهید.

نشست تاریخ‌ها میانه‌ی فرکانس SM 1 کاربر، میانه‌ی TPOT 32 کاربر، توکن خروجی بر ثانیه
فرکانس کامل، خنک‌شده پیش از هر اجرا 2026-10-17 تا 2026-10-21 1,000 تا 1,560 MHz 60.4 ms 273.9 تا 275.1
تحت افت حرارتی (Throttled) 2026-10-22 210 MHz در 1 کاربر، 450 MHz در 32 کاربر 104.1 ms 186.7
قفل‌شده روی 900 MHz 2026-10-22 881 تا 900 MHz، 210 MHz برای خط مبنای (Baseline) 1 کاربره 99.0 ms 208.8
کارت اشتراکی، استخرِ 2,928 توکنی 2026-10-22 368 تا 450 MHz 241.7 ms اجرا نشد

وقتی GPU داغ می‌کند یا مصرف برقش را با پردازش‌های دیگر شریک می‌شود، با فرکانسی پایین‌تر از فرکانس کاملش کار می‌کند و اصطلاحاً تروتل (Throttle) می‌شود. قفل کردن با nvidia-smi -lgc سقف فرکانس را تعیین می‌کند؛ اما نمی‌تواند جلوی افت فرکانس GPU بیش از حد داغ‌شده را به زیر این سقف بگیرد.

منابع: مستندات vLLM در نگارش v0.31.0 (فایل‌های docs/getting_started/quickstart.md و docs/features/reasoning_outputs.md)، capture/gpu/summary/l4.json، capture/gpu/summary/l4-gpu1.json و capture/gpu/summary/gb10.json.

فهرست راهنما

بخش ۱: شروع کار

می‌توانید پیش از تغییر حتی یک تنظیم، مدلی را با vLLM اجرا کرده و از درستی عملکرد آن مطمئن شوید.

  1. 1.1نصب vLLM و راه‌اندازی اولین مدل
  2. 1.2بررسی سلامت سرور
  3. 1.3درک آنچه بر سر درخواست شما می‌آید
  4. 1.4تنظیم گزینه‌های سرور برای محیط عملیاتی

بخش ۴: قابلیت‌های شتاب‌دهنده و سرعت

یک قابلیت افزایش سرعت تنها برای برخی الگوهای ترافیکی بصرفه است؛ پس بر اساس سنجش روی بار کاری واقعی خود تصمیم بگیرید.

  1. 4.1افزایش سرعت رمزگشایی با EAGLE3
  2. 4.2استفاده از دیکودینگ حدسی مبتنی بر ان‌گرام در پردازش‌های متکی بر رونویسی
  3. 4.3گراف‌های CUDA و کامپایل را روشن نگه دارید
  4. 4.4زمان‌بندی ناهمگام را روشن بگذارید
  5. 4.5تغییر بک‌اند اتنشن فقط با دلیلی موجه

بخش ۵: سنجش و اندازه‌گیری

یک بنچمارک تنها زمانی ارزش دارد که با ترافیک کاری شما همخوانی داشته باشد و شرایط آزمون را به‌دقت ثبت کند.

  1. 5.1بنچمارک سرور در 15 دقیقه
  2. 5.2پایش vLLM در محیط عملیاتی
  3. 5.3انتخاب میان vLLM و SGLang

بخش ۶: مقیاس‌پذیری افقی

تنها پس از بهینه‌سازی یک GPU پردازنده‌های گرافیکی بیشتری بیفزایید، و ساختار توزیع را بر اساس ماهیت کار تعیین کنید.

  1. 6.1انتخاب بین موازی‌سازی تنسور، پایپ‌لاین یا داده
  2. 6.2سرو مدل‌های MoE با موازی‌سازی متخصصان
  3. 6.3تفکیک پیش‌پرکنی و رمزگشایی
  4. 6.4اجرای vLLM روی کوبرنتیز (Kubernetes)
  5. 6.5اجرای vLLM روی سایر شتاب‌دهنده‌ها

بخش ۷: عملیات و اشکال‌زدایی

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

  1. 7.1عیب‌یابی بر اساس نشانه‌ها
  2. 7.2اجرای vLLM در محیط عملیاتی