# 📘 نصب و استفاده از vllm ## ⏬ بخش 1: نصب vllm
install via environments ### مقدمه: - بهتر است برای نصب این کتابخانه و یا کتابخانه‌هایی با وابستگی‌های زیاد از `uv` استفاده کنید: 🔗 لینک توضیحات بیشتر: [https://docs.astral.sh/uv](https://docs.astral.sh/uv) - دستور نصب `uv` : ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` - پیشنهاد میشود برای نصب `vllm` .حتما از محیط مجازی استفاده کنید - دستور ساخت: ```uv venv --python 3.12``` - دستور فعالسازی: `source .venv/bin/activate` --- ### نصب vllm - خب حالا نوبت به نصب `vllm` است * نکته: بر اساس مدلی که میخواهید serve کنید نسخه مشخص شده و بهینه شده را انتخاب کنید. * نمونه دستور نصب vllm مناسب با openai\oss:
uv pip install --pre vllm==0.10.1+gptoss \ --extra-index-url https://wheels.vllm.ai/gpt-oss/ \ --extra-index-url https://download.pytorch.org/whl/nightly/cu128 \ --index-strategy unsafe-best-match
install via docker ### مقدمه: - ابتدا داکر مناسب مدل خود را از [docker hub vllm](https://hub.docker.com/u/vllm) انتخاب کنید - نسخه ای که توسط ما استفاده شده است : ` vllm/vllm-openai:latest ` - با تشکر از [mohamad-tohidi/ai_server_setup](https://github.com/mohamad-tohidi/ai_server_setup/blob/main/install_nvidia_container_tool.sh) برای guideline کامل. --- ### نصب پیش نیاز ها و image vllm
1. ` sudo apt-get update -y ` 2. ` sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ` 3. ` sudo systemctl start docker ` 4. ` sudo systemctl enable docker ` 5. ` curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \ sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg ` 6. ` curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \ sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list > /dev/null ` 7. ` sudo sed -i -e '/experimental/ s/^#//g' /etc/apt/sources.list.d/nvidia-container-toolkit.list || true ` 8. ` sudo apt-get update ` 9. ` sudo apt-get install -y nvidia-container-toolkit ` 10. ` sudo nvidia-ctk runtime configure --runtime=docker ` 11. ` sudo systemctl restart docker ` 12. ` docker pull vllm/vllm-openai ` or any tags u want via this format ` docker pull vllm/vllm-openai:nightly-29de3cdee4dd7f805931b459398b15c3b5f7057c `
--- ### راه اندازی vllm با container docker - توضیح کار با کانتینر با یک مثال:
``` sudo docker run --gpus all --ipc=host -p 5001:5001 -v /MODELS/gpt-oss-120b:/model/gpt-oss-120b vllm/vllm-openai:latest --model /model/gpt-oss-120b --port 5001 --gpu-memory-utilization 0.96 --served-model-name gpt-oss-120b --kv-cache-dtype fp8_e4m3 -O3 ``` ⭕ ` sudo docker run ` : اجرای کانتینر با دسترسی root ⭕ ` --gpus all ` :
دسترسی کامل به تمامی GPUهای سیستم ؛ در صورت نصب بودن ` nvidia-container-toolkit ` روی سرور (مطابق مراحل قبلی اگر رفته باشید مشکلی ندارید!)
⭕ ` --ipc=host ` : به اشتراک‌گذاری حافظه IPC بین هاست و کانتینر. ⭕ ` -p 5001:5001 ` : port binding سیستم به docker ⭕ ` -v /MODELS/gpt-oss-120b:/model/gpt-oss-120b ` : ولیوم کردن دایرکتوری سیستم به دایرکتوری داخل docker ⭕ ` vllm/vllm-openai:latest ` : اسم image مورد استفاده ⭕ ` --model /model/gpt-oss-120b --port 5001 --gpu-memory-utilization 0.96 --served-model-name gpt-oss-120b --kv-cache-dtype fp8_e4m3 -O3 ` : پارامتر هایی که مطابق با خود vllm و مدل میتوانید استفاده کنید
## ⚙️بخش 2: پارامتر های serve با vllm
vllm serve params Table ### نکته: - بعد از نصب بر اساس نسخه نصب شده و کانفیگ مدل مورد نظر برای serve با پارامتر های متفاوتی شاید سروکار داشته باشید حتما داکیومنت های سازنده مدل در این باره را مطالعه کنید ### پارامترهای مهم vLLM به صورت عمومی:
| پارامتر | مقدار نمونه | توضیح فارسی | | --------------------------- | -------------------------------- | ---------------------------------------------------------- | | `--model` | مسیر مدل | مسیر محلی که مدل و وزن‌ها در آن قرار دارد | | `--dtype` | `auto`, `half`, `bf16`, `mxfp4` | نوع داده برای محاسبات — `half` سریع‌تر، `mxfp4` حافظه کمتر | | `--max-model-len` | `1024`, `4096`, `8192` | حداکثر طول ورودی/خروجی مدل (تعداد توکن در context) | | `--max-num-batched-tokens` | `1024` تا `32768` | حداکثر تعداد توکن در هر batch (برای سرعت بیشتر) | | `--gpu-memory-utilization` | `0.9` | درصد استفاده از VRAM (پیشنهاد: ۰٫۹ تا ۰٫۹۵) | | `--tensor-parallel-size` | `1` یا `>1` | تقسیم مدل روی چند GPU | | `--kv-cache-memory` | بر حسب بایت (مثلاً `1000000000`) | حجم حافظه اختصاصی برای cache توکن‌ها | | `--host` | `0.0.0.0` | برای دسترسی از سایر سیستم‌ها در شبکه | | `--port` | `3130` | پورت سرور API | | `--download-dir` | مسیر محلی | مسیر کش مدل‌ها در دیسک | | `--tokenizer-mode` | `cpu` یا `auto` | اجرای توکنایزر روی CPU برای صرفه‌جویی در VRAM | | `--quantization` | `auto`, `none`, `mxfp4` | نوع کوانتایزیشن (برای کاهش مصرف VRAM) | | `--enforce-eager` | بدون مقدار | اجرای ساده بدون JIT (برای دیباگ) | | `--max-num-seqs` | `1` | کنترل تعداد درخواست همزمان (برای کنترل حافظه) | | `--enable-prefix-caching` | True | فعال‌سازی cache پیشوند برای ورودی‌های تکراری | | `--chunked-prefill-enabled` | True | تقسیم ورودی‌های طولانی برای استفاده بهینه از حافظه | | `--served-model-name` | openrooter/gpt-oss-120b | اسمی که مدل با آن فراخوانده می شود | | `-O3` | -O3 | فعال‌سازی خودکار چندین بهینه‌سازی پیشرفته برای حداکثر throughput |
## 🧠بخش 3: نمونه کانفیگ های تست شده serve با vllm
environments-base
docker-base