DOCS/journey/plans/251224_gemini_api_streaming_multimodal_improvement.md

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로 이미지/동영상/오디오 처리
• IR Deck PDF 이미지 직접 분석
• Slack 이미지 첨부 분석
• 동영상/오디오 트랜스크립트 생성

UX 개선 예상 효과:

• IR Deck 분석: PDF 이미지 직접 분석으로 OCR 오류 감소, 정확도 향상
• 슬랙 이미지 분석: 사용자가 업로드한 차트/그래프 즉시 분석 가능
• 동영상 요약: 회의록/프레젠테이션 동영상 자동 요약
• 접근성 향상: 시각적 정보를 텍스트로 변환하여 시각 장애인 접근성 개선

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

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

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

개선 내용:

• 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: 멀티모달 기본 지원

• 이미지 처리: inline_data로 이미지 전송
• IR Deck 분석: PDF 이미지 직접 분석 경로 추가
• Slack 이미지: 첨부 이미지 분석 기능

Phase 4: 에러 처리 강화

• Rate Limit 자동 재시도 로직
• 토큰 사용량 모니터링
• 에러 타입별 처리 전략

참고 문서

• Gemini API 참조: https://ai.google.dev/api
• Google Gen AI SDK 문서: https://googleapis.github.io/python-genai/
• 현재 구현: rb8001/app/services/llm/gemini_handler.py:200 (구버전 SDK)
• 신버전 SDK 예시: rb8001/app/services/gemini_file_search_client.py:81
• 프론트엔드: frontend-customer/src/components/chat-interface.tsx:535