mirror of
https://github.com/hwanny1128/HGZero.git
synced 2025-12-06 12:36:23 +00:00
168 lines
4.0 KiB
Markdown
168 lines
4.0 KiB
Markdown
# 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: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)**:
|
|
```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` | 서비스 포트 | 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로 프론트엔드에 스트리밍
|
|
|
|
## 🧪 테스트
|
|
|
|
```bash
|
|
# 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 연결 확인
|
|
```bash
|
|
redis-cli -h 20.249.177.114 -p 6379 -a Hi5Jessica! ping
|
|
# 응답: PONG
|
|
```
|
|
|
|
### Event Hub 설정 (선택)
|
|
- Event Hub가 없어도 SSE 스트리밍은 동작합니다
|
|
- STT 연동 시 필요
|
|
|
|
## 🚧 TODO
|
|
|
|
- [ ] Event Hub 연동 테스트
|
|
- [ ] 프론트엔드 연동 테스트
|
|
- [ ] 에러 핸들링 강화
|
|
- [ ] 로깅 개선
|
|
- [ ] 성능 모니터링
|