dynamo-troubleshoot

Dynamo 故障排查

用途

将 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 <deployment-name>

不要收集 Kubernetes 机密。不要输出 Hugging Face 令牌。

2. 对故障进行分类

使用 references/failure-decision-tree.md，将故障归入一个主要类别：

• 集群／平台
• 命名空间／机密
• 模型缓存／PVC／下载
• 镜像拉取／运行时镜像
• GPU 调度／资源
• Operator／DynamoGraphDeployment 调和
• 前端／路由器
• Worker／后端
• 端点／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 请求
• 只有在 Worker 不发布事件时，才将 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

通过 Agent 协议执行等效操作：

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 状态	未安装 Operator，或命名空间不同	确认已安装 dynamo-platform Operator，且正在监视该命名空间
模型下载作业处于 Pending 状态	PVC 未绑定或缺少 HF 机密	修复 PVC 绑定或创建指定的 HF 机密，然后重新运行作业
Worker 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 收集只读数据包。