بخش 1.1 · شروع کار

نصب vLLM و راه‌اندازی اولین مدل

Install vLLM and serve your first model

فهرست مطالب
  1. ابتدا وضعیت GPU را بررسی کنید
  2. نصب vLLM
  3. اجرای سرور
  4. ارسال اولین درخواست
  5. وقتی خروجی با این متن فرق دارد

از سیستمی کاملاً خام تا دریافت اولین توکن استریم‌شده از سرور vLLM اختصاصی‌تان، فقط سه دستور و یک درخواست فاصله دارید.

یک پردازنده‌ی گرافیکی (GPU) از برند NVIDIA و نام یک مدل را دارید و می‌خواهید اندپوینت اختصاصی و سازگار با OpenAI خودتان را بسازید. در پایان این بخش می‌توانید vLLM را نصب کنید، سرور را راه بیندازید، درخواستی به آن بفرستید و لاگ بالا آمدن سرور را بخوانید.

در تمام دستورها از vLLM نسخه 0.31.0 استفاده می‌کنیم. از آنجا که تقریباً هر دو هفته یک نسخه‌ی فرعی (Minor release) جدید از vLLM منتشر می‌شود، حتماً نسخه را در دستور نصب خود قفل (Pin) کنید.

ابتدا وضعیت GPU را بررسی کنید

پیش از هر چیز، مطمئن شوید درایور پردازنده‌ی گرافیکی شما را می‌شناسد. این دستور را اجرا کنید:

nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv

به ازای هر GPU، یک خط با نام و میزان حافظه‌ی آن می‌بینید. اگر این دستور پیدا نشد، پیش از ادامه‌ی کار درایور NVIDIA را نصب کنید؛ vLLM درایور را برایتان نصب نمی‌کند.

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

نیاز شما مقدار در نسخه 0.31.0
سیستم‌عامل لینوکس، یا WSL در ویندوز برای روش‌های uv و pip. روش Docker به میزبانی با NVIDIA container toolkit نیاز دارد
پردازنده‌ی گرافیکی (GPU) انویدیا، با توان محاسباتی (Compute capability) 7.5 یا بالاتر؛ مانند T4، L4، A100 یا H100
درایور به‌اندازه‌ی کافی جدید برای پشتیبانی از CUDA 12.9 در بسته‌ی پیش‌فرض wheel، و نسخه‌ی R580 یا بالاتر برای ایمیج CUDA 13
پایتون 3.10 تا 3.13
توکن Hugging Face فقط برای مدل‌های دارای دسترسی محدود نیاز است و در قالب متغیر HF_TOKEN تنظیم می‌شود

نصب vLLM

یکی از این سه مسیر را انتخاب کنید. پیشنهاد می‌کنیم همان مسیر اول را بروید، مگر اینکه دلیل خاصی برای انتخاب روش دیگری داشته باشید.

مسیر 1: uv. ابزار uv یک محیط پایتون تر‌و‌تمیز می‌سازد و بیلد PyTorch سازگار با درایور CUDA شما را انتخاب می‌کند.

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm==0.31.0 --torch-backend=auto

مسیر 2: pip. از یک محیط مجازی (Virtual environment) جدید با پایتون 3.12 استفاده کنید و بعد همان نسخه را نصب کنید.

python3.12 -m venv .venv && source .venv/bin/activate
pip install vllm==0.31.0

مسیر 3: Docker. ایمیج رسمی شامل vLLM، PyTorch و CUDA است. ما ایمیج vllm/vllm-openai:v0.31.0 را روی سرور arm64 DGX Spark پول کردیم و بدون مشکل اجرا شد.

docker run --rm --gpus all --ipc=host -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:v0.31.0 Qwen/Qwen3-0.6B --reasoning-parser qwen3

این ایمیج سرور را خودبه‌خود روشن می‌کند؛ بنابراین با داکر از مرحله‌ی بعد رد می‌شوید. کش Hugging Face خود را روی کانتینر سوار (Mount) کنید، وگرنه کانتینر در هر بار راه‌اندازی، وزن‌ها را دوباره دانلود می‌کند. لاگ‌ها را با docker logs روی کانتینر بخوانید.

با دستور vllm --version نصب را بررسی کنید. باید نسخه‌ی 0.31.0 را ببینید.

در مسیرهای uv و pip، در اولین راه‌اندازی، کرنل‌های FlashInfer کامپایل می‌شوند؛ بنابراین به CUDA toolkit شامل nvcc و تنظیم متغیر CUDA_HOME نیاز دارد. ایمیج داکر این ابزار را دارد. ما نسخه 0.31.0 را با uv روی سیستمی نصب کردیم که فقط درایور داشت و هر بار اجرا با خطای Could not find nvcc متوقف شد. این بسته‌ی ابزار را نصب کنید، متغیر CUDA_HOME را به آن ارجاع دهید و دوباره سرور را راه بیندازید. در صفحه‌ی عیب‌یابی بر اساس نشانه‌ها این مشکل و همچنین ناسازگاری نسخه‌ی toolkit را توضیح داده‌ایم.

اجرای سرور

حالا یک مدل کوچک را اجرا کنید. مدل Qwen3-0.6B حدود 0.6 میلیارد پارامتر دارد؛ بنابراین وزن‌های BF16 آن به حدود 1.2 گیگابایت فضا نیاز دارند.

vllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3 2>&1 | tee server.log

سرور روی پورت 8000 به درخواست‌ها گوش می‌دهد. در اولین اجرا، وزن‌های مدل دانلود می‌شوند؛ به همین دلیل بیشتر از دفعات بعدی طول می‌کشد.

دستور tee لاگ را هم‌زمان در ترمینال نشان می‌دهد و در فایل server.log هم می‌نویسد. در بخش‌های بعدی این فایل را با grep جست‌وجو می‌کنیم، پس در تمام اجراها همین نام را نگه دارید.

مدل Qwen3 یک مدل استدلالی است؛ ابتدا فرایند تفکر خود را بین تگ‌های <think> می‌نویسد و سپس پاسخ را می‌آورد. فلگ --reasoning-parser qwen3 به vLLM می‌گوید بخش تفکر را از متن پاسخ بیرون بکشد. بدون این فلگ، بخش تفکر در ابتدای پاسخ باقی می‌ماند. در صفحه‌ی سرو مدل‌های استدلالی کارکرد این پارسر را توضیح داده‌ایم.

لاگ بالا آمدن طولانی است؛ اما شش خط کلیدی بیشتر چیزهایی را که نیاز دارید به شما می‌گویند. در ادامه، این خطوط را از خروجی DGX Spark آورده‌ایم؛ جایی که مدل بزرگ‌تر Qwen3-30B-A3B را سرو کردیم. خروجی سیستم شما هم ساختاری کاملاً مشابه ولی با اعدادی کوچک‌تر خواهد داشت.

خطوط راه‌اندازی برای بررسی، از یک DGX Spark capture/gpu/out-gb10/server-load-vllm.log
(APIServer pid=1) INFO 10-21 10:53:02 [api_utils.py:347]  ▄▄ ▄█ █     █     █ ▀▄▀ █  version 0.31.0
(EngineCore pid=143) INFO 10-21 10:53:14 [gpu_worker.py:479] Using V2 Model Runner
(EngineCore pid=143) INFO 10-21 10:53:17 [cuda.py:526] Using FLASH_ATTN attention backend out of potential backends: ['FLASH_ATTN', 'FLASHINFER', 'TRITON_ATTN', 'FLEX_ATTENTION'].
(EngineCore pid=143) INFO 10-21 10:58:45 [model_runner.py:407] Model loading took 56.93 GiB memory and 330.542793 seconds
(EngineCore pid=143) INFO 10-21 10:59:46 [gpu_worker.py:692] Available KV cache memory: 31.32 GiB
(EngineCore pid=143) INFO 10-21 10:59:46 [kv_cache_utils.py:2464] GPU KV cache size: 234,960 tokens, Maximum concurrency for 8,192 tokens per request: 28.68x

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

خطوط را به این ترتیب بخوانید:

  1. نسخه (The version): باید دقیقاً همان نسخه‌ای باشد که قفل کرده‌اید.
  2. اجراکننده‌ی مدل (The model runner): نسخه 0.31.0 در vLLM به‌طور پیش‌فرض روی CUDA از مدل رانر V2 استفاده می‌کند. برخی قابلیت‌ها آن را به V1 برمی‌گردانند و این خط وضعیت را نشان می‌دهد.
  3. بک‌اند اتنشن (The attention backend): vLLM یکی را با توجه به پردازنده‌ی گرافیکی شما انتخاب می‌کند. تغییر نوع داده‌ی کش کلید-مقدار (KV cache) می‌تواند این خط را عوض کند.
  4. بارگذاری مدل (Model loading): این خط حافظه‌ی مصرف‌شده برای وزن‌ها و زمان بارگذاری آنها را نشان می‌دهد.
  5. حافظه‌ی آزاد کش کلید-مقدار (The available KV cache memory): حافظه‌ای را نشان می‌دهد که پس از وزن‌ها و پروفایل اولیه، برای کش کلید-مقدار باقی مانده است.
  6. اندازه‌ی کش کلید-مقدار (The KV cache size): تعداد توکن‌هایی که در کش جا می‌شوند و همچنین تعداد درخواست‌های هم‌زمان با طول کامل را که جا می‌گیرند، نشان می‌دهد. بخش 2 از همین خط شروع می‌شود.

وقتی پیام Application startup complete. را در لاگ دیدید، سرور آماده است. روی DGX Spark ما، این مرحله برای 57 گیبی‌بایت وزن حدود 8 دقیقه طول کشید. خط بارگذاری مدل زمان 330.5 ثانیه را نشان می‌دهد که 325 ثانیه‌ی آن صرف خواندن فایل‌های وزن‌ها شد.

شش خط راه‌اندازی که باید بررسی شوندشش خط راه‌اندازی نسخه، اجراکننده، بک‌اند اتنشن، حافظه وزن‌ها، حافظه آزاد KV و اندازه استخر را نشان می‌دهند.
شش خط راه‌اندازی که باید پس از هر بار شروع بررسی شوند شش خط از لاگ راه‌اندازی vLLM 0.31.0 روی یک DGX Spark با مدل Qwen3-30B-A3B: نسخه 0.31.0، اجراکننده مدل V2، بک‌اند اتنشن FLASH_ATTN، مقدار 56.93 گیبی‌بایت وزن بارگذاری‌شده در 330 ثانیه، 31.32 گیبی‌بایت حافظه باقی‌مانده برای کش کلید-مقدار، و استخری به ظرفیت 234,960 توکن. خط لاگ مقدار ما اثر تعیین‌کننده version 0.31.0 نسخه در حال اجرا Using V2 Model Runner V2 کدام اجراکننده مدل اجرا می‌شود attention backend FLASH_ATTN کدام کرنل‌ها اتنشن را اجرا می‌کنند Model loading took 56.93 GiB, 330 s حافظه اشغال‌شده توسط وزن‌ها Available KV cache memory 31.32 GiB حافظه باقی‌مانده برای کش کلید-مقدار GPU KV cache size 234,960 توکن ظرفیت تعداد کاربران پس از هر راه‌اندازی و قبل از ارسال ترافیک، هر خط را یک‌بار بررسی کنید.
هر ردیف را از چپ به راست بخوانید: خط لاگ، مقدار ما روی DGX Spark، و اثر تعیین‌کننده آن. برگرفته از capture/gpu/out-gb10/server-load-vllm.log.

ارسال اولین درخواست

یک ترمینال دوم باز کنید. یک درخواست چت با curl بفرستید:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen/Qwen3-0.6B", "messages": [{"role": "user", "content": "Name three prime numbers."}], "max_tokens": 64, "chat_template_kwargs": {"enable_thinking": false}}'

فیلد chat_template_kwargs بخش تفکر را برای همین تک‌درخواست خاموش می‌کند؛ بنابراین 64 توکن برای دریافت پاسخ کاملاً کافی است. خروجی در قالب یک آبجکت JSON برمی‌گردد. متن پاسخ در choices[0].message.content قرار دارد و تعداد توکن‌ها در usage ثبت شده است. در لاگ سرور هم خط جدیدی مسیر درخواست و وضعیت 200 OK را نشان می‌دهد.

اگر تفکر مدل را روشن بگذارید، ممکن است تمام 64 توکن را صرف آن کند. در این صورت، متن تفکر به فیلد reasoning منتقل می‌شود، مقدار content خالی (null) خواهد بود و مقدار finish_reason روی length قرار می‌گیرد. ما دقیقاً همین رفتار را روی یک کارت L4 دیدیم. برای درخواستی که شامل تفکر است، مقدار max_tokens را خیلی بزرگ‌تر بگذارید.

سرور از API شرکت OpenAI پشتیبانی می‌کند؛ بنابراین کلاینت پایتون OpenAI بدون هیچ تغییری در کد کار خواهد کرد:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
stream = client.chat.completions.create(
    model="Qwen/Qwen3-0.6B",
    messages=[{"role": "user", "content": "Name three prime numbers."}],
    stream=True,
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

توکن‌ها هم‌زمان با استریم شدن از سرور، یکی‌یکی چاپ می‌شوند. این اولین توکن استریم‌شده‌ی شماست!

وقتی خروجی با این متن فرق دارد

  • سرور با خطای کمبود حافظه (Out-of-memory) متوقف می‌شود: برنامه‌ی دیگری از GPU استفاده می‌کند یا مدل برای آن زیادی بزرگ است. صفحه‌ی رفع مشکل کمبود حافظه هنگام اجرا را بخوانید.
  • پاسخ با یک بلوک طولانی <think> شروع می‌شود: سرور بدون پارسر استدلال اجرا شده است. آن را با --reasoning-parser qwen3 اجرا کنید، یا در متن درخواست "chat_template_kwargs": {"enable_thinking": false} بفرستید.
  • پاسخ خالی است و مقدار finish_reason روی length است: بخش تفکر تمام max_tokens را مصرف کرده است. مقدار max_tokens را بالا ببرید یا تفکر را برای آن درخواست خاموش کنید.
  • درخواست خطای 404 برمی‌گرداند: نام مدل در درخواست باید دقیقاً مطابق نام نوشته‌شده در vllm serve باشد. برای دیدن آن دستور curl http://localhost:8000/v1/models را اجرا کنید.
  • پاسخ‌ها از نمونه‌برداری متفاوتی نسبت به تنظیم شما استفاده می‌کنند: vLLM به‌طور پیش‌فرض تنظیمات سمپلینگ را از مخزن (Repository) مدل می‌خواند. سرور را با --generation-config vllm راه بیندازید تا مقادیر پیش‌فرض vLLM اعمال شوند.
  • راه‌اندازی سرور چندین دقیقه طول می‌کشد: در اولین اجرا، وزن‌های مدل دانلود می‌شوند. روی DGX Spark، خواندن و بارگذاری وزن مدل‌های بزرگ در نسخه‌ی 0.31.0 کند است.

منابع: مستندات vLLM در نسخه‌ی v0.31.0 (شامل docs/getting_started/quickstart.md، docs/getting_started/installation/gpu.md، docs/getting_started/installation/gpu.cuda.inc.md، docs/deployment/docker.md، docs/features/reasoning_outputs.md)، فایل capture/gpu/out-gb10/server-load-vllm.log، ایشوی 58726، و capture/gpu/out-l4/livecheck-2026-10-23.txt.

ترجمه‌ی فارسی Install vLLM and serve your first model از راهنمای vLLM 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما