파이프라인이 실제로 어떻게 도는가 — 완전 해부

0 ⚠️ 선행 확인 — 지금 이 코드는 실행되지 않는다

이 보고서를 쓰려고 실제 트레이스를 돌리다가 발견한 사항입니다. 디스크 상태가 문서(claude/context.md)와 다릅니다.

본 보고서의 모든 트레이스 수치는 재현 가능한 기준인 .bak(구 858, annotation 포함)에서 측정했습니다. 데이터셋 디렉토리는 읽기만 했고 아무것도 수정하지 않았습니다.

1 전체 데이터 흐름 한 장

 ┌─ 시나리오 1개 (에피소드 ~8.5분) ───────────────────────────────────────────────┐
 │                                                                              │
 │  mp4 ×3 (agentview_left / agentview_right / eye_in_hand)  각 10,230f @20fps   │
 │        │                                                                     │
 │        │  sample_episode()  stride=round(fps/2.0)=10 → 2Hz                    │
 │        ▼                                                                     │
 │  타임스텝별 3-cam 세로 concat → 1536×512 → JPEG(q85)                        │
 │  = FrameRef(global_idx=원본 프레임번호, jpeg=bytes) × 1,023개  (총 88.9MB)     │
 │        │                                                                     │
 │        │  subtasks.json 의 frame_start/end 로 세그먼트 분할 (11개)             │
 │        │  fine_subtasks.json 의 per_test[i].segments[j].fine_subtasks 로 K    │
 │        ▼                                                                     │
 │  ┌── WALK (메모리 적재) ─────────────────────────────────────────────┐         │
 │  │  각 스텝:  slice_segment(lo,hi) → cap_uniform(8) → 8장 선택           │
 │  │           ┌─────────────────────────────────────────────┐        │         │
 │  │           │ system = STEP_SYSTEM (또는 OURS_STEP_SYSTEM) │        │         │
 │  │           │ user   = [ GOAL텍스트 ]                      │        │         │
 │  │           │          [ STATE 이미지 ×8 ]  ← 이번 윈도     │        │         │
 │  │           │          [ 메모리 parts ]     ← policy       │        │         │
 │  │           └─────────────────────────────────────────────┘        │         │
 │  │                       │ structured output (pydantic)             │         │
 │  │                       ▼                                          │         │
 │  │              StepOut{action,object,place,raw,                    │         │
 │  │                      keyframe_positions,memory}                  │         │
 │  │                       │                                          │         │
 │  │                       └──→ policy.observe(out, window)  ← 메모리가 여기서 커짐 │
 │  └──────────────────────────────────────────────────────────────────┘         │
 │        │                                                                     │
 │        ▼  (recall 모드) 에피소드 끝 · 테스트마다 1회 · observe 안 함              │
 │  ┌── FINAL CALL ────────────────────────────────────────────────────┐         │
 │  │  system = RECALL_SYSTEM                                          │         │
 │  │  user   = [ LANG 질의 ] + [ 마지막 세그먼트 STATE ×8 ]              │         │
 │  │           + policy.recall_parts(lang)  ← 메모리를 여기서 꺼냄      │         │
 │  └──────────────────────────────────────────────────────────────────┘         │
 │        │  StepOut.raw                                                        │
 │        ▼                                                                     │
 │  parse_subtask() → (action,object,place) 정규화 → GT와 slot 비교 → row 저장     │
 └──────────────────────────────────────────────────────────────────────────────┘

핵심 대칭: 메모리는 observe()로만 커지고, context_parts()/recall_parts()로만 꺼내진다. 메서드 5종은 이 두 훅의 구현만 다르고, 프롬프트·윈도·채점은 완전히 동일합니다(ours만 walk 프롬프트를 walk_system() 훅으로 교체).

2 비디오 → 프레임: 샘플링 전 과정

실측 대상: combo_002_L29_S48_0006 (.bak 기준).

2.1 원본 3카메라

2.2 sample_episode() — 디코딩과 합성

video.py:41. 카메라마다 전체를 순차 디코딩하면서 idx % stride == 0인 프레임만 보관합니다. seek을 쓰지 않고 전 프레임을 읽습니다(정확도 우선, 시나리오당 3파일 완전 디코딩).

2.3 cap_uniform() — 콜당 8장으로 줄이기

video.py:82. 윈도 안 프레임이 8장을 넘으면 균일 인덱싱으로 8장만 남깁니다(자르기가 아니라 솎아내기 — 윈도의 시간 범위는 유지되고 간격만 벌어집니다).

3 API 콜 1회 해부 (바이트 단위)

3.1 parts 조립 — 순서가 고정돼 있다

runner._unified_call() (walk) 와 run_scenario_recall() Phase 2 (final) 둘 다 동일한 3단 구조입니다.

3.2 _to_messages() — 실제 전송 형태

clients/openai.py:37. 시스템 메시지 1개 + user 메시지 단 1개이고, parts 전체가 그 user 메시지의 content 배열에 순서대로 들어갑니다. 이미지는 base64 data URI로 인라인됩니다(URL 참조 아님).

3.3 실측 페이로드 (fine walk, m3v2, 앞 6콜)

3.4 실제로 전송되는 텍스트 전문

walk user text (step_user_text)

GOAL 문자열 = fine_subtasks.json의 per_test[i].segments[j].instruction. 여기에 "place it on any shelf in the freezer"가 그대로 들어 있는 것이 next-subtask 모드의 recipe leak입니다 — 정답이 질문에 적혀 있습니다.

recall final user text (recall_user_text)

3.5 응답 처리

try-except가 없습니다(프로젝트 규칙). 네트워크/게이트웨이 오류는 openai SDK의 max_retries=5가 처리하고, 그래도 실패하면 예외가 그대로 올라와 런이 죽습니다 — 부분 결과를 조용히 남기지 않기 위함입니다. 실제로 429 COST limit이 이런 식으로 런을 중단시킨 적이 있습니다.

4 시간 동기화 — 인덱스 산술 전부

4.1 좌표계 3개와 변환

slice_segment(frames, lo, hi)는 lo <= f.global_idx < hi로 필터합니다. 세그먼트 경계와 프레임 인덱스가 같은 좌표계라 오프셋 버그 여지가 없습니다 — 과거 렌더러에서 냈던 ×10 실수는 이 성질을 착각한 것이었습니다.

4.2 실측 세그먼트 구조 (combo_002_L29_S48_0006)

4.3 K-분할과 leadup shift — 정확한 산술

세그먼트를 K개 fine chunk로 프레임 수 비례 균등 분할합니다(fine별 실제 경계 데이터가 없어서 쓰는 근사).

여기가 프로젝트 전체를 뒤집은 지점입니다. 두 정렬 방식이 무엇을 STATE로 주는지:

실측 — seg0을 fine walk로 돌 때 각 콜이 실제로 받는 윈도:

부작용: 첫 세그먼트에서 fine#0과 fine#1이 같은 윈도를 받습니다(폴백 때문). 그리고 chunk[3] f[543,724)는 어떤 콜에도 STATE로 안 들어갑니다 — leadup은 구조적으로 마지막 chunk를 관측에서 제외합니다.

4.4 콜 케이던스 vs 실제 동작 속도

• fine sub-task 1개의 실제 소요: median 11.8 s (범위 3.3–82 s, 111개 타깃 세그먼트 측정)
• fine walk 콜 1개 = fine chunk 1개 → 콜 간 비디오 시간 간격도 ≈ 11.8 s → 케이던스는 맞음
• 문제는 케이던스가 아니라 (a) 균등분할 가정 vs 실제 분산(3.3–82 s), (b) K=1인 긴 세그먼트의 거친 샘플링

5 walk 시퀀스: 2모드 × 4변형

5.1 --target memory (next-subtask) — 테스트마다 독립 walk

실측(MoveFridgeToFreezer, tgt_idx=0, K=4, tfi=1): chunk = 2콜(k=0,1) / leadup = 1콜(chunk[0] 하나로 바로 채점). 이 테스트는 타깃이 seg0이라 선행 세그먼트가 없습니다.

5.2 --target recall — walk 1회를 3 테스트가 공유

5.3 실측 콜 수 (combo_002_L29_S48_0006, 세그먼트 11개 / 테스트 3개)

세그먼트별 fine 콜 분포: [4, 1, 1, 1, 3, 1, 6, 1, 8, 1, 1] — transit(K=1)은 안 늘고 조작 세그먼트만 쪼개집니다. K=1로 남은 seg2·seg10이 fine의 이득을 못 받는 구간입니다.

walk 공유가 비용의 핵심입니다. 테스트마다 walk를 새로 돌면 3×가 되는데(메서드당 $18 대), 공유로 ΣK + 3에 묶었습니다. 대신 3 테스트가 같은 메모리를 보므로 테스트별 맞춤 적재는 불가능합니다.

6 메모리 5종 — 저장 메커니즘

모두 StepPolicy의 3+2 훅 구현입니다: observe()(적재) / context_parts()(walk 중 제시) / recall_parts()(회상 시 제시, 기본은 context_parts 위임) / summary()(기록) / walk_system()·walk_schema()(ours만 오버라이드).

6.1 한눈에

6.2 M2 (MemER) — 클러스터링과 eviction

memory/cluster.py. 저장하는 건 이미지가 아니라 정수 인덱스입니다. 이미지는 회상 때 _by_idx(에피소드 전체 디코딩 dict)에서 꺼냅니다 — 그래서 "8분 전 프레임"을 되볼 수 있습니다.

eviction 실측 증거 — 트레이스에서 M2가 최종 보관한 8개가 어느 세그먼트인지:

실측 런에서는 sparse nomination까지 겹쳐 더 적었습니다 — 예: combo_014 M2 최종 보관 6개 [90, 150, 190, 290, 390, 6360].

6.3 M3v2 — append 로그

모델이 emit한 raw 문장을 그대로 덧붙입니다. 회상 때는 번호를 매겨 통째로 넣고 모델이 알아서 찾게 합니다(인덱스 없음).

walk가 진행될수록 이 텍스트가 길어집니다(실측: 콜0 341자 → 마지막 콜 1,565자). 그래도 이미지가 없어 비용은 가장 쌉니다.

6.4 ours — 인라인 태그 + 질의 검색

walk 프롬프트 자체를 바꿉니다(walk_system() → OURS_STEP_SYSTEM, walk_schema() → OursStepOut). 한 콜에서 다음 sub-task와 keyframe 태그를 동시에 받습니다.

실측 — ours만 정답을 맞힌 row (combo_014, 질의 "Show me where the cup with liquid is placed.", GT Place the cup in the microwave):

6.5 walk 종료 시점 메모리 상태 (실측 트레이스)

7 회상 시점(final call) 구성

Phase 2에서 테스트마다 정확히 1콜. STATE는 마지막 세그먼트를 균일 8장으로 훑은 것이고 3 테스트가 이걸 공유합니다.

메서드별 final call 페이로드 (실측)

비용 차이(스윕 실측: m3v2/control $6.20 vs m1 $11.92 vs m2 $10.42)가 이 이미지 수에서 그대로 나옵니다.

8 출력 파싱 → 채점

채점 대상은 StepOut.raw(자연어 문장) 하나입니다. 구조화 필드(action/object/place)는 채점에 쓰지 않고, raw를 다시 파싱해서 씁니다 — GT도 같은 파서를 통과시켜 대칭을 맞춥니다.

파서 버그 이력: 모델이 템플릿의 in/on을 문자 그대로 출력하는 일이 잦은데, 초기 정규식이 이 슬래시 연결어를 몰라 action='other'로 깎였습니다. 현재는 (?:in/on|on/in|into|onto|inside|in|on)으로 수정됐습니다(templates.py:15). 이 수정으로 이미지 메서드가 전반 상향됐고(m2 0.179→0.308), 이전에 보고된 "M3v2가 M2를 3.1× 압도"는 1.8×로 정정됐습니다.

row 스키마 (결과 JSON에 저장되는 것)

9 캐시 · 재개 · 비용 회계

9.1 캐시 레이아웃 — 변형마다 격리

재개 단위는 (시나리오, 테스트)입니다. recall 모드는 시나리오의 테스트가 전부 캐시에 있으면 sample_episode와 walk 전체를 건너뜁니다(run_scenario_recall 초입의 all-hit 체크). 일부만 있으면 walk를 다시 돌고 미캐시 테스트만 final call을 합니다 — 부분 캐시는 walk 비용을 아끼지 못합니다.

9.2 비용 — 게이트웨이 값이 ground truth

토큰 단가 추정을 폐기하고, 게이트웨이가 응답에 실어주는 estimated_cost.amount를 콜마다 누적합니다. 파싱 실패해도 과금은 됐으므로 None 반환 이전에 누적합니다.

주의: ours 스윕의 기록은 $2.07/52콜인데, 이는 대부분 시나리오가 앞선 스모크에서 이미 캐시돼 새로 부른 콜만 집계됐기 때문입니다. 메서드 간 비용 비교에 그대로 쓰면 안 됩니다.

초기 토큰 기반 추정이 6–8× 과소였던 이력이 있어(추정 $38 → 실비 ~$300), 지금은 모든 런이 종료 시 COST $X (calls=… prompt_tok=… completion_tok=…)를 출력합니다.

10 부록

10.1 파일별 책임

10.2 플래그 매트릭스

기본값은 전부 back-compat(chunk/execute/coarse)이라, 플래그를 안 주면 폐기된 측정 설정으로 돕니다. 정본 커맨드는 4개 플래그를 모두 명시해야 합니다.

10.3 재현

10.4 이 보고서에서 새로 드러난 것

• DATA_ROOT가 이미 879를 가리킨다 — 문서와 불일치. 현재 어떤 모드도 실행 불가(segment_goal이 fine_subtasks.json을 요구).
• 구 858 완본은 .bak에 보존돼 있어 과거 결과 재현은 가능.
• 캐시 키에 데이터 버전이 없어 879 전환 시 구 row가 조용히 반환될 위험.
• recall-report의 action_acc는 항상 1.000 — 프롬프트가 action을 강제하므로 지표로 무의미.
• "recent window"는 최근 8프레임이 아니다 — 긴 세그먼트에서는 15초 간격 8장(121초 커버). 시간 해상도가 윈도 길이에 따라 10배 이상 변동.
• leadup은 각 세그먼트의 마지막 chunk를 관측에서 제외하고, 첫 세그먼트에서는 fine#0/#1이 같은 윈도를 받는다.
• K=1로 남은 긴 세그먼트(실측 seg2 73초, seg10 122초)는 fine walk의 이득을 못 받는다 — place 누락의 구조적 원인.
• M2 eviction 실증 — 최종 보관 8개가 전부 후반 세그먼트, 초반 배치는 전멸.
• ours 검색의 결정적 사례 — m3v2가 정답을 로그에 갖고도 최신편향으로 틀린 row를 ours가 object 필터로 맞춤.