5.15 트러블슈팅

dataset이 load되지 않는다

• 수집/변환 뒤 finalize()를 호출했는가?
• meta/info.json의 codebase version과 설치 LeRobot이 호환되는가?
• path를 손으로 만들지 않고 API가 제공한 template을 썼는가?
• Parquet footer와 MP4 index가 정상적으로 닫혔는가?

영상과 관절이 어긋난다

• frame index가 아니라 timestamp로 연결했는가?
• camera buffering latency와 motor timestamp clock source가 같은가?
• variable frame rate video를 constant rate로 가정하지 않았는가?
• action이 observation 이전/이후 어느 시점의 command인지 정의했는가?

loss는 감소하지만 로봇이 거의 움직이지 않는다

• action normalization과 inverse normalization이 같은가?
• state/action joint order가 배포 robot과 같은가?
• LoRA alpha/r scaling과 target module을 확인했는가?
• 새 action projection이 실제로 trainable인가?
• dataset에서 정지 frame이 지나치게 많지 않은가?

동작이 떨리거나 chunk 경계에서 튄다

• chunk의 첫 action이 현재 state와 연속적인가?
• temporal ensemble 또는 execution horizon을 비교했는가?
• absolute와 delta action을 혼동하지 않았는가?
• 제어기 자체 rate와 policy rate가 정수비인지 확인했는가?

GPU memory가 부족하다

• batch size를 줄이고 gradient accumulation을 기록한다.
• mixed precision과 activation checkpointing 지원을 확인한다.
• LoRA rank와 target modules를 줄인다.
• image resolution/camera 수를 줄일 때 성능 영향 ablation을 수행한다.
• OOM 직전 run의 partial checkpoint를 신뢰하지 않는다.

inference가 20 Hz를 만족하지 못한다

• capture/preprocess/model/postprocess/communication을 따로 계측한다.
• action chunk queue와 asynchronous worker를 사용한다.
• stale observation과 queue underrun 정책을 정의한다.
• latency를 숨기기 위해 safety check를 제거하지 않는다.