在 Kubernetes 上构建经过验证的 NVIDIA Dynamo 运行时

构建 AI 应用的团队需要一条可重复的路径，从模型配置到可用的推理端点。NVIDIA Dynamo 是一个分布式推理框架，可协调跨 GPU 工作节点的模型服务。将其部署在 Kubernetes 上只是第一步。成功的模型部署需要更多：GPU 驱动、资源分配、调度、网络和监控必须协同工作。解决这些依赖关系会占用测试模型行为、服务性能和应用程序集成的时间。

NVIDIA DSX AI Factory Platform 汇集了多种技术，帮助生态系统设计、构建和运营更高效的 AI 工厂，Dynamo 就是其中之一。为了更轻松地管理这些基础设施依赖关系，该平台包含 NVIDIA AI Cluster Runtime (AICR)。它将 NVIDIA Dynamo 及其支持基础设施打包成经过验证的配方。每个配方为特定环境和工作负载定义配置，包括固定组件版本、兼容性约束和验证检查。AICR 为平台团队提供了一种可重复的方式来部署和检查运行时，为开发人员提供一致的基础来服务模型和测试应用程序。

本演练涵盖在 Kubernetes 上支持 Dynamo 的基础设施，比较两种路由选项，并展示如何使用 AICR 部署和验证运行时。

为什么底层运行时对 Dynamo 很重要

在 Kubernetes 上运行 Dynamo 模型始于一个 DynamoGraphDeployment，它指定了 vLLM、SGLang 或 NVIDIA TensorRT LLM 应如何在集群的 Pod 中运行。但图只是堆栈的顶层。生产推理集群还需要其下方的运行时层。它必须回答如下问题：

• NVIDIA GPU Operator 是否安装了与节点匹配的驱动栈？
• GPU 节点是否已标记且可被发现？
• 集群是否通过预期的动态资源分配 (DRA) 驱动暴露 GPU？
• 调度器能否以所需的拓扑和组调度语义放置 GPU 工作节点？
• 在工作负载落到降级节点之前，节点健康信号是否可用？
• Prometheus 是否可访问以获取 Dynamo 和加速器指标？
• 当部署应在入口处采用 Kubernetes 原生方式时，Gateway API / Endpoint Picker (EPP) 路径是否已配置？

AICR 在配方中捕获了这些运行时要求。

AICR 为 Dynamo 提供了什么

AICR Dynamo 配方同时打包了 Dynamo 及其依赖的集群运行时组件。

AICR 提供了 dynamo-platform chart 的 1.4.2 版本，其中包括 Dynamo operator、Dynamo 运行时镜像以及 nvidia.com/v1beta1 DynamoGraphDeployment CustomResourceDefinition (CRD) 等资源。v1beta1 取代了之前的 v1alpha1 API 版本。

表 1 列出了配方中包含的支持基础设施组件。

表 1. Dynamo 下方的运行时先决条件以及 AICR 配方为每个先决条件安装的组件

此外，配方固定组件版本并记录配置值、节点选择器、容忍度、校验和以及验证预期，以使部署可重复。

在 Dynamo 1.4 中，前端、工作节点、可选的 Gateway API Inference Extension (GAIE) / Endpoint Picker Plugin (EPP) 组件 以及其他 Dynamo 服务通过 Kubernetes 资源相互发现。因此，AICR 的默认路径不再使用 NATS，dynamo-platform chart 也不再默认安装它。NATS 仍可作为需要它的部署的可选组件。

代理工作负载会反复扩展长令牌前缀，包括系统提示、工具定义、对话历史和工具结果。如果某一轮到达工作节点时 GPU 内存中没有该前缀，系统会重新处理中间令牌，而不是重用缓存结果。Dynamo 将请求路由到已持有相关 KV 块的工作节点，这可以通过其前端路由器或通过 Gateway API 层的 GAIE/EPP 集成实现。

Dynamo 还可以将提示处理（预填充）与令牌生成（解码）分离，这种架构称为分离式服务。在 KV 缓存未命中时，全部或部分提示必须由预填充池重新处理。然后解码工作节点接管逐令牌生成，这具有不同的 GPU、内存、延迟和批处理特性。缓存未命中率取决于工作负载。长时间运行的代理会话与一次性聊天请求的行为不同。分离式服务使操作员能够针对给定的请求组合独立扩展和调整预填充和解码容量。

请求平面和 KV 缓存事件平面是分开的。在 Dynamo 1.4.2 中，默认的 AICR Kubernetes 路径使用 TCP 处理请求，使用 ZMQ 处理 KV 缓存事件。每个 vLLM 工作引擎通过本地 ZMQ 发布者发出原始 KV 缓存事件，例如，使用以下 vLLM 配置：

--enable-prefix-caching --kv-transfer-config \
  {"enable_kv_cache_events": true, "publisher": "zmq", "endpoint": "tcp://*:5557"}

随后，Dynamo 的工作节点运行时订阅该本地 vLLM 事件源，对事件进行规范化，并将它们重新发布到 Dynamo 事件平面。原生 Dynamo Frontend 路由器和 GAIE/EPP 路径都使用这一由 Dynamo 管理的 KV 缓存状态来做出路由决策。

Kubernetes 上的 Dynamo 路由路径有哪些？

Dynamo 在 Kubernetes 上支持两条路由路径。第一条使用 Dynamo Frontend 路由器进行工作节点选择。第二条使用 Kubernetes Gateway API 实现进行入口处理，并使用 Dynamo EPP 进行端点选择。AICR 为任一拓扑交付并验证 Dynamo 运行时。

路径 1：Dynamo Frontend 路由器

默认路径在 Kubernetes Service 后面暴露一个 Dynamo Frontend。以 DYN_ROUTER_MODE=kv 运行时，Frontend 会对每个请求进行分词，使用前缀重叠和当前负载对符合条件的工作节点进行评分，选择一个工作节点，并通过 Dynamo 请求平面（默认使用 TCP）分发该请求。

当应用团队拥有特定于模型的端点，或现有边缘代理只需将流量转发到 Dynamo Frontend Service 时，此路径适用。它是部署和验证 Dynamo 图的最小拓扑，也是经过最多生产验证的服务选项。它不需要路径 2 中使用的额外网关和 EPP 组件。

路径 2：Gateway API Inference Extension 与 Dynamo EPP

此路径将 Dynamo 与 Gateway API 和 Gateway API Inference Extension（GAIE）集成。在 AICR 示例中，agentgateway 将 HTTPRoute 解析为 InferencePool。Dynamo operator 从 DynamoGraphDeployment 创建该 InferencePool：其选择器标识符合条件的工作节点 Pod，而其 endpointPickerRef 标识 Dynamo EPP Service。

网关通过 GAIE 的端点选择接口调用 Dynamo EPP。EPP 对请求进行分词，并使用 Dynamo 的 KV 路由器选择一个端点。它将选择结果和路由元数据返回给网关实现，后者是实际的 HTTP 代理。在此模式下，每个可路由的工作节点 Pod 都包含一个 Dynamo Frontend sidecar，它从网关接收请求并将其转发到本地工作节点容器。Frontend 以 --router-mode direct 运行，因此它应用 EPP 的选择而不会重新路由。

当平台团队管理共享的 Kubernetes 入口，并需要通过 Gateway API 机制配置模型端点工作节点选择、超时、重试和回退时，此路径适用。请注意，两种路由方法都可以在 Gateway API HTTPRoute 后面工作。区别在于哪个组件管理到工作节点的传输：Dynamo Frontend 还是 Gateway 本身。

注意：本文介绍 Dynamo 由 operator 管理的 DynamoGraphDeployment 与 GAIE 的集成；实验性的独立原生 vLLM 接入 是单独的集成。在 Dynamo 1.4 中，此路径使用 GAIE 的 Go EPP 框架，并通过 CGO 嵌入 Dynamo 的 Rust KV 路由器，通过 eppConfig 进行配置。

展望：从 Dynamo 1.5 开始，原生 Rust EPP 将取代 Go/CGO 桥接。它直接实现 GAIE 的轻量级端点选择器（ext_proc）接口，在进程内运行完整的 Dynamo 路由器，并使用 DYN_* 环境变量替代 eppConfig 插件和调度配置文件。聚合和分离路由直接通过 Dynamo 发现机制注册的工作节点角色来处理。周围的 Kubernetes 拓扑保持不变。移除 Go 插件框架和 CGO 边界还减少了每请求的 EPP 开销。

客户端请求通过网关（例如 agentgateway）进入，并匹配由 InferencePool 支持的 HTTPRoute 。Gateway 调用 Dynamo EPP，后者仅执行令牌感知的 KV 选择，并返回所选端点和路由元数据。然后 Gateway 在直接模式下将请求转发到所选工作节点的 Frontend sidecar，后者通过 Dynamo 请求平面将其发送到 vLLM 工作节点。工作节点 KV 缓存状态通过 Dynamo 事件平面到达 EPP，同时 Dynamo operator 从 DynamoGraphDeployment 创建 EPP 和 InferencePool 。

选择路径

路由路径取决于应由 Gateway 还是 Dynamo Frontend 处理向工作节点转发请求，包括超时、重试和回退管理。表 2 比较了 Dynamo Frontend 和 Gateway API/EPP 路径。

表 2. Dynamo 路由器和 GAIE / EPP 路由路径的决策标准

两条路径都使用工作节点发布的 KV 缓存事件来进行精确的缓存感知放置。Dynamo 也可以配置为根据它发送每个请求的位置来预测 KV 缓存状态。预测无法感知驱逐，因此路由器的视图可能与每个工作节点实际持有的内容发生偏差，路由质量可能下降，尤其是在内存压力下。本文中的 AICR 配置启用了实时事件，因此两条路径都使用工作节点报告的 KV 缓存状态进行路由。

AICR 配方流程如何工作

AICR 将运行时设置与应用部署分离。首先，它捕获现有的 Kubernetes 集群并生成匹配的 Dynamo 配方。然后渲染、部署并验证运行时包，之后安装应用的 DynamoGraphDeployment 并测试其推理端点。

步骤 1：对集群进行快照

快照捕获 AICR 用于配方选择和验证的集群状态：

aicr snapshot \
  --namespace aicr-validation \
  --output snapshot.yaml

当未指定放置标志时，AICR 自动以标记为 nvidia.com/gpu.present=true 的节点为目标，并容忍 GPU 节点的污点。--node-selector 和 --toleration 标志在集群需要时提供更具体的放置。

步骤 2：生成 Dynamo 推理配方

AICR 使用快照来识别 Kubernetes 发行版、GPU 加速器和 GPU 节点操作系统。该命令指定工作负载意图和平台：

aicr recipe \
  --snapshot snapshot.yaml \
  --intent inference \
  --platform dynamo \
  --output recipe.yaml

生成的配方记录了固定的组件版本、环境特定配置、兼容性约束和验证检查。对于针对 NVIDIA GB200 NVL72 和 NVIDIA GB300 NVL72 系统的 Amazon EKS Dynamo 推理配方，AICR v1.0.0 选择以下 Helm chart 版本：

表 3. AICR v1.0.0 Amazon EKS Dynamo 推理配方的 Helm chart 版本

AICR 团队在指定的平台和硬件上一起测试了这些组件版本。以下验证步骤验证集群是否满足所选配方的要求。

可选的离线检查

配方选择已经使用了 snapshot.yaml 中的集群事实，因此根据同一快照验证生成的配方几乎没有额外作用。离线验证在针对不同的捕获集群快照测试配方而不联系 Kubernetes 时很有用。它评估声明性约束，而行为检查则报告为跳过。

aicr validate \
  --recipe recipe.yaml \
  --snapshot candidate-snapshot.yaml \
  --no-cluster \
  --output dry-run.json

步骤 3：渲染运行时包

AICR 将配方渲染为可部署的 Helm values 和清单：

aicr bundle \
  --recipe recipe.yaml \
  --accelerated-node-selector nodeGroup=gpu-worker \
  --accelerated-node-toleration dedicated=worker-workload:NoSchedule \
  --accelerated-node-toleration dedicated=worker-workload:NoExecute \
  --system-node-selector nodeGroup=system-worker \
  --system-node-toleration dedicated=system-workload:NoSchedule \
  --system-node-toleration dedicated=system-workload:NoExecute \
  --set-json agentgateway:allowedSourceRanges='["<your-cidr>"]' \
  --deployer helmfile \
  --output bundle

这些放置标志反映了本演练中使用的测试集群。对于具有不同标签和污点的集群，可以调整或省略这些标志。如果集群没有默认 StorageClass，该命令还需要 --storage-class。

步骤 4：部署运行时

对于没有集群内 GitOps 控制器的本地部署，Helmfile 提供了一种部署选项。在本地可用 Helm 和 helm-diff 插件 的情况下，以下命令在应用之前检查 AICR 生成的 release 图：

helmfile -f bundle/helmfile.yaml diff
helmfile -f bundle/helmfile.yaml apply

AICR 在生成的 Helmfile 包中编码了组件依赖关系。Helmfile 按顺序处理这些依赖层级，并并发应用同一层级内的独立组件。重新运行 apply 会将已安装的 Helm release 与生成的配置进行协调。

如果 Helmfile 不可用，可以使用 AICR 的默认 Helm 部署器重新生成包。其生成的 deploy.sh 脚本是用于交互式测试的轻量级后备方案：

aicr bundle \
  --recipe recipe.yaml \
  [... all the flags setting node selectors and tolerations ...] \
  --set-json agentgateway:allowedSourceRanges='["<your-cidr>"]' \
  --deployer helm \
  --output bundle-helm

chmod +x bundle-helm/deploy.sh
 ./bundle-helm/deploy.sh

对于生产环境，AICR 还使用 --deployer argocd、--deployer argocd-helm 和 --deployer flux 渲染 GitOps 包。

步骤 5：验证已安装的运行时

安装后，部署和一致性验证会在安装应用工作负载之前检查活动集群。由于此处未提供快照，AICR 在运行验证器 Job 之前捕获当前集群状态。

aicr validate \
  --recipe recipe.yaml \
  --node-selector nodeGroup=gpu-worker \
  --toleration dedicated=worker-workload:NoSchedule \
  --toleration dedicated=worker-workload:NoExecute \
  --phase deployment \
  --phase conformance \
  --output report.json

只有在这些检查通过后，才会安装应用 DynamoGraphDeployment。性能验证单独运行，因为它会部署一个临时服务工作负载并消耗被测 GPU。

AICR 验证检查什么？

AICR 根据所选配方中编码的检查和约束来验证已安装的运行时。检查因配方而异。对于 Dynamo 推理配方，部署和一致性验证通常涵盖以下内容：

表 4. AICR Dynamo 配方的部署和一致性检查

这些检查在部署应用之前验证已安装的运行时是否满足所选配方的要求。

AICR 将版本化的运行时配置与验证集群是否满足所选配方要求的检查相结合。

开始使用

NVIDIA AI Cluster Runtime (AICR) 和 NVIDIA Dynamo 是 NVIDIA DSX AI Factory Platform 的开源组件。在 Kubernetes 上部署 Dynamo 的团队可以使用 AICR 的配方和部署示例来配置、部署和验证支持其推理工作负载的基础设施。

• 更多项目和社区资源可通过 NVIDIA DSX AI Factory GitHub 获取。
• 讨论可在 NVIDIA DSX AI Factory Slack 社区中进行。NVIDIA DSX OS AI Inference and Contributor Workshop 在 KubeCon + CloudNativeCon North America 期间提供 AICR 的动手体验。需要注册，座位有限。
• KubeCon 上的 NVIDIA 展位 #170 提供 Kubernetes 深度探讨和现场演示。