vllm_docs/README.md

📘 نصب و استفاده از vllm

⏬ بخش 1: نصب vllm

install via environments

مقدمه:

• بهتر است برای نصب این کتابخانه و یا کتابخانه‌هایی با وابستگی‌های زیاد از uv استفاده کنید:
  🔗 لینک توضیحات بیشتر:
  https://docs.astral.sh/uv

• دستور نصب uv :

  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 

نمونه دستور عادی نصب vllm :

uv pip install vllm --torch-backend=auto

صفحه مربوط به اطلاعات بیشتر برای نصب vllm : 🔗https://docs.vllm.ai/en/stable/getting_started/quickstart.html#installation

install via docker

مقدمه:

• ابتدا داکر مناسب مدل خود را از docker hub vllm انتخاب کنید
• نسخه ای که توسط ما استفاده شده است : vllm/vllm-openai:latest
• با تشکر از mohamad-tohidi/ai_server_setup برای 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