TRC TPU All-in-One (KI-delegierte Ausgabe)

last-verified: 2026-06-11 (Die Befehlstabelle / Laufzeitversionen / quotaId können mit GCP abweichen; prüfen Sie das Verifizierungsdatum hier und in der CHANGELOG.md)

Was dies ist: Sie haben gerade ein kostenloses TPU-Kontingent von Google TRC (TPU Research Cloud) erhalten, und Sie möchten die Google Cloud-Webkonsole und -Dokumentation überspringen und einer KI erlauben, die TPU direkt von der Befehlszeile aus anzufordern, zu verbinden und auszuführen. Diese Datei ist das vollständige Anweisungsblatt für die KI – jede Falle wurde vorab praktisch getestet.

So verwenden Sie es:

Claude Code-Benutzer: Legen Sie diesen Ordner in ~/.claude/skills/tpu-trc-setup/ ab und sagen Sie „TRC TPU Setup“ im Gespräch, um es zu aktivieren

Codex / andere KIs: Fügen Sie den vollständigen Text dieser Datei in das Gespräch ein oder legen Sie ihn in ein Repository, damit die KI ihn lesen kann, und sagen Sie dann „Richte die TPU für mich gemäß dieser Anleitung ein.“

Rote Linien (sowohl KI als auch Menschen müssen sie befolgen):

Löschen Sie nur Ressourcen, die Sie selbst erstellt haben – das Projekt kann gemeinsam genutzt werden, und das Löschen der TPU eines anderen bedeutet das Löschen seines Experiments

Netzwerkeinstellungen (Subnetz / Router / NAT) sind gemeinsam genutzte Ressourcen auf Projektebene; fragen Sie den Projektbesitzer, bevor Sie sie ändern

Löschen Sie sie, wenn Sie fertig sind – TPU-Chips sind kostenlos, aber die VM/Festplatte wird stündlich abgerechnet, und ein im Leerlauf befindlicher Knoten über Nacht kostet echtes Geld

Verwenden Sie durchgängig Ihr eigenes Google-Konto; fragen Sie niemals jemanden nach einem Passwort / privaten Schlüssel / Dienstkonto-Schlüssel

1. [Zuerst ausfüllen] Ihre Informationen

Meine Google-Konto-E-Mail:  <IHRE_EMAIL>
Meine GCP-Projekt-ID:         <IHRE_PROJEKT_ID>     # das Projekt, in das das TRC-Kontingent eingespielt wurde
Meine Rolle:                   <Besitzer / Bearbeiter>      # Bearbeiter ist ausreichend

[Fügen Sie unten Ihre TRC-Genehmigungs-E-Mail ein] (Betreff ist normalerweise „Welcome to the TPU Research Cloud“):

<fügen Sie den vollständigen TRC-E-Mail-Text ein>

KI-Schritt eins: Analysieren Sie die obige TRC-E-Mail und erstellen Sie eine Kontingenttabelle, bevor Sie mit der Arbeit beginnen:

Feld	Wo finden Sie es in der E-Mail
TPU-Typ (v2/v3/v4/v5e/v6e) + Chip-Anzahl	Kontingentliste im E-Mail-Text
Zone für jedes Kontingent	gleiche Stelle (ein Kontingent ist nur in der benannten Zone gültig, kein Wechsel)
On-Demand vs. Preemptible/Spot	gleiche Stelle (Spot kann jederzeit unterbrochen werden)
Gültigkeitsdauer	normalerweise 30 Tage ab Genehmigung

TRC-Verpflichtungen: Sie müssen Ergebnisse öffentlich veröffentlichen (Paper / Open Source / Blogbeitrag) + Google Feedback zu Ihren Erfahrungen geben. Bei Problemen wenden Sie sich an [email protected] oder den #tpu-research-cloud-Kanal im Google Developer Community Discord.

2. Einmalige Umgebung (lokaler Rechner)

# 2.1 Google Cloud SDK installieren (überspringen, falls bereits installiert): https://cloud.google.com/sdk/docs/install
gcloud version

# 2.2 Die TPU-Warteschlangenbefehle befinden sich in der Alpha-Komponente – muss installiert werden
gcloud components install alpha

# 2.3 Anmelden + Standardprojekt festlegen
gcloud auth login <IHRE_EMAIL>
gcloud config set project <IHRE_PROJEKT_ID>
gcloud auth list                       # bestätigen, dass das aktive Konto Ihr eigenes ist
gcloud config get-value project        # bestätigen, dass das Projekt korrekt ist

# 2.4 (optional) Einige Python-SDKs benötigen ADC
gcloud auth application-default login

Falle: In einer KI-Ausführungsumgebung ist gcloud oft nicht im PATH, was zu gcloud: command not found führt. Führen Sie zuerst diese Zeile aus und verwenden Sie $GCLOUD im Rest der Datei:

export GCLOUD=$(which gcloud || echo /opt/homebrew/bin/gcloud)   # üblicher Mac-Homebrew-Pfad

3. Vorbereitungs-Scan (vermeiden Sie Duplikate / Löschen von Ressourcen anderer)

# Jede Zone scannen, die in der TRC-E-Mail erscheint
for zone in <zone1> <zone2> <zone3>; do
  echo "=== $zone ==="
  $GCLOUD alpha compute tpus queued-resources list \
    --project=<IHRE_PROJEKT_ID> --zone=$zone \
    --format="table(name, state.state, tpu.nodeSpec[].node.acceleratorType)" 2>/dev/null
done

Bereits ACTIVE → direkt zu §7 springen und nutzen, keine neue erstellen
Eine Ressource mit dem Namenspräfix einer anderen Person → in Ruhe lassen

4. Netzwerkvorbereitung (nur große TPUs mit ≥16 Hosts benötigen dies, z. B. v5e-64 / v6e-64)

Hintergrund: Das externe IP-Kontingent eines GCP-Projekts pro Region beträgt standardmäßig nur 8, während v5e-64 / v6e-64 16 Host-IPs benötigt. Das Erstellen ohne Behandlung schlägt fehl mit einem IN_USE_ADDRESSES limit FAILED. Kleine TPUs (v4-32 hat nur 4 Hosts / Single-Host v2-8 v3-8) benötigen diesen Abschnitt nicht.

# 4.1 Aktuelles IP-Kontingent prüfen (bestätigen, ob das Limit 8 ist)
$GCLOUD compute project-info describe --project=<IHRE_PROJEKT_ID> \
  --format="table(quotas.filter(metric:IN_USE_ADDRESSES))"

# 4.2 Lösung: Mit internen IPs erstellen (--internal-ips, siehe §5), was kein externes IP-Kontingent verbraucht.
#     Voraussetzung A: Das Standard-Subnetz der Region hat Private Google Access aktiviert (um libtpu zu ziehen)
$GCLOUD compute networks subnets update default \
  --region=<REGION> --enable-private-ip-google-access --project=<IHRE_PROJEKT_ID>

#     Voraussetzung B: Die Region benötigt einen Cloud Router + Cloud NAT (für pip install; PGA deckt PyPI nicht ab)
$GCLOUD compute routers create my-tpu-router \
  --network=default --region=<REGION> --project=<IHRE_PROJEKT_ID>
$GCLOUD compute routers nats create my-tpu-nat \
  --router=my-tpu-router --region=<REGION> \
  --auto-allocate-nat-external-ips --nat-all-subnet-ip-ranges \
  --project=<IHRE_PROJEKT_ID>

⚠️ Alle drei Befehle in 4.2 sind gemeinsam genutzte Einstellungen auf Projektebene. Fragen Sie in einem gemeinsam genutzten Projekt zuerst den Besitzer, ob sie bereits konfiguriert sind (einmal konfiguriert = dauerhaft), und erstellen Sie sie nicht neu.

Verstecktes Symptom fehlender NAT: Wenn später ein Worker Abhängigkeiten installiert (z. B. jax), meldet pip Could not find a version that satisfies the requirement jax[tpu], aber das Skript sagt möglicherweise trotzdem „done“ — dies ist ein stiller pip-Fehler, kein Versionsproblem; gehen Sie zurück und fügen Sie die NAT hinzu.

5. TPU erstellen (Warteschlange)

Befehlstabelle

TPU	`--accelerator-type`	`--runtime-version`	Host-Anzahl	benötigt `--internal-ips`?
v2-8	`v2-8`	`tpu-ubuntu2204-base`	1	nein
v3-8	`v3-8`	`tpu-ubuntu2204-base`	1	nein
v4-32	`v4-32`	`tpu-ubuntu2204-base`	4	nein
v5e-64	`v5litepod-64`	`v2-alpha-tpuv5-lite`	16	ja
v6e-64	`v6e-64`	`v2-alpha-tpuv6e`	16	ja

Die Laufzeitversion aktualisiert sich im Laufe der Zeit. Wenn ein Versionsfehler auftritt: zuerst mit $GCLOUD alpha compute tpus versions list --zone=<ZONE> prüfen (⚠️ praktisch getestet: die Liste ist unvollständig — v2-alpha-tpuv5-lite ist möglicherweise nicht in der Liste, aber tatsächlich verwendbar; behandeln Sie die Liste nur als Referenz), und wenn es immer noch nicht übereinstimmt, die offizielle Dokumentation prüfen (§10).

Spot (für Preemptible-Kontingent verwenden)

$GCLOUD alpha compute tpus queued-resources create <Warteschlangenname, z.B. my-v5e-qr> \
  --node-id=<VM_NAME, z.B. my-v5e-vm> \
  --project=<IHRE_PROJEKT_ID> --zone=<ZONE> \
  --accelerator-type=<aus obiger Tabelle> \
  --runtime-version=<aus obiger Tabelle> \
  --provisioning-model=SPOT \
  --internal-ips          # nur für TPUs mit ≥16 Hosts wie v5e-64/v6e-64 hinzufügen

Falle (versionsabhängig): In älteren SDKs muss Spot als --provisioning-model=SPOT geschrieben werden; die Verwendung von --spot / --best-effort führt zu STANDARD provisioning model is incompatible with spot requests. In neueren SDKs (praktisch getestet auf 562.0.0) funktioniert --spot ebenfalls, also ist beides in Ordnung. Im Zweifelsfall --provisioning-model=SPOT verwenden (von allen Versionen erkannt).

On-Demand (für nicht-preemptibles Kontingent, am stabilsten)

$GCLOUD alpha compute tpus queued-resources create <Warteschlangenname> \
  --node-id=<VM_NAME> \
  --project=<IHRE_PROJEKT_ID> --zone=<ZONE> \
  --accelerator-type=<aus obiger Tabelle> \
  --runtime-version=<aus obiger Tabelle> \
  --guaranteed

Anforderungsstrategie

Zonenübergreifende Aufteilung: Wenn das gleiche Kontingent in mehreren Zonen existiert → eine Anforderung parallel in jeder Zone stellen, die Kontingent hat (praktisch getestet: Zonenkontingente in verschiedenen Zonen sind voneinander unabhängig und nicht exklusiv; GCP empfiehlt offiziell auch, Spot auf mehrere Zonen zu verteilen)
Keine doppelte Warteschlangenbildung in derselben Zone: Das Einreihen von zwei Anforderungen desselben Typs in einer Zone ist sinnlos (gleicher Kapazitätspool, keine Beschleunigung, und es kollidiert mit den gleichen Zonenkontingent-Slots)
Sobald eine angenommen ist, sofort die verbleibenden Verlierer stornieren: Andernfalls bleiben sie in der Cloud und warten weiter, und sobald eine ACTIVE wird, beginnt die VM Geld zu verbrennen (kostenlose Chips ≠ kostenlose Maschine)
Bestätigen, dass die Zone Kontingent hat, bevor Sie eine Warteschlange erstellen: Eine Zone ohne Kontingent (Kontingent in §4.5 unten prüfen) wird bei der Warteschlangenbildung immer FAILED sein – reine Verschwendung
Eine Zone, die no more capacity meldet → kein Befehlfehler; Zone wechseln, nicht schnell in derselben Zone wiederholen
Für Modelle mit knappem Angebot wie v6e zeigt die Erfahrung, dass sie „Single-Slot“ sind (eine nach der anderen in die Warteschlange stellen und es füllt sich) – breit streuen Sie sie nicht gleichzeitig mit anderen Modellen
Nach einer Spot-Anforderung beträgt die durchschnittliche Lebensdauer ein paar Stunden → nutzen Sie sie sofort nach der Annahme und sichern Sie Ergebnisse zeitnah

Zuerst prüfen, ob eine Zone Kontingent hat (verschwendete Warteschlangenbildung vermeiden; erfordert `gcloud components install beta`)

# v5e Preemptible-pro-Zone-Kontingent (für andere Modelle die passende quotaId einsetzen, siehe §10 offizielle Dokumentation)
$GCLOUD beta quotas info describe TPUV5sPreemptibleLitepodPerProjectPerZoneForTPUAPI \
  --service=tpu.googleapis.com --project=<IHRE_PROJEKT_ID> \
  --format="yaml(quotaId,dimensionsInfos)"

Lese den Pro-Zone-Wert in dimensionsInfos: '64' = ausreichend für einen 64-Chip-Slice / '0' = explizite Null / fehlend (details: {}) = dieser Zone wurde kein Kontingent gewährt, die Warteschlangenbildung wird immer FAILED sein. (quotaId ist eine Beta-API; die ID kann sich zwischen SDK-Versionen ändern; wenn eine alte Version sie nicht erkennt, führen Sie zuerst gcloud beta quotas info list aus, um die tatsächliche ID zu erhalten.)

6. Warten: Die Zustandsmaschine

# Abfragen (alle 30s ist ausreichend, nicht zu oft abfragen)
$GCLOUD alpha compute tpus queued-resources describe <Warteschlangenname> \
  --project=<IHRE_PROJEKT_ID> --zone=<ZONE> --format="value(state.state)"

Zustand	Bedeutung	Löschbar?	Was zu tun ist
`ACCEPTED`	in der Warteschlange	✅	warten
`WAITING_FOR_RESOURCES`	wartet auf Kapazität (Minuten bis Stunden)	✅	warten
`PROVISIONING`	Hardware wird zugewiesen	❌ kann nicht gelöscht werden	warten (praktisch getestet: kann 2h+ dauern und trotzdem erfolgreich sein – das ist normal)
`ACTIVE`	bereit	✅	sofort zu §7 gehen
`SUSPENDED`	Spot wurde unterbrochen	✅	löschen + erneut in die Warteschlange stellen (praktisch getestet: auf automatische Wiederherstellung zu warten ist im Wesentlichen hoffnungslos)
`FAILED`	Erstellung fehlgeschlagen	✅	zuerst beschreiben, um die Ursache zu sehen, dann entscheiden (Dreier-Klassifizierung unten; nicht blind erneut in die Warteschlange stellen)

Falle: Das Aufrufen von delete im Zustand PROVISIONING führt zu DeleteQueuedResource is not supported when state is PROVISIONING; Sie können nur warten, bis es ACTIVE oder FAILED wird.

FAILED-Dreier-Klassifizierung (entscheiden Sie „erneut in die Warteschlange stellen“ vs. „stoppen“; nicht blind erneut in die Warteschlange stellen)

gcloud alpha compute tpus queued-resources describe <QR> — den Fehler lesen und in drei Eimer sortieren:

Kategorie	Kriterium (error.message)	Bedeutung	Aktion
Kapazität (Wiederholung)	`code: 8` `no more capacity in the zone` / `GCE_STOCKOUT` / `ZONE_RESOURCE_POOL_EXHAUSTED`	Kontingent vorhanden, aber die Zone ist gerade ausgelastet	löschen + Zone wechseln/erneut in die Warteschlange stellen, mit Multi-Zonen-Aufteilung absichern
Strukturell (Stopp)	`PERMISSION_DENIED ... billing` / `billingEnabled: false` / `Limit: 0` / `RESOURCE_EXHAUSTED` / `NO_VALID_BILLING_ACCOUNT`	Kontingent nicht gewährt / Abrechnung aus / Berechtigungsproblem	stoppen, nicht erneut in die Warteschlange stellen (wird nie erfolgreich sein); Abrechnung prüfen oder TRC/Besitzer kontaktieren
Unbekannt	alles andere	noch nie gesehen	Standardmäßig eine einzelne Kapazitäts-Wiederholung und dann beobachten

Abrechnungs-/Projekt-Selbstprüfungsbefehle: $GCLOUD beta billing projects describe <IHRE_PROJEKT_ID> (auf billingEnabled achten), $GCLOUD projects describe <IHRE_PROJEKT_ID>. billingEnabled: false legt die gesamte TPU-API lahm, selbst wenn das Kontingent noch vorhanden ist.

Löschbefehl (verwenden Sie ihn sowohl vor dem erneuten Einreihen als auch nach Abschluss):

$GCLOUD alpha compute tpus queued-resources delete <Warteschlangenname> \
  --project=<IHRE_PROJEKT_ID> --zone=<ZONE> --force --quiet

Optional: w …

[gekürzt für die Übersetzung]

TRC-TPU-All-in-One (KI-delegierte Ausgabe)

Was ist TRC-TPU-All-in-One (KI-delegierte Ausgabe)?

In Ihrer bevorzugten KI fragen

Dokumentation