hgzero/ai-python

AI Service (Python)

실시간 AI 제안사항 서비스 - FastAPI 기반

📋 개요

STT 서비스에서 실시간으로 변환된 텍스트를 받아 Claude API로 분석하여 회의 제안사항을 생성하고, SSE(Server-Sent Events)로 프론트엔드에 스트리밍합니다.

🏗️ 아키텍처

Frontend (회의록 작성 화면)
    ↓ (SSE 연결)
AI Service (Python)
    ↓ (Redis 조회)
Redis (실시간 텍스트 축적)
    ↑ (Event Hub)
STT Service (음성 → 텍스트)

🚀 실행 방법

1. 환경 설정

# .env 파일 생성
cp .env.example .env

# .env에서 아래 값 설정
CLAUDE_API_KEY=sk-ant-...  # 실제 Claude API 키

2. 의존성 설치

# 가상환경 생성 (권장)
python3 -m venv venv
source venv/bin/activate  # Mac/Linux
# venv\Scripts\activate   # Windows

# 패키지 설치
pip install -r requirements.txt

3. 서비스 시작

# 방법 1: 스크립트 실행
./start.sh

# 방법 2: 직접 실행
python3 main.py

4. 서비스 확인

# 헬스 체크
curl http://localhost:8087/health

# SSE 스트림 테스트
curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream

📡 API 엔드포인트

SSE 스트리밍

GET /api/v1/ai/suggestions/meetings/{meeting_id}/stream

응답 형식 (SSE):

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	서비스 포트	8087

🔍 동작 원리

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로 프론트엔드에 스트리밍

🧪 테스트

# Event Hub 없이 SSE만 테스트 (Mock 데이터)
curl -N http://localhost:8087/api/v1/ai/suggestions/meetings/test-meeting/stream

# 5초마다 샘플 제안사항이 발행됩니다

📝 개발 가이드

Claude API 키 발급

1. https://console.anthropic.com/ 접속
2. API Keys 메뉴에서 새 키 생성
3. .env 파일에 설정

Redis 연결 확인

redis-cli -h 20.249.177.114 -p 6379 -a Hi5Jessica! ping
# 응답: PONG

Event Hub 설정 (선택)

• Event Hub가 없어도 SSE 스트리밍은 동작합니다
• STT 연동 시 필요

🚧 TODO

• Event Hub 연동 테스트
• 프론트엔드 연동 테스트
• 에러 핸들링 강화
• 로깅 개선
• 성능 모니터링