لایهای بالاتر از vLLM قابلیتهای مسیریابی و مقیاسپذیری را اضافه میکند و شما آن را بر اساس ویژگیهای مدنظرتان انتخاب میکنید.
وقتی لازم است سرورهای vLLM متعددی را روی یک کلاستر اجرا کنید، با مطالعهی این بخش میتوانید لایهی مناسب برای اجرای vLLM روی کوبرنتیز را برگزینید.
شروع کار با امکانات پایهای یک Deployment
مستندات vLLM یک ساختار سادهی کوبرنتیزی را نشان میدهد: یک Volume برای وزنها، یک Secret برای توکن Hugging Face، یک Deployment که vllm serve را اجرا میکند و یک Service. یک Helm chart جمعوجور در مخزن vLLM همین اجزا را بستهبندی کرده است؛ علاوهبر آن، یک Job برای دانلود مدل و یک مقیاسپذیر خودکار اختیاری کوبرنتیز نیز دارد.
در ادامه، نسخهای حداقلی با ساختار اختصاصی خودمان را برای یک GPU و یک مدل میبینید. ما این پیکربندی را روی کلاستر اجرا نکردهایم. برای استفاده از آن به کلاستری نیاز دارید که در آن پلاگین دستگاه انویدیا (NVIDIA device plugin) منبع nvidia.com/gpu را ارائه دهد. برای مدلی با دسترسی محدود، یک Secret به نام hf-token با کلید token اضافه کنید. همچنین یک Secret به نام vllm-api-key با کلید key بسازید تا مسیرهای /v1 به کلید API نیاز داشته باشند.
apiVersion: apps/v1
kind: Deployment
metadata:
name: vllm-qwen3-8b
spec:
replicas: 1
selector:
matchLabels:
app: vllm-qwen3-8b
template:
metadata:
labels:
app: vllm-qwen3-8b
spec:
terminationGracePeriodSeconds: 120
containers:
- name: vllm
image: vllm/vllm-openai:v0.31.0
args: ["Qwen/Qwen3-8B", "--max-model-len", "8192", "--reasoning-parser", "qwen3"]
ports:
- containerPort: 8000
env:
- name: HF_TOKEN
valueFrom:
secretKeyRef:
name: hf-token
key: token
optional: true
- name: VLLM_API_KEY
valueFrom:
secretKeyRef:
name: vllm-api-key
key: key
resources:
limits:
nvidia.com/gpu: 1
startupProbe:
httpGet:
path: /health
port: 8000
periodSeconds: 10
failureThreshold: 90
readinessProbe:
httpGet:
path: /health
port: 8000
periodSeconds: 10
livenessProbe:
httpGet:
path: /health
port: 8000
periodSeconds: 30
failureThreshold: 3
volumeMounts:
- name: hf-cache
mountPath: /root/.cache/huggingface
- name: shm
mountPath: /dev/shm
volumes:
- name: hf-cache
emptyDir: {}
- name: shm
emptyDir:
medium: Memory
sizeLimit: 2Gi
---
apiVersion: v1
kind: Service
metadata:
name: vllm-qwen3-8b
spec:
selector:
app: vllm-qwen3-8b
ports:
- port: 8000
targetPort: 8000
ایمیج، فرمان vllm serve را اجرا میکند؛ بنابراین بخش args تنها مدل و فلگها را نگه میدارد. آزمون ارزیابی راهاندازی (Startup probe) امکان 90 بار بررسی با فاصلهی 10 ثانیه را میدهد که در مجموع 15 دقیقه میشود. نخستین راهاندازی روی DGX Spark ما حدود 8 دقیقه طول کشید؛ بنابراین این حد آستانه را بر اساس شروع سرد (Cold start) اندازهگیریشده در سیستم خودتان تنظیم کنید. پروبها جلوی ارسال ترافیک توسط کوبرنتیز یا ریاستارت شدن پاد حین بارگذاری وزنها را میگیرند.
کش emptyDir را با یک PersistentVolumeClaim جایگزین کنید تا پاد جدید وزنها را دوباره دانلود نکند. Volume حافظه در مسیر /dev/shm حافظهی اشتراکی را در اختیار فرایندها میگذارد، درست همانطور که پرچم --ipc=host در داکر عمل میکند. از آنجا که کلید API از مسیرهای /health یا /metrics محافظت نمیکند، با یک NetworkPolicy دسترسی پادها به Service را نیز محدود کنید.
این تنظیمات برای چند کپی (Replica) از یک مدل کافی است. یک Service معمولی درخواستها را بهصورت تصادفی پخش میکند؛ در نتیجه ممکن است نوبت گفتوگوی (Turn) بعدی کاربر به رپلیکایی برود که نوبتهای قبلی را هرگز کش نکرده است. همچنین مقیاسپذیری خودکار بر اساس مصرف CPU سیگنال نادرستی برای تصمیمگیری است، چرا که بار GPU همان بار CPU نیست.
انتخاب لایه بر اساس قابلیتهای مورد نیاز
| لایه | امکاناتی که اضافه میکند | چه زمانی انتخابش کنیم |
|---|---|---|
| استک عملیاتی (Production stack) vLLM | یک Helm chart، یک مسیریاب برای نگه داشتن نشستها روی یک رپلیکا، تخلیهی کش کلید-مقدار (KV cache offloading) از طریق LMCache و داشبوردهای Grafana | وقتی پیکربندی مرجع ارائهشده توسط پروژهی vLLM را میخواهید |
| llm-d | مسیریابی که معیارهای vLLM و رخدادهای KV cache را برای انتخاب رپلیکا میخواند، تفکیک پیشپرکنی (prefill) و رمزگشایی (decode)، موازیسازی متخصصان (Expert parallelism) در مقیاس وسیع | وقتی مدلهای بزرگ اجرا میکنید یا پیشپرکنی و رمزگشایی را روی کلاستر از هم جدا کردهاید |
| KServe | پلتفرم سرو مدل با محیط اجرای (Runtime) vLLM و یک ریسورس LLM مبتنی بر llm-d | وقتی سازمان شما در حال حاضر از KServe برای مدلهای دیگر استفاده میکند |
| AIBrix | یک صفحهی کنترل (Control plane) با قابلیتهای مسیریابی، مدیریت LoRA و مقیاسپذیری خودکار بر اساس معیارهای موتور | وقتی با یک Control plane واحد به چندین مدل و تطبیقدهنده (Adapter) نیاز دارید |
| Ray Serve LLM | اجرای vLLM در دل Ray Serve، همراه با سرو چندین مدل | وقتی استک فعلی شما از قبل روی Ray اجرا میشود |
پروژهی llm-d نسخهی 1.0 خود را در تاریخ 2026-10-20 منتشر کرد. این پروژه در مارس 2026 بهعنوان یک پروژهی ساندباکس (Sandbox) به CNCF پیوست. مسیریاب آن از Gateway API Inference Extension پیروی میکند که پروژهای در کوبرنتیز برای مسیریابی به سمت سرورهای مدل است.
شناخت قابلیتهای vLLM که لایهها استفاده میکنند
این لایهها اینترفیسهای مشترک vLLM را میخوانند. بررسی کنید که نسخهی vLLM شما از قابلیتهای مورد نیاز لایهی انتخابیتان پشتیبانی کند:
- معیارها (Metrics): مسیریابها مقادیر
vllm:num_requests_waiting،vllm:num_requests_runningوvllm:kv_cache_usage_percرا برای انتخاب رپلیکا میخوانند. - رخدادهای KV cache: با فلگ
--kv-events-config، موتور vLLM ذخیره و حذف هر بلوک را گزارش میدهد. مسیریاب از این رخدادها استفاده میکند تا درخواست را به رپلیکایی بفرستد که پیشوند (Prefix) آن را نگه داشته است. - اتصالدهندههای KV (یا KV connectors): تفکیک پیشپرکنی و رمزگشایی و همچنین کش اشتراکی، از
--kv-transfer-configاستفاده میکنند. - سلامت (Health): مسیر
/healthبه پروبهای startup، liveness و readiness پاسخ میدهد.
روی سختافزار ما اندازهگیری نشده است. ما اجرایی روی کلاستر نداشتهایم و مانیفست بالا را نیز اعمال نکردیم.
منابع: مستندات vLLM در نسخهی v0.31.0 (مسیرهای docs/deployment/k8s.md، docs/deployment/frameworks/helm.md و docs/deployment/integrations/)، یادداشتهای انتشار و مستندات معماری llm-d v1.0.0 (تاریخ 2026-10-20)، اعلان CNCF دربارهی llm-d (تاریخ 2026-03-24)، مستندات production-stack، AIBrix و KServe (دسترسی در 2026-10-21)، لاگ ثبتشده از راهاندازی GB10 ما در capture/gpu/out-gb10/server-load-vllm.log (آرگومانها در ساعت 10:53:02، آماده شدن سرور در ساعت 11:00:59)، سورسکد vLLM در نسخهی v0.31.0 در vllm/entrypoints/serve/middleware/authenticate.py (کلید فقط از مسیرهای زیرمجموعهی /v1، /v2، /inference و /cohere محافظت میکند).