TRC TPU 全能一體機 (AI 委託版)
最後驗證: 2026-06-11(指令矩陣 / 執行時期版本 / quotaId 會隨著 GCP 而變動；請在此處 + CHANGELOG.md 檢查驗證日期)
這是什麼：您剛從 Google TRC (TPU 研究雲端) 收到免費 TPU 配額， 而且您想跳過 Google Cloud 網頁主控台和文件，讓 AI 直接從命令列為您領取、連接並執行 TPU。 此檔案是提供給 AI 的完整說明書 — 每個潛在陷阱都已事先經過實測。
如何使用：
- Claude Code 使用者：將此資料夾放入
~/.claude/skills/tpu-trc-setup/，並在對話中輸入「TRC TPU setup」來觸發- Codex / 其他 AI：將此檔案的全部內容貼到對話中，或將其放在一個 AI 可讀取的儲存庫中，然後說「按照此說明為我設定 TPU」
紅線 (AI 和人類都必須遵守)：
- 僅刪除您自己建立的資源 — 專案可能是共用的，刪除他人的 TPU 就是刪除他們的實驗
- 網路設定 (子網路 / Router / NAT) 是專案層級的共用資源；在變更前請先詢問專案擁有者
- 用完即刪 — TPU 晶片免費，但 VM/磁碟是按小時計費，一個閒置的節點過夜就是實際的金錢支出
- 全程使用您自己的 Google 帳戶；切勿向任何人索取密碼 / 私鑰 / 服務帳戶金鑰
1. [請先填寫此處] 您的資訊
我的 Google 帳戶電子郵件： <YOUR_EMAIL>
我的 GCP 專案 ID： <YOUR_PROJECT_ID> # 注入 TRC 配額的專案
我的角色： <Owner / Editor> # Editor 就已足夠
[在下方貼上您的 TRC 核准電子郵件] (主旨通常是「Welcome to the TPU Research Cloud」)：
<貼上完整的 TRC 電子郵件文字>
AI 第一步：在開始工作前，解析上述 TRC 電子郵件並產生一個配額表：
| 欄位 | 在電子郵件中的位置 |
|---|---|
| TPU 類型 (v2/v3/v4/v5e/v6e) + 晶片數量 | 電子郵件主體中的配額列表 |
| 每個配額的可用區域 (zone) | 同一位置 (一個配額僅在指定的 zone 中有效，不可互換) |
| 隨需 vs 可搶占/Spot | 同一位置 (Spot 可在任何時候被搶占) |
| 有效期 | 通常為核准日起 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 <YOUR_EMAIL>
gcloud config set project <YOUR_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 電子郵件中出現的每個 zone
for zone in <zone1> <zone2> <zone3>; do
echo "=== $zone ==="
$GCLOUD alpha compute tpus queued-resources list \
--project=<YOUR_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。\n未處理此情況就直接建立會導致 IN_USE_ADDRESSES limit FAILED 失敗。小型 TPU (v4-32 只有 4 個主機 / 單主機 v2-8 v3-8) 不需要此章節。
# 4.1 檢查目前的 IP 配額 (確認限制是否為 8)
$GCLOUD compute project-info describe --project=<YOUR_PROJECT_ID> \
--format="table(quotas.filter(metric:IN_USE_ADDRESSES))"
# 4.2 修正：使用內部 IP (--internal-ips，參見 §5) 建立，完全不使用外部 IP 配額。
# 先決條件 A：該區域的預設子網路已啟用 Private Google Access (以便拉取 libtpu)
$GCLOUD compute networks subnets update default \
--region=<REGION> --enable-private-ip-google-access --project=<YOUR_PROJECT_ID>
# 先決條件 B：該區域需要一個 Cloud Router + Cloud NAT (用於 pip install；PGA 不涵蓋 PyPI)
$GCLOUD compute routers create my-tpu-router \
--network=default --region=<REGION> --project=<YOUR_PROJECT_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=<YOUR_PROJECT_ID>
⚠️ 第 4.2 節中的所有三個指令都是專案層級的共用設定。在共用專案中，請先詢問擁有者這些是否已設定好 (設定一次 = 永久有效)，並且不要重新建立它們。
缺少 NAT 的隱藏症狀：稍後當 worker 安裝依賴項 (例如 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-8 | v2-8 | tpu-ubuntu2204-base | 1 | 否 |
| v3-8 | v3-8 | tpu-ubuntu2204-base | 1 | 否 |
| v4-32 | v4-32 | tpu-ubuntu2204-base | 4 | 否 |
| v5e-64 | v5litepod-64 | v2-alpha-tpuv5-lite | 16 | 是 |
| v6e-64 | v6e-64 | v2-alpha-tpuv6e | 16 | 是 |
runtime-version 會隨著時間更新。當您遇到版本錯誤時：首先 使用
$GCLOUD alpha compute tpus versions list --zone=<ZONE>檢查 (⚠️ 經實測：列表不完整 —v2-alpha-tpuv5-lite可能不在列表中但實際上可用；請僅將列表視為參考)， 如果仍然不匹配，請檢查官方文件 (§10)。
Spot (用於可搶占配額)
$GCLOUD alpha compute tpus queued-resources create <佇列名稱，例如 my-v5e-qr> \
--node-id=<VM_NAME，例如 my-v5e-vm> \
--project=<YOUR_PROJECT_ID> --zone=<ZONE> \
--accelerator-type=<來自上方表格> \
--runtime-version=<來自上方表格> \
--provisioning-model=SPOT \
--internal-ips # 僅對 ≥16 主機的 TPU 添加，例如 v5e-64/v6e-64
陷阱 (版本相關)：在較舊的 SDK 上，搶占必須寫成
--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_NAME> \
--project=<YOUR_PROJECT_ID> --zone=<ZONE> \
--accelerator-type=<來自上方表格> \
--runtime-version=<來自上方表格> \
--guaranteed
領取策略
- 跨區域扇出 (Cross-zone fanout)：如果相同類型的配額存在於多個區域 → 在有配額的每個區域中並行排隊一個請求 (經實測：不同區域的每個區域配額是相互獨立且非排他的；GCP 官方也鼓勵將 spot 分散到多個區域)
- 相同區域內不要重複排隊：在一個區域內為相同類型排隊兩個請求是沒有意義的 (同一容量池，不會加速，並且會與相同的每個區域配額槽衝突)
- 一旦一個被領取，立即取消其餘失敗的請求：否則失敗的請求會留在雲端並持續排隊，一旦某個進入
ACTIVE狀態，VM 就會開始燒錢 (免費晶片 ≠ 免費機器) - 排隊前確認該區域有配額：沒有配額的區域 (請在下方 §4.5 檢查配額) 如果排隊總是會 FAILED — 純屬浪費
- 區域回報
no more capacity→ 不是指令錯誤；請切換區域，不要在相同區域內快速重試 - 對於供應緊張的型號，例如 v6e，經驗表明它們是「單槽」的 (一次只排隊一個，然後它就會被填滿) — 不要同時將它們與其他型號廣泛分散
- 領取 spot 後，平均存活時間為幾小時 → 領取後立即使用它，並及時備份結果
首先檢查區域是否有配額 (避免浪費排隊；需要 gcloud components install beta)
# v5e 每個區域的可搶占配額 (對於其他型號，請替換為匹配的 quotaId，請參閱 §10 官方文件)
$GCLOUD beta quotas info describe TPUV5sPreemptibleLitepodPerProjectPerZoneForTPUAPI \
--service=tpu.googleapis.com --project=<YOUR_PROJECT_ID> \
--format="yaml(quotaId,dimensionsInfos)"
讀取 dimensionsInfos 中的每個區域值：'64' = 足夠一個 64 晶片切片 / '0' = 明確為零 /
缺失 (details: {}) = 該區域未被授予配額，排隊總是會 FAILED。
(quotaId 是一個 beta API；ID 可能因 SDK 版本而異；如果舊版本無法識別，請先執行 gcloud beta quotas info list 來取得真實 ID。)
6. 等待：狀態機
# 輪詢 (每 30 秒一次就夠了，不要太頻繁)
$GCLOUD alpha compute tpus queued-resources describe <佇列名稱> \
--project=<YOUR_PROJECT_ID> --zone=<ZONE> --format="value(state.state)"
| 狀態 | 意義 | 可刪除？ | 要做什麼 |
|---|---|---|---|
ACCEPTED | 在佇列中 | ✅ | 等待 |
WAITING_FOR_RESOURCES | 正在等待容量分配 (幾分鐘到幾小時) | ✅ | 等待 |
PROVISIONING | 正在分配硬體 | ❌ 無法刪除 | 等待 (經實測：可能停滯超過 2 小時但仍然成功 — 這是正常現象) |
ACTIVE | 已就緒 | ✅ | 立即前往 §7 |
SUSPENDED | Spot 被搶占 | ✅ | 刪除 + 重新排隊 (經實測：等待自動恢復基本上無望) |
FAILED | 建立失敗 | ✅ | 先執行 describe 查看根本原因，然後決定 (下方三種分類；不要盲目重新排隊) |
陷阱：在
PROVISIONING狀態下呼叫 delete 會拋出DeleteQueuedResource is not supported when state is PROVISIONING；您只能等待它變成 ACTIVE 或 FAILED。
FAILED 三種分類 (決定「重新排隊」vs「停止」；不要盲目重新排隊)
gcloud alpha compute tpus queued-resources describe <QR> — 讀取錯誤並歸類為三個類別：
| 類別 | 標準 (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 <YOUR_PROJECT_ID>(查看billingEnabled)，$GCLOUD projects describe <YOUR_PROJECT_ID>。billingEnabled: false會使整個 TPU API 癱瘓，即使配額仍然存在。
刪除指令 (在重新排隊前以及完成後都可以使用)：
$GCLOUD alpha compute tpus queued-resources delete <佇列名稱> \
--project=<YOUR_PROJECT_ID> --zone=<ZONE> --force --quiet
可選：w
…
[為翻譯而截斷]