FastAPI + OpenAI + Postgres(pgvector) + Redis 샘플

요구사항

• Python 3.10+
• OpenAI API Key (필수)
• 선택: Docker(로컬 Postgres/Redis 구동용)

1) 환경 설정

cp .env.example .env
# .env에 OPENAI_API_KEY=... 채우기
# DB/Redis 없이 먼저 테스트하려면
# SKIP_DB=true
# SKIP_REDIS=true

2) 의존성 설치 (한 번만)

• Cursor 하단 터미널에서 가상환경을 만든 뒤 설치하세요.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

3) 실행 방법 (VS Code & Cursor)

VS Code

• 좌측 Run and Debug 아이콘(▶️) 클릭 또는 ⇧⌘D 단축키
• "FastAPI: Uvicorn" 구성 선택 후 F5(실행 및 디버그)
• 또는 run.py 파일 열기 → 상단의 "Run Python File" 클릭

Cursor

• 하단 터미널에서 직접 명령어 실행 가능
  • uvicorn app.main:app --reload
• Run and Debug 기능도 VS Code와 동일하게 사용 가능
• 실행 후 접속:
  • 메인 UI: http://127.0.0.1:8000/
  • 문서: http://127.0.0.1:8000/docs

4) 제공 기능(엔드포인트)

• 단순 Q&A: POST /chat-direct
• 대화 세션: POST /chat-session/start, POST /chat-session/send
• 임베딩 저장/검색: POST /embed, GET /search
• STT/TTS: POST /stt(파일 업로드), POST /tts(텍스트→mp3 저장)
• 헬스체크: GET /health

웹 UI

• 랜딩 카드: /
• 단순 질문: /simple
• 세션 대화: /session
• STT 업로드: /stt-ui
• TTS 합성: /tts-ui (여러 줄 입력/음성 선택/파일명 지정 가능, 결과는 /data/tts/*.mp3로 저장되며 브라우저에서 재생)
• 생성 파일 정적 서빙: /data (예: /data/tts/xxx.mp3)

(선택) DB/Redis 사용

• Docker로 인프라 실행:

docker compose up -d

• 스키마 생성:

source .venv/bin/activate
python -m app.migrate

• .env에서 SKIP_DB=false, SKIP_REDIS=false로 설정 후 서버 재시작

(선택) Makefile 단축 명령

• IDE 없이 터미널로 빠르게 실행하고 싶을 때 사용(선택 사항)

make venv && make install   # 최초 1회
make start                   # 백그라운드 실행(+헬스 체크)
make stop                    # 종료
make migrate                 # DB 스키마 생성
make logs                    # 서버 로그 보기

체크리스트(필수 사항 점검)

• .env에 OPENAI_API_KEY가 설정되었는가?
• (DB/Redis 미사용이면) .env에 SKIP_DB=true, SKIP_REDIS=true 설정했는가?
• 가상환경 활성화 후 pip install -r requirements.txt를 완료했는가?
• 포트 8000을 다른 프로세스가 사용 중이지 않은가?
• TTS/STT 결과 저장 경로 data/tts, data/stt가 접근 가능한가(자동 생성됨)?
• DB/Redis 사용 시 docker compose up -d 후 python -m app.migrate를 실행했는가?

문제 해결

• 키 없음: UI에 안내(버튼 비활성), API는 400 반환 → .env의 OPENAI_API_KEY 입력 후 재시작
• 포트 충돌: 다른 Uvicorn 종료(pkill -f "uvicorn app.main:app") 또는 포트 변경
• 폼 처리 에러: python-multipart 설치 필요(이미 requirements에 포함)
• 음성 합성 에러: /tts 응답의 에러 메시지를 확인하여 SDK 버전/파라미터를 점검

테스트

source .venv/bin/activate
pytest -q

수동 실행(대안)

source .venv/bin/activate
uvicorn app.main:app --reload
# 또는
python run.py