از سیستمی کاملاً خام تا دریافت اولین توکن استریمشده از سرور 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 را سرو کردیم. خروجی سیستم شما هم ساختاری کاملاً مشابه ولی با اعدادی کوچکتر خواهد داشت.
(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شش خط بریدهشده از ابتدای لاگ. بنر، پیکربندی کامل موتور و فهرست مسیرها حذف شدهاند.
خطوط را به این ترتیب بخوانید:
- نسخه (The version): باید دقیقاً همان نسخهای باشد که قفل کردهاید.
- اجراکنندهی مدل (The model runner): نسخه 0.31.0 در vLLM بهطور پیشفرض روی CUDA از مدل رانر V2 استفاده میکند. برخی قابلیتها آن را به V1 برمیگردانند و این خط وضعیت را نشان میدهد.
- بکاند اتنشن (The attention backend): vLLM یکی را با توجه به پردازندهی گرافیکی شما انتخاب میکند. تغییر نوع دادهی کش کلید-مقدار (KV cache) میتواند این خط را عوض کند.
- بارگذاری مدل (Model loading): این خط حافظهی مصرفشده برای وزنها و زمان بارگذاری آنها را نشان میدهد.
- حافظهی آزاد کش کلید-مقدار (The available KV cache memory): حافظهای را نشان میدهد که پس از وزنها و پروفایل اولیه، برای کش کلید-مقدار باقی مانده است.
- اندازهی کش کلید-مقدار (The KV cache size): تعداد توکنهایی که در کش جا میشوند و همچنین تعداد درخواستهای همزمان با طول کامل را که جا میگیرند، نشان میدهد. بخش 2 از همین خط شروع میشود.
وقتی پیام Application startup complete. را در لاگ دیدید، سرور آماده است. روی DGX Spark ما، این مرحله برای 57 گیبیبایت وزن حدود 8 دقیقه طول کشید. خط بارگذاری مدل زمان 330.5 ثانیه را نشان میدهد که 325 ثانیهی آن صرف خواندن فایلهای وزنها شد.
ارسال اولین درخواست
یک ترمینال دوم باز کنید. یک درخواست چت با 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.