vLLM 生产栈：K8s 中的基本启动

vLLM生产级部署：Kubernetes环境下的快速上线指南

vLLM生产级堆栈简化了在Kubernetes上部署高吞吐量大模型推理的流程。该架构由一组vLLM实例与一个路由器组成，负责请求分发。支持OpenAI兼容API：聊天/补全、嵌入向量、分词、音频转录及翻译功能。测试环境配置：2台服务器，每台配备8×NVIDIA H200（141GB显存），Astra Linux SE 8系统，Kubernetes 1.30版本，vLLM 0.17.0，生产堆栈版本0.1.10。

配置示例以YAML片段形式展示。完整清单包含标准Kubernetes字段，此处为简洁起见省略。参数冲突情况将单独说明。

支持的模型与加载方式

vLLM支持当前主流的大语言模型。新模型建议使用夜间构建版本。默认从Hugging Face下载模型。在离线环境中，可通过持久化卷（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 可完全禁用Hugging Face Hub的网络请求。通过端口转发访问服务：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!" }
    ]
  }'

开启思维模式的模型会返回 <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"

增加 shmSize: "32Gi" 以支持 mm_processor_cache。设置 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生产级堆栈是开箱即用的Kubernetes层，内置路由与可观测性能力。
• 离线环境下，通过PVC挂载模型并设置 HF_HUB_OFFLINE=1 实现无网部署。
• 工具调用必须启用 --enable-auto-tool-choice 并指定模型专用解析器。
• 多模态模型需定制镜像 + shmSize: 32Gi + tensorParallelSize: 1。
• CPU推理模式下，务必设置 VLLM_CPU_KVCACHE_SPACE 并预留缓冲内存。

— Editorial Team