From 00abe7d83bdef082b1a22dabe542885ff05354b7 Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Wed, 24 Dec 2025 15:43:03 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Gemini=20API=20=EA=B0=9C=EC=84=A0=20?= =?UTF-8?q?=EA=B3=84=ED=9A=8D=EC=97=90=20=EC=8B=A0=EB=B2=84=EC=A0=84=20SDK?= =?UTF-8?q?=20=EC=A0=84=ED=99=98=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 현재 상태: 구버전/신버전 SDK 혼용 사용 - Phase 1 추가: 신버전 SDK(google-genai) 전환 - 스트리밍/멀티모달/에러 처리 Phase 번호 조정 --- ...ni_api_streaming_multimodal_improvement.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 journey/plans/251219_gemini_api_streaming_multimodal_improvement.md diff --git a/journey/plans/251219_gemini_api_streaming_multimodal_improvement.md b/journey/plans/251219_gemini_api_streaming_multimodal_improvement.md new file mode 100644 index 0000000..a5d9467 --- /dev/null +++ b/journey/plans/251219_gemini_api_streaming_multimodal_improvement.md @@ -0,0 +1,119 @@ +# Gemini API 스트리밍 및 멀티모달 개선 계획 + +**날짜**: 2025-12-19 +**작성자**: 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` +