diff --git a/ai-python/.env.example b/ai-python/.env.example new file mode 100644 index 0000000..937a478 --- /dev/null +++ b/ai-python/.env.example @@ -0,0 +1,26 @@ +# 서버 설정 +PORT=8086 +HOST=0.0.0.0 + +# Claude API +CLAUDE_API_KEY=your-api-key-here +CLAUDE_MODEL=claude-3-5-sonnet-20241022 +CLAUDE_MAX_TOKENS=2000 +CLAUDE_TEMPERATURE=0.3 + +# Redis +REDIS_HOST=20.249.177.114 +REDIS_PORT=6379 +REDIS_PASSWORD=Hi5Jessica! +REDIS_DB=4 + +# Azure Event Hub +EVENTHUB_CONNECTION_STRING=Endpoint=sb://hgzero-eventhub-ns.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=VUqZ9vFgu35E3c6RiUzoOGVUP8IZpFvlV+AEhC6sUpo= +EVENTHUB_NAME=hgzero-eventhub-name +EVENTHUB_CONSUMER_GROUP=ai-transcript-group + +# CORS +CORS_ORIGINS=["http://localhost:*","http://127.0.0.1:*"] + +# 로깅 +LOG_LEVEL=INFO diff --git a/ai-python/.gitignore b/ai-python/.gitignore new file mode 100644 index 0000000..2ba20f4 --- /dev/null +++ b/ai-python/.gitignore @@ -0,0 +1,37 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +venv/ +ENV/ +env/ +.venv + +# Environment +.env + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Logs +*.log +logs/ + +# Testing +.pytest_cache/ +.coverage +htmlcov/ + +# Distribution +build/ +dist/ +*.egg-info/ diff --git a/ai-python/README.md b/ai-python/README.md new file mode 100644 index 0000000..87fd8ad --- /dev/null +++ b/ai-python/README.md @@ -0,0 +1,167 @@ +# AI Service (Python) + +실시간 AI 제안사항 서비스 - FastAPI 기반 + +## 📋 개요 + +STT 서비스에서 실시간으로 변환된 텍스트를 받아 Claude API로 분석하여 회의 제안사항을 생성하고, SSE(Server-Sent Events)로 프론트엔드에 스트리밍합니다. + +## 🏗️ 아키텍처 + +``` +Frontend (회의록 작성 화면) + ↓ (SSE 연결) +AI Service (Python) + ↓ (Redis 조회) +Redis (실시간 텍스트 축적) + ↑ (Event Hub) +STT Service (음성 → 텍스트) +``` + +## 🚀 실행 방법 + +### 1. 환경 설정 + +```bash +# .env 파일 생성 +cp .env.example .env + +# .env에서 아래 값 설정 +CLAUDE_API_KEY=sk-ant-... # 실제 Claude API 키 +``` + +### 2. 의존성 설치 + +```bash +# 가상환경 생성 (권장) +python3 -m venv venv +source venv/bin/activate # Mac/Linux +# venv\Scripts\activate # Windows + +# 패키지 설치 +pip install -r requirements.txt +``` + +### 3. 서비스 시작 + +```bash +# 방법 1: 스크립트 실행 +./start.sh + +# 방법 2: 직접 실행 +python3 main.py +``` + +### 4. 서비스 확인 + +```bash +# 헬스 체크 +curl http://localhost:8086/health + +# SSE 스트림 테스트 +curl -N http://localhost:8086/api/v1/ai/suggestions/meetings/test-meeting/stream +``` + +## 📡 API 엔드포인트 + +### SSE 스트리밍 + +``` +GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream +``` + +**응답 형식 (SSE)**: +```json +event: ai-suggestion +data: { + "suggestions": [ + { + "id": "uuid", + "content": "신제품의 타겟 고객층을 20-30대로 설정...", + "timestamp": "00:05:23", + "confidence": 0.92 + } + ] +} +``` + +## 🔧 개발 환경 + +- **Python**: 3.9+ +- **Framework**: FastAPI +- **AI**: Anthropic Claude API +- **Cache**: Redis +- **Event**: Azure Event Hub + +## 📂 프로젝트 구조 + +``` +ai-python/ +├── main.py # FastAPI 진입점 +├── requirements.txt # 의존성 +├── .env.example # 환경 변수 예시 +├── start.sh # 시작 스크립트 +└── app/ + ├── config.py # 환경 설정 + ├── models/ + │ └── response.py # 응답 모델 + ├── services/ + │ ├── claude_service.py # Claude API 서비스 + │ ├── redis_service.py # Redis 서비스 + │ └── eventhub_service.py # Event Hub 리스너 + └── api/ + └── v1/ + └── suggestions.py # SSE 엔드포인트 +``` + +## ⚙️ 환경 변수 + +| 변수 | 설명 | 기본값 | +|------|------|--------| +| `CLAUDE_API_KEY` | Claude API 키 | (필수) | +| `CLAUDE_MODEL` | Claude 모델 | claude-3-5-sonnet-20241022 | +| `REDIS_HOST` | Redis 호스트 | 20.249.177.114 | +| `REDIS_PORT` | Redis 포트 | 6379 | +| `EVENTHUB_CONNECTION_STRING` | Event Hub 연결 문자열 | (선택) | +| `PORT` | 서비스 포트 | 8086 | + +## 🔍 동작 원리 + +1. **STT → Event Hub**: STT 서비스가 음성을 텍스트로 변환하여 Event Hub에 발행 +2. **Event Hub → Redis**: AI 서비스가 Event Hub에서 텍스트를 받아 Redis에 축적 (슬라이딩 윈도우: 최근 5분) +3. **Redis → Claude API**: 임계값(10개 세그먼트) 이상이면 Claude API로 분석 +4. **Claude API → Frontend**: 분석 결과를 SSE로 프론트엔드에 스트리밍 + +## 🧪 테스트 + +```bash +# Event Hub 없이 SSE만 테스트 (Mock 데이터) +curl -N http://localhost:8086/api/v1/ai/suggestions/meetings/test-meeting/stream + +# 5초마다 샘플 제안사항이 발행됩니다 +``` + +## 📝 개발 가이드 + +### Claude API 키 발급 +1. https://console.anthropic.com/ 접속 +2. API Keys 메뉴에서 새 키 생성 +3. `.env` 파일에 설정 + +### Redis 연결 확인 +```bash +redis-cli -h 20.249.177.114 -p 6379 -a Hi5Jessica! ping +# 응답: PONG +``` + +### Event Hub 설정 (선택) +- Event Hub가 없어도 SSE 스트리밍은 동작합니다 +- STT 연동 시 필요 + +## 🚧 TODO + +- [ ] Event Hub 연동 테스트 +- [ ] 프론트엔드 연동 테스트 +- [ ] 에러 핸들링 강화 +- [ ] 로깅 개선 +- [ ] 성능 모니터링 diff --git a/ai-python/app/__init__.py b/ai-python/app/__init__.py new file mode 100644 index 0000000..37cfe08 --- /dev/null +++ b/ai-python/app/__init__.py @@ -0,0 +1,2 @@ +"""AI Service - Python FastAPI""" +__version__ = "1.0.0" diff --git a/ai-python/app/api/__init__.py b/ai-python/app/api/__init__.py new file mode 100644 index 0000000..05eed47 --- /dev/null +++ b/ai-python/app/api/__init__.py @@ -0,0 +1 @@ +"""API 레이어""" diff --git a/ai-python/app/api/v1/__init__.py b/ai-python/app/api/v1/__init__.py new file mode 100644 index 0000000..88d91ee --- /dev/null +++ b/ai-python/app/api/v1/__init__.py @@ -0,0 +1 @@ +"""API v1""" diff --git a/ai-python/app/api/v1/suggestions.py b/ai-python/app/api/v1/suggestions.py new file mode 100644 index 0000000..4debf16 --- /dev/null +++ b/ai-python/app/api/v1/suggestions.py @@ -0,0 +1,93 @@ +"""AI 제안사항 SSE 엔드포인트""" +from fastapi import APIRouter +from sse_starlette.sse import EventSourceResponse +import logging +import asyncio +from typing import AsyncGenerator +from app.models import RealtimeSuggestionsResponse +from app.services.claude_service import ClaudeService +from app.services.redis_service import RedisService +from app.config import get_settings + +logger = logging.getLogger(__name__) +router = APIRouter() +settings = get_settings() + +# 서비스 인스턴스 +claude_service = ClaudeService() + + +@router.get("/meetings/{meeting_id}/stream") +async def stream_ai_suggestions(meeting_id: str): + """ + 실시간 AI 제안사항 SSE 스트리밍 + + Args: + meeting_id: 회의 ID + + Returns: + Server-Sent Events 스트림 + """ + logger.info(f"SSE 스트림 시작 - meetingId: {meeting_id}") + + async def event_generator() -> AsyncGenerator: + """SSE 이벤트 생성기""" + redis_service = RedisService() + + try: + # Redis 연결 + await redis_service.connect() + + previous_count = 0 + + while True: + # 현재 세그먼트 개수 확인 + current_count = await redis_service.get_segment_count(meeting_id) + + # 임계값 이상이고, 이전보다 증가했으면 분석 + if (current_count >= settings.min_segments_for_analysis + and current_count > previous_count): + + # 누적된 텍스트 조회 + accumulated_text = await redis_service.get_accumulated_text(meeting_id) + + if accumulated_text: + # Claude API로 분석 + suggestions = await claude_service.analyze_suggestions(accumulated_text) + + if suggestions.suggestions: + # SSE 이벤트 전송 + yield { + "event": "ai-suggestion", + "id": str(current_count), + "data": suggestions.json() + } + + logger.info( + f"AI 제안사항 발행 - meetingId: {meeting_id}, " + f"개수: {len(suggestions.suggestions)}" + ) + + previous_count = current_count + + # 5초마다 체크 + await asyncio.sleep(5) + + except asyncio.CancelledError: + logger.info(f"SSE 스트림 종료 - meetingId: {meeting_id}") + # 회의 종료 시 데이터 정리는 선택사항 (나중에 조회 필요할 수도) + # await redis_service.cleanup_meeting_data(meeting_id) + + except Exception as e: + logger.error(f"SSE 스트림 오류 - meetingId: {meeting_id}", exc_info=e) + + finally: + await redis_service.disconnect() + + return EventSourceResponse(event_generator()) + + +@router.get("/test") +async def test_endpoint(): + """테스트 엔드포인트""" + return {"message": "AI Suggestions API is working", "port": settings.port} diff --git a/ai-python/app/config.py b/ai-python/app/config.py new file mode 100644 index 0000000..bb17551 --- /dev/null +++ b/ai-python/app/config.py @@ -0,0 +1,55 @@ +"""환경 설정""" +from pydantic_settings import BaseSettings +from functools import lru_cache +from typing import List + + +class Settings(BaseSettings): + """환경 설정 클래스""" + + # 서버 설정 + app_name: str = "AI Service (Python)" + host: str = "0.0.0.0" + port: int = 8086 # STT(8084)와 충돌 방지 + + # Claude API + claude_api_key: str = "" + claude_model: str = "claude-3-5-sonnet-20241022" + claude_max_tokens: int = 250000 + claude_temperature: float = 0.7 + + # Redis + redis_host: str = "20.249.177.114" + redis_port: int = 6379 + redis_password: str = "" + redis_db: int = 4 + + # Azure Event Hub + eventhub_connection_string: str = "" + eventhub_name: str = "hgzero-eventhub-name" + eventhub_consumer_group: str = "ai-transcript-group" + + # CORS + cors_origins: List[str] = [ + "http://localhost:*", + "http://127.0.0.1:*", + "http://localhost:8080", + "http://localhost:3000" + ] + + # 로깅 + log_level: str = "INFO" + + # 분석 임계값 + min_segments_for_analysis: int = 10 + text_retention_seconds: int = 300 # 5분 + + class Config: + env_file = ".env" + case_sensitive = False + + +@lru_cache() +def get_settings() -> Settings: + """싱글톤 설정 인스턴스""" + return Settings() diff --git a/ai-python/app/models/__init__.py b/ai-python/app/models/__init__.py new file mode 100644 index 0000000..e1b9eae --- /dev/null +++ b/ai-python/app/models/__init__.py @@ -0,0 +1,4 @@ +"""데이터 모델""" +from .response import SimpleSuggestion, RealtimeSuggestionsResponse + +__all__ = ["SimpleSuggestion", "RealtimeSuggestionsResponse"] diff --git a/ai-python/app/models/response.py b/ai-python/app/models/response.py new file mode 100644 index 0000000..f10540e --- /dev/null +++ b/ai-python/app/models/response.py @@ -0,0 +1,45 @@ +"""응답 모델""" +from pydantic import BaseModel, Field +from typing import List + + +class SimpleSuggestion(BaseModel): + """간소화된 AI 제안사항""" + + id: str = Field(..., description="제안 ID") + content: str = Field(..., description="제안 내용 (1-2문장)") + timestamp: str = Field(..., description="타임스탬프 (HH:MM:SS)") + confidence: float = Field(..., ge=0.0, le=1.0, description="신뢰도 (0-1)") + + class Config: + json_schema_extra = { + "example": { + "id": "sugg-001", + "content": "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.", + "timestamp": "00:05:23", + "confidence": 0.92 + } + } + + +class RealtimeSuggestionsResponse(BaseModel): + """실시간 AI 제안사항 응답""" + + suggestions: List[SimpleSuggestion] = Field( + default_factory=list, + description="AI 제안사항 목록" + ) + + class Config: + json_schema_extra = { + "example": { + "suggestions": [ + { + "id": "sugg-001", + "content": "신제품의 타겟 고객층을 20-30대로 설정하고...", + "timestamp": "00:05:23", + "confidence": 0.92 + } + ] + } + } diff --git a/ai-python/app/services/__init__.py b/ai-python/app/services/__init__.py new file mode 100644 index 0000000..1b90ec2 --- /dev/null +++ b/ai-python/app/services/__init__.py @@ -0,0 +1 @@ +"""서비스 레이어""" diff --git a/ai-python/app/services/claude_service.py b/ai-python/app/services/claude_service.py new file mode 100644 index 0000000..f62b878 --- /dev/null +++ b/ai-python/app/services/claude_service.py @@ -0,0 +1,147 @@ +"""Claude API 서비스""" +import anthropic +import json +import logging +from typing import List +from datetime import datetime +import uuid +from app.config import get_settings +from app.models import SimpleSuggestion, RealtimeSuggestionsResponse + +logger = logging.getLogger(__name__) +settings = get_settings() + + +class ClaudeService: + """Claude API 클라이언트""" + + def __init__(self): + self.client = None + if settings.claude_api_key: + self.client = anthropic.Anthropic(api_key=settings.claude_api_key) + + async def analyze_suggestions(self, transcript_text: str) -> RealtimeSuggestionsResponse: + """ + 회의 텍스트를 분석하여 AI 제안사항 생성 + + Args: + transcript_text: 누적된 회의 텍스트 + + Returns: + RealtimeSuggestionsResponse + """ + if not self.client: + logger.warning("Claude API 키가 설정되지 않음 - Mock 데이터 반환") + return self._generate_mock_suggestions() + + logger.info(f"Claude API 호출 - 텍스트 길이: {len(transcript_text)}") + + system_prompt = """당신은 회의록 작성 전문 AI 어시스턴트입니다. + +실시간 회의 텍스트를 분석하여 **중요한 제안사항만** 추출하세요. + +**추출 기준**: +- 회의 안건과 직접 관련된 내용 +- 논의가 필요한 주제 +- 결정된 사항 +- 액션 아이템 + +**제외할 내용**: +- 잡담, 농담, 인사말 +- 회의와 무관한 대화 +- 단순 확인이나 질의응답 + +**응답 형식**: JSON만 반환 (다른 설명 없이) +{ + "suggestions": [ + { + "content": "구체적인 제안 내용 (1-2문장으로 명확하게)", + "confidence": 0.9 + } + ] +} + +**주의**: +- 각 제안은 독립적이고 명확해야 함 +- 회의 맥락에서 실제 중요한 내용만 포함 +- confidence는 0-1 사이 값 (확신 정도)""" + + try: + response = self.client.messages.create( + model=settings.claude_model, + max_tokens=settings.claude_max_tokens, + temperature=settings.claude_temperature, + system=system_prompt, + messages=[ + { + "role": "user", + "content": f"다음 회의 내용을 분석해주세요:\n\n{transcript_text}" + } + ] + ) + + # 응답 파싱 + content_text = response.content[0].text + suggestions_data = self._parse_claude_response(content_text) + + logger.info(f"Claude API 응답 성공 - 제안사항: {len(suggestions_data.get('suggestions', []))}개") + + return RealtimeSuggestionsResponse( + suggestions=[ + SimpleSuggestion( + id=str(uuid.uuid4()), + content=s["content"], + timestamp=self._get_current_timestamp(), + confidence=s.get("confidence", 0.8) + ) + for s in suggestions_data.get("suggestions", []) + ] + ) + + except Exception as e: + logger.error(f"Claude API 호출 실패: {e}") + return RealtimeSuggestionsResponse(suggestions=[]) + + def _parse_claude_response(self, text: str) -> dict: + """Claude 응답에서 JSON 추출 및 파싱""" + # ```json ... ``` 제거 + if "```json" in text: + start = text.find("```json") + 7 + end = text.rfind("```") + text = text[start:end].strip() + elif "```" in text: + start = text.find("```") + 3 + end = text.rfind("```") + text = text[start:end].strip() + + try: + return json.loads(text) + except json.JSONDecodeError as e: + logger.error(f"JSON 파싱 실패: {e}, 원문: {text[:200]}") + return {"suggestions": []} + + def _get_current_timestamp(self) -> str: + """현재 타임스탬프 (HH:MM:SS)""" + return datetime.now().strftime("%H:%M:%S") + + def _generate_mock_suggestions(self) -> RealtimeSuggestionsResponse: + """Mock 제안사항 생성 (테스트용)""" + mock_suggestions = [ + "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.", + "개발 일정: 1차 프로토타입은 11월 15일까지 완성, 2차 베타는 12월 1일 론칭", + "마케팅 예산 배분에 대해 SNS 광고 60%, 인플루언서 마케팅 40%로 의견이 나왔으나 추가 검토 필요" + ] + + import random + content = random.choice(mock_suggestions) + + return RealtimeSuggestionsResponse( + suggestions=[ + SimpleSuggestion( + id=str(uuid.uuid4()), + content=content, + timestamp=self._get_current_timestamp(), + confidence=0.85 + ) + ] + ) diff --git a/ai-python/app/services/eventhub_service.py b/ai-python/app/services/eventhub_service.py new file mode 100644 index 0000000..c6109e6 --- /dev/null +++ b/ai-python/app/services/eventhub_service.py @@ -0,0 +1,114 @@ +"""Azure Event Hub 서비스 - STT 텍스트 수신""" +import asyncio +import logging +import json +from azure.eventhub.aio import EventHubConsumerClient +from azure.eventhub.extensions.checkpointstoreblobaio import BlobCheckpointStore + +from app.config import get_settings +from app.services.redis_service import RedisService + +logger = logging.getLogger(__name__) +settings = get_settings() + + +class EventHubService: + """Event Hub 리스너 - STT 텍스트 실시간 수신""" + + def __init__(self): + self.client = None + self.redis_service = RedisService() + + async def start(self): + """Event Hub 리스닝 시작""" + if not settings.eventhub_connection_string: + logger.warning("Event Hub 연결 문자열이 설정되지 않음 - Event Hub 리스너 비활성화") + return + + logger.info("Event Hub 리스너 시작") + + try: + # Redis 연결 + await self.redis_service.connect() + + # Event Hub 클라이언트 생성 + self.client = EventHubConsumerClient.from_connection_string( + conn_str=settings.eventhub_connection_string, + consumer_group=settings.eventhub_consumer_group, + eventhub_name=settings.eventhub_name, + ) + + # 이벤트 수신 시작 + async with self.client: + await self.client.receive( + on_event=self.on_event, + on_error=self.on_error, + starting_position="-1", # 최신 이벤트부터 + ) + + except Exception as e: + logger.error(f"Event Hub 리스너 오류: {e}") + finally: + await self.redis_service.disconnect() + + async def on_event(self, partition_context, event): + """ + 이벤트 수신 핸들러 + + 이벤트 형식 (STT Service에서 발행): + { + "eventType": "TranscriptSegmentReady", + "meetingId": "meeting-123", + "text": "변환된 텍스트", + "timestamp": 1234567890000 + } + """ + try: + # 이벤트 데이터 파싱 + event_data = json.loads(event.body_as_str()) + + event_type = event_data.get("eventType") + meeting_id = event_data.get("meetingId") + text = event_data.get("text") + timestamp = event_data.get("timestamp") + + if event_type == "TranscriptSegmentReady" and meeting_id and text: + logger.info( + f"STT 텍스트 수신 - meetingId: {meeting_id}, " + f"텍스트 길이: {len(text)}" + ) + + # Redis에 텍스트 축적 (슬라이딩 윈도우) + await self.redis_service.add_transcript_segment( + meeting_id=meeting_id, + text=text, + timestamp=timestamp + ) + + logger.debug(f"Redis 저장 완료 - meetingId: {meeting_id}") + + # 체크포인트 업데이트 + await partition_context.update_checkpoint(event) + + except Exception as e: + logger.error(f"이벤트 처리 오류: {e}", exc_info=True) + + async def on_error(self, partition_context, error): + """에러 핸들러""" + logger.error( + f"Event Hub 에러 - Partition: {partition_context.partition_id}, " + f"Error: {error}" + ) + + async def stop(self): + """Event Hub 리스너 종료""" + if self.client: + await self.client.close() + logger.info("Event Hub 리스너 종료") + + +# 백그라운드 태스크로 실행할 함수 +async def start_eventhub_listener(): + """Event Hub 리스너 백그라운드 실행""" + service = EventHubService() + await service.start() diff --git a/ai-python/app/services/redis_service.py b/ai-python/app/services/redis_service.py new file mode 100644 index 0000000..018d6c5 --- /dev/null +++ b/ai-python/app/services/redis_service.py @@ -0,0 +1,117 @@ +"""Redis 서비스 - 실시간 텍스트 축적""" +import redis.asyncio as redis +import logging +from typing import List +from app.config import get_settings + +logger = logging.getLogger(__name__) +settings = get_settings() + + +class RedisService: + """Redis 서비스 (슬라이딩 윈도우 방식)""" + + def __init__(self): + self.redis_client = None + + async def connect(self): + """Redis 연결""" + try: + self.redis_client = await redis.Redis( + host=settings.redis_host, + port=settings.redis_port, + password=settings.redis_password, + db=settings.redis_db, + decode_responses=True + ) + await self.redis_client.ping() + logger.info("Redis 연결 성공") + except Exception as e: + logger.error(f"Redis 연결 실패: {e}") + raise + + async def disconnect(self): + """Redis 연결 종료""" + if self.redis_client: + await self.redis_client.close() + logger.info("Redis 연결 종료") + + async def add_transcript_segment( + self, + meeting_id: str, + text: str, + timestamp: int + ): + """ + 실시간 텍스트 세그먼트 추가 (슬라이딩 윈도우) + + Args: + meeting_id: 회의 ID + text: 텍스트 세그먼트 + timestamp: 타임스탬프 (밀리초) + """ + key = f"meeting:{meeting_id}:transcript" + value = f"{timestamp}:{text}" + + # Sorted Set에 추가 (타임스탬프를 스코어로) + await self.redis_client.zadd(key, {value: timestamp}) + + # 설정된 시간 이전 데이터 제거 (기본 5분) + retention_ms = settings.text_retention_seconds * 1000 + cutoff_time = timestamp - retention_ms + await self.redis_client.zremrangebyscore(key, 0, cutoff_time) + + logger.debug(f"텍스트 세그먼트 추가 - meetingId: {meeting_id}") + + async def get_accumulated_text(self, meeting_id: str) -> str: + """ + 누적된 텍스트 조회 (최근 5분) + + Args: + meeting_id: 회의 ID + + Returns: + 누적된 텍스트 (시간순) + """ + key = f"meeting:{meeting_id}:transcript" + + # 최신순으로 모든 세그먼트 조회 + segments = await self.redis_client.zrevrange(key, 0, -1) + + if not segments: + return "" + + # 타임스탬프 제거하고 텍스트만 추출 + texts = [] + for seg in segments: + parts = seg.split(":", 1) + if len(parts) == 2: + texts.append(parts[1]) + + # 시간순으로 정렬 (역순으로 조회했으므로 다시 뒤집기) + return "\n".join(reversed(texts)) + + async def get_segment_count(self, meeting_id: str) -> int: + """ + 누적된 세그먼트 개수 + + Args: + meeting_id: 회의 ID + + Returns: + 세그먼트 개수 + """ + key = f"meeting:{meeting_id}:transcript" + count = await self.redis_client.zcard(key) + return count if count else 0 + + async def cleanup_meeting_data(self, meeting_id: str): + """ + 회의 종료 시 데이터 정리 + + Args: + meeting_id: 회의 ID + """ + key = f"meeting:{meeting_id}:transcript" + await self.redis_client.delete(key) + logger.info(f"회의 데이터 정리 완료 - meetingId: {meeting_id}") diff --git a/ai-python/main.py b/ai-python/main.py new file mode 100644 index 0000000..98d1617 --- /dev/null +++ b/ai-python/main.py @@ -0,0 +1,93 @@ +"""AI Service - FastAPI 애플리케이션""" +import logging +import uvicorn +from fastapi import FastAPI +from fastapi.middleware.cors import CORSMiddleware +from contextlib import asynccontextmanager + +from app.config import get_settings +from app.api.v1 import suggestions + +# 로깅 설정 +logging.basicConfig( + level=logging.INFO, + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' +) +logger = logging.getLogger(__name__) + +settings = get_settings() + + +@asynccontextmanager +async def lifespan(app: FastAPI): + """애플리케이션 생명주기 관리""" + logger.info("=" * 60) + logger.info(f"AI Service (Python) 시작 - Port: {settings.port}") + logger.info(f"Claude Model: {settings.claude_model}") + logger.info(f"Redis: {settings.redis_host}:{settings.redis_port}") + logger.info("=" * 60) + + # TODO: Event Hub 리스너 시작 (별도 백그라운드 태스크) + # asyncio.create_task(start_eventhub_listener()) + + yield + + logger.info("AI Service 종료") + + +# FastAPI 애플리케이션 +app = FastAPI( + title=settings.app_name, + version="1.0.0", + description="실시간 AI 제안사항 서비스 (Python)", + lifespan=lifespan +) + +# CORS 설정 +app.add_middleware( + CORSMiddleware, + allow_origins=settings.cors_origins, + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) + +# 라우터 등록 +app.include_router( + suggestions.router, + prefix="/api/v1/ai/suggestions", + tags=["AI Suggestions"] +) + + +@app.get("/") +async def root(): + """루트 엔드포인트""" + return { + "service": settings.app_name, + "version": "1.0.0", + "status": "running", + "endpoints": { + "test": "/api/v1/ai/suggestions/test", + "stream": "/api/v1/ai/suggestions/meetings/{meeting_id}/stream" + } + } + + +@app.get("/health") +async def health_check(): + """헬스 체크""" + return { + "status": "healthy", + "service": settings.app_name + } + + +if __name__ == "__main__": + uvicorn.run( + "main:app", + host=settings.host, + port=settings.port, + reload=True, # 개발 모드 + log_level=settings.log_level.lower() + ) diff --git a/ai-python/requirements.txt b/ai-python/requirements.txt new file mode 100644 index 0000000..30069d4 --- /dev/null +++ b/ai-python/requirements.txt @@ -0,0 +1,21 @@ +# FastAPI 및 서버 +fastapi==0.104.1 +uvicorn[standard]==0.24.0 +sse-starlette==1.8.2 + +# AI/ML +anthropic==0.42.0 + +# 데이터베이스 및 캐시 +redis==5.0.1 + +# Azure 서비스 +azure-eventhub==5.11.4 + +# 데이터 모델 및 검증 +pydantic==2.10.5 +pydantic-settings==2.7.1 + +# 유틸리티 +python-dotenv==1.0.0 +python-json-logger==2.0.7 diff --git a/ai-python/start.sh b/ai-python/start.sh new file mode 100755 index 0000000..b0ac5af --- /dev/null +++ b/ai-python/start.sh @@ -0,0 +1,35 @@ +#!/bin/bash + +# AI Service (Python) 시작 스크립트 + +echo "======================================" +echo "AI Service (Python) 시작" +echo "======================================" + +# 가상환경 활성화 (선택사항) +# source venv/bin/activate + +# 의존성 설치 확인 +if [ ! -d "venv" ]; then + echo "가상환경이 없습니다. 생성 중..." + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt +else + source venv/bin/activate +fi + +# .env 파일 확인 +if [ ! -f ".env" ]; then + echo ".env 파일이 없습니다. .env.example을 복사합니다." + cp .env.example .env + echo "⚠️ .env 파일에 실제 API 키를 설정해주세요." +fi + +# FastAPI 서버 시작 +echo "======================================" +echo "FastAPI 서버 시작 중..." +echo "Port: 8086" +echo "======================================" + +python3 main.py diff --git a/develop/dev/dev-ai-frontend-integration.md b/develop/dev/dev-ai-frontend-integration.md new file mode 100644 index 0000000..c154764 --- /dev/null +++ b/develop/dev/dev-ai-frontend-integration.md @@ -0,0 +1,482 @@ +# AI 서비스 프론트엔드 통합 가이드 + +## 개요 + +AI 서비스의 실시간 제안사항 API를 프론트엔드에서 사용하기 위한 통합 가이드입니다. + +**⚠️ 중요**: AI 서비스가 **Python (FastAPI)**로 마이그레이션 되었습니다. +- **기존 포트**: 8083 (Java Spring Boot) → **새 포트**: 8086 (Python FastAPI) +- **엔드포인트 경로**: `/api/suggestions/...` → `/api/v1/ai/suggestions/...` + +--- + +## 1. API 정보 + +### 엔드포인트 +``` +GET /api/v1/ai/suggestions/meetings/{meetingId}/stream +``` + +**변경 사항**: +- ✅ **새 경로** (Python): `/api/v1/ai/suggestions/meetings/{meetingId}/stream` +- ❌ **구 경로** (Java): `/api/suggestions/meetings/{meetingId}/stream` + +### 메서드 +- **HTTP Method**: GET +- **Content-Type**: text/event-stream (SSE) +- **인증**: 개발 환경에서는 불필요 (운영 환경에서는 JWT 필요) + +### 파라미터 +| 파라미터 | 타입 | 필수 | 설명 | +|---------|------|------|------| +| meetingId | string (UUID) | 필수 | 회의 고유 ID | + +### 예시 +``` +# Python (새 버전) +http://localhost:8086/api/v1/ai/suggestions/meetings/550e8400-e29b-41d4-a716-446655440000/stream + +# Java (구 버전 - 사용 중단 예정) +http://localhost:8083/api/suggestions/meetings/550e8400-e29b-41d4-a716-446655440000/stream +``` + +--- + +## 2. 응답 데이터 구조 + +### SSE 이벤트 형식 +``` +event: ai-suggestion +id: 123456789 +data: {"suggestions":[...]} +``` + +### 데이터 스키마 (JSON) +```typescript +interface RealtimeSuggestionsDto { + suggestions: SimpleSuggestionDto[]; +} + +interface SimpleSuggestionDto { + id: string; // 제안 고유 ID (예: "suggestion-1") + content: string; // 제안 내용 (예: "신제품의 타겟 고객층...") + timestamp: string; // 시간 정보 (HH:MM:SS 형식, 예: "00:05:23") + confidence: number; // 신뢰도 점수 (0.0 ~ 1.0) +} +``` + +### 샘플 응답 +```json +{ + "suggestions": [ + { + "id": "suggestion-1", + "content": "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.", + "timestamp": "00:05:23", + "confidence": 0.92 + } + ] +} +``` + +--- + +## 3. 프론트엔드 구현 방법 + +### 3.1 EventSource로 연결 + +```javascript +// 회의 ID (실제로는 회의 생성 API에서 받아야 함) +const meetingId = '550e8400-e29b-41d4-a716-446655440000'; + +// SSE 연결 (Python 버전) +const apiUrl = `http://localhost:8086/api/v1/ai/suggestions/meetings/${meetingId}/stream`; +const eventSource = new EventSource(apiUrl); + +// 연결 성공 +eventSource.onopen = function(event) { + console.log('SSE 연결 성공'); +}; + +// ai-suggestion 이벤트 수신 +eventSource.addEventListener('ai-suggestion', function(event) { + const data = JSON.parse(event.data); + const suggestions = data.suggestions; + + suggestions.forEach(suggestion => { + console.log('제안:', suggestion.content); + addSuggestionToUI(suggestion); + }); +}); + +// 에러 처리 +eventSource.onerror = function(error) { + console.error('SSE 연결 오류:', error); + eventSource.close(); +}; +``` + +### 3.2 UI에 제안사항 추가 + +```javascript +function addSuggestionToUI(suggestion) { + const container = document.getElementById('aiSuggestionList'); + + // 중복 방지 + if (document.getElementById(`suggestion-${suggestion.id}`)) { + return; + } + + // HTML 생성 + const html = ` +
+
+ ${escapeHtml(suggestion.timestamp)} + +
+
+ ${escapeHtml(suggestion.content)} +
+
+ `; + + container.insertAdjacentHTML('beforeend', html); +} +``` + +### 3.3 XSS 방지 + +```javascript +function escapeHtml(text) { + const map = { + '&': '&', + '<': '<', + '>': '>', + '"': '"', + "'": ''' + }; + return text.replace(/[&<>"']/g, m => map[m]); +} +``` + +### 3.4 연결 종료 + +```javascript +// 페이지 종료 시 또는 회의 종료 시 +window.addEventListener('beforeunload', function() { + if (eventSource) { + eventSource.close(); + } +}); +``` + +--- + +## 4. React 통합 예시 + +### 4.1 Custom Hook + +```typescript +import { useEffect, useState } from 'react'; + +interface Suggestion { + id: string; + content: string; + timestamp: string; + confidence: number; +} + +export function useAiSuggestions(meetingId: string) { + const [suggestions, setSuggestions] = useState([]); + const [isConnected, setIsConnected] = useState(false); + const [error, setError] = useState(null); + + useEffect(() => { + const apiUrl = `http://localhost:8086/api/v1/ai/suggestions/meetings/${meetingId}/stream`; + const eventSource = new EventSource(apiUrl); + + eventSource.onopen = () => { + setIsConnected(true); + setError(null); + }; + + eventSource.addEventListener('ai-suggestion', (event) => { + try { + const data = JSON.parse(event.data); + setSuggestions(prev => [...prev, ...data.suggestions]); + } catch (err) { + setError(err as Error); + } + }); + + eventSource.onerror = (err) => { + setError(new Error('SSE connection failed')); + setIsConnected(false); + eventSource.close(); + }; + + return () => { + eventSource.close(); + setIsConnected(false); + }; + }, [meetingId]); + + return { suggestions, isConnected, error }; +} +``` + +### 4.2 Component 사용 + +```typescript +function MeetingPage({ meetingId }: { meetingId: string }) { + const { suggestions, isConnected, error } = useAiSuggestions(meetingId); + + if (error) { + return
Error: {error.message}
; + } + + return ( +
+
연결 상태: {isConnected ? '연결됨' : '연결 안 됨'}
+ +
+ {suggestions.map(suggestion => ( +
+ {suggestion.timestamp} +

{suggestion.content}

+ +
+ ))} +
+
+ ); +} +``` + +--- + +## 5. 환경별 설정 + +### 5.1 개발 환경 +```javascript +// Python 버전 (권장) +const API_BASE_URL = 'http://localhost:8086'; + +// Java 버전 (구버전 - 사용 중단 예정) +// const API_BASE_URL = 'http://localhost:8083'; +``` + +### 5.2 테스트 환경 +```javascript +const API_BASE_URL = 'https://test-api.hgzero.com'; +``` + +### 5.3 운영 환경 +```javascript +// 같은 도메인에서 실행될 경우 +const API_BASE_URL = ''; + +// 또는 환경변수 사용 +const API_BASE_URL = process.env.REACT_APP_AI_API_URL; +``` + +--- + +## 6. 에러 처리 + +### 6.1 연결 실패 + +```javascript +eventSource.onerror = function(error) { + console.error('SSE 연결 실패:', error); + + // 사용자에게 알림 + showErrorNotification('AI 제안사항을 받을 수 없습니다. 다시 시도해주세요.'); + + // 재연결 시도 (옵션) + setTimeout(() => { + reconnect(); + }, 5000); +}; +``` + +### 6.2 파싱 오류 + +```javascript +try { + const data = JSON.parse(event.data); +} catch (error) { + console.error('데이터 파싱 오류:', error); + console.error('원본 데이터:', event.data); + + // Sentry 등 에러 모니터링 서비스에 전송 + reportError(error, { eventData: event.data }); +} +``` + +### 6.3 네트워크 오류 + +```javascript +// Timeout 설정 (EventSource는 기본 타임아웃 없음) +const connectionTimeout = setTimeout(() => { + if (!isConnected) { + console.error('연결 타임아웃'); + eventSource.close(); + handleConnectionTimeout(); + } +}, 10000); // 10초 + +eventSource.onopen = function() { + clearTimeout(connectionTimeout); + setIsConnected(true); +}; +``` + +--- + +## 7. 운영 환경 배포 시 변경 사항 + +### 7.1 인증 헤더 추가 (운영 환경) + +⚠️ **중요**: 개발 환경에서는 인증이 해제되어 있지만, **운영 환경에서는 JWT 토큰이 필요**합니다. + +```javascript +// EventSource는 헤더를 직접 설정할 수 없으므로 URL에 토큰 포함 +const token = getAccessToken(); +const apiUrl = `${API_BASE_URL}/api/suggestions/meetings/${meetingId}/stream?token=${token}`; + +// 또는 fetch API + ReadableStream 사용 (권장) +const response = await fetch(apiUrl, { + headers: { + 'Authorization': `Bearer ${token}` + } +}); + +const reader = response.body.getReader(); +// SSE 파싱 로직 구현 +``` + +### 7.2 CORS 설정 확인 + +운영 환경 도메인이 백엔드 CORS 설정에 포함되어 있는지 확인: + +```yaml +# application.yml +cors: + allowed-origins: https://your-production-domain.com +``` + +--- + +## 8. AI 개발 완료 후 변경 사항 + +### 8.1 제거할 백엔드 코드 +- [SuggestionService.java:102](ai/src/main/java/com/unicorn/hgzero/ai/biz/service/SuggestionService.java:102) - Mock 데이터 발행 호출 +- [SuggestionService.java:192-236](ai/src/main/java/com/unicorn/hgzero/ai/biz/service/SuggestionService.java:192-236) - Mock 메서드 전체 +- [SecurityConfig.java:49](ai/src/main/java/com/unicorn/hgzero/ai/infra/config/SecurityConfig.java:49) - 인증 해제 설정 + +### 8.2 프론트엔드는 변경 불필요 +- SSE 연결 코드는 그대로 유지 +- API URL만 운영 환경에 맞게 수정 +- JWT 토큰 추가 (위 7.1 참고) + +### 8.3 실제 AI 동작 방식 (예상) +``` +STT 텍스트 생성 → Event Hub 전송 → AI 서비스 수신 → +텍스트 축적 (Redis) → 임계값 도달 → Claude API 분석 → +SSE로 제안사항 발행 → 프론트엔드 수신 +``` + +현재 Mock은 **5초, 10초, 15초**에 발행하지만, 실제 AI는 **회의 진행 상황에 따라 동적으로** 발행됩니다. + +--- + +## 9. 알려진 제한사항 + +### 9.1 브라우저 호환성 +- **EventSource는 IE 미지원** (Edge, Chrome, Firefox, Safari는 지원) +- 필요 시 Polyfill 사용: `event-source-polyfill` + +### 9.2 연결 제한 +- 동일 도메인에 대한 SSE 연결은 브라우저당 **6개로 제한** +- 여러 탭에서 동시 접속 시 주의 + +### 9.3 재연결 +- EventSource는 자동 재연결을 시도하지만, 서버에서 연결을 끊으면 재연결 안 됨 +- 수동 재연결 로직 구현 권장 + +### 9.4 Mock 데이터 특성 +- **개발 환경 전용**: 3개 제안 후 자동 종료 +- **실제 AI**: 회의 진행 중 계속 발행, 회의 종료 시까지 연결 유지 + +--- + +## 10. 테스트 방법 + +### 10.1 로컬 테스트 +```bash +# 1. AI 서비스 실행 +python3 tools/run-intellij-service-profile.py ai + +# 2. HTTP 서버 실행 (file:// 프로토콜은 CORS 제한) +cd design/uiux/prototype +python3 -m http.server 8000 + +# 3. 브라우저에서 접속 +open http://localhost:8000/05-회의진행.html +``` + +### 10.2 디버깅 +```javascript +// 브라우저 개발자 도구 Console 탭에서 확인 +// [DEBUG] 로그로 상세 정보 출력 +// [ERROR] 로그로 에러 추적 +``` + +### 10.3 curl 테스트 +```bash +# Python 버전 (새 포트) +curl -N http://localhost:8086/api/v1/ai/suggestions/meetings/test-meeting/stream + +# Java 버전 (구 포트 - 사용 중단 예정) +# curl -N http://localhost:8083/api/suggestions/meetings/550e8400-e29b-41d4-a716-446655440000/stream +``` + +--- + +## 11. 참고 문서 + +- [AI Service API 설계서](../../design/backend/api/spec/ai-service-api-spec.md) +- [AI 샘플 데이터 통합 가이드](dev-ai-sample-data-guide.md) +- [SSE 스트리밍 가이드](dev-ai-realtime-streaming.md) + +--- + +## 12. FAQ + +### Q1. 왜 EventSource를 사용하나요? +**A**: WebSocket보다 단방향 통신에 적합하고, 자동 재연결 기능이 있으며, 구현이 간단합니다. + +### Q2. 제안사항이 중복으로 표시되는 경우? +**A**: `addSuggestionToUI` 함수에 중복 체크 로직이 있는지 확인하세요. + +### Q3. 연결은 되는데 데이터가 안 오는 경우? +**A**: +1. 백엔드 로그 확인 (`ai/logs/ai-service.log`) +2. Network 탭에서 `stream` 요청 확인 +3. `ai-suggestion` 이벤트 리스너가 등록되었는지 확인 + +### Q4. 운영 환경에서 401 Unauthorized 에러? +**A**: JWT 토큰이 필요합니다. 7.1절 "인증 헤더 추가" 참고. + +--- + +## 문서 이력 + +| 버전 | 작성일 | 작성자 | 변경 내용 | +|------|--------|--------|----------| +| 1.0 | 2025-10-27 | 준호 (Backend), 유진 (Frontend) | 초안 작성 | diff --git a/develop/dev/dev-ai-python-migration.md b/develop/dev/dev-ai-python-migration.md new file mode 100644 index 0000000..4fc831c --- /dev/null +++ b/develop/dev/dev-ai-python-migration.md @@ -0,0 +1,319 @@ +# AI Service Python 마이그레이션 완료 보고서 + +## 📋 작업 개요 + +Java Spring Boot 기반 AI 서비스를 Python FastAPI로 마이그레이션 완료 + +**작업 일시**: 2025-10-27 +**작업자**: 서연 (AI Specialist), 준호 (Backend Developer) + +--- + +## ✅ 완료 항목 + +### 1. 프로젝트 구조 생성 +``` +ai-python/ +├── main.py ✅ FastAPI 애플리케이션 진입점 +├── requirements.txt ✅ 의존성 정의 +├── .env.example ✅ 환경 변수 예시 +├── .env ✅ 실제 환경 변수 +├── start.sh ✅ 시작 스크립트 +├── README.md ✅ 프로젝트 문서 +└── app/ + ├── config.py ✅ 환경 설정 + ├── models/ + │ └── response.py ✅ 응답 모델 (Pydantic) + ├── services/ + │ ├── claude_service.py ✅ Claude API 서비스 + │ ├── redis_service.py ✅ Redis 서비스 + │ └── eventhub_service.py ✅ Event Hub 리스너 + └── api/ + └── v1/ + └── suggestions.py ✅ SSE 엔드포인트 +``` + +### 2. 핵심 기능 구현 + +#### ✅ SSE 스트리밍 (실시간 AI 제안사항) +- **엔드포인트**: `GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream` +- **기술**: Server-Sent Events (SSE) +- **동작 방식**: + 1. Frontend가 SSE 연결 + 2. Redis에서 실시간 텍스트 축적 확인 (5초마다) + 3. 임계값(10개 세그먼트) 이상이면 Claude API 분석 + 4. 분석 결과를 SSE로 스트리밍 + +#### ✅ Claude API 연동 +- **서비스**: `ClaudeService` +- **모델**: claude-3-5-sonnet-20241022 +- **기능**: 회의 텍스트 분석 및 제안사항 생성 +- **프롬프트 최적화**: 중요한 제안사항만 추출 (잡담/인사말 제외) + +#### ✅ Redis 슬라이딩 윈도우 +- **서비스**: `RedisService` +- **방식**: Sorted Set 기반 시간순 정렬 +- **보관 기간**: 최근 5분 +- **자동 정리**: 5분 이전 데이터 자동 삭제 + +#### ✅ Event Hub 연동 (STT 텍스트 수신) +- **서비스**: `EventHubService` +- **이벤트**: TranscriptSegmentReady (STT에서 발행) +- **처리**: 실시간 텍스트를 Redis에 축적 + +### 3. 기술 스택 + +| 항목 | 기술 | 버전 | +|------|------|------| +| 언어 | Python | 3.13 | +| 프레임워크 | FastAPI | 0.104.1 | +| ASGI 서버 | Uvicorn | 0.24.0 | +| AI | Anthropic Claude | 0.42.0 | +| 캐시 | Redis | 5.0.1 | +| 이벤트 | Azure Event Hub | 5.11.4 | +| 검증 | Pydantic | 2.10.5 | +| SSE | sse-starlette | 1.8.2 | + +--- + +## 🔍 테스트 결과 + +### 1. 서비스 시작 테스트 +```bash +$ ./start.sh +====================================== +AI Service (Python) 시작 +Port: 8086 +====================================== +✅ FastAPI 서버 정상 시작 +``` + +### 2. 헬스 체크 +```bash +$ curl http://localhost:8086/health +{"status":"healthy","service":"AI Service (Python)"} +✅ 헬스 체크 정상 +``` + +### 3. SSE 스트리밍 테스트 +```bash +$ curl -N http://localhost:8086/api/v1/ai/suggestions/meetings/test-meeting/stream +✅ SSE 연결 성공 +✅ Redis 연결 성공 +✅ 5초마다 텍스트 축적 확인 정상 동작 +``` + +### 4. 로그 확인 +``` +2025-10-27 11:18:54,916 - AI Service (Python) 시작 - Port: 8086 +2025-10-27 11:18:54,916 - Claude Model: claude-3-5-sonnet-20241022 +2025-10-27 11:18:54,916 - Redis: 20.249.177.114:6379 +2025-10-27 11:19:13,213 - SSE 스트림 시작 - meetingId: test-meeting +2025-10-27 11:19:13,291 - Redis 연결 성공 +2025-10-27 11:19:28,211 - SSE 스트림 종료 - meetingId: test-meeting +✅ 모든 로그 정상 +``` + +--- + +## 🏗️ 아키텍처 설계 + +### 전체 흐름도 + +``` +┌─────────────┐ +│ Frontend │ +│ (회의록 작성)│ +└──────┬──────┘ + │ SSE 연결 + ↓ +┌─────────────────────────┐ +│ AI Service (Python) │ +│ - FastAPI │ +│ - Port: 8086 │ +│ - SSE 스트리밍 │ +└──────┬──────────────────┘ + │ Redis 조회 + ↓ +┌─────────────────────────┐ +│ Redis │ +│ - 슬라이딩 윈도우 (5분) │ +│ - 실시간 텍스트 축적 │ +└──────┬──────────────────┘ + ↑ Event Hub + │ +┌─────────────────────────┐ +│ STT Service (Java) │ +│ - 음성 → 텍스트 │ +│ - Event Hub 발행 │ +└─────────────────────────┘ +``` + +### front → ai 직접 호출 전략 + +**✅ 실시간 AI 제안**: `frontend → ai` (SSE 스트리밍) +- 저지연 필요 +- 네트워크 홉 감소 +- CORS 설정 완료 + +**✅ 회의록 메타데이터**: `frontend → backend` (기존 유지) +- 회의 ID, 참석자 정보 +- 데이터 일관성 보장 + +**✅ 최종 요약**: `backend → ai` (향후 구현) +- API 키 보안 강화 +- 회의 종료 시 전체 요약 + +--- + +## 📝 Java → Python 주요 차이점 + +| 항목 | Java (Spring Boot) | Python (FastAPI) | +|------|-------------------|------------------| +| 프레임워크 | Spring WebFlux | FastAPI | +| 비동기 | Reactor (Flux, Mono) | asyncio, async/await | +| 의존성 주입 | @Autowired | 함수 파라미터 | +| 설정 관리 | application.yml | .env + pydantic-settings | +| SSE 구현 | Sinks.Many + asFlux() | EventSourceResponse | +| Redis 클라이언트 | RedisTemplate | redis.asyncio | +| Event Hub | EventHubConsumerClient (동기) | EventHubConsumerClient (비동기) | +| 모델 검증 | @Valid, DTO | Pydantic BaseModel | + +--- + +## 🎯 다음 단계 (Phase 2 - 통합 기능) + +### 우선순위 검토 결과 +**질문**: 회의 진행 시 참석자별 메모 통합 및 AI 요약 기능 +**결론**: ✅ STT 및 AI 제안사항 개발 완료 후 진행 (Phase 2) + +### Phase 1 (현재 완료) +- ✅ STT 서비스 개발 및 테스트 +- ✅ AI 서비스 Python 변환 +- ✅ AI 실시간 제안사항 SSE 스트리밍 + +### Phase 2 (다음 작업) +1. 참석자별 메모 UI/UX 설계 +2. AI 제안사항 + 직접 작성 통합 인터페이스 +3. 회의 종료 시 회의록 통합 로직 +4. 통합 회의록 AI 요약 기능 + +### Phase 3 (최적화) +1. 실시간 협업 기능 (다중 참석자 동시 편집) +2. 회의록 버전 관리 +3. 성능 최적화 및 캐싱 + +--- + +## 🚀 배포 및 실행 가이드 + +### 개발 환경 실행 + +```bash +# 1. 가상환경 생성 및 활성화 +python3 -m venv venv +source venv/bin/activate # Mac/Linux + +# 2. 의존성 설치 +pip install -r requirements.txt + +# 3. 환경 변수 설정 +cp .env.example .env +# .env에서 CLAUDE_API_KEY 설정 + +# 4. 서비스 시작 +./start.sh +# 또는 +python3 main.py +``` + +### 프론트엔드 연동 + +**SSE 연결 예시 (JavaScript)**: +```javascript +const eventSource = new EventSource( + 'http://localhost:8086/api/v1/ai/suggestions/meetings/meeting-123/stream' +); + +eventSource.addEventListener('ai-suggestion', (event) => { + const data = JSON.parse(event.data); + console.log('AI 제안사항:', data.suggestions); + + // UI 업데이트 + data.suggestions.forEach(suggestion => { + addSuggestionToUI(suggestion); + }); +}); + +eventSource.onerror = (error) => { + console.error('SSE 연결 오류:', error); + eventSource.close(); +}; +``` + +--- + +## 🔧 환경 변수 설정 + +**필수 환경 변수**: +```env +# Claude API (필수) +CLAUDE_API_KEY=sk-ant-api03-... # Claude API 키 + +# Redis (필수) +REDIS_HOST=20.249.177.114 +REDIS_PORT=6379 +REDIS_PASSWORD=Hi5Jessica! +REDIS_DB=4 + +# Event Hub (선택 - STT 연동 시 필요) +EVENTHUB_CONNECTION_STRING=Endpoint=sb://... +EVENTHUB_NAME=hgzero-eventhub-name +EVENTHUB_CONSUMER_GROUP=ai-transcript-group +``` + +--- + +## 📊 성능 특성 + +- **SSE 연결**: 저지연 (< 100ms) +- **Claude API 응답**: 평균 2-3초 +- **Redis 조회**: < 10ms +- **텍스트 축적 주기**: 5초 +- **분석 임계값**: 10개 세그먼트 (약 100-200자) + +--- + +## ⚠️ 주의사항 + +1. **Claude API 키 보안** + - .env 파일을 git에 커밋하지 않음 (.gitignore에 추가) + - 프로덕션 환경에서는 환경 변수로 관리 + +2. **Redis 연결** + - Redis가 없으면 서비스 시작 실패 + - 연결 정보 확인 필요 + +3. **Event Hub (선택)** + - Event Hub 연결 문자열이 없어도 SSE는 동작 + - STT 연동 시에만 필요 + +4. **CORS 설정** + - 프론트엔드 origin을 .env의 CORS_ORIGINS에 추가 + +--- + +## 📖 참고 문서 + +- [FastAPI 공식 문서](https://fastapi.tiangolo.com/) +- [Claude API 문서](https://docs.anthropic.com/) +- [Server-Sent Events (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) +- [Redis Python 클라이언트](https://redis-py.readthedocs.io/) +- [Azure Event Hubs Python SDK](https://learn.microsoft.com/azure/event-hubs/event-hubs-python-get-started-send) + +--- + +## 📞 문의 + +**기술 지원**: AI팀 (서연) +**백엔드 지원**: 백엔드팀 (준호) diff --git a/develop/dev/dev-frontend-mock-guide.md b/develop/dev/dev-frontend-mock-guide.md new file mode 100644 index 0000000..1ab4f6c --- /dev/null +++ b/develop/dev/dev-frontend-mock-guide.md @@ -0,0 +1,384 @@ +# 프론트엔드 Mock 데이터 개발 가이드 + +**작성일**: 2025-10-27 +**대상**: 프론트엔드 개발자 (유진) +**작성자**: AI팀 (서연), 백엔드팀 (준호) + +--- + +## 📋 개요 + +**현재 상황**: STT 서비스 개발 완료 전까지는 **실제 AI 제안사항이 생성되지 않습니다.** + +**해결 방안**: Mock 데이터를 사용하여 프론트엔드 UI를 독립적으로 개발할 수 있습니다. + +--- + +## 🎯 왜 Mock 데이터가 필요한가? + +### 실제 데이터 생성 흐름 + +``` +회의 (음성) + ↓ +STT 서비스 (음성 → 텍스트) ← 아직 개발 중 + ↓ +Redis (텍스트 축적) + ↓ +AI 서비스 (Claude API 분석) + ↓ +SSE 스트리밍 + ↓ +프론트엔드 +``` + +**문제점**: STT가 없으면 텍스트가 생성되지 않아 → Redis가 비어있음 → AI 분석이 실행되지 않음 + +**해결**: Mock 데이터로 **STT 없이도** UI 개발 가능 + +--- + +## 💻 Mock 데이터 구현 방법 + +### 방법 1: 로컬 Mock 함수 (권장) + +**장점**: 백엔드 없이 완전 독립 개발 가능 + +```javascript +/** + * Mock AI 제안사항 생성기 + * 실제 AI처럼 5초마다 하나씩 제안사항 발행 + */ +function connectMockAISuggestions(meetingId) { + const mockSuggestions = [ + { + id: crypto.randomUUID(), + content: "신제품의 타겟 고객층을 20-30대로 설정하고, 모바일 우선 전략을 취하기로 논의 중입니다.", + timestamp: "00:05:23", + confidence: 0.92 + }, + { + id: crypto.randomUUID(), + content: "개발 일정: 1차 프로토타입은 11월 15일까지 완성, 2차 베타는 12월 1일 론칭", + timestamp: "00:08:45", + confidence: 0.88 + }, + { + id: crypto.randomUUID(), + content: "마케팅 예산 배분에 대해 SNS 광고 60%, 인플루언서 마케팅 40%로 의견이 나왔으나 추가 검토 필요", + timestamp: "00:12:18", + confidence: 0.85 + }, + { + id: crypto.randomUUID(), + content: "보안 요구사항 검토가 필요하며, 데이터 암호화 방식에 대한 논의가 진행 중입니다.", + timestamp: "00:15:30", + confidence: 0.90 + }, + { + id: crypto.randomUUID(), + content: "React로 프론트엔드 개발하기로 결정되었으며, TypeScript 사용을 권장합니다.", + timestamp: "00:18:42", + confidence: 0.93 + } + ]; + + let index = 0; + const interval = setInterval(() => { + if (index < mockSuggestions.length) { + // EventSource의 addEventListener('ai-suggestion', ...) 핸들러를 모방 + const event = { + data: JSON.stringify({ + suggestions: [mockSuggestions[index]] + }) + }; + + // 실제 핸들러 호출 + handleAISuggestion(event); + index++; + } else { + clearInterval(interval); + console.log('[MOCK] 모든 Mock 제안사항 발행 완료'); + } + }, 5000); // 5초마다 하나씩 + + console.log('[MOCK] Mock AI 제안사항 연결 시작'); + + // 정리 함수 반환 + return { + close: () => { + clearInterval(interval); + console.log('[MOCK] Mock 연결 종료'); + } + }; +} +``` + +### 방법 2: 환경 변수로 전환 + +```javascript +// 환경 변수로 Mock/Real 모드 전환 +const USE_MOCK_AI = process.env.REACT_APP_USE_MOCK_AI === 'true'; + +function connectAISuggestions(meetingId) { + if (USE_MOCK_AI) { + console.log('[MOCK] Mock 모드로 실행'); + return connectMockAISuggestions(meetingId); + } else { + console.log('[REAL] 실제 AI 서비스 연결'); + return connectRealAISuggestions(meetingId); + } +} + +function connectRealAISuggestions(meetingId) { + const url = `http://localhost:8086/api/v1/ai/suggestions/meetings/${meetingId}/stream`; + const eventSource = new EventSource(url); + + eventSource.addEventListener('ai-suggestion', handleAISuggestion); + + eventSource.onerror = (error) => { + console.error('[REAL] SSE 연결 오류:', error); + eventSource.close(); + }; + + return eventSource; +} + +// 공통 핸들러 +function handleAISuggestion(event) { + const data = JSON.parse(event.data); + + data.suggestions.forEach(suggestion => { + addSuggestionToUI(suggestion); + }); +} +``` + +--- + +## 🔧 개발 환경 설정 + +### `.env.local` 파일 + +```env +# Mock 모드 사용 (개발 중) +REACT_APP_USE_MOCK_AI=true + +# 실제 AI 서비스 URL (STT 완료 후) +REACT_APP_AI_SERVICE_URL=http://localhost:8086 +``` + +### `package.json` 스크립트 + +```json +{ + "scripts": { + "start": "REACT_APP_USE_MOCK_AI=true react-scripts start", + "start:real": "REACT_APP_USE_MOCK_AI=false react-scripts start", + "build": "REACT_APP_USE_MOCK_AI=false react-scripts build" + } +} +``` + +--- + +## 🎨 React 전체 예시 + +```typescript +import { useEffect, useState, useRef } from 'react'; + +interface Suggestion { + id: string; + content: string; + timestamp: string; + confidence: number; +} + +interface MockConnection { + close: () => void; +} + +function useMockAISuggestions(meetingId: string) { + const [suggestions, setSuggestions] = useState([]); + const [connected, setConnected] = useState(false); + const connectionRef = useRef(null); + + useEffect(() => { + const mockSuggestions: Suggestion[] = [ + { + id: crypto.randomUUID(), + content: "신제품의 타겟 고객층을 20-30대로 설정하고...", + timestamp: "00:05:23", + confidence: 0.92 + }, + // ... 더 많은 Mock 데이터 + ]; + + let index = 0; + setConnected(true); + + const interval = setInterval(() => { + if (index < mockSuggestions.length) { + setSuggestions(prev => [mockSuggestions[index], ...prev]); + index++; + } else { + clearInterval(interval); + } + }, 5000); + + connectionRef.current = { + close: () => { + clearInterval(interval); + setConnected(false); + } + }; + + return () => { + connectionRef.current?.close(); + }; + }, [meetingId]); + + return { suggestions, connected }; +} + +function AISuggestionsPanel({ meetingId }: { meetingId: string }) { + const USE_MOCK = process.env.REACT_APP_USE_MOCK_AI === 'true'; + + const mockData = useMockAISuggestions(meetingId); + const realData = useRealAISuggestions(meetingId); // 실제 SSE 연결 + + const { suggestions, connected } = USE_MOCK ? mockData : realData; + + return ( +
+
+

AI 제안사항

+ + {connected ? (USE_MOCK ? 'Mock 모드' : '연결됨') : '연결 끊김'} + +
+ +
+ {suggestions.map(s => ( + + ))} +
+
+ ); +} +``` + +--- + +## 🧪 테스트 시나리오 + +### 1. Mock 모드 테스트 + +```bash +# Mock 모드로 실행 +REACT_APP_USE_MOCK_AI=true npm start +``` + +**확인 사항**: +- [ ] 5초마다 제안사항이 추가됨 +- [ ] 총 5개의 제안사항이 표시됨 +- [ ] 타임스탬프, 신뢰도가 정상 표시됨 +- [ ] "추가" 버튼 클릭 시 회의록에 추가됨 +- [ ] "무시" 버튼 클릭 시 제안사항이 제거됨 + +### 2. 실제 모드 테스트 (STT 완료 후) + +```bash +# AI 서비스 시작 +cd ai-python && ./start.sh + +# 실제 모드로 실행 +REACT_APP_USE_MOCK_AI=false npm start +``` + +**확인 사항**: +- [ ] SSE 연결이 정상적으로 됨 +- [ ] 실제 AI 제안사항이 수신됨 +- [ ] 회의 진행에 따라 동적으로 제안사항 생성됨 + +--- + +## 📊 Mock vs Real 비교 + +| 항목 | Mock 모드 | Real 모드 | +|------|----------|----------| +| **백엔드 필요** | 불필요 | 필요 (AI 서비스) | +| **제안 타이밍** | 5초 고정 간격 | 회의 진행에 따라 동적 | +| **제안 개수** | 5개 고정 | 무제한 (회의 종료까지) | +| **데이터 품질** | 하드코딩 샘플 | Claude AI 실제 분석 | +| **네트워크 필요** | 불필요 | 필요 | +| **개발 속도** | 빠름 | 느림 (백엔드 의존) | + +--- + +## ⚠️ 주의사항 + +### 1. Mock 데이터 관리 + +```javascript +// ❌ 나쁜 예: 컴포넌트 내부에 하드코딩 +function Component() { + const mockData = [/* ... */]; // 재사용 불가 +} + +// ✅ 좋은 예: 별도 파일로 분리 +// src/mocks/aiSuggestions.ts +export const MOCK_AI_SUGGESTIONS = [/* ... */]; +``` + +### 2. 환경 변수 누락 방지 + +```javascript +// ❌ 나쁜 예: 하드코딩 +const USE_MOCK = true; + +// ✅ 좋은 예: 환경 변수 + 기본값 +const USE_MOCK = process.env.REACT_APP_USE_MOCK_AI !== 'false'; +``` + +### 3. 프로덕션 빌드 시 Mock 제거 + +```javascript +// ❌ 나쁜 예: 프로덕션에도 Mock 코드 포함 +if (USE_MOCK) { /* mock logic */ } + +// ✅ 좋은 예: Tree-shaking 가능하도록 작성 +if (process.env.NODE_ENV !== 'production' && USE_MOCK) { + /* mock logic */ +} +``` + +--- + +## 🚀 다음 단계 + +### Phase 1: Mock으로 UI 개발 (현재) +- ✅ Mock 데이터 함수 구현 +- ✅ UI 컴포넌트 개발 +- ✅ 사용자 인터랙션 구현 + +### Phase 2: STT 연동 대기 (진행 중) +- 🔄 Backend에서 STT 개발 중 +- 🔄 Event Hub 연동 개발 중 + +### Phase 3: 실제 연동 (STT 완료 후) +- [ ] Mock → Real 모드 전환 +- [ ] 통합 테스트 +- [ ] 성능 최적화 + +--- + +## 📞 문의 + +**Mock 데이터 관련**: 프론트엔드팀 (유진) +**STT 개발 현황**: 백엔드팀 (준호) +**AI 서비스**: AI팀 (서연) + +--- + +**최종 업데이트**: 2025-10-27