使用机器学习工作负载调试 Wiki 排查问题
机器学习工作负载调试 Wiki 是一个 GitHub 代码库，AI 编码智能体可使用该代码库对在 Google Kubernetes Engine (GKE) 上运行的 TPU 工作负载进行问题排查，这些工作负载使用 JAX、XLA 或 Pathways。该 Wiki 使 AI 智能体能够收集工作负载日志、将错误签名与已知故障模式进行匹配、运行诊断工作流，并根据日志报告根本原因。这为代理提供了诊断工作负载崩溃、挂起、重启或抢占所需的信息。
该 Wiki 包含两种形式的参考资料：
- 知识页面：Markdown 页面，用于描述概念、故障症状及其日志签名、问题排查手册和诊断工具。
- 可执行过程：JSON 操作和工作流。操作是单个诊断步骤，例如日志查询或
kubectl命令。工作流会运行一系列操作来诊断特定的故障模式。
运行 /troubleshoot 命令时，一个由专业子代理组成的团队会分类工作负载日志，选择并运行与故障匹配的工作流，并根据主要日志检查每个结论。然后，智能体会报告根本原因、从日志中引用的罪魁祸首主机，以及汇总每次中断的故障表。
密钥文件
下表列出了 Debug ML Workloads Wiki 中的关键文件和目录：
| 路径 | 说明 |
|---|---|
_wiki/TUTORIAL.md |
详细介绍诊断期间发生的情况以及如何评估结果，包括一个实际示例。 |
_wiki/INDEX.md |
Wiki 中每个页面、操作和工作流的目录，以及每个页面、操作和工作流的单行摘要。 |
_wiki/concepts/ |
系统架构和组件生命周期概念，例如 libtpu 程序生命周期、有效吞吐量和工作负载进度监控。 |
_wiki/entities/ |
硬件、软件和平台实体，例如 TPU、GPU、JAX、XLA 和 Pathways。 |
_wiki/symptoms/ |
故障模式、其日志签名以及如何验证每种故障模式。 |
_wiki/playbooks/ |
问题排查策略、决策树流程图和常见陷阱。 |
_wiki/tools/ |
诊断工具、脚本和命令行参考指南。 |
_wiki/workflows/ |
JSON 格式的诊断程序。每个工作流都会运行一系列操作来诊断特定的故障模式。 |
_wiki/actions/ |
JSON 格式的各个诊断步骤，例如日志查询和 kubectl 命令。
|
_wiki/SCHEMA.md |
Wiki 页面必须遵循的页面类型、frontmatter 要求和分类标记。 |
_agents/QUICKSTART.md |
Antigravity 用户的设置和派送详情。 |
CLAUDE.md |
Claude Code 用户的工作区布局、命令行工具和子代理角色。 |
关键命令
下表列出了您可以使用 wiki 运行的命令：
| 命令 | 用法 | 说明 |
|---|---|---|
/troubleshoot |
/troubleshoot WORKLOAD_ID，其中 WORKLOAD_ID 是工作负载或 JobSet 的名称。
|
使用 Cloud Logging、GKE 集群事件、kubelet 日志和节点日志诊断工作负载。路由器、从业者、审核者和顾问子代理会运行诊断并报告根本原因、日志中引用的罪魁祸首主机以及故障表。 |
/dashboard |
/dashboard [TARGET]，其中 TARGET 是可选的项目 ID、集群名称或工作负载 ID。如果您省略 TARGET，信息中心会显示 Google Cloud CLI 配置中设置的项目中的所有 GKE 集群。
|
启动 GKE 容量和分类信息中心，这是一个位于 http://localhost:8080 的本地 Web 应用。该命令会扫描集群以查找目标，然后返回一个指向已过滤到目标的监控信息中心视图的链接。
|
/handoff |
除
|
将 /troubleshoot 发现结果打包到 Cloud Storage 存储桶中，以便与 Cloud Customer Care 共享，然后监控存储桶是否有更新。如需稍后检查更新，请运行 /handoff --watch STORAGE_KEY，其中 STORAGE_KEY 是存储桶中切换文件夹的名称。
|
前提条件
在设置 Wiki 之前，请确定要诊断的工作负载，并记下以下详细信息：
- 工作负载或 JobSet 的名称。
- 运行工作负载的 Google Cloud 项目的 ID。
- 要诊断的运行的大致时间范围。
安装次数
该 Wiki 需要安装以下内容：
- 安装 Python 3，包括
venv模块。该 Wiki 需要 Python 3.9 或更高版本。在 Debian 和 Ubuntu 上，venv模块位于python3-venv软件包中。 - 安装并初始化 Google Cloud CLI。
- 安装
kubectl和gke-gcloud-auth-plugin。 - 安装以下任一 AI 编码智能体。该 Wiki 包含以下两者的配置文件：
所需的角色
代理会使用您的 Google Cloud 凭据运行诊断命令。如需诊断工作负载，请向运行工作负载的项目授予以下 IAM 角色：
- 日志查看器 (
roles/logging.viewer)：允许代理读取工作负载容器、节点和审核日志。 - Kubernetes Engine Viewer (
roles/container.viewer)：允许代理检查运行工作负载的集群、节点和 Pod。 - Compute Viewer (
roles/compute.viewer)：允许代理检查支持集群节点的 Compute Engine 虚拟机，包括虚拟机维护和终止事件。 - Monitoring Viewer (
roles/monitoring.viewer)：允许代理读取 Cloud Monitoring 指标，以便工作流检查工作负载和节点指标。
如需运行 /handoff 命令，您还需要对与 Cloud Customer Care 共享的 Cloud Storage 存储桶拥有 Storage Object Admin (roles/storage.objectAdmin) 角色。此角色允许代理将发现结果上传到存储桶并监控其更新。
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
设置 Wiki
克隆该代码库并前往其根目录：
git clone https://github.com/google/ml-workload-debugging-wiki.git cd ./ml-workload-debugging-wiki该 Wiki 使用相对于代码库根目录的路径，因此请从此目录运行命令并启动智能体。
创建并激活 Python 虚拟环境，然后安装 Wiki 的依赖项：
python3 -m venv _wiki/.venv source _wiki/.venv/bin/activate pip install -r _wiki/requirements.txt为您的用户账号创建本地应用默认凭证 (ADC)。该 Wiki 的 Python 工具使用 ADC 查询 Cloud Logging：
gcloud auth application-default login运行 wiki linter 以验证您的设置：
python3 _wiki/wiki_linter.pylinter 会检查 Wiki 的结构、架构和链接，然后输出 JSON 报告。如果报告包含
"status": "PASS"，则表示检查成功。报告中的警告不会影响状态。
排查工作负载问题
请按照以下步骤，使用机器学习工作负载调试 Wiki 排查工作负载问题：
从 ML Workload Debugging Wiki 代码库的根目录启动智能体：
- Claude Code：在您激活虚拟环境的 shell 中，运行
claude。Claude Code 会从CLAUDE.md加载 Wiki 的指令，并从.claude/目录加载其命令和子智能体定义。 - Antigravity：将代码库的根目录作为工作区打开。维基的 Antigravity 技能和子智能体定义位于
_agents/目录中。如需了解设置详情，请参阅_agents/QUICKSTART.md。
- Claude Code：在您激活虚拟环境的 shell 中，运行
运行
/troubleshoot命令，指定要诊断的工作负载或 JobSet 的名称：/troubleshoot WORKLOAD_ID
向智能体提供项目 ID 和运行时间范围。您可以提供 UTC 时间戳格式 (
YYYY-MM-DDTHH:MM:SSZ) 的精确时间范围，也可以提供自然语言的相对时间范围，例如“一小时前”或“过去 24 小时”。代理会使用时间范围来限定其日志查询的范围，因此请确保该范围涵盖整个运行过程。
默认情况下，诊断工作流会运行只读检查。在代理运行修改集群状态的操作（例如重启或污染节点）之前，它会请求您明确确认。每个命令都必须经过审核和批准。
这些操作在 _wiki/actions/ 中的定义中标记有 requires_approval: true。诊断完成后，代理会报告其发现。
如需了解如何评估发现结果，包括如何识别无法判定的结果，请参阅 _wiki/TUTORIAL.md。