로봇 학습에서는 파일이 생겼다는 사실과 학습에 쓸 수 있다는 사실이 다릅니다. 현재 data/raw/에 있는 HDF5 dry-run 파일은 episode schema가 기록되는지 확인한 결과이지, Franka 정책을 학습하거나 데이터 다양성을 비교할 수 있는 시연 묶음은 아닙니다. 그래서 저는 이 워크스페이스에서 데이터와 모델을 단순한 첨부 파일로 두지 않고, 어떤 조건에서 만들어졌는지와 함께 다룹니다.
data/는 원본에서 학습 입력까지의 단계를 나눕니다
data/raw/에는 원격조작이나 센서에서 바로 나온 episode를, data/synthetic/에는 Isaac Sim이 만든 합성 데이터를, data/processed/에는 필터링·라벨링·train/validation/test 분할을 마친 데이터를 둡니다. 이 구분은 폴더 수를 늘리기 위한 것이 아닙니다. 수집 실패인지, 변환 실패인지, 학습 분할의 문제인지를 다음에 다시 볼 수 있게 하기 위한 경계입니다.
각 데이터셋에는 수집 조건, 로봇과 태스크, 카메라·action의 의미, 성공 판정, 변환 단계, 저장 위치를 메타데이터로 연결합니다. 다른 로봇의 episode를 섞기 전에 하나의 Franka episode 안에서 관측·언어 지시·action이 같은 사건을 가리키는지 먼저 확인하려는 이유도 여기에 있습니다.
데이터 ID는 이 연결의 시작점입니다. 예를 들어 조작 시뮬레이션 데이터라면 MANIP-SIM-YYYYMMDD-v01처럼 프로젝트·유형·날짜·버전을 한 식별자에 넣습니다. 레지스트리에는 이 ID가 어떤 수집 스크립트와 commit에서 생성됐는지, raw에서 processed로 넘어갈 때 어떤 필터와 분할을 거쳤는지, 어느 학습 설정이 이를 읽었는지를 붙입니다. 파일명만 바꾸는 버전과 수집 조건이 달라진 버전을 구분하려는 장치입니다.
models/에는 숫자만 남고, 의미는 학습 설정과 평가에 남습니다
checkpoint 파일은 actor와 critic의 파라미터를 저장하지만, 그것만으로는 어떤 정책인지 설명하지 못합니다. H1 보행에서는 관측 47차원, action 19차원, reward 항, PPO 설정, 평가 시나리오가 함께 있어야 같은 checkpoint를 다시 해석할 수 있습니다. 따라서 정책을 비교할 때는 파일 이름보다 환경 설정과 평가 결과가 먼저 따라와야 합니다.
현재 H1의 3,000 iteration checkpoint를 자연 보행 결과로 쓰지 않는 것도 같은 이유입니다. 저장된 모델이 있다는 사실과 평가 관문을 통과했다는 사실을 분리해야 reward v2 재학습 뒤의 차이를 제대로 볼 수 있습니다.
체크포인트가 다음 단계의 입력이 되려면 최소한 환경 ID, reward 설정, 알고리즘 config, 학습 iteration, 코드 SHA, 평가 결과가 함께 있어야 합니다. G1의 M148 model 1850을 비교용으로만 남긴 것도 파일이 없어서가 아닙니다. 형태와 raw-action을 포함한 승격 관문을 통과한 실행 후보가 아니기 때문입니다. 레지스트리는 ‘파일이 있는가’보다 ‘무슨 권한으로 다시 사용할 수 있는가’를 기록해야 합니다.
Git에서 뺀다는 것은 추적하지 않는다는 뜻이 아닙니다
대용량 HDF5, rosbag, RLDS, .pt·.safetensors를 Git에서 제외하면 저장소는 가벼워집니다. 대신 파일 내용이 자동으로 보존되거나 다른 PC로 전달되지는 않습니다. 그래서 데이터에는 checksum·저장 URI·생성 조건을, 모델에는 checkpoint 경로·평가 상태를 남기는 별도의 계보가 필요합니다. 삭제나 이동이 생기면 레지스트리도 함께 바뀌어야 합니다.
이 원칙이 없으면 두 종류의 오류가 생깁니다. 같은 이름의 checkpoint를 다른 reward 설정에서 덮어쓸 수 있고, JSONL 변환이 끝난 데이터를 공식 RLDS 패키지로 오해할 수 있습니다. 둘 다 파일은 존재하지만 의미가 바뀐 경우입니다. 그래서 실제 자산의 저장과 의미의 저장을 분리하되, ID와 commit으로 다시 연결합니다.
다음 단계가 읽을 수 있는 최소 레코드
데이터 레코드에는 ID, robot·task, 수집 날짜, observation/action schema, episode 수, 성공 판정, raw URI, 변환 이력, split, 생성 코드 SHA를 둡니다. 모델 레코드는 model ID, 기반 모델, 입력 데이터 ID, 환경·학습 config, checkpoint URI, 평가 결과, 승인 상태를 가집니다. 이 두 레코드가 연결돼야 평가 결과에서 원시 episode까지 거슬러 갈 수 있습니다.
현재 dry-run HDF5는 schema fixture이므로 학습 입력 레코드로 승격하지 않습니다. 현재 H1 checkpoint와 G1 비교용 후보도 파일 위치만으로 실행 승인 상태가 되지 않습니다. 앞으로 첫 실제 Franka 데이터가 생기면 raw 등록, 변환 검증, 분할 고정, 학습 config 연결, 평가와 승격을 각각 다른 상태로 남길 예정입니다. 이 단계 중 하나라도 빠지면 다음 모델이 어떤 데이터를 배웠는지 설명할 수 없습니다.
자산과 결과를 연결하는 문서는 따로 둡니다
research-notes/600_Data_Repository/는 데이터셋·전처리 결과·모델·코드가 어떤 실험 질문과 연결되는지 기록하는 레지스트리입니다. 실제 대용량 파일을 설명으로 복사하는 대신, 데이터 ID와 조건, 관련 환경·학습 설정, 평가 결과를 따라갈 수 있게 합니다.
이 구조에서 다음에 확인할 것은 파일 수가 아닙니다. 현재 G1에서는 M160a runtime-capture 산출물을 기존 결과와 분리해 등록하는 일이 먼저고, VLA 트랙을 다시 열 때는 첫 실제 Franka 데이터셋의 수집 조건과 분할을 확정해야 합니다. 데이터와 모델은 그 질문에 답하기 위한 산출물로 남습니다.
함께 읽기: 워크스페이스 구성도 · 기록의 정본