ACT 모델 구조 / lerobot 데이터셋 디렉터리 구조 / Fine-tuning 가중치 위치

[2201042 장성진]

1. ACT (Action Chunking Transformer) 모델 구조 배경

• Zhao et al.의 논문("Learning Fine-Grained Bimanual Manipulation with Low-Cost Hardware")에서 나온 모델
• lerobot에서 처음 시작할 때 권장하는 첫 정책 — 파라미터 ~80M로 가볍고, 단일 GPU로 몇 시간이면 학습 가능
• 소스 코드 위치: src/lerobot/policies/act/modeling_act.py

전체 구조: CVAE(Conditional VAE) + Transformer

① CVAE 인코더 (학습 시에만 사용)

• 입력: [CLS] 토큰 + 현재 관절 위치 + 정답 행동 시퀀스(길이 k)
• BERT 스타일 Transformer encoder(양방향 self-attention, 디코더 없음)를 통과
• [CLS] 토큰이 self-attention으로 나머지 모든 토큰의 정보를 흡수해서 "시퀀스 전체를 요약한 문맥 벡터"가 됨
• 이 CLS 출력을 linear layer에 통과시켜 **잠재변수 z의 평균(μ)·분산(σ)**을 계산
• reparameterization trick으로 z 샘플링: z = μ + σ × ε (ε은 표준정규분포에서 뽑은 랜덤 노이즈)
• z(32차원, style variable)는 "이 시범이 어떤 스타일이었는지"(접근 각도, 속도 등)를 담은 값
• 학습 중 KL divergence로 z들의 분포가 표준정규분포(평균 0)에 가깝도록 강제됨

② CVAE 디코더 (=실제 정책, 학습·추론 둘 다 사용)

1. 비전 처리: 카메라 이미지 → ResNet-18 → feature map → 펼쳐서 시퀀스화 + 2D positional embedding
2. Transformer 인코더(융합): 이미지 feature + 로봇 관절 상태 + z(학습 시 실제 z / 추론 시 0)를 이어붙여서 self-attention → "현재 상황을 종합한 context" 생성
3. Transformer 디코더: k개의 학습된 위치 쿼리(1번째 시점 담당, 2번째 시점 담당, ...)가 cross-attention으로 context를 참조해서, 각자 자기 시점의 행동을 병렬로 동시에 예측
4. 출력: k × 자유도 크기의 텐서 (미래 k스텝의 행동 시퀀스, action chunk)

추론 시 z=0 고정

• 추론 땐 정답 행동이 없어서 인코더 자체를 못 씀 → z를 그냥 0(상수)으로 대입
• 0이 안전한 이유: 학습 중 KL divergence로 "z들이 0 근처에 분포"하도록 이미 훈련해뒀기 때문에, 0이 "여러 스타일의 평균적이고 무난한 값"이 되도록 미리 준비됨
• z=0은 확률분포가 아니라, 그냥 고정된 숫자값

기존 Transformer와의 차이

항목	원조 Transformer	ACT
입력	텍스트 토큰	이미지 feature + 관절 상태 + z
위치 임베딩	1D sin/cos	2D sin/cos (이미지용)
디코더 방식	autoregressive(순차 생성, 이전 출력 되먹임)	병렬(k개 동시 생성, 서로 직접 의존 안 함)
확률적 요소	없음	CVAE(z)로 다양성 반영
출력	단어 확률분포(분류)	관절각 연속값(회귀)

• k개 위치가 병렬로 예측되지만, 학습 시 "k개 전체를 정답과 동시에 비교"하기 때문에, 결과적으로 부드럽게 이어지는 궤적 패턴이 파라미터에 학습됨 (사람 시범 자체가 이미 부드러운 움직임이었기 때문)

Temporal ensembling

• 매 제어 시점마다 새로 k개 행동을 예측하는데, 로봇은 일부만 실행하고 다시 예측하므로 여러 예측이 겹치는 구간이 생김
• 이 겹치는 구간의 예측값들을 평균 내서 부드럽고 안정적인 동작을 만드는 후처리 기법

과적합 vs 일반화

• 모델이 배우는 건 "정확한 사례를 사진 찍듯 암기"가 아니라, "물체가 대략 여기 있으면 팔을 대략 이렇게 움직이는 게 자연스럽다"는 일반화된 패턴
• 과적합(암기)되면 학습 데이터와 조금만 달라도(카메라 각도, 물체 위치 변화) 전혀 대응 못 함 → 실전에서 못 씀

2. lerobot 데이터셋 디렉터리 구조

v2.1 (에피소드당 파일 하나씩)

dataset_name/
├── meta/
│   ├── info.json          ★ 스키마의 권위 있는 원천 (features, fps, 경로 템플릿)
│   ├── episodes.jsonl      ★ 에피소드별 정보(길이, task), 커스텀 필드 추가 지점
│   ├── episodes_stats.jsonl
│   └── tasks.jsonl
├── data/chunk-000/
│   ├── episode_000000.parquet   (상태/행동값)
│   └── ...
└── videos/chunk-000/카메라_key/
    ├── episode_000000.mp4
    └── ...

v3.0 ( 여러 에피소드를 큰 파일에 통합, lerobot ≥0.4.0 )

dataset/
├── meta/
│   ├── info.json          ★
│   ├── stats.json
│   ├── tasks.parquet
│   └── episodes/chunk-000/file-000.parquet   ★ (에피소드 메타데이터, chunked)
├── data/chunk-000/file-000.parquet   (여러 에피소드 통합)
└── videos/카메라_key/chunk-000/file-000.mp4   (여러 에피소드 통합)

• v2.1은 에피소드 수백만 개로 커지면 파일 개수 폭증 → 파일시스템 부담
• v3.0은 관련 데이터를 큰 파일로 묶고, 에피소드 경계는 메타데이터 오프셋으로 탐색

표준성과 강제성

• 강제되는 부분: meta/data/videos 3분류 기본 골격, meta/info.json의 스키마 규약 — 안 지키면 LeRobotDataset 로딩 자체가 실패
• 확장 가능한 부분: info.json, episodes.jsonl(v2.1) / episodes/*.parquet(v3.0)에 커스텀 필드 추가는 자유 (예: AgiBotWorld의 key_frame, instruction_segments, GalaxeaVLA의 커스텀 feature명)
• data/, videos/ 폴더 자체는 정해진 형식을 그대로 따라야 함(확장 대상 아님)

3. Fine-tuning 되는 가중치의 위치 

outputs/train/{job_name}/checkpoints/{step 또는 last}/pretrained_model/
├── config.json          # 정책 설정 직렬화
├── model.safetensors    # ← 실제 가중치 파일 (torch.nn.Module 파라미터)
└── train_config.json    # 학습에 쓰인 전체 파라미터

실제로 이 파일 안에 저장된 학습 대상 가중치 (ACT 기준)

구성 요소 내용 사용 시점

ResNet-18	conv 필터들 (ImageNet pretrained에서 시작, 추가 학습됨)	학습·추론
CVAE 인코더	[CLS] 임베딩, projection layer, BERT 스타일 transformer(Wq/Wk/Wv/Wo, FFN), z 계산 linear layer	학습만
CVAE 디코더 입력단	이미지/관절/z projection layer, positional embedding	학습·추론
CVAE 디코더 융합(인코더)	transformer encoder(Wq/Wk/Wv/Wo, FFN)	학습·추론
CVAE 디코더 출력(디코더)	k개 위치 쿼리, cross-attention 가중치, FFN, 출력 projection	학습·추론

• ACT(~80M) 규모: ResNet만 pretrained에서 시작하고, 나머지는 전체가 학습 대상 (파라미터 적어서 "일부만 얼리기" 전략 잘 안 씀)
• 재개 학습: lerobot-train --config_path=.../train_config.json --resume=true
• Hub 업로드: hf upload ${HF_USER}/act_policy outputs/train/.../pretrained_model

큰 모델(VLA)에서의 fine-tuning 전략 차이 — LoRA

• 수십억 파라미터급 모델(pi0.5, GR00T 등)은 전체 fine-tuning 부담이 커서, LoRA(Low-Rank Adaptation) 같은 기법을 씀
• 원리: 원본 가중치 W는 고정(freeze)하고, "변화량(ΔW)"을 훨씬 작은 두 행렬 A(512×r), B(r×512)의 곱으로 근사해서 그 A, B만 학습
• "저랭크(low-rank)"는 이 변화량이 실제로는 몇 가지 핵심 패턴만으로 충분히 표현 가능하다는 수학적 근거
• ACT처럼 작은 모델은 이 기법이 굳이 필요 없어 — 전체 fine-tuning 자체가 이미 가벼움

(추가) ACT 같은 작은 모델도 "나눠서" 학습하는 경우

ACT(~80M) 규모에서는 보통 전체를 다 학습하지만, 그럼에도 일부만 학습시키는(나머지는 얼리는) 경우

나누는 이유	무엇을 얼리나	목적
데이터가 적을 때	ResNet(비전 백본)	과적합 방지, pretrained 지식 보존 — 데이터가 적을 때 이미 잘 학습된 ResNet의 지식을 보존하기 위한 것
기존 작업에서 신규 작업으로 확장	초기 레이어들	학습 시간 단축, 기존 지식 유지
여러 작업을 하나의 베이스로 관리하고 싶을 때	전체 원본	LoRA처럼 작업별 어댑터만 교체 (드묾)

핵심: ACT 규모에서 "나눈다"의 가장 현실적이고 흔한 이유는 LoRA의 원래 목적(자원 절약)이 아니라, 데이터가 적을 때 이미 잘 학습된 ResNet의 지식을 보존하기 위한 것 LoRA 자체는 파라미터가 훨씬 큰 모델(VLA류)에서 자원 절약을 위해 쓰는 게 일반적이고, ACT처럼 작은 모델에서는 "얼릴지 말지"의 판단 기준이 "자원"보다는 "데이터 양과 과적합 방지"에 더 가깝다.

[Sungryul Lee]

- z(32차원, style variable)는 "이 시범이 어떤 스타일이었는지"(접근 각도, 속도 등)를 담은 값
위 문장의 물리적 의미가 무엇인지 찾아볼것
전문가의 시범동작을 측정한 데이터의 평균,분산을 학습하는게 아니고 모든 궤적에 공통적인 특징(잠재변수z로 정의)을 학습한다고 함
훈련데이터의 각 궤적의 시작점과 목표점의 위치가 모두 다르지만 시작위치에서 목표점을 향해가려는 특징은 모든 훈련 궤적 데이터에서 공통임
결국 CVAE 모델은 이 공통적인 특징의 통계적 분포를 학습한다고 함
그럼 어떻게 하면 이런 특성을 학습하게 할수 있는지 로스함수의 관점에서 설명해볼것

- 학습 중 KL divergence로 z들의 분포가 표준정규분포(평균 0)에 가깝도록 강제됨
KL divergence 로스함수는 두개의 확률분포의 차이를 수치화한 로스함수임 따라서 로스를 0으로 만들면 서로다른 2개의 확률분포를 비슷하도록 만든다는 의미
위에서 학습한 모든 훈련 궤적데이터의 공통점을 수치화한 z벡터가 평균이 0이 되도록 분포를 변형한다는 의미