بخش 6.4 · مقیاس‌پذیری افقی

اجرای vLLM روی کوبرنتیز (Kubernetes)

Run vLLM on Kubernetes

فهرست مطالب
  1. شروع کار با امکانات پایه‌ای یک Deployment
  2. انتخاب لایه بر اساس قابلیت‌های مورد نیاز
  3. شناخت قابلیت‌های vLLM که لایه‌ها استفاده می‌کنند

لایه‌ای بالاتر از 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 محافظت می‌کند).

ترجمه‌ی فارسی Run vLLM on Kubernetes از راهنمای vLLM 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما