Ad-Lib

소상공인을 위한 AI 광고 콘텐츠 생성 서비스입니다. (FastAPI + Worker + Streamlit)

What It Does

• 제품 정보와 레퍼런스 이미지를 입력하면 후보 이미지를 생성합니다.
• 사용자가 후보를 선택하면, 선택 이미지를 기반으로 상세페이지용 결과물을 렌더링합니다.
• 생성/선택/렌더링은 Job으로 비동기 처리되며, API는 Job 상태를 조회하는 방식으로 동작합니다.

Architecture

• frontend (Streamlit): 사용자 입력, Job 제출/폴링, 후보 선택 UI
• api (FastAPI): Job 생성/조회 API, 이미지 업로드(선택) 처리, Redis 큐 enqueue
• worker (Python): 모델 프리로드 후 Redis 큐를 소비하며 AI 파이프라인 실행
• redis: Job queue (BRPOP/LPUSH)
• sqlite: Job 메타데이터 저장 (src/backend/db/adlib.db)
• minio: 이미지/결과물 저장 (Presigned URL 반환)

Quickstart (Docker)

1) 환경변수 준비

• .env.example을 참고해 .env를 준비합니다.
• 최소 설정:
  • OPENAI_API_KEY (텍스트 생성용)
  • MINIO_ACCESS_KEY, MINIO_SECRET_KEY (이미지 업로드가 필요한 경우)

2) 프론트 + 백엔드 + 워커 + 인프라 실행

cd Ad-Lib
docker compose up --build -d redis minio api worker frontend
# Job 데이터베이스 스키마 변경시 실행
docker compose run --rm migrate

브라우저에서 http://localhost:8501로 접속합니다.

GPU 관련

docker-compose.yml의 worker는 gpus: all을 사용합니다.

• NVIDIA Container Toolkit 환경이 아니면 워커 컨테이너가 뜨지 않을 수 있습니다.
• GPU 없이 실행하려면 docker-compose.yml에서 worker.gpus를 제거하고, 모델/파이프라인이 CPU에서 동작 가능한지 별도 확인이 필요합니다.

API Usage

1) Job 생성

• Endpoint: POST /v1/jobs
• Content-Type: multipart/form-data
• 이미지: images 필드로 최대 5개 (jpeg/png/webp, 각 10MB 이하)
• 참고:
  • content_type=product_detail만 워커 파이프라인이 구현되어 있습니다.
  • Idempotency-Key 헤더를 주면 동일 키로 중복 생성이 방지됩니다.

curl -X POST "http://localhost:8000/v1/jobs" \
  -H "Idempotency-Key: demo-001" \
  -F "content_type=product_detail" \
  -F "brand_name=민이네 땅콩" \
  -F "product_name=우도산 땅콩" \
  -F "category=farm" \
  -F "product_description=제주 우도에서 재배된 고소한 땅콩입니다." \
  -F "product_features=고소한 맛, 껍질째 볶음, 제주 우도산" \
  -F "mood=warm, natural, premium, 4k" \
  -F "images=@./input/sample.png"

응답 예시:

{ "job_id": "...", "status": "pending" }

2) Job 상태 조회

• Endpoint: GET /v1/jobs/{job_id}
• 상태: pending | processing | waiting_selection | completed | failed

curl "http://localhost:8000/v1/jobs/<job_id>"

3) 후보 이미지 조회 (선택 단계)

product_detail 생성은 2단계입니다.

1. generate_images 단계에서 후보 이미지를 생성하고 waiting_selection으로 전환
2. 사용자가 후보를 선택하면 render_detail 단계로 재개

curl "http://localhost:8000/v1/jobs/<job_id>/candidates"

4) 후보 이미지 선택 제출

curl -X POST "http://localhost:8000/v1/jobs/<job_id>/selection" \
  -H "Content-Type: application/json" \
  -d '{ "selected_image_urls": ["https://.../candidate1.png"] }'

5) 결과 조회

curl "http://localhost:8000/v1/jobs/<job_id>/result"

결과는 product_detail_page_url(이미지 URL) 형태로 반환됩니다.

Storage (MinIO)

이미지 업로드/결과물 저장은 기본적으로 MinIO를 사용합니다.

• MINIO_ACCESS_KEY/MINIO_SECRET_KEY가 비어 있으면 업로드 기능이 비활성화됩니다.
• 업로드 성공 시 API/워커는 Presigned URL(기본 7일)을 반환합니다.

Repository Layout

Ad-Lib/
  docker-compose.yml
  .env.example
  src/
    backend/          # FastAPI, Alembic, DB, Worker
    backend/db/       # sqlite 파일 저장 디렉터리 (볼륨 마운트)
    backend/worker/   # job 소비/파이프라인 실행
    ai_core/          # 이미지 생성/상세페이지 조립 엔진
    templates/        # 상세페이지 렌더 템플릿
    frontend/         # Streamlit UI

Troubleshooting

• /health가 계속 not ready:
  • 워커가 정상 실행 중인지 로그 확인 (docker compose logs -f worker)
  • REDIS_URL, WORKER_MODEL_READY_KEY가 동일한지 확인
• 이미지 업로드에서 실패:
  • .env의 MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_ENDPOINT 확인
  • MinIO 콘솔(:9001)에서 버킷 생성/접근 권한 확인 (코드에서 없으면 자동 생성 시도)

최종 발표 자료(보고서)

📄 프로젝트 보고서 (PDF)

개인 협업 일지

박병호 -

석지환 -

이승철 - https://www.notion.so/2fbeaebccce680829f4dd5aade8a3104?source=copy_link

전예린 -