⚡

Dynamo故障排查Skill dynamo-troubleshoot

该技能用于诊断和排查NVIDIA Dynamo在Kubernetes上的部署故障。当Pods、模型缓存作业、PVC、工作节点、前端/路由器健康、端点或基准测试作业失败时，通过收集只读调试包、分类故障，并提供明确的下一步修复命令。关键词：Dynamo、Kubernetes、故障排查、LLM推理、部署诊断、Pod、PVC、DynamoGraphDeployment

大模型推理部署 0 次安装 1 次浏览 更新于 9/7/2026
名称 dynamo-troubleshoot
描述 诊断失败或不健康的 Dynamo 部署。当 Pod、模型缓存作业、PVC、工作节点、前端/路由器健康、端点或基准测试作业失败时使用；在正常启动之前，请先使用 recipe-runner/router-starter。
开源协议 Apache-2.0 metadata:
作者 Dan Gil dagil@nvidia.com tags: - dynamo - kubernetes - 故障排查 - day-2

Dynamo 故障排查

<!– SPDX-FileCopyrightText: Copyright © 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: CC-BY-4.0 –>

目的

将 Dynamo 故障转化为清晰的问题类别、最强信号和下一步操作。从只读证据开始，避免敏感信息，一次只修复一层。

前提条件

  • 操作机器上安装 Python 3.10+。
  • kubectl 已配置，具备对目标命名空间的读取权限。
  • 允许读取 Pod、事件、作业、PVC 和 DynamoGraphDeployment 资源（而不是密钥）。
  • 可以访问集群 API 服务器。

指令

1. 收集只读调试包

运行：

python3 scripts/collect_dynamo_debug_bundle.py \
  --namespace "${NAMESPACE}"

如果用户指定了部署名称，请加上：

python3 scripts/collect_dynamo_debug_bundle.py \
  --namespace "${NAMESPACE}" \
  --deployment-name <部署名称>

不要收集 Kubernetes 密钥。不要打印 Hugging Face 令牌。

2. 对故障进行分类

使用 references/failure-decision-tree.md，并归类到以下一个主要类别：

  • 集群/平台
  • 命名空间/密钥
  • 模型缓存/PVC/下载
  • 镜像拉取/运行时镜像
  • GPU 调度/资源
  • 操作员/DynamoGraphDeployment 协调
  • 前端/路由器
  • 工作节点/后端
  • 端点/API
  • 基准/性能作业

3. 自上而下调试

按以下顺序检查：

  1. 命名空间、存储类、GPU 节点和 HF 密钥是否存在
  2. PVC 和模型下载作业
  3. DynamoGraphDeployment 状态和事件
  4. Pod 状态、describe pod 和容器日志
  5. 前端服务和端口转发
  6. /v1/models
  7. /v1/chat/completions
  8. 仅在端点冒烟测试通过后运行基准作业

4. 一次只修复一层

优先采用最小的可逆更改：

  • 创建缺失的命名空间或 HF 密钥
  • 修补 storageClassName
  • 修补镜像标签或镜像拉取密钥
  • 仅在配方仍然有效时减少 GPU 请求
  • 仅在工作节点不发布事件时将 KV 路由器切换到近似模式
  • 修复底层配置后，重新启动失败的作业

每次修复后，重新运行相关的就绪检查，再深入下一层。

可用脚本

脚本 目的 参数
scripts/collect_dynamo_debug_bundle.py 收集只读调试包（Pod、事件、作业、PVC、CR 状态） --namespace, --deployment-name, --output-dir

通过 agentskills.io 的 run_script() 协议调用：

run_script("scripts/collect_dynamo_debug_bundle.py", args=["--namespace", "dynamo-demo"])

示例

收集命名空间中的所有内容进行分类：

python3 scripts/collect_dynamo_debug_bundle.py --namespace dynamo-demo

限定到单个失败的部署：

python3 scripts/collect_dynamo_debug_bundle.py \
  --namespace dynamo-demo \
  --deployment-name qwen-vllm-disagg

通过代理协议的等价方式：

run_script("scripts/collect_dynamo_debug_bundle.py", args=["--namespace", "dynamo-demo", "--deployment-name", "qwen-vllm-disagg"])

输出约定

返回：

  • 问题类别
  • 已检查的证据
  • 最强信号
  • 可能的原因
  • 确切的下一条命令或补丁
  • 已排除的内容
  • 是否可以安全继续部署或基准测试

局限性

  • 只读。绝不修改集群；仅返回修复命令，不执行。
  • 不会收集密钥或打印 Hugging Face 令牌；某些故障模式（认证）可能需要用户端检查。
  • 包大小随部署规模增长；在非常大的命名空间中，使用 --deployment-name 限定范围。
  • 不验证 disagg 传输 — 请使用 dynamo-interconnect-check 进行验证。

故障排查

症状 可能的原因 下一步
kubectl 在事件/Pod 上返回 Forbidden 服务账户缺少读取 RBAC 请求操作员在命名空间上绑定只读角色
包缺少 DynamoGraphDeployment 状态 操作员未安装或不在同一命名空间 验证 dynamo-platform 操作员已安装并正在监视该命名空间
模型下载作业处于 Pending 状态 PVC 未绑定或 HF 密钥缺失 修复 PVC 绑定或创建指定的 HF 密钥，然后重新运行作业
工作节点 Pod 处于 CrashLoopBackOff 状态 镜像/运行时不匹配或 GPU 不可用 检查容器日志；检查节点上 nvidia.com/gpu 的可分配容量

基准测试

参见 BENCHMARK.md 了解 NVCARPS-EVAL 性能报告（由 NVSkills CI 流水线自动生成）。如需刷新，请在触及此技能的上游 PR 上重新运行 /nvskills-ci。

参考

  • 阅读 references/failure-decision-tree.md 了解具体类别的检查。
  • 使用 scripts/collect_dynamo_debug_bundle.py 收集只读包。