使用 Helm 部署#
NIM 旨在搭载 NVIDIA GPU 的系统上运行,GPU 的类型和数量取决于模型。要使用 helm,您必须拥有一个配置了适当 GPU 节点的 Kubernetes 集群,并安装 GPU Operator。
先决条件#
如果您尚未设置 NGC API 密钥,并且不清楚要下载和部署哪个 NIM,请参阅入门指南中的信息。
一旦您设置了您的 NGC API 密钥,请转到 NGC Catalog 并选择 nim-llm helm chart 以选择版本。在大多数情况下,您应选择最新版本。
使用以下命令下载 helm chart
helm fetch https://helm.ngc.nvidia.com/nim/charts/nim-llm-<version_number>.tgz" --username=\$oauthtoken --password=$NGC_API_KEY
这会将 chart 作为文件下载到您的本地计算机。
配置 helm#
以下 helm 选项是配置以使用 Kubernetes 部署 NIM 最重要的选项
image.repository
– 要部署的容器/NIMimage.tag
– 该容器/NIM 的版本存储选项,基于所用环境和集群
model.ngcAPISecret
和imagePullSecrets
用于与 NGC 通信resources
– 当模型需要的 GPU 超过默认的一个时,请使用此选项。请参阅支持的模型,了解有关请求满足可用硬件上模型 GPU 内存需求的 GPU 的详细信息。env
– 这是一个呈现给容器的环境变量数组,如果需要高级配置注意:请勿使用
env
值设置以下环境变量。请改用指示的 helm 选项环境变量
Helm 值
NIM_CACHE_PATH
model.nimCache
NGC_API_KEY
model.ngcAPISecret
NIM_SERVER_PORT
model.openaiPort
NIM_JSONL_LOGGING
model.jsonLogging
NIM_LOG_LEVEL
model.logLevel
在这些情况下,请直接设置 helm 值,而不是依赖环境变量值。您可以将其他环境变量添加到 values 文件的
env
部分。
要使 chart 的部署行为适应您集群的需求,请参阅 helm chart 的 README,其中列出并描述了配置选项。此 README 在 helm 命令行中可用,但输出是纯 markdown。将其输出到文件并使用 markdown 渲染器打开,或使用命令行工具(例如 glow)在终端中渲染。
以下 helm 命令显示 chart README 并使用 glow
在终端中渲染它
helm show readme nim-llm-<version_number>.tgz | glow -p -
要检查所有默认值,请运行以下命令
helm show values nim-llm-<version_number>.tgz
最小示例#
此示例要求您在继续操作之前,已在部署命名空间中建立某些 Kubernetes secret。本文档的其余部分将假定为默认命名空间。
要下载 NIM 容器镜像,您必须设置镜像拉取 secret,在以下示例中为 ngc-secret
。要从 NGC 下载模型引擎或权重,chart 需要一个通用 secret,其中包含一个 NGC API 密钥,该密钥作为值存储在名为 NGC_API_KEY
的键中。以下示例创建了这两个值
kubectl create secret docker-registry ngc-secret --docker-server=nvcr.io --docker-username='$oauthtoken' --docker-password=$NGC_API_KEY
kubectl create secret generic ngc-api --from-literal=NGC_API_KEY=$NGC_API_KEY
创建文件 *custom-values.yaml*,其中包含以下条目。在创建上述 secret 后,这些值将在大多数集群中起作用。
image:
repository: "nvcr.io/nim/meta/llama3-8b-instruct" # container location
tag: 1.0.3 # NIM version you want to deploy
model:
ngcAPISecret: ngc-api # name of a secret in the cluster that includes a key named NGC_API_KEY and is an NGC API key
persistence:
enabled: true
imagePullSecrets:
- name: ngc-secret # name of a secret used to pull nvcr.io images, see http://kubernetes.ac.cn/docs/tasks/configure-pod-container/pull-image-private-registry/
您可以调整之前的配置来部署任何模型,例如 llama3-70b-instruct
,方法是根据模型的需要和大小进行调整。例如
image:
repository: "nvcr.io/nim/meta/llama3-70b-instruct" # container location -- changed for the different model
tag: 1.0.3
model:
ngcAPISecret: ngc-api
persistence:
enabled: true
size: 220Gi # the model files will be quite large
resources:
limits:
nvidia.com/gpu: 4 # much more GPU memory is required
imagePullSecrets:
- name: ngc-secret
请参阅支持的模型部分,以确定您的硬件是否足以运行此 NIM。
存储#
设置 NIM 时,存储空间不足始终是一个令人担忧的问题,下载模型可能会延迟集群中的扩展。模型可能非常大,集群操作员在下载模型时可能会快速填满磁盘空间。请务必在您的 pod 上为模型缓存挂载某种类型的持久存储。当在默认的 emptyDir
之外存储对象时,您有以下互斥选项
持久卷声明 (使用
persistence.enabled
启用)当
persistence.accessMode
设置为 “ReadWriteMany” 时使用,其中多个 pod 可以共享一个 PVC。如果
statefulSet.enabled
设置为false
(默认为true
),这将创建一个带有部署的 PVC,但如果访问模式不是ReadWriteMany
,例如使用 NFS provisioner,则扩展到多个 pod 可能会失败。
持久卷声明模板(使用
persistence.enabled
启用,并保持statefulSet.enabled
为默认值)适用于使用扩展 StatefulSet 的策略进行扩展,以将模型下载到为最大所需副本数创建的每个 PVC,然后再次缩减,将这些 PVC 保留在原位以允许快速扩展。
直接 NFS(使用
nfs.enabled
启用)Kubernetes 不允许在直接 NFS 上设置挂载选项,因此可能需要一些特殊的集群设置。
hostPath(使用
hostPath.enabled
启用)了解使用 hostPath 的安全隐患,并了解这也会将 pod 绑定到一个节点。
多节点模型#
注意
需要 NIM 版本 1.1.0+ 和 helm chart 版本 1.1.2+。此外,NIM 1.3+ 的多节点部署*需要* helm chart 1.3,而早于 1.3 的多节点 NIM 版本需要 helm chart 版本 1.1.2。
在 Kubernetes 上部署多节点 NIM 有两个选项:LeaderWorkerSets 和使用 MPI Operator 的 MPI 作业。
LeaderWorkerSet#
注意
需要 Kubernetes 版本 >1.26
LeaderWorkerSet (LWS) 部署是使用 NIM 部署多节点模型的推荐方法。要启用 LWS 部署,请参阅 LWS 文档中的安装说明。helm chart 默认对多节点部署使用 LWS。
使用 LWS 部署时,您将看到 Leader
和 Worker
pod 协同工作以运行您的多节点模型。
LWS 部署支持手动扩展和自动扩展,其中整组 pod 被视为单个副本。但是,在使用 LWS 部署时,扩展存在一些限制。如果手动扩展(未启用 autoscaling
),则无法扩展到高于 helm chart 中设置的初始副本数。
使用以下示例 values 文件,使用此方法部署 Llama 3.1 405B 模型。请参阅支持的模型部分,以确定您的硬件是否足以运行此模型。
image:
# Adjust to the actual location of the image and version you want
repository: nvcr.io/nim/meta/llama-3.1-405b-instruct
tag: 1.0.3
imagePullSecrets:
- name: ngc-secret
model:
name: meta/llama-3_1-405b-instruct
ngcAPISecret: ngc-api
# NVIDIA recommends using an NFS-style read-write-many storage class.
# All nodes will need to mount the storage. In this example, we assume a storage class exists name "nfs".
persistence:
enabled: true
size: 1000Gi
accessMode: ReadWriteMany
storageClass: nfs
annotations:
helm.sh/resource-policy: "keep"
# This should match `multiNode.gpusPerNode`
resources:
limits:
nvidia.com/gpu: 8
multiNode:
enabled: true
workers: 2
gpusPerNode: 8
# Downloading the model will take quite a long time. Give it as much time as ends up being needed.
startupProbe:
failureThreshold: 1500
MPI 作业#
使用 MPI Operator 的 MPI 作业是集群不支持 LeaderWorkerSet(Kubernetes 版本低于 v1.27)的替代部署选项。要启用 MPI 作业,请安装 MPI operator。这是一个 custom-values.yaml
文件示例,用于禁用 LeaderWorkerSets
并启动 MPI 作业
image:
# Adjust to the actual location of the image and version you want
repository: nvcr.io/nim/meta/llama-3.1-405b-instruct
tag: 1.0.3
imagePullSecrets:
- name: ngc-secret
model:
name: meta/llama-3_1-405b-instruct
ngcAPISecret: ngc-api
# NVIDIA recommends using an NFS-style read-write-many storage class.
# All nodes will need to mount the storage. In this example, we assume a storage class exists name "nfs".
persistence:
enabled: true
size: 1000Gi
accessMode: ReadWriteMany
storageClass: nfs
annotations:
helm.sh/resource-policy: "keep"
# This should match `multiNode.gpusPerNode`
resources:
limits:
nvidia.com/gpu: 8
multiNode:
enabled: true
leaderWorkerSet:
enabled: False
workers: 2
gpusPerNode: 8
# Downloading the model will take quite a long time. Give it as much time as ends up being needed.
startupProbe:
failureThreshold: 1500
对于 MPI 作业,您将看到为您的模型部署的 launcher
pod 和一个或多个 worker
pod。launcher
pod 不需要任何 GPU,部署日志将通过 launcher
pod 提供。
使用 MPI 作业进行部署时,您可以设置副本数,但是,如果不重新部署 helm chart,则不支持动态扩展。MPI 作业也不会自动重启,因此如果多节点集中的任何 pod 失败,则必须手动卸载并重新安装该作业才能重新启动。
启用 Open Telemetry 跟踪和指标#
env:
- name: NIM_ENABLE_OTEL
value: "1"
- name: NIM_OTEL_SERVICE_NAME
value: <name of the service>
- name: NIM_OTEL_TRACES_EXPORTER
value: otlp
- name: NIM_OTEL_METRICS_EXPORTER
value: otlp
- name: HOST_IP
valueFrom:
fieldRef:
fieldPath: status.hostIP
- name: NIM_OTEL_EXPORTER_OTLP_ENDPOINT
value: "http://$(HOST_IP):4318"
NVIDIA 建议在 Kubernetes 中安装 OpenTelemetry 收集器期间,您在自定义 values.yaml
文件中设置这些环境变量,以通过 OpenTelemetry 启用跟踪和指标收集。此版本要求您配置收集器以使用主机端口运行,并将其作为 DaemonSet 安装。如果您在安装收集器时使用不同的配置,请将 NIM_OTEL_EXPORTER_OTLP_ENDPOINT 变量设置为正确的摄取 URL。
有关环境变量的详细说明,请参阅环境变量。
在 Kubernetes 中启动 NIM#
您现在可以启动 chart 了。
helm install my-nim nim-llm-<version_number>.tgz -f path/to/your/custom-values.yaml
等待 pod 达到 “Ready” 状态。
运行推理#
在前面的示例中,OpenAI 兼容 API 端点通过默认类型的 Kubernetes 服务在端口 8000 上公开,没有入口,因为身份验证不是由 NIM 本身处理的。以下命令假定已部署 Llama 3 8B Instruct 模型。调整请求 JSON 正文中的 “model” 值以使用不同的模型。
使用以下命令将服务端口转发到本地计算机以测试推理。
kubectl port-forward service/my-nim-nim-llm 8000:http-openai
然后尝试一个请求
curl -X 'POST' \
'http://127.0.0.1:8000/v1/chat/completions' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"content": "You are a polite and respectful chatbot helping people plan a vacation.",
"role": "system"
},
{
"content": "What should I do for a 4 day vacation in Spain?",
"role": "user"
}
],
"model": "meta/llama3-8b-instruct",
"max_tokens": 16,
"top_p": 1,
"n": 1,
"stream": false,
"stop": "\n",
"frequency_penalty": 0.0
}'
故障排除 FAQ#
问:如果我的 pod 卡在 “Pending” 状态怎么办?答:尝试运行 kubectl describe pod <pod name>
,并检查 Events
部分以查看调度程序正在等待什么。节点污点可能需要容忍,GPU 不足以及存储挂载问题都是常见原因。
问:我尝试使用 statefulset.enabled: false
和 persistence.enabled: true
扩展或升级部署。为什么 pod 永远无法启动?答:要在不使用 StatefulSet
PVC 模板的情况下进行扩展或升级(这在时间和存储方面效率都不高),您必须使用 ReadWriteMany
存储类,以便可以将其挂载在不同的节点上,手动克隆 ReadOnlyMany
卷或类似直接 NFS 存储的东西。在没有持久性的情况下,每个启动的 pod 都必须将其模型下载到 emptyDir
卷。NFS PVC provisioner 或 CephFS provisioner 等 ReadWriteMany
存储类是理想的选择。
问:最后一条日志消息之一是关于 “Preparing model workspace. This step might download additional files to run the model.”。为什么在此期间失败了?答:可能是模型权重尚未完成下载,但 Kubernetes 达到了启动探测的故障阈值。尝试增加 startupProbe.failureThreshold
。对于大型模型或非常慢的网络连接,尤其如此。
附加信息#
helm chart 的内部 README 包括以下参数。NVIDIA 建议您使用下载的 README 中的 chart 版本,因为它具有该 chart 版本的最新和最正确的这些参数版本。
参数#
部署参数#
名称 |
描述 |
值 |
---|---|---|
|
[默认值: {}] 部署的亲和性设置。 |
|
|
设置容器的特权和访问控制设置(仅影响主容器,不影响 pod 级别)。 |
|
|
使用此处列出的数组覆盖发送到 NIM 的命令行选项。 |
|
|
使用此处列出的数组覆盖 NIM 容器的命令行参数。 |
|
|
将任意环境变量添加到主容器。 |
|
|
将任意额外的卷添加到部署集定义。 |
|
|
从 |
|
|
指定要部署的 NIM-LLM 镜像。 |
|
|
指定镜像标签或版本。 |
|
|
设置镜像拉取策略。 |
|
|
指定主容器和任何 init 容器所需的 secret 名称列表。 |
|
|
指定模型 init 容器(如果需要)。 |
|
|
仅限旧版容器。实例化和配置 NGC init 容器。它应预装 NGC CLI 或预装 |
|
|
完全指定您的用例所需的任何其他 init 容器。 |
|
|
指定健康检查端口。– 仅用于 |
|
|
为 NIM 设置节点选择器 – 例如 |
|
|
在主部署 pod 上设置其他注释。 |
|
|
指定 pod 的安全上下文设置。 |
|
|
指定 pod 的用户 UID。 |
|
|
指定 pod 的组 ID。 |
|
|
指定文件系统所有者组 ID。 |
|
|
指定部署的静态副本计数。 |
|
|
为正在运行的服务指定资源限制和请求。 |
|
|
指定要呈现给正在运行的服务的 GPU 数量。 |
|
|
指定是否应创建服务帐户。 |
|
|
设置要添加到服务帐户的注释。 |
|
|
指定要使用的服务帐户的名称。如果未设置且 create 为 |
|
|
启用 |
|
|
指定 pod 分配的容忍度。允许调度程序调度具有匹配污点的 pod。 |
自动扩展参数#
用于创建 Horizontal Pod Autoscaler
的值。如果未启用自动扩展,则其余参数将被忽略。NVIDIA 建议使用自定义指标 API,通常使用 prometheus-adapter 实现。CPU 和内存的标准指标在扩展 NIM 中的用途有限。
名称 |
描述 |
值 |
---|---|---|
|
启用水平 pod 自动扩展器。 |
|
|
指定自动扩展的最小副本数。 |
|
|
指定自动扩展的最大副本数。 |
|
|
自动扩展的指标数组。 |
|
Ingress 参数#
名称 |
描述 |
值 |
---|---|---|
|
启用 ingress。 |
|
|
指定 Ingress 的类名。 |
|
|
指定 ingress 的其他注释。 |
|
|
指定主机列表,每个主机列表都包含路径列表。 |
|
|
指定主机名。 |
|
|
指定 ingress 路径。 |
|
|
指定路径类型。 |
|
|
指定服务类型。它可以是 |
|
|
指定 TLS |
|
探测参数#
名称 |
描述 |
值 |
---|---|---|
|
启用 `livenessProbe`。 |
|
|
|
|
|
`LivenessProbe` 要使用的脚本命令(目前不支持)。 |
|
|
`LivenessProbe` 端点路径。 |
|
|
`livenessProbe` 的初始延迟秒数。 |
|
|
`livenessProbe` 的超时秒数。 |
|
|
`livenessProbe` 的周期秒数。 |
|
|
`livenessProbe` 的成功阈值。 |
|
|
`livenessProbe` 的失败阈值。 |
|
|
启用 |
|
|
就绪端点路径。 |
|
|
`readinessProbe` 的初始延迟秒数。 |
|
|
`readinessProbe` 的超时秒数。 |
|
|
`readinessProbe` 的周期秒数。 |
|
|
`readinessProbe` 的成功阈值。 |
|
|
`readinessProbe` 的失败阈值。 |
|
|
启用 |
|
|
|
|
|
`startupProbe` 的初始延迟秒数。 |
|
|
`startupProbe` 的超时秒数。 |
|
|
`startupProbe` 的周期秒数。 |
|
|
`startupProbe` 的成功阈值。 |
|
|
`startupProbe` 的失败阈值。 |
|
指标参数#
名称 |
描述 |
值 |
---|---|---|
|
在端口 8002 上打开 triton 推理服务器的指标端口。 |
|
|
启用指标端点 – 仅用于 |
|
|
用于 |
|
|
启用 |
|
|
为 ServiceMonitor 指定其他标签。 |
|
模型参数#
名称 |
描述 |
值 |
---|---|---|
|
挂载可写存储或为 NIM 预填充模型缓存的路径。 |
|
|
指定 API 中模型的名称(通常是 NIM 的名称)。这主要用于 helm 测试,通常在其他情况下是可选的。这必须与来自 * /v1/models* 的名称匹配,以允许 |
|
|
预先存在的 secret 的名称,该 secret 具有名为 |
|
|
NGC API 密钥文字,设置为 API secret 和镜像拉取 secret 时使用。 |
|
|
指定 Open AI API 端口。 |
|
|
指定要添加到已部署 pod 的额外标签。 |
|
|
打开或关闭 JSON 行日志记录。默认为 true。 |
|
|
NIM 服务的日志级别。变量的可能值包括 TRACE、DEBUG、INFO、WARNING、ERROR、CRITICAL。 |
|
已弃用和旧版模型参数#
名称 |
描述 |
值 |
---|---|---|
|
设置为 |
|
|
(已弃用)指定模型的 GPU 要求。 |
|
|
(已弃用)指定模型卷中要挂载的路径(如果不是根目录)– 默认值适用于 |
|
|
(已弃用)指定解压缩模型的location。 |
|
存储参数#
名称 |
描述 |
值 |
---|---|---|
|
如果启用了 |
|
|
启用持久卷的使用。 |
|
|
指定现有的持久卷声明。如果使用 |
|
|
指定持久卷存储类。如果设置为 |
|
|
指定 |
|
|
指定删除时的持久卷声明保留策略。仅与 Stateful Set 卷模板一起使用。 |
|
|
指定缩放时的持久卷声明保留策略。仅与 Stateful Set 卷模板一起使用。 |
|
|
指定持久卷声明的大小(例如 40Gi)。 |
|
|
向持久卷声明添加注释。 |
|
|
使用 |
|
|
启用 |
|
|
指定节点上用作 |
|
|
将模型缓存配置为位于共享的直接挂载 NFS 上。注意:您无法使用直接 NFS 挂载为 pod 设置挂载选项,而无需节点安装 nfsmount.conf。在大多数情况下,基于 NFS 的 |
|
|
启用直接 pod NFS 挂载。 |
|
|
指定 NFS 服务器上要挂载的路径。 |
|
|
指定 NFS 服务器地址。 |
|
|
设置为 true 以作为只读挂载。 |
|
服务参数#
名称 |
描述 |
值 |
---|---|---|
|
指定部署的服务类型。 |
|
|
覆盖默认服务名称 |
|
|
指定服务的 Open AI 端口。 |
|
|
指定要添加到服务的其他注释。 |
|
|
指定要添加到服务的其他标签。 |
|
多节点参数#
目前,必须跨多个节点的大型模型在仅使用 GPU Operator 的普通 Kubernetes 上无法工作。当自动或通过环境变量选择优化的 TensorRT 配置文件时,需要安装 LeaderWorkerSets 或 [MPI Operator]](https://github.com/kubeflow/mpi-operator) 的 MPIJobs
。由于 MPIJob
是一种批处理类型资源,其设计并未考虑服务稳定性和可靠性,因此如果您的集群版本允许,则应使用 LeaderWorkerSets。目前,多节点部署仅支持优化的配置文件。
名称 |
描述 |
值 |
---|---|---|
|
启用多节点部署。 |
|
|
设置等待工作节点启动的秒数,超过此时间将失败。 |
|
|
将呈现给每个 pod 的 GPU 数量。在大多数情况下,这应该与 |
|
|
指定每个多节点副本要启动多少个 worker pod。 |
|
|
NVIDIA 建议您使用 |
|
|
为 MPI 设置 SSH 私钥以使用现有的 secret。否则,Helm chart 在安装期间随机生成一个密钥。 |
|
|
注解仅应用于 |
|
|
资源部分仅应用于 |
|
|
启用优化的多节点部署(目前是唯一支持的选项)。 |
|