From 0d887d9dbd1953919be207579132f6bec8cf2b91 Mon Sep 17 00:00:00 2001
From: init_mahdi <initmahdi@gmail.com>
Date: Sat, 1 Nov 2025 13:50:45 +0330
Subject: [PATCH] before-command-example

---
 README.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 122 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 702f76e..3ced66b 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,13 @@
 
 # 📘 نصب و استفاده از vllm 
 
-## بخش 1: نصب vllm
+## ⏬ بخش 1: نصب vllm
 
 <details>
-<summary> install via environments </summary>
 
-#### مقدمه:
+<summary style="text-align: center; color: red; font-weight: bold; cursor: pointer;" > install via environments </summary>
+
+### مقدمه:
 - بهتر است برای نصب این کتابخانه و یا کتابخانه‌هایی با وابستگی‌های زیاد از `uv` استفاده کنید:  
   🔗 لینک توضیحات بیشتر:  
   [https://docs.astral.sh/uv](https://docs.astral.sh/uv)
@@ -20,6 +21,9 @@
 - دستور ساخت: 
     ```uv venv --python 3.12```
 - دستور فعالسازی: `source .venv/bin/activate`
+
+---
+
 ### نصب vllm
 - خب حالا نوبت به نصب `vllm` است 
 * نکته: بر اساس مدلی که میخواهید serve کنید نسخه مشخص شده و بهینه شده را انتخاب کنید. 
@@ -45,7 +49,119 @@
 </details>
 
 <details>
-<summary> install via docker </summary>
+<summary style="text-align: center; color: red; font-weight: bold; cursor: pointer;"> install via docker </summary>
 
-detail of docker
-</details>
\ No newline at end of file
+### مقدمه:
+- ابتدا داکر مناسب مدل خود را از [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 
+<div dir="ltr" align="left">
+
+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 ` 
+</div>
+
+---
+
+### راه اندازی vllm با container docker
+- توضیح کار با کانتینر با یک مثال:
+
+<div dir="ltr" align="left">
+
+``` 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 ` : 
+
+<div dir="ltr" align="right">
+
+ دسترسی کامل به تمامی GPUهای سیستم ؛ در صورت نصب بودن ` nvidia-container-toolkit `  روی سرور (مطابق مراحل قبلی اگر رفته باشید مشکلی ندارید!)
+</div>
+
+⭕ ` --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 و مدل میتوانید استفاده کنید
+
+</div>
+
+</details>
+
+## ⚙️بخش 2: پارامتر های serve با vllm 
+<details>
+
+<summary style="text-align: center; color: red; font-weight: bold; cursor: pointer;" > vllm serve params Table </summary>
+
+### نکته:
+- بعد از نصب بر اساس نسخه نصب شده و کانفیگ مدل مورد نظر برای serve با پارامتر های متفاوتی شاید سروکار داشته باشید 
+
+حتما داکیومنت های سازنده مدل در این باره را مطالعه کنید
+### پارامترهای مهم vLLM به صورت عمومی:
+
+<div dir="ltr" align="center">
+
+| پارامتر                     | مقدار نمونه                      | توضیح فارسی                                                |
+| --------------------------- | -------------------------------- | ---------------------------------------------------------- |
+| `--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 |
+ 
+</div>
+</details>
+
+
+
+## 🧠بخش 3: نمونه کانفیگ های تست شده  serve با vllm 
+
+<details>
+<summary style="text-align: center; color: red; font-weight: bold; cursor: pointer;" > environments-base </summary>
+
+
+</details>
+
+<details>
+<summary style="text-align: center; color: red; font-weight: bold; cursor: pointer;" > docker-base </summary>
+
+</details>
+
+
+
+</div>
\ No newline at end of file