diff --git a/book/100_philosophy/125_베이즈_성장과_관계의_철학.md b/book/100_philosophy/125_베이즈_성장과_관계의_철학.md index d26e505..2e2f0b8 100644 --- a/book/100_philosophy/125_베이즈_성장과_관계의_철학.md +++ b/book/100_philosophy/125_베이즈_성장과_관계의_철학.md @@ -37,7 +37,7 @@ date: 2025-09-19 - **기억과 학습:** 로빙은 새로운 정보를 만났을 때, 단순히 저장하는 것이 아니라 베이즈 추론을 통해 기존 기억의 신뢰도를 재평가하고, 어떤 것을 더 중요하게 기억할지 결정합니다. ([[430_기억의_망각과_요약_장기컨텍스트_최적화]]) - **스킬 숙련도:** 스킬의 성공과 실패 경험(증거)은 스킬의 성공 확률(믿음)을 베이지안 방식으로 업데이트하여 숙련도를 높입니다. ([[195_철학에서_설계로]]) -- **윤리적 진화:** 로빙의 윤리 시스템은 고정된 규칙이 아니라, 사용자와의 상호작용을 통해 무엇이 더 '사랑에 기반한' 행동인지 확률적으로 학습하며 진화합니다. ([[plans/completed/250815_로빙_사랑기반_윤리시스템_단계별_구현계획]]) +- **윤리적 진화:** 로빙의 윤리 시스템은 고정된 규칙이 아니라, 사용자와의 상호작용을 통해 무엇이 더 '사랑에 기반한' 행동인지 확률적으로 학습하며 진화합니다. ([[plans/archive/250815_로빙_사랑기반_윤리시스템_단계별_구현계획]]) 결국 로빙의 성장은 다음의 베이지안 사이클로 요약될 수 있습니다. > **과거의 경험(Prior) + 새로운 정보(Evidence) → 더 나은 자신(Posterior)** diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md index 0ff2dec..5c2450b 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_문서_작성_원칙.md @@ -46,7 +46,7 @@ **용도**: 미래 계획, 아이디어만 (아직 구현 안 됨) **규칙**: -- **구현 완료 시 `journey/troubleshooting/`으로 이동** (필수) +- **구현 완료 시 `journey/plans/archive/`로 이동** (필수) - **구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 - **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화 - **시나리오/테스트/리포트 별도 파일 금지** - 하나의 파일에 통합 @@ -54,6 +54,7 @@ **구분**: - `plans/`: 미구현 계획만 (will do) +- `plans/archive/`: 구현 완료된 계획 (참고용 보관) - `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned) --- @@ -231,7 +232,7 @@ 2. **`journey/plans/`**: 구현 계획 작성 (만들기 전) - 아키텍처/Phase/필요작업만 - - 구현 완료 시 `troubleshooting/`으로 이동 + - 구현 완료 시 `plans/archive/`로 이동하고 troubleshooting 문서와 링크 연결 3. **`journey/troubleshooting/`**: 구현 과정 기록 (만들면서/만든 후) - 문제 해결, 교훈, 테스트 결과 diff --git a/journey/plans/251224_gemini_api_streaming_multimodal_improvement.md b/journey/plans/251224_gemini_api_streaming_multimodal_improvement.md deleted file mode 100644 index 3dae0f6..0000000 --- a/journey/plans/251224_gemini_api_streaming_multimodal_improvement.md +++ /dev/null @@ -1,151 +0,0 @@ -# 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` - diff --git a/journey/plans/completed/250804_로빙_임베딩_서비스_분리_아키텍처.md b/journey/plans/archive/250804_로빙_임베딩_서비스_분리_아키텍처.md similarity index 100% rename from journey/plans/completed/250804_로빙_임베딩_서비스_분리_아키텍처.md rename to journey/plans/archive/250804_로빙_임베딩_서비스_분리_아키텍처.md diff --git a/journey/plans/completed/250806_로빙문서_5단계_개선계획.md b/journey/plans/archive/250806_로빙문서_5단계_개선계획.md similarity index 100% rename from journey/plans/completed/250806_로빙문서_5단계_개선계획.md rename to journey/plans/archive/250806_로빙문서_5단계_개선계획.md diff --git a/journey/plans/completed/250812_auth_db_테이블_단순화_방안.md b/journey/plans/archive/250812_auth_db_테이블_단순화_방안.md similarity index 100% rename from journey/plans/completed/250812_auth_db_테이블_단순화_방안.md rename to journey/plans/archive/250812_auth_db_테이블_단순화_방안.md diff --git a/journey/plans/completed/250812_로컬개발자_Slack사용자매핑_구현계획.md b/journey/plans/archive/250812_로컬개발자_Slack사용자매핑_구현계획.md similarity index 100% rename from journey/plans/completed/250812_로컬개발자_Slack사용자매핑_구현계획.md rename to journey/plans/archive/250812_로컬개발자_Slack사용자매핑_구현계획.md diff --git a/journey/plans/completed/250815_로빙_사랑기반_윤리시스템_단계별_구현계획.md b/journey/plans/archive/250815_로빙_사랑기반_윤리시스템_단계별_구현계획.md similarity index 100% rename from journey/plans/completed/250815_로빙_사랑기반_윤리시스템_단계별_구현계획.md rename to journey/plans/archive/250815_로빙_사랑기반_윤리시스템_단계별_구현계획.md diff --git a/journey/plans/completed/250819_claude_사용자구분및ChromaDB격리문제.md b/journey/plans/archive/250819_claude_사용자구분및ChromaDB격리문제.md similarity index 100% rename from journey/plans/completed/250819_claude_사용자구분및ChromaDB격리문제.md rename to journey/plans/archive/250819_claude_사용자구분및ChromaDB격리문제.md diff --git a/journey/plans/completed/250819_gmail_item_detailed_tasks.md b/journey/plans/archive/250819_gmail_item_detailed_tasks.md similarity index 100% rename from journey/plans/completed/250819_gmail_item_detailed_tasks.md rename to journey/plans/archive/250819_gmail_item_detailed_tasks.md diff --git a/journey/plans/completed/250819_gmail_item_implementation_plan.md b/journey/plans/archive/250819_gmail_item_implementation_plan.md similarity index 100% rename from journey/plans/completed/250819_gmail_item_implementation_plan.md rename to journey/plans/archive/250819_gmail_item_implementation_plan.md diff --git a/journey/plans/completed/250819_rb8001_gmail_integration_completed.md b/journey/plans/archive/250819_rb8001_gmail_integration_completed.md similarity index 100% rename from journey/plans/completed/250819_rb8001_gmail_integration_completed.md rename to journey/plans/archive/250819_rb8001_gmail_integration_completed.md diff --git a/journey/plans/completed/250819_skill_email_db_connection_completed.md b/journey/plans/archive/250819_skill_email_db_connection_completed.md similarity index 100% rename from journey/plans/completed/250819_skill_email_db_connection_completed.md rename to journey/plans/archive/250819_skill_email_db_connection_completed.md diff --git a/journey/plans/completed/250820_email_callback_architecture_completed.md b/journey/plans/archive/250820_email_callback_architecture_completed.md similarity index 100% rename from journey/plans/completed/250820_email_callback_architecture_completed.md rename to journey/plans/archive/250820_email_callback_architecture_completed.md diff --git a/journey/plans/completed/250823_4pm_email_briefing_demo_plan.md b/journey/plans/archive/250823_4pm_email_briefing_demo_plan.md similarity index 100% rename from journey/plans/completed/250823_4pm_email_briefing_demo_plan.md rename to journey/plans/archive/250823_4pm_email_briefing_demo_plan.md diff --git a/journey/plans/completed/250828_slack_integration_level3_plan.md b/journey/plans/archive/250828_slack_integration_level3_plan.md similarity index 100% rename from journey/plans/completed/250828_slack_integration_level3_plan.md rename to journey/plans/archive/250828_slack_integration_level3_plan.md diff --git a/journey/plans/completed/250901_rb8001_chat_history_implementation_plan.md b/journey/plans/archive/250901_rb8001_chat_history_implementation_plan.md similarity index 100% rename from journey/plans/completed/250901_rb8001_chat_history_implementation_plan.md rename to journey/plans/archive/250901_rb8001_chat_history_implementation_plan.md diff --git a/journey/plans/archive/251224_gemini_api_streaming_multimodal_improvement.md b/journey/plans/archive/251224_gemini_api_streaming_multimodal_improvement.md new file mode 100644 index 0000000..29d69ea --- /dev/null +++ b/journey/plans/archive/251224_gemini_api_streaming_multimodal_improvement.md @@ -0,0 +1,33 @@ +# Gemini API 스트리밍 및 멀티모달 개선 계획 + +**날짜**: 2025-12-24 +**작성자**: happybell80 +**관련 파일**: `rb8001/app/services/llm/gemini_handler.py` +**상태**: ✅ 구현 완료 + +→ 상세: [troubleshooting/251225_gemini_api_streaming_multimodal_improvement.md](../troubleshooting/251225_gemini_api_streaming_multimodal_improvement.md) + +--- + +## 개선 항목 + +1. 신버전 SDK 전환 (google-genai) +2. 스트리밍 응답 (streamGenerateContent, SSE 엔드포인트) +3. 멀티모달 지원 (이미지, PDF 처리) +4. 사고 기능 활용 (thinkingBudget, includeThoughts) +5. 에러 처리 강화 (Rate Limit 재시도, 토큰 모니터링) + +## 구현 Phase + +- Phase 1: 신버전 SDK 전환 +- Phase 2: 스트리밍 기본 구현 +- Phase 3: 멀티모달 기본 지원 +- Phase 4: 사고 기능 활용 +- Phase 5: 에러 처리 강화 + +--- + +## 참고 문서 + +- Gemini API 참조: https://ai.google.dev/api +- Google Gen AI SDK 문서: https://googleapis.github.io/python-genai/ diff --git a/journey/plans/completed/기억_개선_5단계_계획.md b/journey/plans/archive/기억_개선_5단계_계획.md similarity index 100% rename from journey/plans/completed/기억_개선_5단계_계획.md rename to journey/plans/archive/기억_개선_5단계_계획.md diff --git a/journey/plans/completed/로빙_브레인_경량화_아키텍처_v3.md b/journey/plans/archive/로빙_브레인_경량화_아키텍처_v3.md similarity index 100% rename from journey/plans/completed/로빙_브레인_경량화_아키텍처_v3.md rename to journey/plans/archive/로빙_브레인_경량화_아키텍처_v3.md diff --git a/journey/troubleshooting/251225_gemini_api_streaming_multimodal_improvement.md b/journey/troubleshooting/251225_gemini_api_streaming_multimodal_improvement.md new file mode 100644 index 0000000..fd912bd --- /dev/null +++ b/journey/troubleshooting/251225_gemini_api_streaming_multimodal_improvement.md @@ -0,0 +1,47 @@ +# Gemini API 스트리밍 및 멀티모달 개선 구현 + +**날짜**: 2025-12-25 +**작성자**: happybell80 +**관련 파일**: `rb8001/app/services/llm/gemini_handler.py`, `rb8001/app/router/llm_endpoint.py` + +--- + +## 구현 완료 + +Gemini API 신버전 SDK 전환 및 스트리밍/멀티모달/사고 기능 추가 완료. + +### 주요 변경사항 + +- **신버전 SDK 전환**: `google-generativeai` → `google-genai` (Phase 1) +- **스트리밍 구현**: `generate_content_stream`, SSE 엔드포인트 `/api/llm/stream` (Phase 2) +- **멀티모달 지원**: 이미지, PDF 처리 (`Part.from_bytes`) (Phase 3) +- **사고 기능**: `thinkingBudget`, `includeThoughts` 파라미터 지원 (Phase 4) +- **에러 처리 강화**: Rate Limit 재시도 (지수 백오프), 토큰 모니터링 (Phase 5) + +### 구현 파일 + +- `rb8001/app/services/llm/gemini_handler.py`: 신버전 SDK 전환, stream_chat 메서드 추가, 멀티모달/사고 기능 통합 +- `rb8001/app/router/llm_endpoint.py`: `/api/llm/stream` SSE 엔드포인트 추가 + +### 테스트 결과 + +- 기본 chat API: 정상 작동 (토큰 모니터링 확인) +- 스트리밍 API: 청크 단위 응답 정상 전달 +- 배포: 성공적으로 배포 완료 및 검증 + +--- + +## 교훈 + +### 신버전 SDK 메서드명 확인 필수 +- 스트리밍 메서드: `generate_content_stream` (초기 `stream_generate_content` 사용 시 에러 발생) +- SDK 문서나 실제 객체 확인 (`dir(client.models)`)로 정확한 메서드명 확인 필요 + +### 동기 generator를 async generator로 변환 +- 신버전 SDK의 `generate_content_stream`은 동기 generator 반환 +- `asyncio.to_thread(next, stream)`로 각 청크를 비동기로 처리하여 AsyncIterator로 변환 필요 + +### 원칙 문서 준수 +- 구현 완료 시 plans/archive/로 이동하고 troubleshooting 문서와 링크 연결 +- 원칙 문서에 명확한 규칙 명시 필요 +