vLLM Helm图表学习指南：零基础实战教程

2026-06-17阅读 0热度 0

资源管理

文件一览

本目录结构清晰，各文件职责明确。逐一解析： * **Chart.yaml**：记录Chart的元数据，包括名称、版本、维护者等核心信息。相当于每个Helm Chart的身份标识。 * **ct.yaml & lintconf.yaml**：分别用于Chart测试与YAML语法校验，保障开发流程的规范性与稳定性。 * **values.schema.json**：JSON Schema文件，对`values.yaml`中所有参数进行强制校验，确保配置符合预定义的规则，避免误填导致部署异常。 * **values.yaml**：核心配置入口，内置所有可自定义的默认值，例如镜像地址、副本数量、资源请求与限制等。 * **templates/_helpers.tpl**：辅助模板，封装了通用函数（如服务命名、端口定义等），便于在多个模板间复用逻辑。 * **templates/configmap.yaml & secrets.yaml**：分别管理非敏感配置和敏感信息，避免将环境变量与密钥硬编码至容器镜像中。 * **templates/custom-objects.yaml**：用于定义自定义Kubernetes资源对象，满足非标准需求。 * **templates/deployment.yaml**：最关键的部署模板，定义Deployment的完整规范，涵盖启动命令、资源约束、存活探针与就绪探针等。 * **templates/hpa.yaml**：水平Pod自动扩缩容模板，支持基于CPU或内存利用率动态调整Pod副本数。 * **templates/job.yaml**：一次性任务模板，例如在启动主容器前从S3同步模型权重文件。 * **templates/poddisruptionbudget.yaml**：Pod中断预算，保证节点维护或滚动更新期间应用仍保持最低可用Pod数量。 * **templates/pvc.yaml**：持久卷声明模板，为模型文件提供持久化存储。 * **templates/service.yaml**：Service模板，将vLLM Pod暴露给集群内部或外部服务。

实战示例：材料与配置

单纯文件名不足以理解细节，下面展示核心示例配置与文件内容，方便直接参考。

.helmignore

指定打包Chart时可忽略的文件，避免将无关开发文件包含进来。

*.png
.git/
ct.yaml
lintconf.yaml
values.schema.json
/workflows

Chart.yaml

元数据文件。本Chart名为`chart-vllm`，应用类型，初始版本`0.0.1`，维护者为`mfournioux`。

apiVersion: v2
name: chart-vllm
description: Chart vllm

# 图表类型：应用型
type: application

# 版本号，遵循语义化版本规范
version: 0.0.1

maintainers:
  - name: mfournioux

templates/_helpers.tpl

核心逻辑所在。例如，`chart.resources`函数利用`required`指令强制用户必须配置CPU和内存的请求与限制。特别值得注意的GPU检查逻辑：仅当`requests`和`limits`中`nvidia.com/gpu`均大于0时，才会在资源清单中添加GPU配置。这避免了无效GPU资源的错误申请。

{{/* 定义资源配额 */}}
{{- define "chart.resources" -}}
requests:
  memory: {{ required "Value 'resources.requests.memory' must be defined !" .Values.resources.requests.memory | quote }}
  cpu: {{ required "Value 'resources.requests.cpu' must be defined !" .Values.resources.requests.cpu | quote }}
  {{- if and (gt (int (index .Values.resources.requests "nvidia.com/gpu")) 0) (gt (int (index .Values.resources.limits "nvidia.com/gpu")) 0) }}
  nvidia.com/gpu: {{ required "Value 'resources.requests.nvidia.com/gpu' must be defined !" (index .Values.resources.requests "nvidia.com/gpu") | quote }}
  {{- end }}
limits:
  memory: {{ required "Value 'resources.limits.memory' must be defined !" .Values.resources.limits.memory | quote }}
  cpu: {{ required "Value 'resources.limits.cpu' must be defined !" .Values.resources.limits.cpu | quote }}
  {{- if and (gt (int (index .Values.resources.requests "nvidia.com/gpu")) 0) (gt (int (index .Values.resources.limits "nvidia.com/gpu")) 0) }}
  nvidia.com/gpu: {{ required "Value 'resources.limits.nvidia.com/gpu' must be defined !" (index .Values.resources.limits "nvidia.com/gpu") | quote }}
  {{- end }}
{{- end }}

templates/deployment.yaml: 核心部署逻辑

整套配置的核心。Deployment名称为`{{ .Release.Name }}-deployment-vllm`。通过`initContainers`执行模型下载任务：正式容器启动前，从S3兼容对象存储同步模型文件到共享PVC。正式容器运行`vllm serve`命令，加载`/data`目录下的模型。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: "{{ .Release.Name }}-deployment-vllm"
  ...
spec:
  ...
  template:
    ...
    spec:
      initContainers:
        - name: wait-download-model
          image: amazon/aws-cli:2.6.4
          command:
            - /bin/bash
          args:
            - -eucx
            - while aws --endpoint-url $S3_ENDPOINT_URL s3 sync --dryrun s3://$S3_BUCKET_NAME/$S3_PATH /data | grep -q download; do sleep 10; done
          ...
          volumeMounts:
            - name: {{ .Release.Name }}-storage
              mountPath: /data
      containers:
        - name: "vllm"
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          command:
            - vllm
            - serve
            - /data/
            - --served-model-name
            - opt-125m
            - --dtype
            - bfloat16
            - --host
            - "0.0.0.0"
            - --port
            - "8000"
          ...
          volumeMounts:
            - name: {{ .Release.Name }}-storage
              mountPath: /data
      volumes:
        - name: {{ .Release.Name }}-storage
          persistentVolumeClaim:
            claimName: {{ .Release.Name }}-storage-claim
      # 只有请求了GPU资源时，才设置NVIDIA运行时与节点亲和性
      {{- if and (gt (int (index .Values.resources.requests "nvidia.com/gpu")) 0) (gt (int (index .Values.resources.limits "nvidia.com/gpu")) 0) }}
      runtimeClassName: nvidia
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                - key: nvidia.com/gpu.product
                  operator: In
                  {{- with .Values.gpuModels }}
                  values:
                    {{- toYaml . | nindent 20 }}
                  {{- end }}
      {{- end }}

values.yaml: 你该关心哪些默认值

以下`values.yaml`中的参数需要根据实际环境调整： * **`image`**: 默认`vllm/vllm-openai:latest`，生产环境建议锁定具体版本标签。 * **`resources`**: 默认请求4个CPU、16Gi内存、1张NVIDIA GPU。若将`nvidia.com/gpu`设为0，Deployment将完全跳过GPU资源申请与NVIDIA运行时配置。 * **`extraInit`**: 若模型文件存放在S3兼容对象存储，需配置此段。`s3modelpath`指定模型路径，`pvcStorage`设置本地缓存盘大小。 * **`readinessProbe` & `livenessProbe`**: 健康检查采用标准`/health`路径，可根据模型启动耗时调整`initialDelaySeconds`与`periodSeconds`。 * **`autoscaling`**: HPA开关默认关闭，开启后可设置CPU使用率阈值动态扩缩。

values.schema.json: 规矩的“守护者”

JSON Schema文件对所有可配置项进行了严格约束。例如，`image`的`repository`、`tag`、`command`为必填；`resources`的`requests`、`limits`同样为必填。一旦遗漏必填项，Helm会立即报错，避免生成残缺Pod。对于追求“配置即规范”的团队，此文件价值显著。 **

总结一下

** 本Helm Chart是一份高度定制化、生产就绪的vLLM部署蓝图。它将模型下载、资源配置、健康检查、自动扩缩容、GPU调度等复杂操作统一管理。无论是快速跑通OPT-125M等小型模型，还是部署承载高并发请求的大模型服务，基于此Chart修改`values.yaml`都是可靠起点。