Hugging Face 오픈소스 LLM을 AWS 스팟 인스턴스 기본으로 서빙하는 AWS CDK 템플릿. 초기 타겟: upstage/Solar-Open2-250B.
설계 문서: docs/superpowers/specs/2026-07-23-token-forge-design.md
사용자 ──HTTP──> ALB ──> ASG(min1/max1, p5.48xlarge Spot, 멀티 AZ)
└─ EC2: DLAMI + Docker(upstage/vllm-solar-open2)
├─ 부팅: S3 가중치 캐시 → 없으면 HF 다운로드 후 S3 시딩
└─ vLLM OpenAI 호환 서버 (--api-key = Secrets Manager)
- p5 스팟 vCPU 쿼터 192개 — 대부분 계정 기본 0. Service Quotas에서 "All P Spot Instance Requests"(L-7212CCBC) 상향 신청 필요. 신규 계정은 부분 승인이 흔하므로 EC2 쿼터 증설 요청 가이드 의 어필 문안 작성법 참고.
- 비용 참고: p5.48xlarge 스팟 약 $30~50/hr (리전·시점 변동). 사용 후
cdk destroy권장. - Node 20+, AWS CDK CLI (
npm i -g aws-cdk), 부트스트랩된 계정(cdk bootstrap).
npm install
cdk deploy -c model=solar-open2-250b -c profile=int4 -c region=us-east-2
# 옵션: -c profile=bf16 -c alertEmail=you@example.com첫 부팅은 HF 다운로드 + S3 시딩으로 오래 걸린다(INT4 ~150GB). 이후 재프로비저닝은 S3 캐시에서 s5cmd 로드로 단축(목표 ~15분).
API_KEY=$(aws secretsmanager get-secret-value \
--secret-id <ApiKeySecretArn 출력값> --query SecretString --output text)
scripts/smoke-test.sh <EndpointUrl 출력값> "${API_KEY}"OpenAI SDK: base_url="<EndpointUrl>/v1", api_key=${API_KEY}.
models/<model-name>.yaml 1개 추가 → cdk deploy -c model=<model-name> -c profile=<profile>.
스키마는 models/solar-open2-250b.yaml 참고 (vllmImage, profiles.<name>.{weightsRepo,instanceType,vllmFlags,maxModelLen}).
| 증상 | 확인 |
|---|---|
| 30분 넘게 InService 0 (SNS 알람) | p5 스팟 쿼터/용량 부족. Service Quotas·다른 리전 검토 |
| 인스턴스가 계속 교체됨 | SSM 세션 접속 → cat /var/log/token-forge-boot.log, docker logs vllm (OOM 등). vLLM 컨테이너 로그는 CloudWatch Logs 그룹 /token-forge/vllm에서도 확인 가능 (인스턴스 종료 후에도 보존) |
| 스팟 중단 알림 수신 | 정상 — ASG가 자동 재프로비저닝. S3 캐시로 ~15분 내 복구 |
| HF 다운로드 3회 실패 | 로그 확인 후 인스턴스 종료(ASG 교체) 또는 네트워크 점검 |
- 유휴 자동 셧다운(기본 켜짐): ALB 요청이 30분간 없으면 인스턴스를 자동으로 0대로 내리고 SNS로 알린다.
간격 변경
-c idleMinutes=60, 비활성화-c idleMinutes=0. - 수동 온/오프:
scripts/stop.sh <stack-name> <region> # GPU 비용 정지 (ALB/S3만 유지, ~$16/월) scripts/start.sh <stack-name> <region> # 재기동 — S3 캐시로 수 분~15분 내 서비스 복귀
- 장기 미사용:
cdk destroy권장. S3 가중치 캐시는 Retain으로 남아 재배포 시 고속 부팅.
오토스케일링 없음(min1/max1), 웹 UI 없음, HTTPS는 도메인+ACM 필요로 향후 과제 (현재 HTTP + API 키 — 민감 데이터에는 사용 금지).