다크 모드
AI Server (FastAPI) 개요
truloop-ai-server는 AI 기반 콘텐츠 생성과 이미지 분석을 담당하는 서비스입니다. FastAPI와 Celery를 결합하여 비동기 AI 태스크를 처리합니다.
기술 스택
| 항목 | 기술 | 설명 |
|---|---|---|
| 언어 | Python 3.11 | .python-version으로 관리 |
| 웹 프레임워크 | FastAPI | 비동기 REST API |
| 비동기 태스크 | Celery | Redis/Valkey 기반 태스크 큐 |
| DB | PostgreSQL (SQLAlchemy) | truloop-core와 DB 공유 |
| 캐시/브로커 | Redis/Valkey | Celery broker & backend |
| AI 프로바이더 | OpenRouter, Junis AI, Replicate, FAL | LLM, 콘텐츠/이미지/비디오 생성 |
| 패키지 관리 | uv | 빠른 Python 패키지 매니저 |
| 코드 품질 | Ruff, mypy | 포맷팅, 린팅, 타입 체크 |
| 에러 추적 | Sentry | Production 에러 모니터링 |
| 모니터링 | Prometheus | 커스텀 메트릭 (/metrics) |
| 관리자 | SQLAdmin | 웹 기반 관리 UI |
주요 기능
| 기능 | 설명 |
|---|---|
| 이미지 분석 | Claude(OpenRouter) 기반 이미지 태깅, 설명 생성 |
| 콘텐츠 생성 | Junis AI를 통한 템플릿 기반 다국어 콘텐츠 생성 |
| 하이라이트 생성 | 이미지 기반 하이라이트 비디오 콘텐츠 |
| 포스터 생성 | AI 이미지를 활용한 포스터 콘텐츠 |
| 스토리 생성 | 이미지 설명 기반 텍스트(블록 JSON) 스토리 콘텐츠 |
| 프롬프트 관리 | DB 기반 버전 관리되는 AI 프롬프트 템플릿 |
| 최적 이미지 선택 | AI 기반 토너먼트 방식 이미지 자동 선택 |
프로젝트 구조
truloop-ai-server/
├── app/
│ ├── api/ # API 엔드포인트
│ │ ├── main.py # FastAPI 앱 진입점
│ │ └── v1/ # v1 API
│ │ ├── content_templates/ # 콘텐츠 생성/웹훅 엔드포인트
│ │ ├── image_analysis/ # 이미지 분석 엔드포인트
│ │ ├── prompts/ # 프롬프트 관리 엔드포인트
│ │ └── metrics.py # Prometheus 메트릭 엔드포인트
│ ├── common/ # 공통 타입 정의
│ │ └── types.py # TemplateType, MediaContentType enum
│ ├── config/ # 설정
│ │ ├── logging.py # 로깅 설정
│ │ └── metrics_logging.py # 메트릭 로깅 설정
│ ├── models/ # SQLAlchemy 모델
│ │ ├── loop.py # Loop 모델
│ │ ├── loop_media.py # 룹 미디어 모델 (읽기 전용)
│ │ ├── loop_generated_content.py # 생성 콘텐츠 모델
│ │ ├── loop_content_input_media.py # 콘텐츠 입력 미디어 연결 테이블
│ │ ├── content_template.py # 콘텐츠 템플릿 모델
│ │ ├── prompt_template.py # AI 프롬프트 템플릿 모델
│ │ ├── prompt_version.py # AI 프롬프트 버전 모델
│ │ └── user.py # User 모델
│ ├── services/ # 비즈니스 로직
│ │ ├── content_template/ # 콘텐츠 생성 서비스
│ │ │ ├── content_generation_service.py # 콘텐츠 생성 오케스트레이션
│ │ │ ├── content_template_service.py # 템플릿 CRUD
│ │ │ ├── best_image_selector.py # AI 기반 이미지 선택
│ │ │ └── junis_content_generator.py # Junis AI 연동
│ │ ├── image_analysis/ # 이미지 분석 서비스
│ │ ├── media/ # 미디어 서비스
│ │ │ ├── media_service.py # DB 조회 전용 서비스
│ │ │ └── media_upload_client.py # 외부 Media API 업로드 클라이언트
│ │ ├── notification/ # 알림 서비스 (mock)
│ │ ├── interfaces/ # 서비스 인터페이스 (ABC)
│ │ └── common/ # 공통 유틸리티 (Claude 호출, Rate Limiter)
│ ├── core/ # 핵심 유틸리티
│ │ ├── database.py # DB 연결 관리 (psycopg3)
│ │ ├── redis_connection.py # Redis/Valkey 연결
│ │ ├── task_registry.py # 중앙집중식 Celery Task 관리
│ │ ├── metrics.py # Prometheus 메트릭
│ │ ├── admin.py # SQLAdmin 설정
│ │ ├── sentry.py # Sentry 초기화
│ │ ├── responses.py # 표준 API 응답 포맷
│ │ ├── aws_clients.py # AWS S3 클라이언트
│ │ ├── thread_monitor.py # Thread 모니터링
│ │ └── database_metrics.py # DB 커넥션 풀 메트릭
│ ├── schemas/ # Pydantic 스키마
│ ├── middleware/ # 미들웨어
│ ├── templates/ # Jinja2 HTML 템플릿 (Admin)
│ └── static/ # 정적 파일
├── tasks/ # Celery 태스크
│ └── content_generation_tasks.py
├── celery_app.py # Celery 앱 설정
├── pyproject.toml # 의존성 및 설정 (uv + hatch)
└── .python-version # Python 3.11API 엔드포인트
정보
모든 경로에 API_BASE_PATH 환경변수 prefix가 적용됩니다. 예: API_BASE_PATH=/ai이면 /ai/api/content-generation/*.
| 경로 | 설명 |
|---|---|
POST {prefix}/api/content-generation/highlights | 하이라이트 콘텐츠 생성 (미디어 EID 지정) |
POST {prefix}/api/content-generation/highlights/auto-select | 하이라이트 콘텐츠 생성 (자동 이미지 선택) |
POST {prefix}/api/content-generation/posters | 포스터 콘텐츠 생성 (미디어 EID 지정) |
POST {prefix}/api/content-generation/posters/auto-select | 포스터 콘텐츠 생성 (자동 이미지 선택) |
POST {prefix}/api/content-generation/webhook/content-generation | Junis AI 웹훅 콜백 |
GET {prefix}/api/content-generation/estimate-completion-time | 예상 완료 시간 조회 |
GET {prefix}/api/content-generation/{id} | 생성 콘텐츠 조회 |
POST {prefix}/api/image-analysis/analyze | 이미지 분석 요청 |
GET {prefix}/api/content-templates/* | 콘텐츠 템플릿 조회 |
GET {prefix}/api/prompts/* | 프롬프트 관리 |
GET {prefix}/health | 헬스체크 (DB, Redis 병렬 체크) |
GET {prefix}/liveness | 서버 생존 확인 |
GET {prefix}/readiness | Readiness 체크 (/health와 동일) |
GET {prefix}/metrics | Prometheus 메트릭 |
GET {prefix}/admin/* | SQLAdmin 관리 UI |
GET {prefix}/admin-server-request | 관리자 콘텐츠 생성 폼 |
개발 명령어
bash
# 의존성 설치
uv sync
# FastAPI 서버 실행
uvicorn app.api.main:app --reload --host 0.0.0.0 --port 8000
# Celery Worker 실행
celery -A celery_app worker --loglevel=info
# Docker Compose (PostgreSQL + Redis 포함)
docker-compose -f docker-compose.dev.yml up
# 코드 포맷
ruff format .
# 린트 및 자동 수정
ruff check . --fix
# 타입 체크
mypy appDB 공유 구조
truloop-ai-server는 truloop-core와 동일한 Aurora PostgreSQL 인스턴스를 공유합니다.
| 테이블 | 읽기 | 쓰기 | 설명 |
|---|---|---|---|
loops | O | O | 룹 정보 조회, 스토리 결과 저장 (story 필드), description 업데이트 |
loop_media | O | O | 미디어 정보 조회, ai_metadata.description 업데이트 (이미지 분석 시) |
content_templates | O | X | 템플릿 정보 조회 |
loop_generated_content | O | O | 생성 콘텐츠 기록 (상태, 결과 저장) |
loop_content_input_media | O | O | 콘텐츠 생성에 사용된 입력 미디어 연결 |
ai_prompt_templates | O | O | AI 프롬프트 템플릿 관리 |
ai_prompt_versions | O | O | 프롬프트 버전 관리 |
users | O | X | 사용자 정보 조회 (eid 등) |
변경 이력
| 날짜 | 내용 |
|---|---|
| 2026-03-11 | ECS Fargate ARM64 (Graviton) 전환 반영 — Docker 빌드 플랫폼 linux/arm64, 리소스 최적화 (0.5 vCPU/1GB) |
| 2026-03-10 | 최초 작성 |