TRC TPU tout-en-un (édition déléguée à l'IA)

dernière-vérification : 2026-06-11 (la matrice des commandes / versions d'exécution / quotaId dérivent avec GCP ; vérifiez la date de vérification ici + CHANGELOG.md)

Ce que c'est : vous venez de recevoir un quota de TPU gratuit de Google TRC (TPU Research Cloud), et vous voulez éviter la console web Google Cloud et la documentation pour laisser une IA réclamer, se connecter et exécuter le TPU directement depuis la ligne de commande. Ce fichier est la feuille d'instructions complète pour l'IA — chaque piège a été testé sur le terrain à l'avance.

Comment l'utiliser :

Utilisateurs de Claude Code : placez ce dossier dans ~/.claude/skills/tpu-trc-setup/ et dites "configuration TPU TRC" dans la conversation pour le déclencher

Codex / autres IA : collez le texte complet de ce fichier dans la conversation, ou placez-le dans un dépôt pour que l'IA le lise, puis dites "configure le TPU pour moi en suivant ceci"

Règles impératives (IA et humains doivent obéir) :

Ne supprimez que les ressources que vous avez créées vous-même — le projet peut être partagé, et supprimer le TPU de quelqu'un d'autre, c'est supprimer son expérience

Les paramètres réseau (sous-réseau / routeur / NAT) sont des ressources partagées au niveau du projet ; demandez au propriétaire du projet avant de les modifier

Supprimez quand vous avez fini — les puces TPU sont gratuites, mais la VM/disque est facturée à l'heure, et un nœud inactif toute une nuit coûte cher

Utilisez votre propre compte Google tout au long ; ne demandez jamais à personne un mot de passe / une clé privée / une clé de compte de service

1. [Remplissez ceci d'abord] Vos informations

Mon adresse email Google :  <VOTRE_EMAIL>
Mon ID de projet GCP :      <VOTRE_ID_PROJET>     # le projet dans lequel le quota TRC a été injecté
Mon rôle :                   <Propriétaire / Éditeur>      # Éditeur suffit

[Collez votre email d'approbation TRC ci-dessous] (L'objet est généralement "Bienvenue dans le TPU Research Cloud") :

<collez le texte complet de l'email TRC>

Étape IA numéro un : analysez l'email TRC ci-dessus et produisez un tableau des quotas avant de commencer le travail :

Champ	Où le trouver dans l'email
Type de TPU (v2/v3/v4/v5e/v6e) + nombre de puces	liste des quotas dans le corps de l'email
zone pour chaque quota	même endroit (un quota est valable uniquement dans la zone nommée, pas d'échange)
à la demande vs préemptible/spot	même endroit (le spot peut être préempté à tout moment)
période de validité	généralement 30 jours à compter de l'approbation

Obligations TRC : vous devez publier les résultats publiquement (article / open source / blog) + donner un retour d'expérience à Google. Pour les problèmes, contactez [email protected] ou le canal #tpu-research-cloud sur le Discord de la communauté des développeurs Google.

2. Environnement unique (machine locale)

# 2.1 Installez le Google Cloud SDK (ignorez si déjà installé) : https://cloud.google.com/sdk/docs/install
gcloud version

# 2.2 Les commandes de file d'attente TPU se trouvent dans le composant alpha — doit être installé
gcloud components install alpha

# 2.3 Connectez-vous + définissez le projet par défaut
gcloud auth login <VOTRE_EMAIL>
gcloud config set project <VOTRE_ID_PROJET>
gcloud auth list                       # confirmez que le compte actif est le vôtre
gcloud config get-value project        # confirmez que le projet est correct

# 2.4 (facultatif) Certains SDK Python ont besoin d'ADC
gcloud auth application-default login

Piège : dans un environnement d'exécution IA, gcloud n'est souvent pas dans le PATH, ce qui génère gcloud: command not found. Exécutez cette ligne d'abord, et utilisez $GCLOUD dans tout le reste du fichier :

export GCLOUD=$(which gcloud || echo /opt/homebrew/bin/gcloud)   # chemin commun mac homebrew

3. Analyse préliminaire (éviter de créer des doublons / supprimer ceux des autres)

# Scannez chaque zone qui apparaît dans l'email TRC
for zone in <zone1> <zone2> <zone3>; do
  echo "=== $zone ==="
  $GCLOUD alpha compute tpus queued-resources list \
    --project=<VOTRE_ID_PROJET> --zone=$zone \
    --format="table(name, state.state, tpu.nodeSpec[].node.acceleratorType)" 2>/dev/null
done

Déjà ACTIVE → passez directement au §7 et utilisez-le, ne créez pas un nouveau
Une ressource avec le préfixe du nom de quelqu'un d'autre → laissez-la tranquille

4. Pré-vérification réseau (nécessaire uniquement pour les grands TPU avec ≥16 hôtes, par ex. v5e-64 / v6e-64)

Contexte : le quota d'adresses IP externes d'un projet GCP par région est limité à seulement 8, alors que v5e-64 / v6e-64 nécessite 16 IP d'hôtes. Créer sans gérer cela échouera avec IN_USE_ADDRESSES limit FAILED. Les petits TPU (v4-32 a seulement 4 hôtes / monohôte v2-8 v3-8) n'ont pas besoin de cette section.

# 4.1 Vérifiez le quota IP actuel (confirmez si la limite est 8)
$GCLOUD compute project-info describe --project=<VOTRE_ID_PROJET> \
  --format="table(quotas.filter(metric:IN_USE_ADDRESSES))"

# 4.2 Solution : créez avec des IP internes (--internal-ips, voir §5), qui n'utilise aucun quota d'IP externe.
#     Prérequis A : le sous-réseau par défaut de la région a l'accès Google privé activé (pour télécharger libtpu)
$GCLOUD compute networks subnets update default \
  --region=<RÉGION> --enable-private-ip-google-access --project=<VOTRE_ID_PROJET>

#     Prérequis B : la région a besoin d'un Cloud Router + Cloud NAT (pour pip install ; PGA ne couvre pas PyPI)
$GCLOUD compute routers create my-tpu-router \
  --network=default --region=<RÉGION> --project=<VOTRE_ID_PROJET>
$GCLOUD compute routers nats create my-tpu-nat \
  --router=my-tpu-router --region=<RÉGION> \
  --auto-allocate-nat-external-ips --nat-all-subnet-ip-ranges \
  --project=<VOTRE_ID_PROJET>

⚠️ Les trois commandes de la section 4.2 sont des paramètres partagés au niveau du projet. Dans un projet partagé, demandez d'abord au propriétaire s'ils sont déjà configurés (configurés une fois = permanents), et ne les recréez pas.

Symptôme caché d'un NAT manquant : plus tard, lorsqu'un worker installe des dépendances (par ex. jax), pip signale Could not find a version that satisfies the requirement jax[tpu] mais le script peut toujours dire "terminé" — c'est un échec silencieux de pip, pas un problème de version ; retournez en arrière et ajoutez le NAT.

5. Créer le TPU (file d'attente)

Matrice de commandes

TPU	`--accelerator-type`	`--runtime-version`	nombre d'hôtes	nécessite `--internal-ips` ?
v2-8	`v2-8`	`tpu-ubuntu2204-base`	1	non
v3-8	`v3-8`	`tpu-ubuntu2204-base`	1	non
v4-32	`v4-32`	`tpu-ubuntu2204-base`	4	non
v5e-64	`v5litepod-64`	`v2-alpha-tpuv5-lite`	16	oui
v6e-64	`v6e-64`	`v2-alpha-tpuv6e`	16	oui

La version d'exécution évolue avec le temps. Lorsque vous rencontrez une erreur de version : vérifiez d'abord avec $GCLOUD alpha compute tpus versions list --zone=<ZONE> (⚠️ testé sur le terrain : la liste est incomplète — v2-alpha-tpuv5-lite peut ne pas être dans la liste mais est en fait utilisable ; traitez la liste comme une référence uniquement), et si cela ne correspond toujours pas, consultez la documentation officielle (§10).

Spot (utilisez ceci pour un quota préemptible)

$GCLOUD alpha compute tpus queued-resources create <nom file d'attente, par ex. my-v5e-qr> \
  --node-id=<NOM_VM, par ex. my-v5e-vm> \
  --project=<VOTRE_ID_PROJET> --zone=<ZONE> \
  --accelerator-type=<depuis le tableau ci-dessus> \
  --runtime-version=<depuis le tableau ci-dessus> \
  --provisioning-model=SPOT \
  --internal-ips          # ajoutez uniquement pour les TPU avec ≥16 hôtes comme v5e-64/v6e-64

Piège (dépend de la version) : sur les anciens SDK, spot doit être écrit comme --provisioning-model=SPOT ; écrire --spot / --best-effort génère STANDARD provisioning model is incompatible with spot requests. Sur les nouveaux SDK (testé sur le terrain version 562.0.0) --spot fonctionne, donc les deux sont acceptables. En cas de doute, utilisez --provisioning-model=SPOT (reconnu par toutes les versions).

À la demande (utilisez ceci pour un quota non préemptible, le plus stable)

$GCLOUD alpha compute tpus queued-resources create <nom file d'attente> \
  --node-id=<NOM_VM> \
  --project=<VOTRE_ID_PROJET> --zone=<ZONE> \
  --accelerator-type=<depuis le tableau ci-dessus> \
  --runtime-version=<depuis le tableau ci-dessus> \
  --guaranteed

Stratégie de réclamation

Fanout multi-zone : si le même type de quota existe dans plusieurs zones → mettez en file d'attente une requête en parallèle dans chaque zone qui a un quota (testé sur le terrain : les quotas par zone dans différentes zones sont mutuellement indépendants et non exclusifs ; GCP encourage officiellement également la répartition du spot sur plusieurs zones)
Pas de mise en file d'attente en double dans la même zone : mettre en file d'attente deux requêtes du même type dans une zone est inutile (même pool de capacité, pas d'accélération, et cela entre en conflit avec les mêmes emplacements de quota par zone)
Dès que l'une est réclamée, annulez immédiatement les perdantes restantes : sinon les perdantes restent dans le cloud et continuent la file d'attente, et une fois que l'une devient ACTIVE, la VM commence à brûler de l'argent (puces gratuites ≠ machine gratuite)
Confirmez que la zone a un quota avant de mettre en file d'attente : une zone sans quota (vérifiez le quota au §4.5 ci-dessous) échouera toujours en FAILED si mise en file d'attente — pure perte de temps
Une zone signalant no more capacity → pas une erreur de commande ; changez de zone, ne réessayez pas rapidement dans la même zone
Pour les modèles à offre restreinte comme v6e, l'expérience montre qu'ils sont "à emplacement unique" (mettez en file d'attente un à la fois et cela se remplit) — ne les répartissez pas largement en même temps que d'autres modèles
Après une réclamation spot, la durée de vie moyenne est de quelques heures → utilisez-le dès que vous le réclamez et sauvegardez les résultats rapidement

Vérifiez d'abord si une zone a un quota (évitez les files d'attente inutiles ; nécessite `gcloud components install beta`)

# Quota par zone préemptible v5e (pour d'autres modèles, remplacez le quotaId correspondant, voir documentation officielle §10)
$GCLOUD beta quotas info describe TPUV5sPreemptibleLitepodPerProjectPerZoneForTPUAPI \
  --service=tpu.googleapis.com --project=<VOTRE_ID_PROJET> \
  --format="yaml(quotaId,dimensionsInfos)"

Lisez la valeur par zone dans dimensionsInfos : '64' = assez pour une tranche de 64 puces / '0' = zéro explicite / manquant (details : {}) = cette zone n'a pas reçu de quota, la mise en file d'attente échouera toujours en FAILED. (quotaId est une API bêta ; l'ID peut changer entre les versions du SDK ; si une ancienne version ne le reconnaît pas, exécutez d'abord gcloud beta quotas info list pour obtenir le vrai ID.)

6. Attente : la machine à états

# Interrogez (toutes les 30s suffisent, n'interrogez pas trop souvent)
$GCLOUD alpha compute tpus queued-resources describe <nom file d'attente> \
  --project=<VOTRE_ID_PROJET> --zone=<ZONE> --format="value(state.state)"

État	Signification	Supprimable ?	Que faire
`ACCEPTED`	dans la file d'attente	✅	attendez
`WAITING_FOR_RESOURCES`	en attente de capacité (minutes à heures)	✅	attendez
`PROVISIONING`	allocation du matériel	❌ ne peut pas être supprimé	attendez (testé sur le terrain : peut stagner 2h+ et encore réussir — c'est normal)
`ACTIVE`	prêt	✅	allez au §7 immédiatement
`SUSPENDED`	le spot a été préempté	✅	supprimez + remettez en file d'attente (testé sur le terrain : attendre une récupération automatique est essentiellement sans espoir)
`FAILED`	la création a échoué	✅	décrivez d'abord pour voir la cause racine, puis décidez (classification en trois catégories ci-dessous ; ne remettez pas en file d'attente aveuglément)

Piège : appeler delete dans l'état PROVISIONING génère DeleteQueuedResource is not supported when state is PROVISIONING ; vous ne pouvez qu'attendre qu'il devienne ACTIVE ou FAILED.

Classification des échecs FAILED en trois catégories (décidez "remettre en file d'attente" vs "arrêter" ; ne remettez pas en file d'attente aveuglément)

gcloud alpha compute tpus queued-resources describe <QR> — lisez l'erreur et classez-la dans trois catégories :

Catégorie	Critère (error.message)	Signification	Action
capacité (réessai)	`code : 8` `no more capacity in the zone` / `GCE_STOCKOUT` / `ZONE_RESOURCE_POOL_EXHAUSTED`	le quota existe mais la zone est en rupture de stock pour le moment	supprimez + changez/remettez en file d'attente, couvrez-vous avec un fanout multi-zone
structurel (arrêt)	`PERMISSION_DENIED ... billing` / `billingEnabled : false` / `Limit : 0` / `RESOURCE_EXHAUSTED` / `NO_VALID_BILLING_ACCOUNT`	quota non accordé / facturation désactivée / problème de permission	arrêtez, ne remettez pas en file d'attente (cela ne réussira jamais) ; vérifiez la facturation ou contactez TRC/propriétaire
inconnu	tout le reste	jamais vu auparavant	par défaut, un seul réessai de capacité, puis observez

Commandes d'auto-vérification de la facturation/projet : $GCLOUD beta billing projects describe <VOTRE_ID_PROJET> (regardez billingEnabled), $GCLOUD projects describe <VOTRE_ID_PROJET>. billingEnabled : false paralyse toute l'API TPU, même si le quota est toujours là.

Commande de suppression (utilisez-la à la fois avant de remettre en file d'attente et après avoir terminé) :

$GCLOUD alpha compute tpus queued-resources delete <nom file d'attente> \
  --project=<VOTRE_ID_PROJET> --zone=<ZONE> --force --quiet

(Facultatif : suite tronquée pour la traduction)

7. Connexion au TPU (SSH) et vérification d'état

...

8. Nettoyage

...

9. Références

...

lijiajie-git/tpu-trc-quickstart

Qu'est-ce que tpu-trc-quickstart ?

Demander à votre IA préférée

Documentation

TRC TPU tout-en-un (édition déléguée à l'IA)

1. [Remplissez ceci d'abord] Vos informations

2. Environnement unique (machine locale)

3. Analyse préliminaire (éviter de créer des doublons / supprimer ceux des autres)

4. Pré-vérification réseau (nécessaire uniquement pour les grands TPU avec ≥16 hôtes, par ex. v5e-64 / v6e-64)

5. Créer le TPU (file d'attente)

Matrice de commandes

Spot (utilisez ceci pour un quota préemptible)

À la demande (utilisez ceci pour un quota non préemptible, le plus stable)

Stratégie de réclamation

Vérifiez d'abord si une zone a un quota (évitez les files d'attente inutiles ; nécessite `gcloud components install beta`)

6. Attente : la machine à états

Classification des échecs FAILED en trois catégories (décidez "remettre en file d'attente" vs "arrêter" ; ne remettez pas en file d'attente aveuglément)

7. Connexion au TPU (SSH) et vérification d'état

8. Nettoyage

9. Références

10. Documentation officielle

Skills associés

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

Demander à votre IA préférée

Documentation

TRC TPU tout-en-un (édition déléguée à l'IA)

1. [Remplissez ceci d'abord] Vos informations

2. Environnement unique (machine locale)

3. Analyse préliminaire (éviter de créer des doublons / supprimer ceux des autres)

4. Pré-vérification réseau (nécessaire uniquement pour les grands TPU avec ≥16 hôtes, par ex. v5e-64 / v6e-64)

5. Créer le TPU (file d'attente)

Matrice de commandes

Spot (utilisez ceci pour un quota préemptible)

À la demande (utilisez ceci pour un quota non préemptible, le plus stable)

Stratégie de réclamation

Vérifiez d'abord si une zone a un quota (évitez les files d'attente inutiles ; nécessite gcloud components install beta)

6. Attente : la machine à états

Classification des échecs FAILED en trois catégories (décidez "remettre en file d'attente" vs "arrêter" ; ne remettez pas en file d'attente aveuglément)

7. Connexion au TPU (SSH) et vérification d'état

8. Nettoyage

9. Références

10. Documentation officielle

Skills associés

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

Vérifiez d'abord si une zone a un quota (évitez les files d'attente inutiles ; nécessite `gcloud components install beta`)