ML 워크로드 디버깅 위키로 문제 해결

ML 워크로드 디버깅 위키는 AI 코딩 에이전트가 JAX, XLA 또는 Pathways를 사용하여 Google Kubernetes Engine (GKE)에서 실행되는 TPU 워크로드의 문제를 해결하는 데 사용하는 GitHub 저장소입니다. 위키를 사용하면 AI 에이전트가 워크로드 로그를 수집하고, 오류 서명을 알려진 실패 모드와 일치시키고, 진단 워크플로를 실행하고, 로그를 기반으로 근본 원인을 보고할 수 있습니다. 이를 통해 에이전트는 워크로드 비정상 종료, 중단, 다시 시작 또는 선점을 진단하는 데 필요한 정보를 얻을 수 있습니다.

위키에는 두 가지 형태의 참조 자료가 포함되어 있습니다.

• 지식 페이지: 개념, 실패 증상 및 로그 서명, 문제 해결 플레이북, 진단 도구를 설명하는 마크다운 페이지입니다.
• 실행 가능한 절차: JSON 작업 및 워크플로 작업은 로그 쿼리 또는 kubectl 명령어와 같은 단일 진단 단계입니다. 워크플로는 특정 장애 모드를 진단하기 위해 일련의 작업을 실행합니다.

/troubleshoot 명령어를 실행하면 전문 하위 에이전트팀이 워크로드 로그를 분류하고, 실패와 일치하는 워크플로를 선택하고 실행하며, 기본 로그와 비교하여 각 결론을 확인합니다. 그런 다음 에이전트는 근본 원인, 로그에서 인용된 원인 호스트, 각 중단을 요약한 실패 표를 보고합니다.

키 파일

다음 표에는 ML 워크로드 디버그 위키의 주요 파일과 디렉터리가 나와 있습니다.

경로	설명
_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/	로그 쿼리 및 kubectl 명령어와 같은 JSON의 개별 진단 단계입니다.
_wiki/SCHEMA.md	위키 페이지가 따라야 하는 페이지 유형, 프런트매터 요구사항, 분류 태그입니다.
_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 클러스터가 표시됩니다.	http://localhost:8080에서 로컬 웹 앱인 GKE 용량 및 분류 대시보드를 시작합니다. 이 명령어는 대상의 클러스터를 스캔한 후 대상으로 필터링된 대시보드 뷰에 대한 링크를 반환합니다.
/handoff	/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch] WORKLOAD_ID를 제외한 모든 인수는 선택사항입니다. CASE_ID: 지원 케이스 번호입니다. --bucket=BUCKET: 버킷의 이름입니다. 이 플래그를 생략하면 에이전트가 버킷을 요청합니다. --findings=PATH: 기존 발견 항목 파일의 경로입니다. 이 플래그를 설정하면 명령어가 /troubleshoot를 실행하지 않습니다. --no-watch: 버킷 모니터링을 사용 중지합니다.	/troubleshoot 발견 항목을 Cloud Storage 버킷에 패키징하여 Cloud Customer Care와 공유한 다음 버킷의 업데이트를 모니터링합니다. 나중에 업데이트를 확인하려면 /handoff --watch STORAGE_KEY를 실행합니다. 여기서 STORAGE_KEY는 버킷에 있는 핸드오프 폴더의 이름입니다.

기본 요건

위키를 설정하기 전에 진단할 워크로드를 식별하고 다음 세부정보를 기록해 둡니다.

• 워크로드 또는 JobSet의 이름입니다.
• 워크로드를 실행하는 Google Cloud 프로젝트의 ID입니다.
• 진단할 실행의 대략적인 기간입니다.

설치

위키를 사용하려면 다음을 설치해야 합니다.

1. venv 모듈을 포함하여 Python 3을 설치합니다. 위키에는 Python 3.9 이상이 필요합니다. Debian 및 Ubuntu에서 venv 모듈은 python3-venv 패키지에 있습니다.
2. Google Cloud CLI를 설치하고 초기화합니다.
3. kubectl 및 gke-gcloud-auth-plugin를 설치합니다.
4. 다음 AI 코딩 에이전트 중 하나를 설치합니다. 위키에는 다음 두 가지의 구성 파일이 포함되어 있습니다.
   • Claude Code
   • Google Antigravity

필요한 역할

에이전트는 Google Cloud 사용자 인증 정보로 진단 명령어를 실행합니다. 워크로드를 진단하려면 워크로드를 실행하는 프로젝트에 다음 IAM 역할을 부여합니다.

• 로그 뷰어 (roles/logging.viewer): 에이전트가 워크로드 컨테이너, 노드, 감사 로그를 읽을 수 있습니다.
• Kubernetes Engine 뷰어 (roles/container.viewer): 에이전트가 워크로드를 실행한 클러스터, 노드, 포드를 검사할 수 있습니다.
• Compute 뷰어 (roles/compute.viewer): 에이전트가 VM 유지보수 및 종료 이벤트를 포함하여 클러스터 노드를 지원하는 Compute Engine VM을 검사할 수 있습니다.
• 모니터링 뷰어 (roles/monitoring.viewer): 에이전트가 워크로드 및 노드 측정항목을 검사하는 워크플로의 Cloud Monitoring 측정항목을 읽을 수 있습니다.

/handoff 명령어를 실행하려면 Cloud Customer Care와 공유하는 Cloud Storage 버킷에 대한 스토리지 객체 관리자(roles/storage.objectAdmin) 역할도 필요합니다. 이 역할을 통해 에이전트는 발견 항목을 버킷에 업로드하고 업데이트를 모니터링할 수 있습니다.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

위키 설정하기

1. 저장소를 클론하고 루트 디렉터리로 이동합니다.

   git clone https://github.com/google/ml-workload-debugging-wiki.git
   cd ./ml-workload-debugging-wiki
   

   위키는 저장소 루트를 기준으로 하는 경로를 사용하므로 이 디렉터리에서 명령어를 실행하고 에이전트를 시작합니다.

2. Python 가상 환경을 만들고 활성화한 후 위키의 종속 항목을 설치합니다.

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

3. 사용자 계정의 로컬 애플리케이션 기본 사용자 인증 정보 (ADC)를 만듭니다. 위키의 Python 도구는 ADC를 사용하여 Cloud Logging을 쿼리합니다.

   gcloud auth application-default login
   

4. wiki linter를 실행하여 설정을 확인합니다.

   python3 _wiki/wiki_linter.py
   

   린터는 위키의 구조, 스키마, 링크를 확인한 후 JSON 보고서를 출력합니다. 보고서에 "status": "PASS"가 포함되어 있으면 검사가 성공한 것입니다. 보고서의 경고는 상태에 영향을 미치지 않습니다.

워크로드 문제 해결

ML 워크로드 디버깅 위키를 사용하여 워크로드 문제를 해결하려면 다음 단계를 따르세요.

1. ML Workload Debugging Wiki 저장소의 루트에서 에이전트를 시작합니다.

   • Claude Code: 가상 환경을 활성화한 셸에서 claude를 실행합니다. Claude Code는 CLAUDE.md에서 위키의 안내를 로드하고 .claude/ 디렉터리에서 명령어 및 하위 에이전트 정의를 로드합니다.
   • Antigravity: 저장소의 루트를 작업공간으로 엽니다. 위키의 Antigravity 기술 및 하위 에이전트 정의는 _agents/ 디렉터리에 있습니다. 설정 세부정보는 _agents/QUICKSTART.md를 참조하세요.

2. 진단하려는 워크로드 또는 JobSet의 이름을 지정하여 /troubleshoot 명령어를 실행합니다.

   /troubleshoot WORKLOAD_ID
   

3. 상담사에게 프로젝트 ID와 실행 기간을 제공합니다. UTC 타임스탬프 형식 (YYYY-MM-DDTHH:MM:SSZ)으로 정확한 기간을 제공하거나 자연어로 '1시간 전' 또는 '지난 24시간'과 같은 상대적인 기간을 제공할 수 있습니다. 에이전트는 기간을 사용하여 로그 쿼리 범위를 지정하므로 전체 실행을 포함하는지 확인합니다.

진단 워크플로는 기본적으로 읽기 전용 검사를 실행합니다. 에이전트가 노드의 전원 순환 또는 taint와 같이 클러스터 상태를 수정하는 작업을 실행하기 전에 명시적인 확인을 요청합니다. 각 명령어는 검토 및 승인을 받아야 합니다. 이러한 작업은 _wiki/actions/의 정의에서 requires_approval: true로 표시됩니다. 진단이 완료되면 에이전트가 결과를 보고합니다.

불확실한 결과를 인식하는 방법을 포함하여 결과를 평가하는 방법을 알아보려면 _wiki/TUTORIAL.md를 참고하세요.