[파이썬] AI 활용 웹 서비스 개발 기록 : 7 main / ai_server 설명

이전 내용

[파이썬] AI 활용 웹 서비스 개발 기록 : 6 scheme_files

---

전체 디렉터리 구조

 

- 기술 스택

• FastAPI (비동기 REST API)
• SQLAlchemy (ORM)
• Pydantic (입력값 검증)
• PostgreSQL (RDBMS)
• 로깅 시스템 (logger): logging 모듈 기반 로그 기록
• 비밀번호 해싱: Passlib (bcrypt)
• 이메일 처리: SMTP + 커스텀 EmailService
• 유효성 검사: re 정규표현식, 수동 로직
• 백그라운드 작업: BackgroundTasks
• 세션 처리: FastAPI session middleware
• 세션 상태 관리: st.session_state
• API 키 관리: dotenv (.env), st.secrets

- 구현 의도

• 단순한 CRUD API를 넘어서 실서비스에서 필요한 유효성 검사, 예외 처리, 중복 방지 등 실제 운영 환경에서 중요한 요소들을 고려해 설계.
• 실무에서 바로 사용 가능한 사용자 인증 API를 처음부터 끝까지 설계 및 개발
• DB 설계, 암호화, 유효성 검사, 예외처리, 이메일 전송 등 실무 요구 사항 반영
• 보안 및 사용자 경험을 모두 고려한 구조라는 점에서 팀 프로젝트 혹은 SaaS 백엔드 개발에 바로 투입 가능

---

---

◆ ai_server.py

- FastAPI 라우터 코드

- 동화 생성, 음성 및 이미지 생성, 음악/영상 검색, 동화 저장 등 AI 관련 기능들을 API로 제공하는 FastAPI 라우터 구현

- 주요 라이브러리: FastAPI (APIRouter, HTTPException, Response), datetime, base64

- 주요 모듈: 컨트롤러(story_controller, music_controller, video_controller) 및 Pydantic 스키마 사용

 

[주요 API 엔드포인트 및 기능]

경로	메서드	설명	입력 스키마	반환 데이터 형식
/health	GET	서비스 상태 확인 (헬스체크)	없음	JSON (서비스 상태, 타임스탬프)
/generate/story	POST	이름과 테마로 동화 생성	StoryRequest	생성된 동화 텍스트(JSON)
/generate/voice	POST	텍스트 → 음성 파일 생성 후 Base64로 인코딩 반환	TTSRequest	Base64 인코딩 음성 데이터 JSON
/generate/voice/binary	POST	텍스트 → 음성 파일 생성 후 바이너리 직접 반환	TTSRequest	audio/mpeg 바이너리 스트림
/generate/image	POST	텍스트 → 이미지 생성 URL 반환	ImageRequest	이미지 URL(JSON)
/save/image	POST	동화 및 이미지 DB에 저장	SaveStoryRequest	상태 메시지(JSON)
/gallery/images	POST	사용자 ID 기준으로 흑백 이미지 목록 조회	UserIdRequest	이미지 목록(JSON)
/search/url	POST	테마 기반 음악 검색	MusicRequest	음악 검색 결과 리스트(JSON)
/search/video	POST	테마 기반 영상 검색	VideoRequest	영상 검색 결과 리스트(JSON)

 

[고도화 아이디어]

아이디어	내용	기대 효과
예외 처리 강화	각 API에 더 구체적인 예외처리 및 에러 로그 추가	안정적인 서비스, 문제 원인 신속 파악 가능
비동기 처리	async def로 전환 및 비동기 I/O 활용	응답 속도 향상, 동시 요청 처리 능력 증가
응답 모델 명시	FastAPI response_model 파라미터 활용	문서 자동화 및 클라이언트 신뢰도 상승
로깅 및 모니터링	요청/응답 로그 기록 및 모니터링 시스템 연동	운영 안정성 및 문제 조기 발견 가능

※ Streamlit 및 OpenAI API의 경우, 일부 기능에서 비동기 처리가 불가한 사항 있었음.

---

◆ main.py

- FastAPI 메인 앱

- FastAPI 기반 API 서버 초기화, 미들웨어 설정, 라우터 등록, 데이터베이스 초기화 및 에러 핸들링 담당

- 주요 라이브러리: FastAPI, Starlette 세션 미들웨어, CORS 미들웨어, SQLAlchemy, 로깅

 

[주요 기능]

기능	설명
FastAPI 앱 생성	앱 제목, 설명, 버전 설정 포함
세션 미들웨어 추가	사용자 세션 관리 위한 쿠키 기반 세션 미들웨어 구성 (1시간 만료, same_site=lax)
CORS 미들웨어 추가	Streamlit 프론트엔드(http://localhost:8501)와 통신 허용, 크로스도메인 정책 설정
로깅 설정	logging 모듈 사용, 서버 로그 레벨 INFO로 설정, 시스템 정보 로깅
라우터 등록	사용자 관련(users_router), 아이 관련(babies_router), AI 동화 생성 관련(ai_router) 라우터 등록
DB 초기화	서버 시작 시 init_db() 호출로 DB 테이블 생성 및 초기화
예외 처리	HTTPException 에러에 대해 JSON 형태로 에러 메시지 반환

 

[고도화 아이디어]

아이디어	내용	기대 효과
JWT 기반 인증 및 권한 관리	현재 세션 쿠키 방식 대신 JWT 토큰 사용으로 인증 및 권한 관리 구현	무상태(stateless) 인증 지원, 모바일/REST API 확장성 향상
사용자 역할별 권한 분리	Role 기반 권한 체크 미들웨어 추가 (예: 관리자, 일반 사용자 등)	보안 강화, 기능별 접근 제한 구현 용이
캐싱 레이어 도입	Redis 등 캐시 서버 연동하여 자주 호출되는 API 응답 캐싱	서버 부하 감소, 응답속도 향상
헬스체크 및 모니터링 통합	Prometheus, Grafana 연동으로 실시간 서비스 상태 모니터링	장애 조기 감지, 운영 편의성 증대
국제화(i18n) 지원	다국어 응답 및 에러 메시지 처리 기능 추가	글로벌 서비스 확장 대비
문서 자동 생성 보강	OpenAPI 스키마에 예제, 상세 설명 추가, API 버전 관리 도입	API 사용자 경험 향상, 협업 편의성
테스트 자동화 구축	단위 테스트, 통합 테스트 작성 및 CI/CD 파이프라인 연동	코드 품질 보증, 배포 자동화 지원
API Gateway 및 인증 분리	별도의 API Gateway 배치 및 인증/인가 로직 분리	보안성 강화, 서비스 확장 및 관리 용이
장애 대응 자동화	재시도 로직, Circuit Breaker 패턴, 장애 알림 연동	안정적인 서비스 제공, 운영 부담 감소
트랜잭션 관리 최적화	DB 트랜잭션 범위 조절 및 비동기 트랜잭션 활용	데이터 무결성 보장, 성능 향상
DB 마이그레이션 자동화	Alembic 등 마이그레이션 도구 도입 및 자동화	버전 관리, 안전한 배포 지원
로컬 개발환경 도커화	Docker, Docker Compose로 개발/테스트 환경 컨테이너화	환경 일관성 보장, 협업 효율 증대

---

★ config.toml

[client]
showSidebarNavigation = false

- Streamlit 설정 파일(.streamlit/config.toml) 안에서 사용하는 설정 중 하나

 

[사용 상황]

•  (예: streamlit-navigation 라이브러리 사용 시) 직접 만든 네비게이션 UI만 사용하고 싶을 때
• 깔끔한 사이드바를 원할 때
• 사용 환경 (예: 로그인 여부)에 따라 다른 환경을 보여주고 싶을 때

[역할]

항목	설명
설정 키	showSidebarNavigation
위치	[client] 섹션
값	true 또는 false
기본값	true
설정 예시	showSidebarNavigation = false

▶ showSidebarNavigation = false는 Streamlit 앱의 사이드바에 생기는 기본적인 페이지 탐색기(Navigation)를 숨기는 역할

 

로그인 여부에 따라 보여지는 페이지를 다르게 설정했어도, 이 파일이 없다면 실현이 안되기 때문에 매우 중요.

---