چیتشیت
سرویسدهی LLM با vLLM
LLM Serving with vLLM
نصب، راهاندازی، اندازهگذاری، تیونینگ و دیباگ سرور vLLM 0.31.0. فلگها، مقادیر پیشفرض، متریکها و خطاهای شناختهشده.
فهرست مطالب
استک سرویسدهی
معمارییک درخواست
گامبهگام- سهمیههر گام یک سهمیهی توکن دارد که با
--max-num-batched-tokensتنظیم میشود. - درخواستهای در حال اجراهرکدام تا سقف سهمیه، توکنهای مورد نیازش را دریافت میکند.
- درخواستهای در صف انتظارتا وقتی سهمیه و فضا باقی است پذیرفته میشوند. فلگ
--max-num-seqsآنها را محدود میکند. - حافظه پر شداجرای درخواست متوقف شده و بعداً دوباره محاسبه میشود.
راهاندازی سرور
کد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.0 | uv 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، حافظه و درایور را چاپ میکند. |
پیشفرضها
پیشفرضها| تنظیم | پیشفرض | نکته |
|---|---|---|
--host | every network interface | برای تست محلی روی 127.0.0.1 بگذارید |
--port | 8000 | پورت HTTP سرور |
--gpu-memory-utilization | 0.92 | سهم هر نمونه از کل حافظه GPU |
--max-num-batched-tokens | 2048 | زیر 70 گیگابایت حافظه GPU. از 70 گیگابایت به بالا 8192 |
--max-num-seqs | 256 | زیر 70 گیگابایت حافظه GPU. از 70 گیگابایت به بالا 1024 |
--block-size | 16 | توکنها در یک بلوک KV |
--kv-cache-dtype | auto | نوع دادهی مدل. مقدار 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) استفاده کنید.
- قبل از تغییر هر فلگ، بخش عیبیابی را بخوانید.