TRC TPU all-in-one (Edição delegada para IA)

última-verificação: 2026-06-11 (a matriz de comandos / versões de runtime / quotaId variam com o GCP; verifique a data de verificação aqui + CHANGELOG.md)

O que é isto: você acabou de receber uma cota de TPU gratuita do Google TRC (TPU Research Cloud), e quer pular o console web do Google Cloud e a documentação e deixar uma IA solicitar, conectar e executar a TPU para você diretamente da linha de comando. Este arquivo é a folha de instruções completa para a IA — todas as armadilhas foram testadas em campo antecipadamente.

Como usar:

Usuários do Claude Code: coloque esta pasta em ~/.claude/skills/tpu-trc-setup/ e diga "configuração TPU TRC" na conversa para ativá-la

Codex / outras IAs: cole o texto completo deste arquivo na conversa, ou coloque-o em um repositório para a IA ler, depois diga "configure a TPU para mim seguindo isto"

Linhas vermelhas (tanto a IA quanto humanos devem obedecer):

Exclua apenas recursos que você mesmo criou — o projeto pode ser compartilhado, e excluir a TPU de outra pessoa significa excluir o experimento dela

As configurações de rede (sub-rede / Roteador / NAT) são recursos compartilhados no nível do projeto; pergunte ao proprietário do projeto antes de alterá-los

Exclua quando terminar — os chips TPU são gratuitos, mas a VM/o disco é cobrado por hora, e um nó ocioso durante a noite é dinheiro real

Use sua própria conta do Google durante todo o processo; nunca peça a ninguém uma senha / chave privada / chave de conta de serviço

1. [Preencha isto primeiro] Suas informações

Meu e-mail da conta Google:  <SEU_EMAIL>
Meu ID do projeto GCP:         <SEU_PROJECT_ID>     # o projeto onde a cota TRC foi injetada
Meu papel:                   <Proprietário / Editor>      # Editor é suficiente

[Cole abaixo seu e-mail de aprovação do TRC] (O assunto geralmente é "Welcome to the TPU Research Cloud"):

<cole o texto completo do e-mail TRC>

Passo um para a IA: analise o e-mail TRC acima e produza uma tabela de cotas antes de começar o trabalho:

Campo	Onde encontrar no e-mail
Tipo de TPU (v2/v3/v4/v5e/v6e) + contagem de chips	lista de cotas no corpo do e-mail
zona para cada cota	mesmo local (uma cota é válida apenas na zona nomeada, sem troca)
sob demanda vs preemptível/spot	mesmo local (spot pode ser interrompido a qualquer momento)
período de validade	geralmente 30 dias a partir da aprovação

Obrigações do TRC: você deve publicar resultados publicamente (artigo / código aberto / postagem em blog) + dar feedback ao Google sobre sua experiência. Para problemas, entre em contato com [email protected] ou o canal #tpu-research-cloud no Discord da Comunidade de Desenvolvedores Google.

2. Ambiente único (máquina local)

# 2.1 Instale o Google Cloud SDK (pule se já estiver instalado): https://cloud.google.com/sdk/docs/install
gcloud version

# 2.2 Os comandos de fila de TPU estão no componente alpha — deve instalar
gcloud components install alpha

# 2.3 Faça login + defina o projeto padrão
gcloud auth login <SEU_EMAIL>
gcloud config set project <SEU_PROJECT_ID>
gcloud auth list                       # confirme que a conta ativa é a sua
gcloud config get-value project        # confirme que o projeto está correto

# 2.4 (opcional) Alguns SDKs Python precisam do ADC
gcloud auth application-default login

Armadilha: em um ambiente de execução de IA gcloud geralmente não está no PATH, gerando gcloud: command not found. Execute esta linha primeiro e use $GCLOUD em todo o restante do arquivo:

export GCLOUD=$(which gcloud || echo /opt/homebrew/bin/gcloud)   # caminho comum do homebrew no mac

3. Varredura de pré-trabalho (evitar criar duplicatas / excluir coisas de outros)

# Escaneie cada zona que aparece no e-mail TRC
for zone in <zona1> <zona2> <zona3>; do
  echo "=== $zone ==="
  $GCLOUD alpha compute tpus queued-resources list \
    --project=<SEU_PROJECT_ID> --zone=$zone \
    --format="table(name, state.state, tpu.nodeSpec[].node.acceleratorType)" 2>/dev/null
done

Já ACTIVE → pule diretamente para §7 e use, não crie um novo
Um recurso com prefixo de nome de outra pessoa → deixe-o quieto

4. Pré-verificação de rede (necessário apenas para TPUs grandes com ≥16 hosts, ex.: v5e-64 / v6e-64)

Contexto: a cota de IP externo de um projeto GCP por região tem como padrão apenas 8, enquanto v5e-64 / v6e-64 precisa de 16 IPs de host. Criar sem lidar com isso falhará com o limite IN_USE_ADDRESSES FALHOU. TPUs pequenas (v4-32 tem apenas 4 hosts / v2-8 v3-8 de host único) não precisam desta seção.

# 4.1 Verifique a cota IP atual (confirme se o limite é 8)
$GCLOUD compute project-info describe --project=<SEU_PROJECT_ID> \
  --format="table(quotas.filter(metric:IN_USE_ADDRESSES))"

# 4.2 Correção: criar com IPs internos (--internal-ips, veja §5), que não usa cota de IP externo.
#     Pré-requisito A: a sub-rede padrão da região tem o Acesso Privado do Google ativado (para baixar libtpu)
$GCLOUD compute networks subnets update default \
  --region=<REGIAO> --enable-private-ip-google-access --project=<SEU_PROJECT_ID>

#     Pré-requisito B: a região precisa de um Cloud Router + Cloud NAT (para pip install; PGA não cobre PyPI)
$GCLOUD compute routers create my-tpu-router \
  --network=default --region=<REGIAO> --project=<SEU_PROJECT_ID>
$GCLOUD compute routers nats create my-tpu-nat \
  --router=my-tpu-router --region=<REGIAO> \
  --auto-allocate-nat-external-ips --nat-all-subnet-ip-ranges \
  --project=<SEU_PROJECT_ID>

⚠️ Todos os três comandos em 4.2 são configurações compartilhadas no nível do projeto. Em um projeto compartilhado, primeiro pergunte ao proprietário se eles já estão configurados (configurados uma vez = permanente), e não os recrie.

Sintoma oculto de NAT ausente: mais tarde, quando um worker instala dependências (ex.: jax), o pip relata Could not find a version that satisfies the requirement jax[tpu] mas o script pode ainda dizer "concluído" — esta é uma falha silenciosa do pip, não um problema de versão; volte e adicione o NAT.

5. Criar a TPU (fila)

Matriz de comandos

TPU	`--accelerator-type`	`--runtime-version`	contagem de hosts	precisa de `--internal-ips`?
v2-8	`v2-8`	`tpu-ubuntu2204-base`	1	não
v3-8	`v3-8`	`tpu-ubuntu2204-base`	1	não
v4-32	`v4-32`	`tpu-ubuntu2204-base`	4	não
v5e-64	`v5litepod-64`	`v2-alpha-tpuv5-lite`	16	sim
v6e-64	`v6e-64`	`v2-alpha-tpuv6e`	16	sim

O runtime-version é atualizado ao longo do tempo. Quando você encontrar um erro de versão: primeiro verifique com $GCLOUD alpha compute tpus versions list --zone=<ZONA> (⚠️ testado em campo: a lista é incompleta — v2-alpha-tpuv5-lite pode não estar na lista, mas é realmente utilizável; trate a lista apenas como referência), e se ainda não corresponder, verifique os documentos oficiais (§10).

Spot (use para cota preemptível)

$GCLOUD alpha compute tpus queued-resources create <nome da fila, ex.: my-v5e-qr> \
  --node-id=<NOME_VM, ex.: my-v5e-vm> \
  --project=<SEU_PROJECT_ID> --zone=<ZONA> \
  --accelerator-type=<da tabela acima> \
  --runtime-version=<da tabela acima> \
  --provisioning-model=SPOT \
  --internal-ips          # adicione apenas para TPUs com ≥16 hosts, como v5e-64/v6e-64

Armadilha (dependente da versão): em SDKs mais antigos, spot deve ser escrito como --provisioning-model=SPOT; escrever --spot / --best-effort gera STANDARD provisioning model é incompatível com solicitações spot. Em SDKs mais novos (testado em campo na versão 562.0.0) --spot funciona, então qualquer um está correto. Quando estiver em dúvida, use --provisioning-model=SPOT (reconhecido por todas as versões).

Sob demanda (use para cota não preemptível, mais estável)

$GCLOUD alpha compute tpus queued-resources create <nome da fila> \
  --node-id=<NOME_VM> \
  --project=<SEU_PROJECT_ID> --zone=<ZONA> \
  --accelerator-type=<da tabela acima> \
  --runtime-version=<da tabela acima> \
  --guaranteed

Estratégia de solicitação

Fan-out entre zonas: se o mesmo tipo de cota existe em várias zonas → coloque uma solicitação em fila em paralelo em cada zona que tem cota (testado em campo: cotas por zona em diferentes zonas são mutuamente independentes e não exclusivas; o GCP oficialmente também incentiva a distribuição de spot entre várias zonas)
Sem duplicação de fila na mesma zona: enfileirar duas solicitações do mesmo tipo em uma zona é inútil (mesmo pool de capacidade, sem ganho de velocidade, e colide com os mesmos slots de cota por zona)
Assim que uma for solicitada, cancele imediatamente as restantes perdedoras: caso contrário, as perdedoras permanecem na nuvem e continuam na fila, e assim que uma se torna ACTIVE a VM começa a queimar dinheiro (chips grátis ≠ máquina grátis)
Confirme que a zona tem cota antes de enfileirar: uma zona sem cota (verifique a cota em §4.5 abaixo) sempre falhará se enfileirada — puro desperdício
Uma zona relatando no more capacity → não é um erro de comando; troque de zona, não tente novamente rapidamente na mesma zona
Para modelos com oferta restrita como v6e, a experiência diz que eles são "slot único" (enfileire um de cada vez e ele preenche) — não os espalhe amplamente junto com outros modelos ao mesmo tempo
Após uma solicitação spot, a sobrevivência média é de algumas horas → use-a assim que for solicitada e faça backup dos resultados prontamente

Primeiro verifique se uma zona tem cota (evite fila desperdiçada; requer `gcloud components install beta`)

# cota por zona preemptível v5e (para outros modelos, substitua o quotaId correspondente, veja documentos oficiais §10)
$GCLOUD beta quotas info describe TPUV5sPreemptibleLitepodPerProjectPerZoneForTPUAPI \
  --service=tpu.googleapis.com --project=<SEU_PROJECT_ID> \
  --format="yaml(quotaId,dimensionsInfos)"

Leia o valor por zona em dimensionsInfos: '64' = suficiente para uma fatia de 64 chips / '0' = zero explícito / ausente (details: {}) = essa zona não recebeu cota, enfileirar sempre falhará. (quotaId é uma API beta; o ID pode mudar entre versões do SDK; se uma versão antiga não o reconhecer, execute primeiro gcloud beta quotas info list para obter o ID real.)

6. Esperando: a máquina de estados

# Poll (a cada 30s é suficiente, não faça poll com muita frequência)
$GCLOUD alpha compute tpus queued-resources describe <nome da fila> \
  --project=<SEU_PROJECT_ID> --zone=<ZONA> --format="value(state.state)"

Estado	Significado	Excluível?	O que fazer
`ACCEPTED`	na fila	✅	espere
`WAITING_FOR_RESOURCES`	em fila por capacidade (minutos a horas)	✅	espere
`PROVISIONING`	alocando hardware	❌ não pode excluir	espere (testado em campo: pode travar por 2h+ e ainda ter sucesso — isso é normal)
`ACTIVE`	pronto	✅	vá para §7 imediatamente
`SUSPENDED`	spot foi interrompido	✅	exclua + re-enfileire (testado em campo: esperar pela recuperação automática é essencialmente inútil)
`FAILED`	criação falhou	✅	descreva primeiro para ver a causa raiz, depois decida (classificação de três categorias abaixo; não re-enfileire cegamente)

Armadilha: chamar delete no estado PROVISIONING gera DeleteQueuedResource não é suportado quando o estado é PROVISIONING; você só pode esperar que se torne ACTIVE ou FAILED.

Classificação de FAILED em três categorias (decida "re-enfileirar" vs "parar"; não re-enfileire cegamente)

gcloud alpha compute tpus queued-resources describe <QR> — leia o erro e classifique em três baldes:

Categoria	Critério (error.message)	Significado	Ação
capacidade (re-tentar)	`code: 8` `no more capacity in the zone` / `GCE_STOCKOUT` / `ZONE_RESOURCE_POOL_EXHAUSTED`	cota existe, mas a zona está sem capacidade no momento	exclua + mude/re-enfileire, cubra com fan-out em várias zonas
estrutural (parar)	`PERMISSION_DENIED ... billing` / `billingEnabled: false` / `Limit: 0` / `RESOURCE_EXHAUSTED` / `NO_VALID_BILLING_ACCOUNT`	cota não concedida / cobrança desligada / problema de permissão	pare, não re-enfileire (nunca terá sucesso); verifique a cobrança ou entre em contato com TRC/proprietário
desconhecido	qualquer outra coisa	nunca visto antes	por padrão, tente uma re-enfileirada de capacidade única e observe

Comandos de auto-verificação de projeto/cobrança: $GCLOUD beta billing projects describe <SEU_PROJECT_ID> (veja billingEnabled), $GCLOUD projects describe <SEU_PROJECT_ID>. billingEnabled: false derruba toda a API TPU, mesmo que a cota ainda esteja lá.

Comando de exclusão (use antes de re-enfileirar e depois de terminar):

$GCLOUD alpha compute tpus queued-resources delete <nome da fila> \
  --project=<SEU_PROJECT_ID> --zone=<ZONA> --force --quiet

7. Usar a TPU

# Obter o nome da VM (o node-id que você definiu em §5)
$GCLOUD compute tpus describe <NOME_VM> --zone=<ZONA> \
  --project=<SEU_PROJECT_ID> --format="yaml(serviceAccount, network, state, acceleratorType)"

# SSH para a VM
$GCLOUD compute ssh <NOME_VM> --zone=<ZONA> --project=<SEU_PROJECT_ID> --tunnel-through-iap

# Ou, se a VM tiver IP externo:
$GCLOUD compute ssh <NOME_VM> --zone=<ZONA> --project=<SEU_PROJECT_ID>

# Verificar se os chips TPU estão visíveis
sudo lspci | grep -i accelerat
# ou
ls /dev/accel*

# Instalar JAX com suporte TPU
pip install "jax[tpu]" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html

# Teste rápido
python3 -c "import jax; print(jax.devices())"

8. Limpeza (IMPORTANTE — fazer sempre depois de usar)

# Excluir o recurso enfileirado (e a VM)
$GCLOUD alpha compute tpus queued-resources delete <nome da fila> \
  --project=<SEU_PROJECT_ID> --zone=<ZONA> --force --quiet

# Verificar se a VM foi excluída
$GCLOUD compute tpus list --zone=<ZONA> --project=<SEU_PROJECT_ID>

9. Solução de problemas

Sintoma	Causa mais provável	Solução
`gcloud: command not found`	`gcloud` não está no PATH	Execute `export GCLOUD=$(which gcloud
`PERMISSION_DENIED`	Problemas de permissão IAM	Verifique se o e-mail tem papel `Editor`; verifique faturamento; contate proprietário do projeto
`IN_USE_ADDRESSES limit`	Cota de IP externo excedida (≥16 hosts)	Use `--internal-ips` com Cloud Router + NAT (veja §4)
`Could not find a version [...] jax[tpu]`	NAT ausente fazendo pip falhar	Verifique §4.2 e adicione Cloud NAT
A fila fica em `PROVISIONING` para sempre	Espera normal por alocação	Pode levar horas — é normal. Continue esperando ou cancele e tente outra zona.
`code: 8` `no more capacity`	Zona sem capacidade no momento	Mude de zona ou espere; não tente novamente rapidamente na mesma zona.

10. Referências

Nota final: Esta skill foi projetada para ser segura e eficiente para uso em primeira mão por IA. Siga as linhas vermelhas e as instruções cuidadosamente.

TRC TPU All-in-One (Edição para IA)

O que é TRC TPU All-in-One (Edição para IA)?

Perguntar na sua IA favorita

Documentação

TRC TPU all-in-one (Edição delegada para IA)

1. [Preencha isto primeiro] Suas informações

2. Ambiente único (máquina local)

3. Varredura de pré-trabalho (evitar criar duplicatas / excluir coisas de outros)

4. Pré-verificação de rede (necessário apenas para TPUs grandes com ≥16 hosts, ex.: v5e-64 / v6e-64)

5. Criar a TPU (fila)

Matriz de comandos

Spot (use para cota preemptível)

Sob demanda (use para cota não preemptível, mais estável)

Estratégia de solicitação

Primeiro verifique se uma zona tem cota (evite fila desperdiçada; requer `gcloud components install beta`)

6. Esperando: a máquina de estados

Classificação de FAILED em três categorias (decida "re-enfileirar" vs "parar"; não re-enfileire cegamente)

7. Usar a TPU

8. Limpeza (IMPORTANTE — fazer sempre depois de usar)

9. Solução de problemas

10. Referências

Habilidades Relacionadas

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

Perguntar na sua IA favorita

Documentação

TRC TPU all-in-one (Edição delegada para IA)

1. [Preencha isto primeiro] Suas informações

2. Ambiente único (máquina local)

3. Varredura de pré-trabalho (evitar criar duplicatas / excluir coisas de outros)

4. Pré-verificação de rede (necessário apenas para TPUs grandes com ≥16 hosts, ex.: v5e-64 / v6e-64)

5. Criar a TPU (fila)

Matriz de comandos

Spot (use para cota preemptível)

Sob demanda (use para cota não preemptível, mais estável)

Estratégia de solicitação

Primeiro verifique se uma zona tem cota (evite fila desperdiçada; requer gcloud components install beta)

6. Esperando: a máquina de estados

Classificação de FAILED em três categorias (decida "re-enfileirar" vs "parar"; não re-enfileire cegamente)

7. Usar a TPU

8. Limpeza (IMPORTANTE — fazer sempre depois de usar)

9. Solução de problemas

10. Referências

Habilidades Relacionadas

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

Primeiro verifique se uma zona tem cota (evite fila desperdiçada; requer `gcloud components install beta`)