ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
DOCS/journey/plans/251224_gemini_api_streaming_multimodal_improvement.md
Claude-51124 9674adfd6f docs: PDF 문서 이해 기능 구체화 
- Phase 3에 PDF 직접 전달 기능 상세 추가 (Part.from_bytes, Files API)
- 최대 1,000페이지, 50MB 지원 명시
- 다이어그램/차트/표 분석 기능 추가
- 문서 이해 가이드 링크 추가
2025-12-24 15:52:27 +09:00

6.5 KiB
Raw Blame History

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 자동 재시도 로직
  • 토큰 사용량 모니터링 (사고 토큰 포함)
  • 에러 타입별 처리 전략

참고 문서