vLLM Production Stack: K8s에서 기본 실행

vLLM 프로덕션 스택: 쿠버네티스 배포 및 기본 설정

vLLM 프로덕션 스택은 쿠버네티스 기반으로 고성능 LLM 추론을 간편하게 구현할 수 있도록 도와줍니다. 이 스택은 여러 개의 vLLM 인스턴스와 요청 라우팅을 담당하는 라우터로 구성되어 있으며, OpenAI 호환 API를 지원합니다: 채팅/완성, 임베딩, 토크나이저, 오디오 변환, 번역 등 다양한 기능을 제공합니다. 테스트 환경은 2대의 서버(8× NVIDIA H200, 141GB), Astra Linux SE 8, 쿠버네티스 1.30, vLLM 0.17.0, 프로덕션 스택 0.1.10입니다.

설정 예시는 YAML 스니펫 형태로 제시됩니다. 전체 매니페스트에는 표준 쿠버네티스 필드가 포함되지만, 간결성을 위해 일부는 생략했습니다. 파라미터 충돌 사항은 별도로 안내됩니다.

지원 모델 및 로딩 방법

vLLM는 대부분의 최신 LLM을 지원합니다. 새로운 모델 사용 시 나이트리 빌드를 권장합니다. 기본적으로 모델은 허깅페이스에서 다운로드됩니다. 오프라인 환경에서는 PVC를 통해 마운트할 수 있습니다:

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

기본 Qwen3-8B 배포 설정

로컬 마운트와 함께 OpenAI API 지원을 포함한 Qwen3-8B 배포 예시:

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

HF_HUB_OFFLINE=1 설정은 모든 허깅페이스 허브 호출을 비활성화합니다. 포트 포워딩 명령어: kubectl port-forward svc/... 9191:9191. 테스트 요청 예시:

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

사고 모드(Thinking Mode) 활성화 시 모델은 <think>...</think> 블록을 반환합니다.

도구 호출 및 사고 모드 설정

도구 호출 기능을 활성화하려면 서버 측 옵션을 설정해야 합니다:

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

이 설정 없이 작업하면 에이전트 워크플로우가 실패합니다. 사고 모드는 --default-chat-template-kwargs를 통해 활성화/비활성화 가능합니다:

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

클라이언트 측의 chat_template_kwargs는 서버 설정을 오버라이드할 수 있습니다. DeepSeek 모델의 경우 {"thinking": false}를 사용하세요.

멀티모달 모델 및 CPU 백엔드 설정

멀티모달 모델은 커스텀 이미지가 필요합니다:

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"

mm_processor_cache를 위해 shmSize: "32Gi"를 증가시키고, tensorParallelSize: 1로 설정하세요. Qwen3-Omni-30B의 경우 --limit-mm-per-prompt를 사용하세요.

CPU 전용 추론을 위한 임베딩 모델(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는 메모리 버퍼와 함께 반드시 설정되어야 합니다.

핵심 런타임 파라미터

| 파라미터 | 목적 | 중요할 때 |

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

| enablePrefixCaching | 공유 접두사 KV 캐시 활성화 | 반복되는 프롬프트 시작 시 |

| enableChunkedPrefill | 긴 프리필 단계 분할 | 긴 입력, 혼합 부하 시 |

| maxModelLen | 최대 컨텍스트 길이 제한 | 메모리 절약, 긴 컨텍스트 처리 |

| dtype | 가중치 데이터 타입 설정 | 정밀도 조절 |

| tensorParallelSize | GPU 분할 크기 | 대규모 모델 처리 |

| maxNumSeqs | 배치당 최대 시퀀스 수 | 병렬성, 지연 시간 관리 |

| gpuMemoryUtilization | GPU 메모리 사용률 | OOM 최적화 |

gpuMemoryUtilization=0.98는 KV 캐시를 위한 여유 공간을 확보합니다. maxModelLen은 메모리 절약을 위해 컨텍스트 길이를 제한합니다. enablePrefixCaching는 반복적인 접두사를 빠르게 처리할 수 있게 해줍니다.

핵심 요약

• vLLM 프로덕션 스택은 내장된 라우터와 감시 기능을 갖춘 즉시 사용 가능한 쿠버네티스 계층입니다.
• 오프라인 환경에서는 PVC를 통해 모델을 마운트하고 HF_HUB_OFFLINE=1을 설정하세요.
• 도구 호출은 --enable-auto-tool-choice와 모델별 파서가 필요합니다.
• 멀티모달 모델: 커스텀 이미지 + shmSize 32Gi + tensorParallelSize 설정.
• CPU 모드: VLLM_CPU_KVCACHE_SPACE에 메모리 버퍼를 함께 설정하세요.

— Editorial Team