참고 자료
진행자 준비 가이드
Physical AI 로봇 워크숍의 기본 트랙은 참가자 사본에서 로컬 MuJoCo를 실행하고 실제 Bedrock 직접 계획을 연결하는 00–04장, 예상 약 110분입니다. 05–13장의 참가자 AWS 배포는 약 280분, 14–18장의 진행자·운영자 Isaac Sim·EKS는 약 195분을 편성 기준으로 삼습니다. 장별 시간과 트랙별 합계는 준비 상태·배포 대기·실습·질문에 따라 조정합니다. 전체 완료 시한이나 필수 여유 시간은 정하지 않습니다. 각 트랙의 일정·권한·비용은 따로 준비합니다.
수업 전에 준비할 환경
| 항목 | 준비·확인할 내용 |
|---|---|
| 편집기 | 참가자별 VSCode Server 접속과 터미널 |
| 언어 환경 | Node 24.18.1 이상인 24 계열, Python 3.11, npm, uv |
| helper 의존성 | python3 환경의 boto3: doctor --aws에서 사용 |
| AWS CLI | 실제 Bedrock을 켤 때 참가자 실행기의 계정 재확인에 사용 |
| 패키지 | 참가자 npm ci, Python 고정 의존성 설치가 가능한 저장소·캐시 |
| AI 코딩 도구 | 사용할 도구 한 개의 실제 대화 시작·인증 |
| 컴퓨트 | MuJoCo CPU 실습을 여러 참가자가 수행할 수 있는 자원과 여유 디스크 |
| 모델 | 계정·리전·역할로 실제 Converse 구조화 계획 성공 |
| 참가자 경계 | 중복 없는 3–10자 팀 ID, 배정 계정, 충돌 없는 포트 |
| 브라우저 | 참가자 API 포트만 전달하는 접속 방법과 올바른 Origin |
| 증거 보관 | 참가자 .local/evidence/와 RESULTS.md, 종료 담당자 |
Node와 Python이 설치되어 있어도 현재 셸에서 다른 버전을 선택할 수 있습니다.
진행자가 제공한 PATH에서 node --version, python3 --version을 다시 확인합니다.
패키지 설치와 브라우저 다운로드를 수업 중 최초로 수행하지 않도록 준비합니다.
GPU·Docker·AgentCore CLI는 핵심 과정의 필수 도구가 아닙니다.
참가자 사본 준비 리허설
운영 소스 루트에서는 workshop/scripts/lab.py 준비 도구만 사용합니다.
루트의 scripts/deploy.py, cleanup.py, verify-demo.py는 참가자 핵심 실습 명령이 아닙니다.
특히 검증이라는 이름의 스크립트도 실제 운영 사이트에 작업을 생성할 수 있으므로
참가자 사본과 명시적인 주소가 있는 교재 명령을 사용합니다.
리허설 참가자 이름의 예시는 rehearsal입니다.
별도 계정 ID를 확인해 입력하고 기존 참가자 설정을 덮어쓰지 않습니다.
cd /home/ec2-user/my-project/robot-arm
export ROBOT_REPO="$PWD"
export ROBOT_TEAM=rehearsal
export ROBOT_CONFIG="$ROBOT_REPO/workshop/.local/$ROBOT_TEAM.json"
read -r -p "리허설 AWS 계정 ID 12자리: " ROBOT_ACCOUNT_ID
python3 workshop/scripts/lab.py init \
--participant "$ROBOT_TEAM" --account-id "$ROBOT_ACCOUNT_ID" \
--config "$ROBOT_CONFIG"
python3 workshop/scripts/lab.py doctor --config "$ROBOT_CONFIG"
python3 workshop/scripts/lab.py prepare --config "$ROBOT_CONFIG"
python3 workshop/scripts/lab.py info --config "$ROBOT_CONFIG"
프로필이 필요한 환경에서는 init에 배정 프로필의 --profile을 추가합니다.
이미 사본이 있다면 info로 상태를 확인하고 그 사본에서 이어 갑니다.
01장의 환경 변수 블록에서도 같은 리허설 이름을 사용합니다.
준비기의 이름 기반 포트 선택만으로 실제 OS 포트 사용 여부까지 보장되지는 않습니다.
참가자 설정 간 중복 검사와 실제 서버 바인딩을 모두 확인합니다.
필요하면 새 설정을 만들 때 비어 있는 연속 세 포트의 첫 값을 init --api-port에 배정합니다.
이미 준비한 사본의 포트·계정 바인딩을 수동으로 바꾸지 않습니다.
계정·모델 접근 확인
같은 참가자 설정에서 다음을 실행합니다.
python3 "$ROBOT_REPO/workshop/scripts/lab.py" doctor \
--config "$ROBOT_CONFIG" --aws
이 결과는 계정 접근 확인입니다. 이어서 04장과 같은 로컬 API 설정,
동일한 MODEL_ID·역할·프로필로 실제 /api/plan을 확인해야 합니다.
Bedrock 콘솔에 모델이 보이거나 일반 채팅이 성공한 것만으로 리허설을 마치지 않습니다.
이 코드는 Converse.outputConfig.textFormat의 JSON schema 출력을 사용합니다.
해당 모델·추론 프로필과 요청 형식이 실제로 허용되는지 확인합니다.
프로젝트 기본 예시 모델이 배정 계정에서 지원되지 않으면 수업 전에 대체 모델을 검토합니다. 참가자 helper의 검토된 모델 목록과 코드의 구조화 출력 계약을 함께 확인합니다. 현장에서 참가자마다 임의 모델을 순서대로 시도하게 하지 않습니다. 모델 요청 권한과 사용량 한도, 참가자 수에 맞는 호출 분산을 준비합니다. 이 문서는 새로운 IAM 정책이나 계정 단위 모델 설정을 자동 적용하지 않습니다.
기본 자동 검증은 계획 2건·물리 실행 2건입니다. 브라우저 발표 실습과 재시도는 호출 수가 추가되므로 예상 사용량에 포함합니다. 요금·지원 모델·할당량은 행사 시점의 계정과 공식 문서에서 다시 확인합니다.
반드시 해 볼 리허설
- 새 참가자 설정·사본을 만들고 의존성 설치와 빌드를 완료합니다.
- 본인 포트에서 MuJoCo와 규칙 기반 API를 시작합니다.
- PC 브라우저에서 새 단일 물체 실행과 기록 JSON을 확인합니다.
- CLI의 빨간 상자 단독 이동·파랑부터 쌓기·힘 0 실패를 실행합니다.
- 03장의 테스트 파일을 실제로 작성하고 계약 검사·전체 테스트·빌드를 확인합니다.
- 같은 참가자 API를 Bedrock 직접 호출로 전환하고 04장의 두 실행을 확인합니다.
- 서버 프로세스를 종료하고 결과·미완료 항목을 기록합니다.
단계별 시작·종료 시각, 명령, 실제 결과를 남깁니다. 저장소의 기존 운영 검증 기록을 참가자 리허설의 결과로 복사하지 않습니다. 문서 빌드 성공과 소스 단위 검사 통과도 이 전체 리허설을 대신하지 않습니다.
원격 브라우저 준비
브라우저가 사용하는 127.0.0.1은 참가자 PC입니다.
EC2의 루프백 API에 접속하려면 제공된 포트 전달이 필요합니다.
기본 과정은 빌드된 앱과 API가 같은 포트에서 제공되므로 Vite 포트를 따로 열 필요가 없습니다.
MuJoCo 포트는 외부에 노출하지 않습니다.
별도 HTTPS 미리보기 주소를 제공할 때는 경로 접두사가 없는 앱 Origin을 사용합니다.
/proxy/<port>/ 같은 경로 기반 전달은 앱의 절대 경로와 맞지 않을 수 있습니다.
실제 접속 주소를 PUBLIC_ORIGIN으로 설정하고 쿠키·CSRF가 유지되는 새 작업을 확인합니다.
화면 정적 파일만 열리는 것을 API 연결 성공으로 판단하지 않습니다.
이 핵심 실습을 위해 DNS 레코드나 공유 보안 그룹을 바꾸지 않습니다.
04장의 터미널 자동 검증은 루프백 HTTP Origin으로 먼저 수행합니다. HTTPS Origin으로 발급된 Secure 쿠키를 HTTP 검사에 섞으면 세션이 유지되지 않습니다. HTTPS 미리보기 시연은 자동 검증 후 API의 Origin을 전환하고 새 브라우저 세션으로 확인합니다.
단계별 확인과 일정 조정
시계의 누적 경과 대신 다음 단계로 넘어갈 근거를 확인합니다. 실습 반복·질문·휴식과 배포 대기를 반영해 진행자가 일정을 조정합니다.
| 진행 단계 | 확인할 결과 | 조정 방법 |
|---|---|---|
| 00장 · 목표 확인 | 세 트랙의 대상·권한, 물리 성공 기준 | 계획·실행·재생의 차이부터 확인 |
| 01장 · 환경 준비 | 참가자 사본·포트·빌드 | 환경·패키지 문제를 진행자가 처리 |
| 02장 · 새 실행 | 본인 브라우저의 새 단일 물체 실행 | API 준비 상태와 포트 전달·Origin 구분 |
| 02장 · 실패 실험 | 단독 이동·파랑부터 쌓기·힘 0 실패 근거 | CPU 경쟁을 줄이고 실패 기록 보존 |
| 03장 · 계약 확장 | 새 계약 테스트 파일 | 한 거부 사례와 실제 import부터 점검 |
| 03장 · 검토 | 계약 검사와 빌드 | 오류를 고치고 모델 연결 전 상태 기록 |
| 04장 · 모델 연결 | 실제 provider: bedrock 계획과 새 실행 |
모델·권한·물리 오류를 분리 |
| 04장 · 시연 | 시연·결과표·종료 확인 | 미완료 단계와 담당자를 정리하고 질문 시간 확보 |
| 마무리 | 실제 완료 범위 기록 | 성공으로 덮어쓰지 않고 후속 과제 지정 |
무거운 물리 회귀 검사를 모든 참가자가 동시에 시작하면 지연이 커질 수 있습니다. 팀별로 분산하되 실행하지 않은 검사를 통과했다고 기록하지 않습니다. 모델 권한이나 서비스 문제가 계속되면 02–03장 결과를 보존하고 실제 Bedrock 부분을 미완료로 남깁니다. 시뮬레이션 기록만으로 AI 호출까지 완료했다고 표시하지 않습니다.
발표에서 확인할 표현
참가자는 다음 문장을 자신의 결과로 설명할 수 있어야 합니다.
한국어 지시를 허용된 작업 계획으로 만들고, 제어기와 MuJoCo로 새 배치를 실행했습니다. 물체의 들어 올림·놓기·지지·안정성을 기록에서 확인했고, 잡지 못한 경우에는 실패로 남겼습니다.
모델 호출을 하지 못했다면 첫 문장의 계획 제공자를 규칙 기반으로 명시합니다. 학습된 운동 정책, 실물 로봇, 비전 인식 또는 Isaac Sim 검증을 추가로 주장하지 않습니다. 자세한 기준은 Physical AI 범위를 사용합니다.
AWS 배포와 운영자 GPU 트랙 준비
05–13장에서는 참가자별 ECR·S3·DynamoDB·AgentCore·Fargate·CloudFront 구성을 다룹니다.
별도 시간, 계정 권한, 기존 VPC/Subnet, 인증서, 수동 DNS 등록과 정리 담당자가 필요합니다.
운영 robot-atlas·참조 jeju-atlas의 자원을 참가자 배포로 바꾸지 않습니다.
14–18장의 Isaac Sim GPU 트랙은 진행자·운영자 전용입니다.
사용자 지정 gpu-cluster-01, 기존 VPC, Private EKS Auto Mode의 g6e/g7e Spot 배치에서
GPU 준비·복구 실험을 수행합니다.
행사 전에 실제 GPU 가용성, 이미지·라이선스·드라이버 호환성,
장면별 VRAM, 체크포인트와 비용 한도를 확인합니다.
MuJoCo 실습이 완료되었다는 이유로 GPU 호환성이나 Spot 복구 시간을 검증했다고 기록하지 않습니다.
해당 트랙의 생성·정리·복구 절차는 그 트랙의 실제 배포 문서와 검증 기록을 따릅니다.
실제 RTX·물리 실행 근거와 통제된 NodeClaim·Pod 교체 복구 근거를 따로 기록하고,
통제 복구를 실제 EC2 Spot 회수 알림 주입으로 표현하지 않습니다.
핵심 종료 시 참가자는 본인 API·MuJoCo만 중지합니다. 공유 EC2, VPC, NAT, Subnet과 다른 참가자의 프로세스·결과는 정리하지 않습니다.