Soluciona problemas con la wiki de depuración de cargas de trabajo de AA

La wiki de depuración de cargas de trabajo de AA es un repositorio de GitHub que los agentes de programación de IA usan para solucionar problemas de las cargas de trabajo de TPU que se ejecutan en Google Kubernetes Engine (GKE) con JAX, XLA o Pathways. La wiki permite que los agentes de IA recopilen registros de cargas de trabajo, hagan coincidir las firmas de errores con los modos de falla conocidos, ejecuten flujos de trabajo de diagnóstico y, además, informen las causas raíz en función de los registros. Esto proporciona a los agentes la información necesaria para diagnosticar fallas, bloqueos, reinicios o interrupciones de las cargas de trabajo.

La wiki contiene dos formas de material de referencia:

• Páginas de conocimiento: Son páginas de Markdown que describen conceptos, síntomas de fallas y sus firmas de registro, guías de solución de problemas y herramientas de diagnóstico.
• Procedimientos ejecutables: Acciones y flujos de trabajo de JSON. Una acción es un solo paso de diagnóstico, como una consulta de registro o un comando kubectl. Un flujo de trabajo ejecuta una secuencia de acciones para diagnosticar un modo de falla específico.

Cuando ejecutas el comando /troubleshoot, un equipo de agentes secundarios especializados clasifica los registros de la carga de trabajo, selecciona y ejecuta el flujo de trabajo que coincide con la falla y verifica cada conclusión con los registros principales. Luego, el agente informa la causa raíz, los hosts culpables según se cita en los registros y una tabla de fallas que resume cada interrupción.

Archivos de claves

En la siguiente tabla, se enumeran los archivos y directorios clave de la wiki de Debug ML Workloads:

Ruta	Descripción
_wiki/TUTORIAL.md	Un recorrido por lo que sucede durante un diagnóstico y cómo evaluar los resultados, incluido un ejemplo práctico.
_wiki/INDEX.md	Un catálogo de cada página, acción y flujo de trabajo de la wiki, con un resumen de una línea de cada uno.
_wiki/concepts/	Conceptos de arquitectura del sistema y ciclo de vida de los componentes, como el ciclo de vida del programa libtpu, el buen rendimiento y la supervisión del progreso de la carga de trabajo.
_wiki/entities/	Entidades de hardware, software y plataforma, como TPU, GPU, JAX, XLA y Pathways.
_wiki/symptoms/	Modos de falla, sus firmas de registro y cómo verificar cada uno
_wiki/playbooks/	Estrategias de solución de problemas, diagramas de flujo de árboles de decisión y errores comunes.
_wiki/tools/	Herramientas de diagnóstico, secuencias de comandos y guías de referencia de línea de comandos.
_wiki/workflows/	Procedimientos de diagnóstico en JSON. Cada flujo de trabajo ejecuta una secuencia de acciones para diagnosticar un modo de falla específico.
_wiki/actions/	Pasos de diagnóstico individuales en JSON, como consultas de registro y comandos de kubectl.
_wiki/SCHEMA.md	Los tipos de páginas, los requisitos de metadatos iniciales y las etiquetas de taxonomía que deben seguir las páginas de la wiki.
_agents/QUICKSTART.md	Detalles de configuración y envío para los usuarios de Antigravity.
CLAUDE.md	El diseño del espacio de trabajo, las herramientas de línea de comandos y los roles de subagente para los usuarios de Claude Code.

Comandos clave

En la siguiente tabla, se enumeran los comandos que puedes ejecutar con la wiki:

Comando	Uso	Descripción
/troubleshoot	/troubleshoot WORKLOAD_ID, donde WORKLOAD_ID es el nombre de la carga de trabajo o JobSet.	Diagnostica una carga de trabajo con Cloud Logging, eventos de clúster de GKE, registros de kubelet y registros de nodos. Los subagentes de enrutador, profesional, revisor y asesor ejecutan el diagnóstico y, luego, informan la causa raíz, los hosts culpables según se cita en los registros y una tabla de fallas.
/dashboard	/dashboard [TARGET], donde TARGET es un ID del proyecto, un nombre de clúster o un ID de carga de trabajo opcional. Si omites TARGET, el panel muestra todos los clústeres de GKE del proyecto que se estableció en la configuración de Google Cloud CLI.	Inicia el panel de capacidad y clasificación de GKE, una app web local en http://localhost:8080. El comando analiza los clústeres en busca del destino y, luego, devuelve un vínculo a una vista del panel filtrada para el destino.
/handoff	/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch] Todos los argumentos, excepto WORKLOAD_ID, son opcionales: CASE_ID: Es el número de tu caso de asistencia. --bucket=BUCKET: el nombre del bucket. Si omites esta marca, el agente solicitará un bucket. --findings=PATH: Es la ruta de acceso a un archivo de hallazgos existente. Si configuras esta marca, el comando no ejecuta /troubleshoot. --no-watch: Desactiva la supervisión del bucket.	Empaqueta los hallazgos de /troubleshoot en un bucket de Cloud Storage para compartirlos con la Atención al cliente de Cloud y, luego, supervisa el bucket en busca de actualizaciones. Para buscar actualizaciones más adelante, ejecuta /handoff --watch STORAGE_KEY, donde STORAGE_KEY es el nombre de la carpeta de transferencia en el bucket.

Requisitos previos

Antes de configurar la wiki, identifica la carga de trabajo que deseas diagnosticar y ten en cuenta los siguientes detalles:

• Es el nombre de la carga de trabajo o del JobSet.
• Es el ID del proyecto de Google Cloud que ejecuta la carga de trabajo.
• Es el período aproximado de la ejecución que se diagnosticará.

Instalaciones

La wiki requiere las siguientes instalaciones:

1. Instala Python 3, incluido el módulo venv. La wiki requiere Python 3.9 o una versión posterior. En Debian y Ubuntu, el módulo venv se encuentra en el paquete python3-venv.
2. Instala y, luego, inicializa la CLI de Google Cloud.
3. Instala kubectl y gke-gcloud-auth-plugin.
4. Instala uno de los siguientes agentes de programación de IA. La wiki incluye archivos de configuración para ambos:
   • Claude Code
   • Google Antigravity

Roles obligatorios

Los agentes ejecutan comandos de diagnóstico con tus credenciales de Google Cloud . Para diagnosticar una carga de trabajo, otorga los siguientes roles de IAM al proyecto que ejecuta la carga de trabajo:

• Visualizador de registros (roles/logging.viewer): Permite que los agentes lean los registros de auditoría, del nodo y del contenedor de la carga de trabajo.
• Visualizador de Kubernetes Engine (roles/container.viewer): Permite que los agentes inspeccionen el clúster, los nodos y los Pods que ejecutaron la carga de trabajo.
• Visualizador de Compute (roles/compute.viewer): Permite que los agentes inspeccionen las VMs de Compute Engine que respaldan los nodos del clúster, incluidos los eventos de mantenimiento y finalización de las VM.
• Visualizador de Monitoring (roles/monitoring.viewer): Permite que los agentes lean las métricas de Cloud Monitoring para los flujos de trabajo que inspeccionan las métricas de cargas de trabajo y nodos.

Para ejecutar el comando /handoff, también necesitas el rol de administrador de objetos de almacenamiento (roles/storage.objectAdmin) en el bucket de Cloud Storage que compartes con la Atención al cliente de Cloud. Este rol permite que los agentes suban hallazgos al bucket y lo supervisen para detectar actualizaciones.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Configura la wiki

1. Clona el repositorio y navega a su directorio raíz:

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

   La wiki usa rutas de acceso relativas a la raíz del repositorio, por lo que debes ejecutar los comandos y, luego, iniciar el agente desde este directorio.

2. Crea y activa un entorno virtual de Python, y, luego, instala las dependencias de la wiki:

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

3. Crea credenciales predeterminadas de la aplicación (ADC) locales para tu cuenta de usuario. Las herramientas de Python de la wiki usan ADC para consultar Cloud Logging:

   gcloud auth application-default login
   

4. Para verificar tu configuración, ejecuta el linter de la wiki:

   python3 _wiki/wiki_linter.py
   

   El linter verifica la estructura, los esquemas y los vínculos de la wiki y, luego, imprime un informe JSON. Si el informe contiene "status": "PASS", la verificación se realizó correctamente. Las advertencias del informe no afectan el estado.

Soluciona problemas de una carga de trabajo

Sigue estos pasos para solucionar problemas de una carga de trabajo con la wiki de depuración de cargas de trabajo de AA:

1. Inicia tu agente desde la raíz del repositorio de la wiki de depuración de cargas de trabajo de AA:

   • Claude Code: En la shell en la que activaste el entorno virtual, ejecuta claude. Claude Code carga las instrucciones de la wiki desde CLAUDE.md y sus definiciones de comandos y subagentes desde el directorio .claude/.
   • Antigravity: Abre la raíz del repositorio como tu espacio de trabajo. Las definiciones de la habilidad y el subagente de Antigravity de la wiki se encuentran en el directorio _agents/. Para obtener detalles de la configuración, consulta _agents/QUICKSTART.md.

2. Ejecuta el comando /troubleshoot y especifica el nombre de la carga de trabajo o el JobSet que deseas diagnosticar:

   /troubleshoot WORKLOAD_ID
   

3. Proporciona al agente el ID del proyecto y el período de la ejecución. Puedes proporcionar un período preciso en formato de marca de tiempo UTC (YYYY-MM-DDTHH:MM:SSZ) o períodos relativos en lenguaje natural, como "hace una hora" o "últimas 24 horas". Los agentes usan el período para definir el alcance de sus consultas de registros, así que asegúrate de que abarque toda la ejecución.

Los flujos de trabajo de diagnóstico ejecutan verificaciones de solo lectura de forma predeterminada. Antes de que el agente ejecute una acción que modifique el estado del clúster, como reiniciar o marcar un nodo, solicita tu confirmación explícita. Cada comando se debe revisar y aprobar. Estas acciones se marcan con requires_approval: true en sus definiciones en _wiki/actions/. El agente informa sus hallazgos una vez que se completa el diagnóstico.

Para aprender a evaluar los hallazgos, incluido cómo reconocer un resultado no concluyente, consulta _wiki/TUTORIAL.md.