# 파이프라인 리팩토링 v2 — 17단계 독립 실행 설계 ## 목표 모든 LLM 호출 단계가: 1. **독립 실행** — API로 개별 단계만 실행 가능 2. **체크포인트** — 단계별 결과 JSON + DB 이중 저장 3. **Resume** — 중단 시 해당 단계부터 재개 4. **모델 선택** — UI에서 단계별 다른 모델 설정 5. **Opik 추적** — 단계별 trace/span 6. **게이트** — 전 단계 100% 완료 확인 후 다음 단계 ## 17개 단계 정의 ### 분석 Phase (10단계) | # | step_id | 이름 | 기본 모델 | 입력 | 출력 | 체크포인트 | |---|---------|------|-----------|------|------|------------| | 1 | entity_style | 스타일+요소이름 | gemini-pro | fulltext | style + entity names | entity_step1.json | | 2 | entity_review | GPT 리뷰/필터 | gpt | step1 결과 + fulltext | filtered entities | entity_step2a.json | | 3 | entity_detail_batch | GPT 상세 추출 | gpt | filtered entities + fulltext | descriptions + traits | entity_step2b.json | | 4 | entity_t2i | T2I 프롬프트 (병렬) | gemini-flash | entity + description | t2i_prompt per entity | entity_step3.json | | 5 | scene_segmentation | 씬 세그먼테이션 | gemini-lite | fulltext | segments[] | segments.json | | 6 | scene_split | 큰 씬 분할 | gemini-flash | long segments | split segments | segments.json (업데이트) | | 7 | scene_dependency | 씬 연관 분석 | gemini-pro | segments + fulltext | dependencies | scene_dependencies.json | | 8 | outlook_extraction | 아웃룩 추출 | gemini-pro | segments + characters + fulltext | outlooks + assignments | outlook_extraction.json | | 9 | scene_detail | 씬 상세 분석 (병렬) | gpt | segment + entities + outlooks | T2I + visible_entities | scene_detail.json | | 10 | scene_verify | 교차 검증 (병렬) | gemini-pro | scene_detail + fulltext | verified visible_entities | scene_verify.json | ### 이미지 Phase (7단계) | # | step_id | 이름 | 기본 모델 | 입력 | 출력 | 체크포인트 | |---|---------|------|-----------|------|------|------------| | 11 | world_guide | 월드 가이드 | gpt | fulltext + entities + stills | world_guide JSON | world_guide.json | | 12 | ref_image_gen | 요소 참조 이미지 | gemini-image | entity t2i | PNG files | ref_checkpoint.json | | 13 | composite_image_gen | 합성 이미지 | gemini-image | char ref + outlook ref | PNG files | composite_checkpoint.json | | 14 | prompt_translation | T2I 번역 (병렬) | gemini-flash | T2I 마커 → 영어 | translated prompt | (씬별 DB) | | 15 | scene_image_gen | 씬 이미지 T2I (병렬) | gemini-image | translated prompt + refs | PNG files | scene_checkpoint.json | | 16 | angle_recommend | 앵글 추천 | gpt-vision | N개 씬 이미지 | best image + angle | (씬별 DB) | | 17 | final_select | 최종 선택 | gpt-vision | N+1개 이미지 | primary 선택 | (씬별 DB) | ### 보조 (on-demand) | step_id | 이름 | 기본 모델 | |---------|------|-----------| | prompt_sanitize | 프롬프트 안전화 | gpt | | outlook_dedup | 아웃룩 중복 판별 | gpt | | project_summary | 프로젝트 요약 | gemini-pro | | ref_validation | 참조 이미지 검증 | gpt-vision | ## API 설계 ``` # 분석 세부 단계 POST /episodes/{eid}/steps/entity-style POST /episodes/{eid}/steps/entity-review POST /episodes/{eid}/steps/entity-detail-batch POST /episodes/{eid}/steps/entity-t2i POST /episodes/{eid}/steps/scene-segmentation POST /episodes/{eid}/steps/scene-split POST /episodes/{eid}/steps/scene-dependency POST /episodes/{eid}/steps/outlook-extraction POST /episodes/{eid}/steps/scene-detail POST /episodes/{eid}/steps/scene-verify # 이미지 세부 단계 POST /episodes/{eid}/steps/world-guide POST /episodes/{eid}/steps/ref-image-gen POST /episodes/{eid}/steps/composite-image-gen POST /episodes/{eid}/steps/prompt-translation POST /episodes/{eid}/steps/scene-image-gen POST /episodes/{eid}/steps/angle-recommend POST /episodes/{eid}/steps/final-select # 전체 상태 조회 GET /episodes/{eid}/steps/status # 개별 단계 결과 조회 GET /episodes/{eid}/steps/{step_id}/result # 단계별 모델 설정 (기존 llm-config 확장) GET /projects/{pid}/llm-config → 17단계 전부 표시 PUT /projects/{pid}/llm-config → 개별 모델 변경 ``` ## 각 단계 API 공통 동작 ```python POST /episodes/{eid}/steps/{step_id} ?mode=resume (기본: 이미 완료면 스킵) ?mode=force (기존 결과 삭제 후 재실행) Response: 200: {"ok": true, "status": "started"} (백그라운드) 200: {"ok": true, "status": "skipped", "reason": "already completed"} 400: {"error": "gate.previous_step_incomplete", "message": "..."} ``` ## 게이트 체인 ``` entity_style → entity_review → entity_detail_batch → entity_t2i → scene_segmentation → scene_split → scene_dependency → outlook_extraction → scene_detail → scene_verify → world_guide → ref_image_gen → composite_image_gen → prompt_translation → scene_image_gen → angle_recommend → final_select ``` ## 체크포인트 구조 ``` projects/{pid}/checkpoints/ steps/ entity_style.json # {status, result, model, started_at, completed_at} entity_review.json entity_detail_batch.json entity_t2i.json # {status, completed: {name: data}, failed: {name: error}} segments.json scene_split.json scene_dependencies.json outlook_extraction.json scene_detail.json # {status, completed: {scene_index: data}, failed: {}} scene_verify.json images/ {episode_id}/ ref_checkpoint.json composite_checkpoint.json scene_checkpoint.json ``` ## Opik 추적 ```python @opik.track(name="pipeline_step") def run_step(step_id, episode_id, project_config): with opik.span(name=step_id): result = call_structured(step=step_id, ...) checkpoint.save(step_id, result) return result ``` ## UI 설계 ``` 에피소드 상세 페이지: ┌─────────────────────────────────────────┐ │ 파이프라인 단계 (17단계) │ │ │ │ [분석] │ │ 1. ✅ 스타일+이름 gemini-pro 2.3s │ [재실행] │ 2. ✅ GPT 리뷰 gpt 1.8s │ [재실행] │ 3. ✅ GPT 상세 gpt 3.1s │ [재실행] │ 4. ✅ T2I 생성 gemini-flash 12s │ [재실행] │ 5. ✅ 세그먼테이션 gemini-lite 0.8s │ [재실행] │ 6. ✅ 씬 분할 gemini-flash 2.1s │ [재실행] │ 7. ✅ 연관 분석 gemini-pro 1.5s │ [재실행] │ 8. ✅ 아웃룩 gemini-pro 4.2s │ [재실행] │ 9. ⏳ 씬 상세 32/50 gpt --- │ [중지] │ 10. ⬜ 교차 검증 gemini-pro --- │ │ │ │ [이미지] │ │ 11. ⬜ 월드 가이드 gpt --- │ │ 12. ⬜ 참조 이미지 gemini-image --- │ │ ... │ └─────────────────────────────────────────┘ ``` ## 구현 순서 Phase 1: 백엔드 StepRunner 프레임워크 - StepRunner 베이스 클래스 (체크포인트, 게이트, Opik) - 17개 Step 클래스 구현 - 통합 API 라우터 Phase 2: 프론트엔드 - PipelineStepsPanel 컴포넌트 - 단계별 실행/중지/재실행 버튼 - 모델 선택 드롭다운 Phase 3: 기존 코드 정리 - analysis_service.py의 모놀리식 run_analysis 제거 - image_service.py의 모놀리식 generate_images 제거