大模型Helm Chart配置：从零部署到参数调优

大模型Helm Chart配置的核心目标，是把模型服务所需的镜像、资源、存储和网络参数统一写进一个可复用的Chart里，用helm install一条命令完成部署。
本文按零基础用户能照做的顺序，讲清准备条件、关键配置项修改、安装验证和常见报错处理。

先确认集群和工具是否就绪

开始前需要有一个可用的Kubernetes集群，并且本机已安装kubectl和helm。
执行下面两条命令确认版本和集群连通性：

helm version --short
kubectl get nodes

如果kubectl get nodes能列出节点且状态为Ready，说明集群正常。
Helm建议使用v3版本，避免v2的Tiller兼容问题。

大模型服务通常需要GPU节点。
如果集群里有GPU机器，先确认节点资源可被调度：

kubectl describe node  | grep -i nvidia

输出中能看到nvidia.com/gpu资源，才说明GPU插件已生效。
没有GPU时也可以先用CPU跑小参数模型做流程验证。

获取Chart并理解目录结构

从模型服务方提供的仓库或内部制品库拉取Chart。
常见命令如下：

helm repo add llm-charts https://<你的chart仓库地址>
helm repo update
helm search repo llm-charts

把Chart下载到本地便于修改：

helm pull llm-charts/ --untar
cd 

目录里重点看两个文件：values.yaml存放默认配置，templates/下是Kubernetes资源模板。不要直接改templates/里的模板，
优先通过values.yaml覆盖参数，
方便后续升级和回滚。

可以先导出默认值作为参考：

helm show values llm-charts/ > default-values.yaml

修改关键配置项

大模型Helm Chart配置中最容易出问题的几类参数是镜像、资源限制、模型存储和端口。
下面给出一份最小可用的my-values.yaml示例，按你的实际环境替换占位内容：

image:
  repository: <模型服务镜像地址>
  tag: "<镜像标签>"
  pullPolicy: IfNotPresent

resources:
  limits:
    nvidia.com/gpu: 1
    memory: "32Gi"
  requests:
    memory: "16Gi"

persistence:
  enabled: true
  size: "100Gi"
  storageClass: "<你的StorageClass名>"

service:
  type: ClusterIP
  port: 8000

model:
  name: "<模型名称或路径>"

几个配置项的说明：

• image.repository和tag必须和实际镜像一致，标签写错会报ImagePullBackOff。
• resources.limits里的nvidia.com/gpu数量不能超过节点实际GPU数，否则Pod会一直Pending。
• 模型文件较大时开启persistence，避免每次重启重新下载。storageClass要填集群里真实存在的名称，可用kubectl get storageclass查看。
• service.port是容器内服务端口，后续做端口转发或Ingress都基于它。

如果模型需要从对象存储或Hugging Face拉取，
在values.yaml里找到对应的下载配置段，
填入访问密钥或镜像源地址。密钥不要明文提交到代码仓库，
建议用Kubernetes Secret挂载。

安装并验证部署结果

用自定义values文件安装，指定命名空间：

kubectl create namespace llm
helm install my-llm ./ -n llm -f my-values.yaml

安装后先看Pod状态：

kubectl get pods -n llm -w

等到Pod状态变为Running且READY列为1/1。
如果长时间Pending，用kubectl describe pod -n llm查看事件，常见原因是资源不足或存储类不存在。

接着验证服务端口是否可访问：

kubectl port-forward -n llm svc/ 8000:8000

另开终端请求健康检查接口（路径以实际镜像为准）：

curl http://127.0.0.1:8000/health

返回正常状态码和内容，说明大模型Helm Chart配置的基础部署已跑通。

常见报错与避坑提醒

• ImagePullBackOff：先确认镜像地址和标签正确，再检查集群是否能访问镜像仓库。私有仓库需要配置imagePullSecrets。
• Pod一直Pending：多半是GPU或内存请求超过节点可分配量。调低requests或增加节点，不要盲目调高limits。
• 模型加载失败：检查存储卷是否挂载成功、模型路径是否和model.name一致。用kubectl logs -n llm看启动日志。
• 升级后配置未生效：Helm升级需要带-f my-values.yaml，否则会回退到默认值。升级命令为helm upgrade my-llm ./ -n llm -f my-values.yaml。

修改values.yaml后建议先用helm template渲染检查，避免把YAML缩进错误带进集群：

helm template my-llm ./ -f my-values.yaml > rendered.yaml

确认rendered.yaml内容符合预期后再执行安装或升级。

关于资源限制和副本数

大模型服务对显存敏感，resources.requests设置过低可能导致调度到显存不足的节点，设置过高又浪费资源。
建议先按单副本、单GPU跑通，再根据实际显存占用调整。
副本数增加前确认模型是否支持多实例并行，以及存储卷是否支持多Pod同时读写。

如果使用Ingress对外暴露服务，
把service.type保持为ClusterIP，
在Ingress里指向对应Service即可，
不要直接把Service改成LoadBalancer增加不必要的云负载均衡费用。

整套流程跑完后，建议把my-values.yaml纳入版本管理，并在文件头部注释清楚适用集群和镜像版本。
后续换环境时只需替换存储类和镜像地址，大模型Helm Chart配置本身可以复用。