Resolver problemas com o wiki de depuração de cargas de trabalho de ML

O Wiki de depuração de cargas de trabalho de ML é um repositório do GitHub que os agentes de programação de IA usam para resolver problemas de cargas de trabalho de TPU em execução no Google Kubernetes Engine (GKE) com JAX, XLA ou Pathways. O wiki permite que os agentes de IA coletem registros de carga de trabalho, correspondam assinaturas de erro com modos de falha conhecidos, executem fluxos de trabalho de diagnóstico e relatem causas raiz com base em registros. Isso fornece aos agentes as informações necessárias para diagnosticar falhas, travamentos, reinicializações ou preempções de carga de trabalho.

O wiki contém dois tipos de material de referência:

• Páginas de conhecimento: páginas de Markdown que descrevem conceitos, sintomas de falha e as assinaturas de registro, playbooks de solução de problemas e ferramentas de diagnóstico.
• Procedimentos executáveis: ações e fluxos de trabalho JSON. Uma ação é uma única etapa de diagnóstico, como uma consulta de registro ou um comando kubectl. Um fluxo de trabalho executa uma sequência de ações para diagnosticar um modo de falha específico.

Quando você executa o comando /troubleshoot, uma equipe de subagentes especializados faz a triagem dos registros de carga de trabalho, seleciona e executa o fluxo de trabalho que corresponde à falha e verifica cada conclusão em relação aos registros principais. Em seguida, o agente informa a causa raiz, os hosts culpados conforme citados nos registros e uma tabela de falhas que resume cada interrupção.

Arquivos de chave

A tabela a seguir lista os principais arquivos e diretórios no wiki de depuração de cargas de trabalho de ML:

Caminho	Descrição
_wiki/TUTORIAL.md	Um tutorial sobre o que acontece durante um diagnóstico e como avaliar os resultados, incluindo um exemplo prático.
_wiki/INDEX.md	Um catálogo de todas as páginas, ações e fluxos de trabalho no wiki, com um resumo de uma linha de cada um.
_wiki/concepts/	Arquitetura do sistema e conceitos de ciclo de vida de componentes, como o ciclo de vida do programa libtpu, goodput e monitoramento do progresso da carga de trabalho.
_wiki/entities/	Entidades de hardware, software e plataforma, como TPU, GPU, JAX, XLA e Pathways.
_wiki/symptoms/	Modos de falha, as assinaturas de registro deles e como verificar cada um.
_wiki/playbooks/	Estratégias de solução de problemas, fluxogramas de árvore de decisão e armadilhas comuns.
_wiki/tools/	Ferramentas de diagnóstico, scripts e guias de referência de linha de comando.
_wiki/workflows/	Procedimentos de diagnóstico em JSON. Cada fluxo de trabalho executa uma sequência de ações para diagnosticar um modo de falha específico.
_wiki/actions/	Etapas de diagnóstico individuais em JSON, como consultas de registro e comandos kubectl.
_wiki/SCHEMA.md	Os tipos de página, os requisitos de frontmatter e as tags de taxonomia que as páginas da wiki precisam seguir.
_agents/QUICKSTART.md	Detalhes de configuração e envio para usuários do Antigravity.
CLAUDE.md	O layout do espaço de trabalho, as ferramentas de linha de comando e os papéis de subagente para usuários do Claude Code.

Comandos principais

A tabela a seguir lista os comandos que podem ser executados com o wiki:

Comando	Uso	Descrição
/troubleshoot	/troubleshoot WORKLOAD_ID, em que WORKLOAD_ID é o nome da carga de trabalho ou do JobSet.	Diagnostica uma carga de trabalho usando o Cloud Logging, eventos de cluster do GKE, registros do kubelet e registros de nós. Os subagentes de roteador, profissional, revisor e consultor executam o diagnóstico e informam a causa raiz, os hosts culpados conforme citado nos registros e uma tabela de falhas.
/dashboard	/dashboard [TARGET], em que TARGET é um ID do projeto, nome de cluster ou ID de carga de trabalho opcional. Se você omitir TARGET, o painel vai mostrar todos os clusters do GKE no projeto definido na configuração da Google Cloud CLI.	Inicia o painel de capacidade e triagem do GKE, um app da Web local em http://localhost:8080. O comando verifica os clusters em busca do destino e retorna um link para uma visualização de painel filtrada para o destino.
/handoff	/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch] Todos os argumentos, exceto WORKLOAD_ID, são opcionais: CASE_ID: o número do seu caso de suporte. --bucket=BUCKET: o nome do bucket Se você omitir essa sinalização, o agente vai solicitar um bucket. --findings=PATH: o caminho para um arquivo de descobertas existente. Se você definir essa flag, o comando não vai executar /troubleshoot. --no-watch: desativa o monitoramento de buckets.	Empacota as descobertas de /troubleshoot em um bucket do Cloud Storage para compartilhar com o Cloud Customer Care e, em seguida, monitora o bucket em busca de atualizações. Para verificar se há atualizações mais tarde, execute /handoff --watch STORAGE_KEY, em que STORAGE_KEY é o nome da pasta de transferência no bucket.

Pré-requisitos

Antes de configurar o wiki, identifique a carga de trabalho que você quer diagnosticar e anote os seguintes detalhes:

• O nome da carga de trabalho ou do JobSet.
• O ID do projeto do Google Cloud que executa a carga de trabalho.
• O período aproximado da execução a ser diagnosticada.

Instalações

O wiki requer as seguintes instalações:

1. Instale o Python 3, incluindo o módulo venv. O wiki requer o Python 3.9 ou mais recente. No Debian e no Ubuntu, o módulo venv está no pacote python3-venv.
2. Instale e inicialize a Google Cloud CLI.
3. Instale o kubectl e o gke-gcloud-auth-plugin.
4. Instale um dos seguintes agentes de programação de IA. O wiki inclui arquivos de configuração para:
   • Claude Code
   • Google Antigravity

Funções exigidas

Os agentes executam comandos de diagnóstico com suas credenciais do Google Cloud . Para diagnosticar uma carga de trabalho, conceda os seguintes papéis do IAM ao projeto que executa a carga de trabalho:

• Visualizador de registros (roles/logging.viewer): permite que os agentes leiam os registros de auditoria, nó e contêiner da carga de trabalho.
• Leitor do Kubernetes Engine (roles/container.viewer): permite que os agentes inspecionem o cluster, os nós e os pods que executaram a carga de trabalho.
• Leitor do Compute (roles/compute.viewer): permite que os agentes inspecionem as VMs do Compute Engine que dão suporte aos nós do cluster, incluindo eventos de manutenção e encerramento de VMs.
• Leitor do Monitoring (roles/monitoring.viewer): permite que os agentes leiam as métricas do Cloud Monitoring para fluxos de trabalho que inspecionam métricas de carga de trabalho e nó.

Para executar o comando /handoff, você também precisa do papel de Administrador de objetos do Storage (roles/storage.objectAdmin) no bucket do Cloud Storage que você compartilha com o Cloud Customer Care. Esse papel permite que os agentes façam upload de descobertas para o bucket e o monitorem em busca de atualizações.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Configurar o wiki

1. Clone o repositório e navegue até o diretório raiz:

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

   O wiki usa caminhos relativos à raiz do repositório. Portanto, execute os comandos e inicie o agente nesse diretório.

2. Crie e ative um ambiente virtual do Python e instale as dependências do wiki:

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

3. Crie Application Default Credentials (ADC) locais para sua conta de usuário. As ferramentas Python do wiki usam o ADC para consultar o Cloud Logging:

   gcloud auth application-default login
   

4. Verifique sua configuração executando o linter do wiki:

   python3 _wiki/wiki_linter.py
   

   O linter verifica a estrutura, os esquemas e os links do wiki e, em seguida, imprime um relatório JSON. Se o relatório tiver "status": "PASS", a verificação foi bem-sucedida. Os avisos no relatório não afetam o status.

Resolver problemas de uma carga de trabalho

Siga estas etapas para resolver problemas em uma carga de trabalho com o wiki de depuração de carga de trabalho de ML:

1. Inicie o agente na raiz do repositório do Wiki de depuração de cargas de trabalho de ML:

   • Claude Code: no shell em que você ativou o ambiente virtual, execute claude. O Claude Code carrega as instruções do wiki de CLAUDE.md e as definições de comando e subagente do diretório .claude/.
   • Antigravity: abra a raiz do repositório como seu espaço de trabalho. As definições de habilidade e subagente do Antigravity do wiki estão no diretório _agents/. Para detalhes sobre a configuração, consulte _agents/QUICKSTART.md.

2. Execute o comando /troubleshoot, especificando o nome da carga de trabalho ou do JobSet que você quer diagnosticar:

   /troubleshoot WORKLOAD_ID
   

3. Informe ao agente o ID do projeto e o período da execução. É possível fornecer um período preciso no formato de carimbo de data/hora UTC (YYYY-MM-DDTHH:MM:SSZ) ou períodos relativos em linguagem natural, como "há uma hora" ou "nas últimas 24 horas". Os agentes usam o período para definir o escopo das consultas de registro. Portanto, verifique se ele abrange toda a execução.

Por padrão, os fluxos de trabalho de diagnóstico executam verificações somente leitura. Antes de o agente executar uma ação que modifica o estado do cluster, como reiniciar ou aplicar taint em um nó, ele solicita sua confirmação explícita. Cada comando precisa ser analisado e aprovado. Essas ações são marcadas com requires_approval: true nas definições em _wiki/actions/. O agente informa as descobertas após a conclusão do diagnóstico.

Para saber como avaliar as descobertas, incluindo como reconhecer um resultado inconclusivo, consulte _wiki/TUTORIAL.md.