Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用機器學習工作負載偵錯 Wiki 進行疑難排解

機器學習工作負載偵錯 Wiki 是 GitHub 存放區，AI 程式設計代理會使用這個存放區，對在 Google Kubernetes Engine (GKE) 上執行的 TPU 工作負載進行疑難排解，並使用 JAX、XLA 或 Pathways。AI 代理可透過維基收集工作負載記錄、比對錯誤簽章與已知故障模式、執行診斷工作流程，並根據記錄回報根本原因。這項資訊可協助代理診斷工作負載當機、停止運作、重新啟動或搶占等問題。

維基百科包含兩種參考資料：

知識頁面：Markdown 頁面，說明概念、故障症狀及其記錄簽章、疑難排解教戰手冊和診斷工具。
可執行的程序：JSON 動作和工作流程。動作是指單一診斷步驟，例如記錄查詢或 kubectl 指令。工作流程會執行一連串動作，診斷特定故障模式。

執行 /troubleshoot 指令時，專門的子代理團隊會分類工作負載記錄、選取並執行與失敗相符的工作流程，並根據主要記錄檢查每項結論。接著，代理會回報根本原因、記錄中引用的問題主機，以及摘要說明各項中斷情形的故障表。

金鑰檔案

下表列出 Debug ML Workloads Wiki 中的重要檔案和目錄：

路徑	說明
`_wiki/TUTORIAL.md`	逐步說明診斷期間會發生的情況，以及如何評估結果，包括實際範例。
`_wiki/INDEX.md`	維基中每個頁面、動作和工作流程的目錄，並附上各項目的單行摘要。
`_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`	維基頁面必須遵循的頁面類型、frontmatter 規定和分類標記。
`_agents/QUICKSTART.md`	Antigravity 使用者的設定和調度詳細資料。
`CLAUDE.md`	Claude Code 使用者的工作區版面配置、指令列工具和子代理角色。

重要指令

下表列出可與維基搭配執行的指令：

指令用量說明

/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 的本機網頁應用程式。這個指令會掃描叢集中的目標，然後傳回篩選出目標的資訊主頁檢視畫面連結。

指令	用量	說明
`/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` 的本機網頁應用程式。這個指令會掃描叢集中的目標，然後傳回篩選出目標的資訊主頁檢視畫面連結。
`/handoff`	`/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch]` 除了 `WORKLOAD_ID` 以外，所有引數均為選用： `CASE_ID`：客服案件編號。 `--bucket=BUCKET`：bucket 的名稱。如果省略這個旗標，代理會要求提供 bucket。 `--findings=PATH`：現有發現項目檔案的路徑。如果設定這個旗標，指令就不會執行 `/troubleshoot`。 `--no-watch`：關閉 bucket 監控功能。	將 `/troubleshoot` 發現項目封裝至 Cloud Storage bucket，以便與 Cloud Customer Care 共用，然後監控 bucket 是否有更新。如要日後檢查更新，請執行 `/handoff --watch STORAGE_KEY`，其中 `STORAGE_KEY` 是 bucket 中的交接資料夾名稱。

/handoff

/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch]

除了 WORKLOAD_ID 以外，所有引數均為選用：

CASE_ID：客服案件編號。
--bucket=BUCKET：bucket 的名稱。如果省略這個旗標，代理會要求提供 bucket。
--findings=PATH：現有發現項目檔案的路徑。如果設定這個旗標，指令就不會執行 /troubleshoot。
--no-watch：關閉 bucket 監控功能。

將 /troubleshoot 發現項目封裝至 Cloud Storage bucket，以便與 Cloud Customer Care 共用，然後監控 bucket 是否有更新。如要日後檢查更新，請執行 /handoff --watch STORAGE_KEY，其中 STORAGE_KEY 是 bucket 中的交接資料夾名稱。

必要條件

設定維基前，請先找出要診斷的工作負載，並記下下列詳細資料：

工作負載或 JobSet 的名稱。
執行工作負載的 Google Cloud 專案 ID。
要診斷的執行作業大致時間範圍。

安裝

維基需要安裝下列項目：

安裝 Python 3，包括 venv 模組。維基需要 Python 3.9 以上版本。在 Debian 和 Ubuntu 上，venv 模組位於 python3-venv 套件中。
安裝並初始化 Google Cloud CLI。
安裝 kubectl 和 gke-gcloud-auth-plugin。
安裝下列其中一個 AI 程式設計代理。維基包含以下兩者的設定檔：
- Claude Code
- Google Antigravity

必要的角色

代理會使用您的 Google Cloud 憑證執行診斷指令。如要診斷工作負載，請將下列 IAM 角色授予執行工作負載的專案：

記錄檢視器 (roles/logging.viewer)：可讓代理程式讀取工作負載容器、節點和稽核記錄。
Kubernetes Engine 檢視者 (roles/container.viewer)：可讓代理程式檢查執行工作負載的叢集、節點和 Pod。
Compute 檢視者 (roles/compute.viewer)：可讓代理程式檢查支援叢集節點的 Compute Engine VM，包括 VM 維護和終止事件。
Monitoring 檢視者 (roles/monitoring.viewer)：可讓代理讀取 Cloud Monitoring 指標，用於檢查工作負載和節點指標的工作流程。

如要執行 /handoff 指令，您也必須具備與 Cloud Customer Care 共用的 Cloud Storage bucket 的 Storage 物件管理員 (roles/storage.objectAdmin) 角色。這個角色可讓代理將發現項目上傳至 bucket，並監控 bucket 是否有更新。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

設定維基

複製存放區，然後前往根目錄：
```
git clone https://github.com/google/ml-workload-debugging-wiki.git
cd ./ml-workload-debugging-wiki
```
維基使用的路徑是相對於存放區根目錄，因此請從這個目錄執行指令並啟動代理。

建立並啟用 Python 虛擬環境，然後安裝維基的依附元件：

python3 -m venv _wiki/.venv
source _wiki/.venv/bin/activate
pip install -r _wiki/requirements.txt

為使用者帳戶建立本機應用程式預設憑證 (ADC)。維基的 Python 工具會使用 ADC 查詢 Cloud Logging：
```
gcloud auth application-default login
```
執行 wiki linter 驗證設定：
```
python3 _wiki/wiki_linter.py
```
linter 會檢查維基的結構、結構定義和連結，然後輸出 JSON 報表。如果報表包含 "status": "PASS"，表示檢查成功。報表中的警告不會影響狀態。

疑難排解工作負載

請按照下列步驟，使用機器學習工作負載偵錯 Wiki 排解工作負載問題：

從 ML Workload Debugging Wiki 存放區的根目錄啟動代理：
- Claude Code：在啟用虛擬環境的殼層中，執行 claude。Claude Code 會從 CLAUDE.md 載入 Wiki 的指令，並從 .claude/ 目錄載入指令和子代理定義。
- Antigravity：開啟存放區的根目錄做為工作區。維基的 Antigravity 技能和子代理定義位於 _agents/ 目錄中。如需設定詳情，請參閱 _agents/QUICKSTART.md。
執行 /troubleshoot 指令，並指定要診斷的工作負載或 JobSet 名稱：
```
/troubleshoot WORKLOAD_ID
```
請提供專案 ID 和執行日期範圍。您可以提供世界標準時間戳記格式 (YYYY-MM-DDTHH:MM:SSZ) 的精確日期範圍，或以自然語言表示相對日期範圍，例如「一小時前」或「過去 24 小時」。代理會使用日期範圍來限定記錄查詢範圍，因此請務必涵蓋整個執行作業。

診斷工作流程預設會執行唯讀檢查。代理在執行會修改叢集狀態的動作 (例如重新啟動或標記節點) 之前，會要求您明確確認。每項指令都必須經過審查和核准。在 _wiki/actions/ 的定義中，這些動作會標示 requires_approval: true。診斷完成後，代理會回報結果。

如要瞭解如何評估結果，包括如何辨識無法判定的結果，請參閱「_wiki/TUTORIAL.md」。