# 설계 스펙: T2I Moderation 처리 + 프롬프트 피드백 루프

**작성일**: 2026-03-15
**범위**: Content moderation 거절 처리, 프롬프트 자동 수정, 생성 피드백 추적

---

## 1. 문제

Gemini T2I API는 폭력, 선정성, 위험 콘텐츠를 감지하면 이미지 생성을 거절한다.
시나리오 기반 씬 프롬프트에는 전투, 부상, 긴장 장면이 빈번하므로 높은 거절률이 예상된다.

## 2. 해결 구조

### 2.1 Moderation 감지

Gemini API 거절 응답 패턴:
- `candidates` 배열 비어있음
- `promptFeedback.blockReason` = "SAFETY" 등
- `candidates[0].finishReason` = "SAFETY"

### 2.2 프롬프트 자동 수정 (Sanitizer)

거절 시 GPT-5.4로 프롬프트를 수정:
1. 원본 씬 프롬프트 + 거절 사유를 GPT에 전달
2. 시각적 의도는 유지하면서 T2I 안전 정책을 충족하는 대안 프롬프트 생성
3. 수정된 프롬프트로 재시도
4. 최대 3회 재시도 (원본 → 수정1 → 수정2 → 대안씬)

### 2.3 대안씬 전략

3회 수정 후에도 거절되면:
- 씬의 시각적 의미를 완전히 변환 (예: 전투장면 → 전투 직후 정적 장면)
- "대안씬" 플래그와 함께 저장

### 2.4 생성 피드백 추적 (Opik 구조)

모든 T2I 호출 결과를 기록:
```
generation_trace (프로젝트 DB)
├── id
├── image_asset_id
├── attempt_number       (1, 2, 3...)
├── prompt_used          (실제 사용된 프롬프트)
├── prompt_version       (original / sanitized_v1 / sanitized_v2 / alternative)
├── model_name           (gemini-3.1-flash-image-preview)
├── status               (success / moderation_blocked / error / timeout)
├── block_reason         (SAFETY, HARM, etc.)
├── block_categories     (JSON - violence, sexual, etc.)
├── response_time_ms
├── sanitizer_feedback   (수정 시 GPT가 제안한 변경 내용)
├── created_at
```

### 2.5 프롬프트 버전 관리

수정된 프롬프트 추적:
- `original` → 원본 씬 스틸에서 추출한 프롬프트
- `sanitized_v1` → 1차 수정
- `sanitized_v2` → 2차 수정
- `alternative` → 대안씬

각 버전과 수정 사유를 generation_trace에 기록.

## 3. 모듈 구조

```
backend/app/modules/
├── prompt_sanitizer.py      # 프롬프트 수정 모듈
├── generation_tracker.py    # T2I 호출 결과 추적 (Opik 구조)
└── llm/
    └── gemini_image_client.py  # moderation 감지 + 재시도 로직 추가
```

## 4. 프롬프트

```
prompts/_base/prompt_sanitizer/v1/
├── sanitize_system.md    # 시스템 프롬프트: T2I 안전 정책 인지 + 수정 지침
└── sanitize_user.md      # 유저 프롬프트: 원본 + 거절 사유 → 수정 프롬프트
```