vLLM Production Stack: podstawowe uruchomienie w K8s

vLLM Production Stack: wdrożenie i podstawowe ustawienia dla środowiska produkcyjnego

vLLM Production Stack upraszcza wdrażanie wydajnego inferencji LLM w Kubernetes. Składa się z grupy instancji vLLM oraz routera do kierowania żądań. Obsługuje interfejs API kompatybilny z OpenAI: chat/completions, embeddings, tokenizer, a także transkrypcję i tłumaczenie audio. Środowisko testowe: 2 serwery z 8× NVIDIA H200 (141 GB), Astra Linux SE 8, Kubernetes 1.30, vLLM 0.17.0, Production Stack 0.1.10.

Przykłady konfiguracji przedstawione są fragmentami YAML. Pełne manifests zawierają standardowe pola Kubernetes, które nie są powtarzane dla skrócenia. Konflikty parametrów są oznaczone osobno.

Obsługiwane modele i ich ładowanie

vLLM obsługuje większość aktualnych modeli LLM. Dla nowych modeli użyj obrazów nightly. Modele domyślnie pobierane są z Hugging Face. W przypadku braku dostępu do internetu zamontuj je przez PVC:

extraVolumeMounts:
  - mountPath: /models/Qwen3-8B
    name: model
    readOnly: true
extraVolumes:
  - name: model
    persistentVolumeClaim:
      claimName: pvc-qwen3-8b

Podstawowe uruchomienie Qwen3-8B

Wdrożenie Qwen3-8B z lokalnym zamontowaniem i obsługą API OpenAI:

servingEngineSpec:
  enableEngine: true
  modelSpec:
    - name: qwen3-8b
      repository: vllm-openai
      tag: v0.17.0
      env:
        - name: HF_HUB_OFFLINE
          value: "1"
      modelURL: /models/Qwen3-8B
      extraVolumeMounts:
        - mountPath: /models/Qwen3-8B
          name: model
          readOnly: true
      extraVolumes:
        - name: model
          persistentVolumeClaim:
            claimName: pvc-qwen3-8b
      replicaCount: 1
      requestCPU: 8
      requestGPU: 1
      requestMemory: 16Gi
      vllmConfig:
        extraArgs:
          - --served-model-name
          - Qwen/Qwen3-8B
        gpuMemoryUtilization: 0.98

Zmienna HF_HUB_OFFLINE=1 wyłącza połączenia z HF. Przekierowanie portu: kubectl port-forward svc/... 9191:9191. Testowe żądanie:

curl -N http://localhost:9191/v1/chat/completions \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "Qwen/Qwen3-8B",
    "messages": [
      { "role": "user", "content": "Napisz: Cześć!" }
    ]
  }'

Model w trybie myślenia zwraca blok <think></think>.

Wywoływanie narzędzi i tryby myślenia

Aby włączyć wywoływanie narzędzi, włącz opcje serwerowe:

extraArgs:
  - --enable-auto-tool-choice
  - --tool-call-parser
  - qwen3_coder

Bez tych ustawień scenariusze agentów kończą się błędem. Tryb myślenia/nie-myślenia ustala się przez --default-chat-template-kwargs:

extraArgs:
  - --default-chat-template-kwargs
  - '{"enable_thinking": false}'

Klientowe chat_template_kwargs nadpisują serwerowe. Dla DeepSeek: {"thinking": false}.

Modele wielomodalne i backend CPU

Modele wielomodalne wymagają niestandardowego obrazu:

FROM vllm/vllm-openai:v0.17.0
RUN uv pip install --system "vllm[audio]==0.17.0" && \
    uv pip install --system "vllm[video]==0.17.0"

Zwiększ shmSize: "32Gi" pod mm_processor_cache. Wymagane jest tensorParallelSize: 1. Dla Qwen3-Omni-30B: --limit-mm-per-prompt.

Uruchomienie na CPU dla modeli embedding (Qwen3-Embedding-0.6B):

env:
  - name: VLLM_CPU_KVCACHE_SPACE
    value: "48"
vllmConfig:
  extraArgs:
    - --served-model-name
    - Qwen3-Embedding-0.6B

VLLM_CPU_KVCACHE_SPACE jest wymagane z rezerwą pamięci.

Kluczowe parametry uruchomienia

| Parametr | Zadanie | Kiedy ważny |

|----------|---------|-------------|

| enablePrefixCaching | Buforowanie wspólnego prefiksu KV-cache | Wspólne początki promptów |

| enableChunkedPrefill | Dzielenie długiego prefilla | Długie wejścia, mieszana obciążenie |

| maxModelLen | Maks. długość kontekstu | Oszczędność pamięci, długi kontekst |

| dtype | Typ liczb dla wag | Utrzymanie precyzji |

| tensorParallelSize | Podział na GPU | Duże modele |

| maxNumSeqs | Maks. sekwencji w batcie | Paralelizm, opóźnienia |

| gpuMemoryUtilization | Wykorzystanie pamięci GPU | Optymalizacja OOM |

gpuMemoryUtilization=0.98 pozostawia zapas na KV-cache. maxModelLen ogranicza kontekst dla oszczędności pamięci. enablePrefixCaching przyspiesza powtarzające się prefiksy.

Co warto wiedzieć

• vLLM Production Stack to gotowa warstwa K8s z routerem i funkcjonalnością observability.
• Dla pracy offline zamontuj modele przez PVC, ustaw HF_HUB_OFFLINE=1.
• Wywoływanie narzędzi wymaga --enable-auto-tool-choice i parsera specyficznego dla modelu.
• Modele wielomodalne: niestandardowy obraz + shmSize 32Gi + tensorParallelSize.
• Tryb CPU: VLLM_CPU_KVCACHE_SPACE z rezerwą pamięci.

— Editorial Team