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

تنظیم گزینه‌های سرور برای محیط عملیاتی

Set the server options every deployment needs

فهرست مطالب
  1. انتخاب آدرس و پورت
  2. تعیین یک نام پایدار برای مدل
  3. الزامی کردن کلید API
  4. اصلاح الگوی چت
  5. مدیریت خروجی لاگ‌ها
  6. غیرفعال‌سازی ارسال آمار مصرف
  7. نگهداری تنظیمات در فایل
  8. بررسی صحت تنظیمات

چند گزینه‌ی کلیدی در سرور مشخص می‌کنند چه کسانی به آن دسترسی داشته باشند، کلاینت‌ها چه نامی برای مدل بفرستند و چه اطلاعاتی در لاگ ثبت شود.

اولین سرور شما راه افتاده است و حالا برنامه‌های دیگر باید بتوانند آن را فراخوانی کنند. در پایان این بخش، می‌توانید آدرس، نام مدل، کلید API، الگوی چت (chat template) و نحوه‌ی ثبت لاگ را تنظیم کنید.

ما سرعت اجرای این گزینه‌ها را نسنجیده‌ایم. فقط آدرس، نام مدل، کلید API، فایل YAML و فلگ حذف‌شده‌ی لاگ را روی یک کارت گرافیک L4 همراه با مدل کوچک Qwen3-0.6B آزمایش کرده‌ایم. بقیه‌ی موارد برگرفته از مستندات vLLM و کدهای منبع نسخه‌ی 0.31.0 هستند.

انتخاب آدرس و پورت

گزینه مقدار پیش‌فرض در نسخه‌ی 0.31.0 زمان استفاده
--host تنظیم نشده است؛ سرور روی تمام رابط‌های شبکه گوش می‌دهد سرور فقط باید به یک رابط شبکه پاسخ دهد، مثل 127.0.0.1 برای تست محلی
--port 8000 برنامه‌ی دیگری پورت 8000 را اشغال کرده باشد، یا بخواهید دو سرور را روی یک سیستم اجرا کنید

حالت پیش‌فرض روی همه‌ی رابط‌های شبکه گوش می‌دهد؛ بنابراین سایر سیستم‌های متصل به شبکه هم می‌توانند به سرور دسترسی داشته باشند. برای آزمایش روی سیستم خودتان، گزینه‌ی --host 127.0.0.1 را قرار دهید.

تعیین یک نام پایدار برای مدل

به‌طور پیش‌فرض، نام مدل در API همان نامی است که به vllm serve داده‌اید؛ مثل Qwen/Qwen3-8B. کلاینت‌ها هم باید دقیقاً همین نام را ارسال کنند. فلگ --served-model-name نام جایگزینی را مشخص می‌کند که کلاینت‌ها باید به کار ببرند:

vllm serve Qwen/Qwen3-8B --served-model-name chat

حالا کلاینت‌ها عبارت "model": "chat" را ارسال می‌کنند. با این کار، می‌توانید بدون دست زدن به کد کلاینت‌ها، مدل را به یک چک‌پوینت (checkpoint) جدید ارتقا دهید. این نام در متریک‌ها هم با برچسب model_name ثبت می‌شود. اگر چند نام وارد کنید، سرور به تک‌تک آن‌ها پاسخ می‌دهد.

الزامی کردن کلید API

گزینه‌ی --api-key سرور را موظف می‌کند تا وجود کلید را در هدر Authorization بررسی کند. همچنین می‌توانید آن را با متغیر محیطی VLLM_API_KEY مقداردهی کنید تا کلید در فهرست فرایندها دیده نشود.

ابتدا هر سروری را که از قبل روی پورت 8000 فعال است متوقف کنید. سپس در ترمینال اول، سرور را همراه با یک کلید راه بیندازید:

VLLM_API_KEY=change-me vllm serve Qwen/Qwen3-8B --host 127.0.0.1 2>&1 | tee server.log

وقتی سرور آماده شد، در ترمینال دوم درخواستی را همراه با این کلید بفرستید:

curl http://localhost:8000/v1/models -H "Authorization: Bearer change-me"

این کلید فقط از مسیرهای زیرمجموعه‌ی /v1، /v2، /inference و /cohere محافظت می‌کند. سایر مسیرها روی همین پورت، مانند /invocations، /metrics و /health همچنان باز و عمومی می‌مانند. ما این موضوع را روی یک L4 بررسی کردیم؛ بدون ارسال کلید، مسیر /v1/models خطای 401 داد، اما پاسخ مسیرهای /health و /metrics با کد 200 برگشت و درخواست چت به /invocations هم کد 200 گرفت.

بنابراین، این کلید به‌تنهایی سرور را روی شبکه‌ی عمومی امن نمی‌کند. همان‌طور که در صفحه‌ی اجرای vLLM در محیط عملیاتی آمده است، حتماً یک گیت‌وی (gateway) پیش روی آن بگذارید.

اصلاح الگوی چت

فریم‌ورک vLLM پیام‌های چت را بر اساس الگوی چتِ موجود در مخزن (repository) مدل قالب‌بندی می‌کند. بعضی مخزن‌ها اصلاً این الگو را ندارند یا الگوی نادرستی دارند. در این صورت، مدل پرامپتی با ساختار نامناسب تحویل می‌گیرد و پاسخ‌های ضعیفی تولید می‌کند.

فلگ --chat-template مسیر یک فایل یا متن خود الگو را می‌گیرد. گزینه‌ی --default-chat-template-kwargs هم مقادیر پیش‌فرضی را برای الگو در همه‌ی درخواست‌ها اعمال می‌کند؛ مانند '{"enable_thinking": false}' برای Qwen3. با این حال، هر درخواست به‌صورت جداگانه همچنان می‌تواند chat_template_kwargs اختصاصی خودش را داشته باشد. در صفحه‌ی سرو مدل‌های استدلالی از همین قابلیت برای Qwen3 استفاده شده است.

مدیریت خروجی لاگ‌ها

گزینه مقدار پیش‌فرض عملکرد
--enable-log-requests غیرفعال یک سطر لاگ شامل شناسه و پارامترهای هر درخواست ثبت می‌کند
--max-log-len بدون محدودیت طول متن پرامپت را در این سطرها به تعداد کاراکتر مشخصی محدود می‌کند
VLLM_LOGGING_LEVEL INFO سطح لاگ vLLM را مشخص می‌کند؛ مانند DEBUG برای بررسی مشکلات پیچیده
--uvicorn-log-level info سطح لاگ سرور HTTP را تعیین می‌کند
--disable-uvicorn-access-log غیرفعال سطر مربوط به هر درخواست HTTP را حذف می‌کند؛ مثل هر بار آزمون ارزیابی (probe) برای مسیر /health

با فعال کردن --enable-log-requests در سطح DEBUG، متن پرامپت هم در سطرهای مربوط به درخواست ثبت می‌شود. روی سروری که داده‌های محرمانه را مدیریت می‌کند، هرگز از این تنظیم استفاده نکنید.

در نسخه‌های قدیمی‌تر فلگی به نام --disable-log-requests وجود داشت. در نسخه‌ی 0.31.0 این فلگ حذف شده است و ثبت سطر درخواست‌ها تا زمانی که خودتان آن را فعال نکنید، خاموش می‌ماند.

غیرفعال‌سازی ارسال آمار مصرف

فریم‌ورک vLLM به‌طور پیش‌فرض داده‌های ناشناسی را درباره‌ی مشخصات سخت‌افزار و پیکربندی مدل ارسال می‌کند. برای غیرفعال کردن آن، کافی است متغیر محیطی VLLM_NO_USAGE_STATS=1 یا DO_NOT_TRACK=1 را در محیط سرور تنظیم کنید.

نگهداری تنظیمات در فایل

دستور vllm serve --config config.yaml این گزینه‌ها را از یک فایل YAML می‌خواند. هر کلید در این فایل، همان نام بلند فلگ بدون دو خط تیره است؛ مانند served-model-name: chat. اگر گزینه‌ای را مستقیماً در خط فرمان وارد کنید، اولویت با مقدار خط فرمان خواهد بود و مقدار فایل نادیده گرفته می‌شود.

بررسی صحت تنظیمات

سطر non-default args را نزدیک به ابتدای لاگ بررسی کنید. این سطر تمام گزینه‌هایی را که از مقدار پیش‌فرض تغییر داده‌اید فهرست می‌کند:

grep "non-default args" server.log

سپس اندپوینت /v1/models را یک بار با کلید و یک بار بدون آن فراخوانی کنید. بدون کلید، سرور باید خطای HTTP 401 برگرداند:

منابع: مستندات vLLM در نسخه‌ی v0.31.0 (بخش‌های docs/configuration/serve_args.md، docs/usage/usage_stats.md، docs/usage/security.md، docs/usage/troubleshooting.md)، سورس‌کد vLLM در نسخه‌ی v0.31.0 (فایل‌های vllm/entrypoints/launchers/cli_args.py، vllm/entrypoints/launchers/launcher.py، vllm/engine/arg_utils.py، vllm/config/model.py، vllm/envs.py)، لاگ capture/gpu/out-gb10/server-load-vllm.log و capture/gpu/out-l4/livecheck-2026-10-22.txt.

ترجمه‌ی فارسی Set the server options every deployment needs از راهنمای vLLM 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما