Communitygithub.com

lijiajie-git/tpu-trc-quickstart

Google TPU Research Cloud (TRC) 無料 TPU のプロビジョニングを、キュー投入からクレーム、SSH、ヘルスチェックまで、1コマンドかつ AI 主導で行います。構成駆動のデーモン設計、現場検証済みのエラーマップを備えたプロビジョン専用ツールです。

tpu-trc-quickstart とは？

これは、Google TRC (TPU Research Cloud) から無料で付与された TPU クォータを、コマンドラインから AI に任せてクレーム、接続、実行まで行うための完全手順書です。GCP の Web コンソールやドキュメントを参照することなく、AI が自動的に TPU をプロビジョニングできるよう、事前に現場で検証されたあらゆる落とし穴を網羅しています。Claude Code、Codex、その他の AI エージェントで動作し、構成ファイルを読み込ませるかスキルフォルダに配置するだけで利用可能です。キュー投入からクレーム、SSH 接続、ヘルスチェックまでを一貫して実行し、容量不足や API バージョンの差異、内部 IP 設定の必要性といった GCP 特有のトラブルにも事前に対処しています。

対応✓Claude Code✓Codex CLI~Cursor
npx skills add lijiajie-git/tpu-trc-quickstart
オリジナルを見る→すべてのスキルを見る

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

ドキュメント

TRC TPU オールインワン（AI 委譲版）

最終確認日: 2026-06-11（コマンドマトリックス、ランタイムバージョン、quotaId は GCP の更新により変動します。ここで確認日と CHANGELOG.md を確認してください）

これは何か: Google TRC（TPU Research Cloud）から無料 TPU クォータを受け取ったら、Google Cloud Web コンソールやドキュメントを調べる代わりに、AI に TPU のクレーム、接続、実行をコマンドラインから丸ごと任せたい場合のためのものです。 このファイルは AI 向けの完全な指示書であり、あらゆる落とし穴は事前に現場検証済みです。

使い方:

  • Claude Code ユーザー: このフォルダを ~/.claude/skills/tpu-trc-setup/ に配置し、会話中に「TRC TPU setup」と発言するとトリガーされます
  • Codex / その他の AI: このファイルの全文を会話に貼り付けるか、リポジトリに置いて AI に読ませ、「これに従って TPU をセットアップして」と指示します

絶対遵守ルール（AI・人間共通）:

  1. 自分が作成したリソースのみ削除すること — プロジェクトは共有されている可能性があり、他人の TPU を削除すると相手の実験が失われます
  2. ネットワーク設定（サブネット/ルーター/NAT）はプロジェクト全体の共有リソースです。変更する前にプロジェクトオーナーに確認すること
  3. 使用後は必ず削除 — TPU チップは無料ですが、VM/ディスクは時間単位で課金され、アイドル状態のマシンを一晩放置すると実際の費用が発生します
  4. 常に自分の Google アカウントを使用し、他人にパスワード/秘密鍵/サービスアカウントキーを要求しないこと

1. [最初に記入] あなたの情報

My Google account email:  <あなたのメールアドレス>
My GCP project ID:         <あなたのプロジェクトID>     # TRC クォータが注入されたプロジェクト
My role:                   <Owner / Editor>      # Editor で十分

[以下に TRC 承認メールを貼り付けてください]（件名は通常 "Welcome to the TPU Research Cloud" です）:

<TRC メール全文を貼り付け>

AI ステップ 1: 上記の TRC メールを解析し、作業開始前にクォータテーブルを生成してください:

フィールドメール内の該当箇所
TPU タイプ (v2/v3/v4/v5e/v6e) + チップ数メール本文のクォータ一覧
各クォータのゾーン同上（クォータは指定ゾーンでのみ有効、変更不可）
オンデマンド vs プリエンプティブ/スポット同上（スポットはいつでもプリエンプトされる可能性あり）
有効期限通常は承認から30日

TRC の義務: 結果を公開（論文/オープンソース/ブログ記事）し、Google にフィードバックを提供する必要があります。 問題が発生した場合は [email protected] または Google Developer Community Discord の #tpu-research-cloud チャンネルまで。

2. 一度だけ必要な環境設定（ローカルマシン）

# 2.1 Google Cloud SDK のインストール（既存の場合はスキップ）: https://cloud.google.com/sdk/docs/install
gcloud version

# 2.2 TPU キューコマンドは alpha コンポーネントに含まれています — インストール必須
gcloud components install alpha

# 2.3 ログイン + デフォルトプロジェクトの設定
gcloud auth login <あなたのメールアドレス>
gcloud config set project <あなたのプロジェクトID>
gcloud auth list                       # アクティブアカウントが自分のものか確認
gcloud config get-value project        # プロジェクトが正しいか確認

# 2.4 （オプション）一部の Python SDK で ADC が必要
gcloud auth application-default login

落とし穴: AI 実行環境では gcloud が PATH にないことが多く、gcloud: command not found が発生します。 まず以下の行を実行し、以降は $GCLOUD を使用してください:

export GCLOUD=$(which gcloud || echo /opt/homebrew/bin/gcloud)   # 一般的な Mac Homebrew のパス

3. 事前スキャン（重複作成 / 他人のリソース削除を防ぐ）

# TRC メールに記載されたすべてのゾーンをスキャン
for zone in <ゾーン1> <ゾーン2> <ゾーン3>; do
  echo "=== $zone ==="
  $GCLOUD alpha compute tpus queued-resources list \
    --project=<あなたのプロジェクトID> --zone=$zone \
    --format="table(name, state.state, tpu.nodeSpec[].node.acceleratorType)" 2>/dev/null
done
  • すでに ACTIVE → §7 に進んでそのまま使用し、新しく作成しないこと
  • 他人の名前プレフィックスが付いたリソース → そのままにしておくこと

4. ネットワーク事前確認（ホスト数が 16 以上の大規模 TPU のみ必要、例: v5e-64 / v6e-64）

背景: GCP プロジェクトのリージョンあたり外部 IP クォータはデフォルトで8のみですが、v5e-64 / v6e-64 には 16 のホスト IP が必要です。 これに対処せずに作成すると IN_USE_ADDRESSES limit で FAILED になります。小規模 TPU（v4-32 はホスト4台 / シングルホスト v2-8 v3-8）はこのセクションは不要です。

# 4.1 現在の IP クォータを確認（制限が 8 かどうか確認）
$GCLOUD compute project-info describe --project=<あなたのプロジェクトID> \
  --format="table(quotas.filter(metric:IN_USE_ADDRESSES))"

# 4.2 修正: 内部 IP （--internal-ips、§5 参照）で作成すれば、外部 IP クォータは消費されません。
#     前提条件 A: リージョンのデフォルトサブネットで Private Google Access が有効であること（libtpu の pull に必要）
$GCLOUD compute networks subnets update default \
  --region=<リージョン> --enable-private-ip-google-access --project=<あなたのプロジェクトID>

#     前提条件 B: リージョンに Cloud Router + Cloud NAT が必要（pip install 用、PGA は PyPI をカバーしません）
$GCLOUD compute routers create my-tpu-router \
  --network=default --region=<リージョン> --project=<あなたのプロジェクトID>
$GCLOUD compute routers nats create my-tpu-nat \
  --router=my-tpu-router --region=<リージョン> \
  --auto-allocate-nat-external-ips --nat-all-subnet-ip-ranges \
  --project=<あなたのプロジェクトID>

⚠️ 4.2 の3つのコマンドはすべてプロジェクト全体の共有設定です。共有プロジェクトでは、まずオーナーにこれらがすでに設定されているか確認し（一度設定すれば永続）、再作成しないでください。

NAT 欠落の隠れた症状: 後でワーカーが依存関係（例: jax）をインストールする際、pip が Could not find a version that satisfies the requirement jax[tpu] と報告するのに、スクリプトは「完了」と表示することがあります — これはバージョン問題ではなくpip のサイレント失敗です。戻って NAT を追加してください。

5. TPU の作成（キュー投入）

コマンドマトリックス

TPU--accelerator-type--runtime-versionホスト数--internal-ips 必要？
v2-8v2-8tpu-ubuntu2204-base1いいえ
v3-8v3-8tpu-ubuntu2204-base1いいえ
v4-32v4-32tpu-ubuntu2204-base4いいえ
v5e-64v5litepod-64v2-alpha-tpuv5-lite16はい
v6e-64v6e-64v2-alpha-tpuv6e16はい

ランタイムバージョンは時間とともに更新されます。バージョンエラーが発生した場合: まず $GCLOUD alpha compute tpus versions list --zone=<ゾーン> で確認してください （⚠️ 現場検証済み: リストは不完全です — v2-alpha-tpuv5-lite はリストにない場合もありますが、実際には使用可能です。リストは参考としてのみ扱ってください）、 それでも一致しない場合は公式ドキュメント（§10）を確認してください。

スポット（プリエンプティブルクォータ用）

$GCLOUD alpha compute tpus queued-resources create <キュー名、例: my-v5e-qr> \
  --node-id=<VM名、例: my-v5e-vm> \
  --project=<あなたのプロジェクトID> --zone=<ゾーン> \
  --accelerator-type=<上の表から> \
  --runtime-version=<上の表から> \
  --provisioning-model=SPOT \
  --internal-ips          # v5e-64/v6e-64 などホスト数16以上の場合のみ追加

落とし穴（バージョン依存）: 古い SDK では spot は --provisioning-model=SPOT と記述する必要があり、--spot / --best-effort と書くと STANDARD provisioning model is incompatible with spot requests が発生します。新しい SDK（562.0.0 で検証済み）では --spot も動作するため、どちらでも問題ありません。 不明な場合は --provisioning-model=SPOT（全バージョンで認識されます）を使用してください。

オンデマンド（非プリエンプティブルクォータ、最も安定）

$GCLOUD alpha compute tpus queued-resources create <キュー名> \
  --node-id=<VM名> \
  --project=<あなたのプロジェクトID> --zone=<ゾーン> \
  --accelerator-type=<上の表から> \
  --runtime-version=<上の表から> \
  --guaranteed

クレーム戦略

  • クロスゾーンファンアウト: 同じタイプのクォータが複数のゾーンに存在する場合 → クォータがある各ゾーンに並列で1つのリクエストをキュー投入します （現場検証済み: 異なるゾーンのゾーン別クォータは互いに独立しており、排他的ではありません。GCP 公式でもスポットは複数ゾーンに分散することを推奨しています）
  • 同じゾーンへの重複キュー投入はしない: 同じゾーンに同じタイプのリクエストを複数キュー投入しても無意味です（同じ容量プール、速度向上なし、同じゾーン別クォータスロットに衝突します）
  • 1つがクレームされたら、すぐに残りのロスをキャンセルする: そうしないとロスがクラウドに残ってキューイングを続け、1つが ACTIVE になると VM が課金を開始します（無料チップ ≠ 無料マシン）
  • キュー投入前にゾーンにクォータがあることを確認する: クォータのないゾーン（§4.5 でクォータを確認）にキュー投入すると常に FAILED になります — 完全な無駄です
  • no more capacity と報告されるゾーン → コマンドエラーではありません。ゾーンを切り替え、同じゾーンで急速にリトライしないでください
  • v6e のような供給が逼迫しているモデルでは、経験上「シングルスロット」（一度に1つずつキュー投入して満たされる）です — 他のモデルと同時に広範囲に分散しないでください
  • スポットクレーム後の平均生存時間は数時間です → クレームしたらすぐに使用し、結果は速やかにバックアップしてください

まずゾーンにクォータがあるか確認する（無駄なキュー投入を回避; gcloud components install beta が必要）

# v5e プリエンプティブのゾーン別クォータ（他のモデルの場合は適切な quotaId に置き換えてください。§10 公式ドキュメント参照）
$GCLOUD beta quotas info describe TPUV5sPreemptibleLitepodPerProjectPerZoneForTPUAPI \
  --service=tpu.googleapis.com --project=<あなたのプロジェクトID> \
  --format="yaml(quotaId,dimensionsInfos)"

dimensionsInfos のゾーン別値を確認: '64' = 64チップスライス1つに十分 / '0' = 明示的にゼロ / 欠落（details: {}） = そのゾーンにはクォータが付与されていません、キュー投入は常に FAILED になります。 （quotaId はベータ API であり、SDK バージョンによって ID が変わる可能性があります。古いバージョンで認識されない場合は、まず gcloud beta quotas info list を実行して実際の ID を確認してください。）

6. 待機: ステートマシン

# ポーリング（30秒ごとで十分、あまり頻繁にポーリングしないこと）
$GCLOUD alpha compute tpus queued-resources describe <キュー名> \
  --project=<あなたのプロジェクトID> --zone=<ゾーン> --format="value(state.state)"
状態意味削除可能？どうするべき
ACCEPTEDキュー内✅待機
WAITING_FOR_RESOURCES容量を待機中（数分～数時間）✅待機
PROVISIONINGハードウェアを割り当て中❌ 削除不可待機（現場検証済み: 2時間以上停止しても成功する可能性あり — これは正常です）
ACTIVE準備完了✅すぐに §7 へ
SUSPENDEDスポットがプリエンプトされた✅削除して再キュー投入（現場検証済み: 自動復旧を待つのはほぼ無駄）
FAILED作成失敗✅まず describe で根本原因を確認し、その後判断（以下の3分類に従ってください。盲目的に再キュー投入しないこと）

落とし穴: PROVISIONING 状態での削除は DeleteQueuedResource is not supported when state is PROVISIONING をスローします。ACTIVE または FAILED になるまで待つしかありません。

FAILED の3分類（「再キュー投入」か「停止」かを判断。盲目的に再キュー投入しない）

gcloud alpha compute tpus queued-resources describe <QR> — エラーを読み、以下の3つのカテゴリに分類:

カテゴリ基準 (error.message)意味アクション
容量（リトライ可）code: 8 no more capacity in the zone / GCE_STOCKOUT / ZONE_RESOURCE_POOL_EXHAUSTEDクォータはあるがゾーンに在庫がない削除 + ゾーン切り替え/再キュー投入、マルチゾーンファンアウトでヘッジ
構造的（停止）PERMISSION_DENIED ... billing / billingEnabled: false / Limit: 0 / RESOURCE_EXHAUSTED / NO_VALID_BILLING_ACCOUNTクォータ未付与/課金オフ/権限問題停止、再キュー投入しない（成功しません）。課金または TRC/オーナーに確認
不明その他未確認のエラー一度だけ容量リトライしてから観察

課金/プロジェクトの自己確認コマンド: $GCLOUD beta billing projects describe <あなたのプロジェクトID>（billingEnabled を確認）、 $GCLOUD projects describe <あなたのプロジェクトID>。billingEnabled: false は、クォータがまだ存在していても、TPU API 全体を停止させます。

削除コマンド（再キュー投入前と完了後の両方で使用）:

$GCLOUD alpha compute tpus queued-resources delete <キュー名> \
  --project=<あなたのプロジェクトID> --zone=<ゾーン> --force --quiet

オプション: 省略（原文が途中で切れているため）

関連スキル

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community