IntentFlow

로컬 음성→의도→응답→음성 파이프라인(학습/실험용).

Quickstart

1. 모델/보이스 파일을 models/, voices/에 배치
2. .env.sample → .env 복사 후 파라미터 조정
3. make up # Weaviate, Piper, Orchestrator 컨테이너 기동
4. make seed # seed.yaml → VDB 업서트(추후 구현)
5. curl http://localhost:8000/health

API

• POST /voice/infer : 오디오(Base64) → 텍스트/의도/응답/오디오(b64)

프로젝트 구조

intentflow/
├─ docs/                    # 문서
│  ├─ DEVELOPMENT_PLAN.md   # 전체 개발 계획 (메인 문서)
│  ├─ week_plans/          # 주간 개발 계획
│  │  ├─ week_01_happy_path.md   # 해피패스 완성 (A1~B6)
│  │  ├─ week_02_fallback.md     # 백업/튜닝 (C1~C2)
│  │  ├─ week_03_monitoring.md   # 모니터링 강화
│  │  └─ week_04_intent_design.md # Intent 설계 완성 (D1~D2)
│  ├─ milestones/          # 마일스톤 문서
│  │  ├─ milestone_1_core_pipeline.md
│  │  ├─ milestone_2_fallback_system.md
│  │  └─ milestone_3_production_ready.md
│  ├─ progress/            # 진행 상황 문서
│  │  ├─ daily_standup_template.md
│  │  └─ weekly_review_template.md
│  ├─ task_master/         # 작업 관리 문서
│  │  ├─ task_flow.md      # 전체 작업 흐름 정의
│  │  └─ task_guide.md     # 작업 가이드
│  ├─ ARCHITECTURE.md      # 시스템 아키텍처
│  ├─ API_SPEC.md          # API 명세
│  ├─ INTENT_DESIGN.md     # Intent 설계
│  └─ TUNING_GUIDE.md      # 튜닝 가이드
├─ orchestrator/           # FastAPI 백엔드
├─ web/                    # 프론트엔드 데모
├─ intents/                # 의도 정의 및 임포트
├─ models/                 # AI 모델 파일들
├─ voices/                 # TTS 보이스 파일들
├─ data/samples/           # 샘플 데이터
└─ docker-compose.yml      # 컨테이너 설정

개발 계획

🎯 현재 상태

• 완료: HealthCheck API (A1) ✅
• 진행 중: Config Setup (A2) 🔄
• 대기 중: STT, Embedding, Vector Search, Template Render, TTS, Orchestrate API 등

📅 개발 로드맵

Week 01: 해피패스 완성 (A1~B6)

• Config Setup 완료
• STT Infer 구현 (Whisper)
• Embedding 서비스 구현
• Vector Search 구현 (Weaviate)
• Template Render 구현
• TTS Synthesize 구현 (Piper)
• Orchestrate API 완성

Week 02: 백업/튜닝 (C1~C2)

• LLM Fallback 구현
• Parameter Tuning 실험

Week 03: 모니터링 강화

• 성능 모니터링 구현
• 메트릭 수집 및 대시보드

Week 04: Intent 설계 완성 (D1~D2)

• Intent Define (YAML 규격)
• Intent Test (회귀테스트)

📊 성공 지표

• /voice/infer 응답 시간 p95 ≤ 1500ms
• Intent 매칭 정확도 ≥ 85%
• LLM 폴백률 ≤ 30%
• /health uptime ≥ 99.9%

🛠️ 개발 환경 준비사항

1. 모델 파일: models/ 디렉토리에 Whisper 모델 배치
2. 보이스 파일: voices/ 디렉토리에 Piper 모델 배치
3. 환경 설정: .env.sample → .env 복사 및 설정

개발 환경 설정

# 가상환경 생성 및 의존성 설치
make venv && make deps

# 로컬 개발 서버 실행
make run

# 웹 테스트 인터페이스 실행
make web
# 브라우저에서 http://localhost:5500 접속

웹 인터페이스 주요 기능:

• 🎤 브라우저에서 직접 음성 녹음
• 📁 오디오 파일 업로드 테스트
• 📊 Intent 후보 및 스코어 확인
• 🔊 TTS 응답 즉시 재생
• 📝 테스트 히스토리 관리
• 🌓 다크 모드 지원

## Docker 환경

IntentFlow는 완전한 Docker 환경을 지원합니다. 상세한 가이드는 [DOCKER_SETUP.md](docs/DOCKER_SETUP.md)를 참고하세요.

```bash
# 모든 서비스 시작 (Weaviate, Piper, Orchestrator)
make up

# 서비스 상태 확인
docker compose ps

# 로그 확인
docker compose logs -f orchestrator

# Health check
curl http://localhost:8000/health

# 컨테이너 중지
make down

주요 서비스:

• Weaviate: 벡터 데이터베이스 (port 8080)
• Piper: TTS 서비스 (port 8081)
• Orchestrator: 메인 애플리케이션 (port 8000)

개발 워크플로우:

# 옵션 1: 하이브리드 (권장)
make up    # 의존 서비스만 Docker로
make run   # Orchestrator는 로컬에서 (빠른 개발)

# 옵션 2: 완전 컨테이너
docker compose up -d  # 모든 서비스 컨테이너로

문서 가이드

• 개발 사이클: DEVELOPMENT_CYCLE.md ⭐ 시작하기
• 슬래시 명령어: COMMAND_README.md
• Docker 환경: DOCKER_SETUP.md 🐳 컨테이너 가이드
• 웹 테스트 인터페이스: web/README.md 🌐 웹 UI 가이드
• 전체 개발 계획: DEVELOPMENT_PLAN.md
• 작업 흐름: task_flow.md
• 시스템 아키텍처: ARCHITECTURE.md
• API 명세: API_SPEC.md