چیت‌شیت

سرویس‌دهی LLM با vLLM

LLM Serving with vLLM

نصب، راه‌اندازی، اندازه‌گذاری، تیونینگ و دیباگ سرور vLLM 0.31.0. فلگ‌ها، مقادیر پیش‌فرض، متریک‌ها و خطاهای شناخته‌شده.

  • ۱۱ بخش
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. استک سرویس‌دهی
  2. یک درخواست
  3. راه‌اندازی سرور
  4. وظایف
  5. دستورها
  6. پیش‌فرض‌ها
  7. اصطلاحات کلیدی
  8. عیب‌یابی
  9. واژه‌نامه
  10. پرسش‌ها
  11. نکات

استک سرویس‌دهی

معماری
‏HTTPدرخواست‌هایک گامتخصیصخواندنکلاینت‏curl یا OpenAI SDKسرور API‏HTTP و توکنایزرهسته موتوراسکژولرورکر GPUوزن‌ها و گذر رو به جلواستخر بلوک‌های KVبلوک‌های 16 توکنیمتریک‌هااندپوینت ‎/metrics

یک درخواست

گام‌به‌گام
  1. سهمیههر گام یک سهمیه‌ی توکن دارد که با --max-num-batched-tokens تنظیم می‌شود.
  2. درخواست‌های در حال اجراهرکدام تا سقف سهمیه، توکن‌های مورد نیازش را دریافت می‌کند.
  3. درخواست‌های در صف انتظارتا وقتی سهمیه و فضا باقی است پذیرفته می‌شوند. فلگ --max-num-seqs آن‌ها را محدود می‌کند.
  4. حافظه پر شداجرای درخواست متوقف شده و بعداً دوباره محاسبه می‌شود.

راه‌اندازی سرور

کد
bash
uv venv --python 3.12 --seed                                               # محیط تمیز Python 3.12
source .venv/bin/activate                                                  # استفاده از آن در این شل
uv pip install vllm==0.31.0 --torch-backend=auto                           # نصب با نگارش ثابت (pinned)
vllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3 2>&1 | tee server.log  # راه‌اندازی و نگهداری لاگ
curl http://localhost:8000/v1/models                                       # اجرا در ترمینال دوم

وظایف

کار و کد
وظیفهکد
نصب vLLM 0.31.0uv pip install vllm==0.31.0 --torch-backend=auto
راه‌اندازی سرور با پارسر استدلالvllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3
بررسی روت سلامت (health)curl -i http://localhost:8000/health
مشاهده‌ی نام مدلcurl http://localhost:8000/v1/models
خاموش کردن تفکر برای یک درخواست"chat_template_kwargs": {"enable_thinking": false}

دستورها

دستورها
دستورکارکرد
vllm --versionنسخه‌ی نصب‌شده را چاپ می‌کند. باید 0.31.0 باشد.
docker logsلاگ کانتینرِ اجراکننده‌ی سرور را می‌خواند.
nvidia-smi --query-gpu=name,memory.total,driver_version --format=csvنام GPU، حافظه و درایور را چاپ می‌کند.

پیش‌فرض‌ها

پیش‌فرض‌ها
تنظیمپیش‌فرضنکته
--hostevery network interfaceبرای تست محلی روی 127.0.0.1 بگذارید
--port8000پورت HTTP سرور
--gpu-memory-utilization0.92سهم هر نمونه از کل حافظه GPU
--max-num-batched-tokens2048زیر 70 گیگابایت حافظه GPU. از 70 گیگابایت به بالا 8192
--max-num-seqs256زیر 70 گیگابایت حافظه GPU. از 70 گیگابایت به بالا 1024
--block-size16توکن‌ها در یک بلوک KV
--kv-cache-dtypeautoنوع داده‌ی مدل. مقدار fp8 بایت به ازای هر توکن را نصف می‌کند
`-O0` to `-O3`-O2سطح بهینه‌سازی کامپایل و گراف CUDA

اصطلاحات کلیدی

مفهوم‌ها
هش پیشوند
هشِ یک بلوک و بلوکِ قبل از آن؛ طوری که یک هش نام‌بخش کل یک پیشوند است.
پیش‌دستی
‏vLLM درخواست را متوقف می‌کند تا بلوک‌هایش آزاد شوند و بعداً دوباره آن را محاسبه می‌کند.

عیب‌یابی

عیب‌یابی
  • توقف راه‌اندازی به دلیل کش کلید-مقدار و حداکثر طول

    علت
    یک درخواست با طول --max-model-len بیش از باقیمانده‌ی کش کلید-مقدار حافظه می‌خواهد
    راه‌حل
    مقدار --max-model-len را برابر با طولانی‌ترین درخواست خود بگذارید
  • توقف راه‌اندازی با خطای نبود nvcc

    علت
    کتابخانه FlashInfer در اولین اجرا کامپایل می‌شود و هاست فاقد CUDA toolkit است
    راه‌حل
    نصب toolkit، تنظیم CUDA_HOME و راه‌اندازی مجدد
  • کرش سرور پس از کش کلید-مقدار FP8

    علت
    کش FP8 کتابخانه FlashInfer را انتخاب می‌کند که در اینجا کامپایل نمی‌شود
    راه‌حل
    افزودن فلگ --attention-backend TRITON_ATTN
  • پاسخ با یک بلوک تفکر طولانی شروع می‌شود

    علت
    یک مدل استدلالی بدون پارسر اجرا شده است
    راه‌حل
    راه‌اندازی با --reasoning-parser qwen3
  • خطای HTTP 400 درباره حداکثر طول زمینه

    علت
    مجموع توکن‌های پرامپت و max_tokens از --max-model-len بیشتر است
    راه‌حل
    ارسال پرامپت کوتاه‌تر یا max_tokens کمتر
  • اجرای دوم بنچمارک سریع‌تر است

    علت
    سید (seed) ثابت پرامپت‌ها را تکرار می‌کند و کش پیشوند به آن‌ها پاسخ می‌دهد
    راه‌حل
    ریست کردن کش پیشوند و استفاده از سید جدید

واژه‌نامه

اصطلاح‌ها
سرور API
فرایندی که HTTP را سرو می‌کند، توکنایزیشن را انجام می‌دهد و پاسخ را استریم می‌کند.
هسته موتور
فرایندی که اسکژولر و مدیریت کش کلید-مقدار را اجرا می‌کند.
بلوک
گروه ثابتی از 16 توکن در کش کلید-مقدار.
پیش‌دستی
متوقف کردن یک درخواست در حال اجرا برای آزادسازی بلوک‌هایش و سپس محاسبه‌ی مجدد آن.

پرسش‌ها

پرسش و پاسخ
آیا دریافت کد 200 از health/ به معنی تکمیل درخواست است؟
خیر. این روت هیچ توکنی تولید نمی‌کند.
چرا پاسخ خالی است در حالی که finish_reason روی length قرار دارد؟
فرایند تفکر کل سهمیه‌ی max_tokens را مصرف کرده است. مقدار max_tokens را افزایش دهید یا بخش تفکر را خاموش کنید.
چرا اسکژولر اول به درخواست‌های رمزگشایی پاسخ می‌دهد؟
هر درخواست در حال اجرا ابتدا توکن‌هایش را از سهمیه برمی‌دارد تا استریم پیوسته و روان بماند.
چرا بلوک‌ها به ازای هر درخواست رزرو نمی‌شوند؟
هیچ حافظه‌ای برای طولی که درخواست شاید هرگز به آن نرسد، رزرو و بلااستفاده نمی‌ماند.

نکات

نکته‌ها
  • لاگ را با tee server.log ذخیره کنید و خطوط ابتدای راه‌اندازی را در هر اجرا بخوانید.
  • در صورت نصب با pip، ابزار CUDA toolkit را قبل از اولین راه‌اندازی نصب کنید.
  • از روت سلامت برای بررسی زنده بودن (liveness) و از یک درخواست واقعی برای آماده‌به‌کاری (readiness) استفاده کنید.
  • قبل از تغییر هر فلگ، بخش عیب‌یابی را بخوانید.