# Gemini API 스트리밍 및 멀티모달 개선 계획

**날짜**: 2025-12-24
**작성자**: happybell80
**관련 파일**: `rb8001/app/services/llm/gemini_handler.py`

---

## 개선 목표

현재 Gemini API는 표준 `generateContent`만 사용 중. 스트리밍, 멀티모달, 에러 처리 개선으로 UX 및 기능성 향상.

## 현재 상태

- **구버전 SDK 사용**: 메인 LLM 호출은 `google-generativeai` (구버전) 사용 중
- **신버전 SDK 부분 사용**: File Search만 `google-genai` (신버전) 사용
- **혼용 문제**: 두 SDK 혼용으로 API 일관성 부족, 신버전 기능 미활용

## 개선 항목

### 1. 신버전 SDK 전환 (google-genai)

**현재 상태**: `google-generativeai` (구버전) 사용, `google-genai` (신버전)는 File Search만 사용

**개선 내용**:
- 메인 LLM 호출을 `google-genai`로 전환
- `genai.Client(api_key=...)` 기반 통일된 클라이언트 사용
- 구버전 SDK 의존성 제거

**UX 개선 예상 효과**:
- **API 일관성**: 단일 SDK로 통일하여 유지보수성 향상
- **기능 활용**: 신버전 SDK의 스트리밍, 개선된 에러 처리 등 활용 가능
- **향후 확장성**: 신버전 SDK의 지속적인 업데이트 및 기능 추가 활용

**적용 우선순위**: 높음 (다른 개선의 기반)

### 2. 스트리밍 응답 (streamGenerateContent)

**현재 상태**: 전체 응답 완료 후 반환 (`generate_content_async`)

**개선 내용**:
- SSE(Server-Sent Events) 기반 스트리밍 구현
- `streamGenerateContent` 엔드포인트 사용
- 프론트엔드에 청크 단위 전달

**UX 개선 예상 효과**:
- **응답 지연 시간 감소**: 첫 토큰부터 표시로 체감 대기 시간 50-70% 감소
- **타이핑 애니메이션**: 실시간 텍스트 생성으로 대화형 느낌 향상
- **긴 응답 처리**: IR Deck 분석, 뉴스 요약 등 긴 응답도 부분 표시로 사용자 이탈 감소
- **로딩 상태 개선**: "생성 중..." 대신 실제 생성 내용 표시로 피드백 명확화

**적용 우선순위**: 높음 (대화형 UX 핵심)

### 3. 멀티모달 지원 (이미지/동영상/오디오)

**현재 상태**: 텍스트만 처리

**개선 내용**:
- `inline_data` 또는 `file_data`로 이미지/동영상/오디오 처리
- **PDF 문서 이해**: `Part.from_bytes()` 또는 Files API로 PDF 직접 전달 (최대 1,000페이지, 50MB)
  - 텍스트, 이미지, 다이어그램, 차트, 표 분석 및 해석
  - 구조화된 출력 추출, 요약, 질문 답변
  - 레이아웃/서식 유지 트랜스크립션 (HTML 등)
- IR Deck PDF 직접 분석 (현재는 OCR/파싱 경로 사용)
- Slack 이미지 첨부 분석
- 동영상/오디오 트랜스크립트 생성

**UX 개선 예상 효과**:
- **IR Deck 분석**: PDF 직접 전달로 OCR 오류 감소, 정확도 향상, 다이어그램/차트 해석 가능
- **문서 처리 효율**: 최대 1,000페이지 PDF 단일 요청으로 처리, Files API로 재사용 시 지연 시간 개선
- **슬랙 이미지 분석**: 사용자가 업로드한 차트/그래프 즉시 분석 가능
- **동영상 요약**: 회의록/프레젠테이션 동영상 자동 요약
- **접근성 향상**: 시각적 정보를 텍스트로 변환하여 시각 장애인 접근성 개선

**적용 우선순위**: 중간 (IR Deck 분석에 직접 활용)

### 4. 사고(Thinking) 기능 활용

**현재 상태**: 사고 제어 미사용, 기본 동작(사고 없음)

**개선 내용**:
- `thinkingBudget` 설정으로 복잡한 작업에 추론 능력 향상
- Gemini 2.5 Flash-Lite: `thinkingBudget` 범위 512~24576 (최소 512 필요)
- 구버전 SDK는 `ThinkingConfig` 미지원 → 신버전 SDK 전환 필요

**UX 개선 예상 효과**:
- **복잡한 작업 품질 향상**: 코딩, 수학, 데이터 분석 등 복잡한 작업의 정확도 향상
- **추론 과정 투명화**: `includeThoughts=True`로 모델의 추론 과정 확인 가능
- **작업별 최적화**: 간단한 작업은 사고 비활성화(0), 복잡한 작업은 사고 활성화(512~24576)

**적용 우선순위**: 중간 (신버전 SDK 전환 후 적용)

### 5. 에러 처리 및 모니터링 강화

**현재 상태**: 기본 에러 처리만 존재

**개선 내용**:
- Rate Limit(429) 자동 재시도 및 백오프
- 토큰 사용량 모니터링 및 알림 (사고 토큰 포함)
- 응답 구조 검증 강화
- 에러 타입별 처리 전략

**UX 개선 예상 효과**:
- **안정성 향상**: Rate Limit 발생 시 자동 재시도로 사용자 개입 불필요
- **투명성**: 토큰 사용량 표시로 비용 인식 개선 (출력 토큰 + 사고 토큰)
- **에러 복구**: 일시적 오류 자동 복구로 사용자 경험 중단 최소화

**적용 우선순위**: 높음 (프로덕션 안정성)

## 구현 Phase

### Phase 1: 신버전 SDK 전환
- `gemini_handler.py`: `google-generativeai` → `google-genai` 전환
- `genai.Client(api_key=...)` 기반 클라이언트 사용
- `generate_content` → `client.models.generate_content` 전환
- 구버전 SDK 의존성 제거

### Phase 2: 스트리밍 기본 구현
- `gemini_handler.py`: `streamGenerateContent` 메서드 추가
- FastAPI: SSE 엔드포인트 추가
- 프론트엔드: 스트리밍 응답 처리 (chat-interface.tsx)

### Phase 3: 멀티모달 기본 지원
- PDF 문서 이해: `Part.from_bytes()` 또는 Files API로 PDF 직접 전달
  - IR Deck 분석: 현재 OCR/파싱 경로 대신 PDF 직접 전달로 전환
  - 최대 1,000페이지, 50MB 지원
  - 다이어그램, 차트, 표 분석 및 해석
- 이미지 처리: `inline_data`로 이미지 전송
- Slack 이미지: 첨부 이미지 분석 기능

### Phase 4: 사고 기능 활용
- 신버전 SDK 전환 후 `thinking_config` 지원 확인
- 작업 복잡도에 따른 `thinkingBudget` 동적 설정 (간단: 0, 복잡: 512~24576)
- 사고 요약(`includeThoughts=True`) 옵션 추가

### Phase 5: 에러 처리 강화
- Rate Limit 자동 재시도 로직
- 토큰 사용량 모니터링 (사고 토큰 포함)
- 에러 타입별 처리 전략

## 참고 문서

- Gemini API 참조: https://ai.google.dev/api
- Gemini 생각 가이드: https://ai.google.dev/docs/thinking
- Gemini 문서 이해 가이드: https://ai.google.dev/docs/document-understanding
- Google Gen AI SDK 문서: https://googleapis.github.io/python-genai/
- 현재 구현: `rb8001/app/services/llm/gemini_handler.py:200` (구버전 SDK, thinking_config 미지원)
- 신버전 SDK 예시: `rb8001/app/services/gemini_file_search_client.py:81`
- 프론트엔드: `frontend-customer/src/components/chat-interface.tsx:535`
- 테스트 스크립트: `test_llm/test_thinking_budget.py`