Communitygithub.com

lijiajie-git/tpu-trc-퀵스타트

Google TRC(TPU Research Cloud) 무료 TPU를 대기열 → 할당 → SSH → 상태 확인까지 단일 명령어로 AI 기반 프로비저닝하는 도구입니다. 구성 기반 데몬, 현장 검증 오류 맵을 제공합니다.

tpu-trc-퀵스타트란 무엇인가요?

이 스킬은 Google TRC(TPU Research Cloud) 프로그램을 통해 무료 TPU 할당을 받은 개발자가, Google Cloud 웹 콘솔 없이도 명령줄에서 AI 비서(Claude Code, Codex 등)를 활용해 TPU를 신청(Queue), 할당(Claim), SSH 연결 및 상태 확인(Health Check)까지 원클릭으로 수행할 수 있도록 설계되었습니다. 실제 현장에서 발생할 수 있는 모든 오류 상황(용량 부족, 할당량 초과, 버전 불일치 등)이 사전에 테스트되어 명령어 매트릭스와 오류 분류표(용량/구조적/알 수 없는 오류의 세 가지 유형)로 정리되어 있습니다. 여러 GCP 영역(Zone)에 걸친 병렬 큐잉(Fan-out), 대규모 TPU(v5e-64/v6e-64)에 필요한 내부 IP 및 NAT 설정, SPOT/On-demand 프로비저닝 모델 선택 등 고급 기능을 지원하며, 이미 Active 상태인 TPU를 중복 생성하지 않도록 사전 스캔을 수행합니다. 또한, 공유 프로젝트에서 타인의 리소스를 삭제하지 않도록 주의하는 '레드 라인' 규칙을 명시하여 안전한 사용을 보장합니다.

지원 대상✓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 웹 콘솔과 문서를 건너뛰고 AI가 명령줄에서 직접 TPU를 신청하고 연결하고 실행하도록 하고 싶습니다. 이 파일은 AI를 위한 완전한 명령 시트입니다 — 모든 함정이 사전에 현장 테스트되었습니다.

사용 방법:

  • Claude Code 사용자: 이 폴더를 ~/.claude/skills/tpu-trc-setup/에 넣고 대화에서 "TRC TPU 설정"이라고 말하면 트리거됩니다.
  • Codex / 기타 AI: 이 파일의 전체 텍스트를 대화에 붙여넣거나 AI가 읽을 수 있도록 저장소에 넣은 다음, "이것을 따라 TPU를 설정해줘"라고 말하세요.

절대 규칙 (AI와 인간 모두 따라야 함):

  1. 직접 생성한 리소스만 삭제하세요 — 프로젝트가 공유될 수 있으며, 다른 사람의 TPU를 삭제하면 실험이 사라집니다.
  2. 네트워크 설정(서브넷 / 라우터 / NAT)은 프로젝트 수준의 공유 리소스입니다. 변경하기 전에 프로젝트 소유자에게 물어보세요.
  3. 사용이 끝나면 삭제하세요 — TPU 칩은 무료이지만 VM/디스크는 시간당 청구되며, 밤새 유휴 상태로 두면 실제 비용이 발생합니다.
  4. 항상 자신의 Google 계정을 사용하세요. 누구에게도 비밀번호 / 개인 키 / 서비스 계정 키를 요청하지 마세요.

1. [먼저 작성] 사용자 정보

내 Google 계정 이메일:  <YOUR_EMAIL>
내 GCP 프로젝트 ID:       <YOUR_PROJECT_ID>     # TRC 할당이 주입된 프로젝트
내 역할:                  <Owner / Editor>      # Editor이면 충분

[아래에 TRC 승인 이메일을 붙여넣으세요] (제목은 일반적으로 "TPU Research Cloud에 오신 것을 환영합니다"입니다):

<TRC 이메일 전체 텍스트 붙여넣기>

AI 첫 번째 단계: 위 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 <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 이메일에 나타나는 모든 영역 스캔
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가 필요합니다. 이것을 처리하지 않으면 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 설치용; 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의 숨겨진 증상: 나중에 작업자가 종속성을 설치할 때(예: 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=<ZONE>으로 확인하세요. (⚠️ 현장 테스트됨: 목록은 불완전 — v2-alpha-tpuv5-lite는 목록에 없을 수 있지만 실제로는 사용 가능합니다. 목록을 참조용으로만 취급하세요.) 그래도 일치하지 않으면 공식 문서(§10)를 확인하세요.

스팟 (선점형 할당량에 사용)

$GCLOUD alpha compute tpus queued-resources create <큐 이름, 예: my-v5e-qr> \
  --node-id=<VM_이름, 예: my-v5e-vm> \
  --project=<YOUR_PROJECT_ID> --zone=<ZONE> \
  --accelerator-type=<위 표에서> \
  --runtime-version=<위 표에서> \
  --provisioning-model=SPOT \
  --internal-ips          # v5e-64/v6e-64와 같이 호스트가 16개 이상인 TPU에만 추가

함정 (버전 의존적): 이전 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_이름> \
  --project=<YOUR_PROJECT_ID> --zone=<ZONE> \
  --accelerator-type=<위 표에서> \
  --runtime-version=<위 표에서> \
  --guaranteed

할당 전략

  • 교차 영역 팬아웃: 동일한 유형의 할당량이 여러 영역에 있는 경우 → 할당량이 있는 각 영역에 병렬로 요청을 대기열에 넣습니다. (현장 테스트됨: 다른 영역의 영역별 할당량은 상호 독립적이며 배타적이지 않습니다. GCP는 공식적으로도 여러 영역에 스팟을 분산하도록 권장합니다.)
  • 동일 영역에 중복 대기열 금지: 한 영역에 동일한 유형의 요청 두 개를 대기열에 넣는 것은 의미가 없습니다(동일한 용량 풀, 속도 향상 없음, 동일한 영역별 할당량 슬롯과 충돌).
  • 하나가 할당되는 즉시 나머지 대기열을 즉시 취소: 그렇지 않으면 대기열이 클라우드에 남아 계속 대기하게 되고, 하나가 ACTIVE가 되면 VM이 비용을 소모하기 시작합니다(무료 칩 ≠ 무료 머신).
  • 대기열에 넣기 전에 영역에 할당량이 있는지 확인: 할당량이 없는 영역(아래 §4.5에서 할당량 확인)은 대기열에 넣으면 항상 FAILED됩니다 — 순전히 낭비입니다.
  • 영역이 no more capacity를 보고하는 경우 → 명령어 오류가 아닙니다. 영역을 전환하고, 같은 영역에서 빠르게 재시도하지 마세요.
  • v6e와 같이 공급이 빡빡한 모델의 경우 경험상 "단일 슬롯"입니다(한 번에 하나씩 대기열에 넣으면 채워짐). 다른 모델과 동시에 광범위하게 분산하지 마세요.
  • 스팟 할당 후 평균 생존 시간은 몇 시간입니다 → 할당되는 즉시 사용하고 결과를 신속히 백업하세요.

먼저 영역에 할당량이 있는지 확인 (대기열 낭비 방지; 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' = 명시적 0 / 누락 (details: {}) = 해당 영역에 할당량이 부여되지 않음, 대기열에 넣으면 항상 FAILED됩니다. (quotaId는 베타 API입니다. SDK 버전에 따라 ID가 변경될 수 있습니다. 이전 버전이 인식하지 못하면 먼저 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스팟이 선점됨✅삭제 + 재대기 (현장 테스트됨: 자동 복구를 기다리는 것은 본질적으로 희망이 없음)
FAILED생성 실패✅먼저 describe하여 근본 원인을 확인한 다음 결정 (아래 세 가지 분류; 맹목적으로 재대기하지 마세요)

함정: PROVISIONING 상태에서 삭제를 호출하면 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

…

[일부 잘림]

관련 스킬

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