Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Memecahkan masalah dengan Wiki Proses Debug Workload ML

ML Workload Debugging Wiki adalah repositori GitHub yang digunakan agen coding AI untuk memecahkan masalah workload TPU yang berjalan di Google Kubernetes Engine (GKE) dengan JAX, XLA, atau Pathways. Wiki ini memungkinkan agen AI mengumpulkan log workload, mencocokkan tanda tangan error dengan mode kegagalan yang diketahui, menjalankan alur kerja diagnostik, dan melaporkan akar masalah berdasarkan log. Hal ini memberi agen informasi yang diperlukan untuk mendiagnosis error, hang, mulai ulang, atau preemption workload.

Wiki berisi dua bentuk materi referensi:

Halaman pengetahuan: Halaman Markdown yang menjelaskan konsep, gejala kegagalan, dan tanda tangan lognya, playbook pemecahan masalah, dan alat diagnostik.
Prosedur yang dapat dieksekusi: Alur kerja dan tindakan JSON. Tindakan adalah satu langkah diagnostik, seperti kueri log atau perintah kubectl. Alur kerja menjalankan urutan tindakan untuk mendiagnosis mode kegagalan tertentu.

Saat Anda menjalankan perintah /troubleshoot, tim sub-agen khusus akan melakukan triase log workload, memilih dan menjalankan alur kerja yang sesuai dengan kegagalan, dan memeriksa setiap kesimpulan terhadap log utama. Agen kemudian melaporkan akar masalah, host penyebab seperti yang dikutip dari log, dan tabel kegagalan yang merangkum setiap gangguan.

File kunci

Tabel berikut mencantumkan file dan direktori utama dalam Wiki Workload ML Debug:

Jalur	Deskripsi
`_wiki/TUTORIAL.md`	Panduan tentang apa yang terjadi selama diagnosis dan cara mengevaluasi hasilnya, termasuk contoh yang berhasil.
`_wiki/INDEX.md`	Katalog setiap halaman, tindakan, dan alur kerja di wiki, dengan ringkasan satu baris untuk masing-masing.
`_wiki/concepts/`	Konsep arsitektur sistem dan siklus proses komponen, seperti siklus proses program libtpu, goodput, dan pemantauan progres workload.
`_wiki/entities/`	Entitas hardware, software, dan platform, seperti TPU, GPU, JAX, XLA, dan Pathways.
`_wiki/symptoms/`	Mode kegagalan, tanda tangan lognya, dan cara memverifikasi masing-masing mode.
`_wiki/playbooks/`	Strategi pemecahan masalah, diagram alir pohon keputusan, dan kesalahan umum.
`_wiki/tools/`	Alat diagnostik, skrip, dan panduan referensi command line.
`_wiki/workflows/`	Prosedur diagnostik dalam JSON. Setiap alur kerja menjalankan urutan tindakan untuk mendiagnosis mode kegagalan tertentu.
`_wiki/actions/`	Langkah-langkah diagnostik individual dalam JSON, seperti kueri log dan perintah `kubectl`.
`_wiki/SCHEMA.md`	Jenis halaman, persyaratan frontmatter, dan tag taksonomi yang harus diikuti oleh halaman wiki.
`_agents/QUICKSTART.md`	Detail penyiapan dan pengiriman untuk pengguna Antigravity.
`CLAUDE.md`	Tata letak ruang kerja, alat command line, dan peran subagen, untuk pengguna Claude Code.

Perintah tombol

Tabel berikut mencantumkan perintah yang dapat Anda jalankan dengan wiki:

Perintah Penggunaan Deskripsi

/troubleshoot /troubleshoot WORKLOAD_ID, dengan WORKLOAD_ID adalah nama workload atau JobSet. Mendiagnosis workload menggunakan Cloud Logging, peristiwa cluster GKE, log kubelet, dan log node. Sub-agen router, praktisi, peninjau, dan penasihat menjalankan diagnosis dan melaporkan akar masalah, host penyebab seperti yang dikutip dari log, dan tabel kegagalan.

/dashboard /dashboard [TARGET], dengan TARGET adalah project ID, nama cluster, atau ID workload opsional. Jika Anda menghilangkan TARGET, dasbor akan menampilkan semua cluster GKE dalam project yang ditetapkan dalam konfigurasi Google Cloud CLI Anda. Memulai Dasbor Kapasitas & Triase GKE, aplikasi web lokal di http://localhost:8080. Perintah ini memindai cluster untuk mencari target, lalu menampilkan link ke tampilan dasbor yang difilter ke target.

Perintah	Penggunaan	Deskripsi
`/troubleshoot`	`/troubleshoot WORKLOAD_ID`, dengan `WORKLOAD_ID` adalah nama workload atau JobSet.	Mendiagnosis workload menggunakan Cloud Logging, peristiwa cluster GKE, log kubelet, dan log node. Sub-agen router, praktisi, peninjau, dan penasihat menjalankan diagnosis dan melaporkan akar masalah, host penyebab seperti yang dikutip dari log, dan tabel kegagalan.
`/dashboard`	`/dashboard [TARGET]`, dengan `TARGET` adalah project ID, nama cluster, atau ID workload opsional. Jika Anda menghilangkan `TARGET`, dasbor akan menampilkan semua cluster GKE dalam project yang ditetapkan dalam konfigurasi Google Cloud CLI Anda.	Memulai Dasbor Kapasitas & Triase GKE, aplikasi web lokal di `http://localhost:8080`. Perintah ini memindai cluster untuk mencari target, lalu menampilkan link ke tampilan dasbor yang difilter ke target.
`/handoff`	`/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch]` Semua argumen kecuali `WORKLOAD_ID` bersifat opsional: `CASE_ID`: nomor kasus dukungan Anda. `--bucket=BUCKET`: nama bucket. Jika Anda menghapus flag ini, agen akan meminta bucket. `--findings=PATH`: jalur ke file temuan yang ada. Jika Anda menetapkan flag ini, perintah tidak akan menjalankan `/troubleshoot`. `--no-watch`: menonaktifkan pemantauan bucket.	Mengemas temuan `/troubleshoot` ke dalam bucket Cloud Storage untuk dibagikan kepada Cloud Customer Care, lalu memantau bucket untuk mengetahui adanya update. Untuk memeriksa update nanti, jalankan `/handoff --watch STORAGE_KEY`, dengan `STORAGE_KEY` adalah nama folder serah terima di bucket.

/handoff

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

Semua argumen kecuali WORKLOAD_ID bersifat opsional:

CASE_ID: nomor kasus dukungan Anda.
--bucket=BUCKET: nama bucket. Jika Anda menghapus flag ini, agen akan meminta bucket.
--findings=PATH: jalur ke file temuan yang ada. Jika Anda menetapkan flag ini, perintah tidak akan menjalankan /troubleshoot.
--no-watch: menonaktifkan pemantauan bucket.

Mengemas temuan /troubleshoot ke dalam bucket Cloud Storage untuk dibagikan kepada Cloud Customer Care, lalu memantau bucket untuk mengetahui adanya update. Untuk memeriksa update nanti, jalankan /handoff --watch STORAGE_KEY, dengan STORAGE_KEY adalah nama folder serah terima di bucket.

Prasyarat

Sebelum menyiapkan wiki, identifikasi workload yang ingin Anda diagnosis, dan perhatikan detail berikut:

Nama workload atau JobSet.
ID project Google Cloud yang menjalankan workload.
Perkiraan rentang waktu eksekusi yang akan didiagnosis.

Penginstalan

Wiki memerlukan penginstalan berikut:

Instal Python 3, termasuk modul venv. Wiki memerlukan Python 3.9 atau yang lebih baru. Di Debian dan Ubuntu, modul venv ada dalam paket python3-venv.
Instal dan lakukan inisialisasi pada Google Cloud CLI.
Instal kubectl dan gke-gcloud-auth-plugin.
Instal salah satu agen coding AI berikut. Wiki ini menyertakan file konfigurasi untuk:
- Claude Code
- Google Antigravity

Peran yang diperlukan

Agen menjalankan perintah diagnostik dengan kredensial Google Cloud Anda. Untuk mendiagnosis workload, berikan peran IAM berikut ke project yang menjalankan workload:

Logs Viewer (roles/logging.viewer): memungkinkan agen membaca container workload, node, dan log audit.
Kubernetes Engine Viewer (roles/container.viewer): memungkinkan agen memeriksa cluster, node, dan pod yang menjalankan workload.
Compute Viewer (roles/compute.viewer): memungkinkan agen memeriksa VM Compute Engine yang mendukung node cluster, termasuk peristiwa pemeliharaan dan penghentian VM.
Monitoring Viewer (roles/monitoring.viewer): memungkinkan agen membaca metrik Cloud Monitoring untuk alur kerja yang memeriksa metrik workload dan node.

Untuk menjalankan perintah /handoff, Anda juga memerlukan peran Storage Object Admin (roles/storage.objectAdmin) di bucket Cloud Storage yang Anda bagikan ke Cloud Customer Care. Peran ini memungkinkan agen mengupload temuan ke bucket dan memantaunya untuk mengetahui update.

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Menyiapkan wiki

Buat clone repositori dan buka direktori root-nya:
```
git clone https://github.com/google/ml-workload-debugging-wiki.git
cd ./ml-workload-debugging-wiki
```
Wiki menggunakan jalur yang relatif terhadap root repositori, jadi jalankan perintah dan mulai agen Anda dari direktori ini.

Buat dan aktifkan lingkungan virtual Python, lalu instal dependensi wiki:

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

Buat Kredensial Default Aplikasi (ADC) lokal untuk akun pengguna Anda. Alat Python wiki menggunakan ADC untuk mengkueri Cloud Logging:
```
gcloud auth application-default login
```
Verifikasi penyiapan Anda dengan menjalankan linter wiki:
```
python3 _wiki/wiki_linter.py
```
Linter memeriksa struktur, skema, dan link wiki, lalu mencetak laporan JSON. Jika laporan berisi "status": "PASS", pemeriksaan berhasil. Peringatan dalam laporan tidak memengaruhi status.

Memecahkan masalah workload

Gunakan langkah-langkah berikut untuk memecahkan masalah workload dengan Wiki Proses Debug Workload ML:

Mulai agen Anda dari root repositori ML Workload Debugging Wiki:
- Claude Code: Di shell tempat Anda mengaktifkan lingkungan virtual, jalankan claude. Claude Code memuat petunjuk wiki dari CLAUDE.md serta definisi perintah dan subagennya dari direktori .claude/.
- Antigravity: Buka root repositori sebagai ruang kerja Anda. Definisi subagen dan keahlian Antigravity wiki berada di direktori _agents/. Untuk mengetahui detail penyiapan, lihat _agents/QUICKSTART.md.
Jalankan perintah /troubleshoot, dengan menentukan nama workload atau JobSet yang ingin Anda diagnosis:
```
/troubleshoot WORKLOAD_ID
```
Berikan project ID dan rentang waktu operasi kepada agen. Anda dapat memberikan rentang waktu yang tepat dalam format stempel waktu UTC (YYYY-MM-DDTHH:MM:SSZ), atau rentang waktu relatif dalam bahasa alami, seperti "satu jam yang lalu" atau "24 jam terakhir". Agen menggunakan rentang waktu untuk mencakup kueri log mereka, jadi pastikan rentang waktu tersebut mencakup seluruh operasi.

Alur kerja diagnostik menjalankan pemeriksaan hanya baca secara default. Sebelum agen menjalankan tindakan yang mengubah status cluster, seperti mematikan dan menghidupkan ulang atau menodai node, agen akan meminta konfirmasi eksplisit dari Anda. Setiap perintah harus ditinjau dan disetujui. Tindakan ini ditandai dengan requires_approval: true dalam definisinya di _wiki/actions/. Agen akan melaporkan temuannya setelah diagnosis selesai.

Untuk mempelajari cara mengevaluasi temuan, termasuk cara mengenali hasil yang tidak meyakinkan, lihat _wiki/TUTORIAL.md.