codeit_part4_team2#

🔌 소형가전 AI 광고 콘텐츠 생성 서비스

코드잇 AI 엔지니어 10기 파트4 2팀 고급 프로젝트 — 쇼핑몰에 입점한 소형가전 판매 소상공인이 제품 사진 1장을 올리면 브랜드 톤 4종과 판매 시간대에 맞춘 광고 이미지·문구 세트를 자동 생성하는 서비스입니다.

기간: 2026-08-05 ~ 08-28 (제출), 발표 08-31 팀: Codeit AI 10기 Part4 Team 2

---

팀 구성

이름	역할	담당
안은남	PM & 데이터/평가 리드 (팀장)	서비스 기획·스코프 관리, 스프린트 운영, 데이터셋 수집·전처리·EDA, 평가 하네스, 보고서 총괄
성치용	생성 모델 개발	베이스 모델 선정·학습 파이프라인·튜닝
유수빈	생성 모델 개발	톤 4종 데이터 정의·톤별 LoRA·품질 평가
김재헌	추론 파이프라인 & 서빙 (인프라 오너)	ControlNet/IP-Adapter 파이프라인, 추론 최적화, GCP VM·CUDA·배포 단독 소유
박재철	프롬프트/텍스트 + 서비스 개발 (R4+R5)	광고 문구·프롬프트 자동 보강, OpenAI 예산 관리, FastAPI 백엔드, Streamlit(프로토타입)·Next.js(실제 서비스) 프론트엔드, YouTube 게시 플로우

---

프로젝트 목표

온라인 이커머스(쿠팡/스마트스토어/알리/테무)에서 소형가전을 사입해 재판매하는 소상공인은 제품 사진 촬영·광고 이미지 제작·SNS 업로드를 매번 직접 해야 하고, 시간대·계절·행사마다 광고 이미지를 새로 만들어야 합니다.

본 프로젝트는 생성형 AI를 통해

• 제품 보존형 광고 이미지 자동 생성 (제품은 그대로, 배경·조명·연출만 교체)
• 톤 4종(감성/모던/실용/프리미엄) 동시 생성 — 사장님은 고르기만 하면 됨
• 시간대(아침/출근러시아워/오후/퇴근러시아워/저녁/심야)별 소구점·비주얼·문구 자동 전환
• 쇼핑몰 규격(썸네일 1:1, 상세배너, SNS카드 4:5) 일괄 출력
• 소상공인이 선택한 러시아워 결과를 3장면·한국어 TTS 기반 무표정 AI 코믹 쇼츠로 변환하고 사람 승인 후 내부 노출·YouTube 예약 게시

기능을 지원하는 것을 목표로 합니다.

---

서비스 파이프라인

사용자 (쇼핑몰 소형가전 판매 소상공인)
  ↓
Web(Next.js, 실제 서비스) / Streamlit(프로토타입) — 상품 업로드 → 목적/시간대 선택 → 생성 (박재철)
  ↓
FastAPI — 상태관리, Job 큐, History (박재철)
  ↓
Prompt Builder — 톤×시간대 템플릿 결합, 제품 보존 지시, 문구 생성 (박재철)
  ↓
model_server — SDXL/SD1.5 + 톤 LoRA×4 + ControlNet/IP-Adapter, 제품 보존 마스킹 (성치용·유수빈·김재헌)
  ↓
PIL 오버레이 — 한글 문구, 규격별 배치 (박재철)
  ↓
결과 (이미지 + 문구) → History 저장
  ↓ 러시아워 결과에서 운영자가 코믹 쇼츠 선택
대표 이미지 1장 재사용 + 기존 /infer 순차 2회 → CPU MeloTTS 4문장 → FFmpeg 9:16 렌더
  ↓
사람의 발음·자막·제품 보존 검수 → 내부 노출 승인 → 선택 시 YouTube 예약 게시

이미지 생성 프롬프트는 영어(모델 성능 최적화), 광고 문구는 한국어(사용자 노출용)로 분리합니다. 이미지 내 한글은 모델이 그리지 않고 PIL로 오버레이합니다 — 문구만 고칠 때 이미지를 재생성하지 않아도 됩니다. 쇼츠 음악은 사용하지 않습니다. TTS 모델은 고정 리비전·파일 해시를 확인하고 CPU에서 실행하며, 발음 위험 문장은 사람이 실제 영상을 듣고 확인하기 전에는 승인할 수 없습니다. Next.js(web/)가 최종 서비스 화면이고, Streamlit(app/frontend/)은 기능 검증용 프로토타입으로 병행 유지됩니다 — 상세: web/README.md

---

프로젝트 구조

ad-creative-studio/
├── docker-compose.yml         # Docker 배포 — model_server(GPU) + backend 컨테이너
├── app/
│   ├── frontend/            # Streamlit — 기능 검증용 프로토타입 (streamlit_app.py + pages/)
│   ├── backend/              # FastAPI
│   │   ├── api/               # products / generations / jobs / history / usage
│   │   ├── schemas/           # Pydantic 요청/응답 스키마
│   │   └── services/          # openai_client, model_server_client, generation_service, overlay, store
│   └── prompt/                # Prompt Builder — 톤×시간대 템플릿, 문구 생성 규칙
├── web/                       # Next.js — 최종 서비스 프론트엔드 (박재철 담당, web/README.md 참고)
├── model_server/              # GPU 추론 서버 — SDXL/SD1.5 + 톤 LoRA + ControlNet/IP-Adapter (성치용·유수빈·김재헌 담당)
├── deploy/                    # 배포 자산 — Dockerfile, systemd, 큐/모니터링 (김재헌 담당)
├── eval/                      # 평가 자산 — eval_criteria.md, metrics.py, golden_dataset/
├── data/{samples,outputs,uploads}/  # 실제 파일은 .gitignore 처리
├── notebooks/{model,data,eval}/  # 실험 노트북 (nbstripout 필터 적용, 아래 참고)
├── scripts/                   # 실행/운영 스크립트
├── docs/                      # api_contract.md, prompt_spec.md, architecture.md, report/ 등
├── tests/                     # pytest (백엔드/모델)
├── web-tests/                 # Next.js 프론트엔드 테스트
├── tools/                     # 운영/감사 스크립트
└── .github/                   # PR/Issue 템플릿, CI(pytest 자동 실행)

---

환경 설정

사전 요구사항

• Python 3.11+
• GCP VM (L4 24GB) 접속 권한 — model_server 실행용 (김재헌 관리)
• OpenAI API Key — 텍스트 전용, 팀 공용 (박재철 관리, $20 경고/$25 상한)

설치

git clone https://github.com/codeit-part4-team2/ad-creative-studio.git
cd ad-creative-studio

python -m venv venv
source venv/bin/activate       # Windows: venv\Scripts\activate

pip install -e ".[dev,frontend]"    # 개발·테스트·웹 UI 전부
# 또는
pip install -r requirements.txt

nbstripout --install    # 노트북 작업 시 필수 (최초 1회) — notebooks/README.md 참고

실행

cp .env.example .env            # 실제 값 채우기, 커밋 금지

# 1) 백엔드 API (Mock 모델, 실제 model_server 없이도 동작)
uvicorn app.backend.main:app --reload --port 8000 --env-file .env   # http://127.0.0.1:8000/docs

# 2) 프론트엔드 (다른 터미널)
streamlit run app/frontend/streamlit_app.py            # http://localhost:8501

# 또는 스크립트로 한 번에
./scripts/run_local_stack.sh

# 3) 테스트
pytest -q

model_server(R2·R3) 연동 방법은 docs/api_contract.md 참고. Mock↔실제 모델 전환은 app/backend/services/generation_service.py의 generation_service 한 줄만 바꾸면 됩니다. VM 접속 및 모델 서빙 상시 환경은 SETUP.md 참고.

Docker로 실행 (model_server + backend)

cp .env.example .env            # HOST_HOME 등 채우기
docker compose up --build        # model_server(GPU) + backend 컨테이너 기동

GPU 컨테이너 실행에는 호스트에 nvidia-container-toolkit이 필요합니다. 상세: deploy/README.md

웹 프론트엔드 (Next.js, 최종 서비스 화면)

FastAPI 백엔드가 먼저 떠 있어야 합니다. 설치·실행 방법은 web/README.md 참고. Streamlit(app/frontend/)은 기능 검증용 프로토타입으로 계속 병행 유지됩니다.

평가 지표

단계	지표
1순위	Product Preservation (제품 보존율) — 다른 지표보다 먼저 측정
생성 품질/속도	정확도와 적합도, 일관성과 안정성, 응답 속도·부하 처리
서비스 완성도	유저 중심 인터페이스, 제어 가능성

세부 측정 방법은 eval/eval_criteria.md 참고.

---

브랜치 전략

브랜치	용도
main	항상 실행 가능한 상태 유지. 직접 push 금지, PR로만 반영
feature/<역할>-<내용>	예: feature/r4r5-wizard-ui, feature/r3-controlnet

• PR 최소 1인 리뷰 (기본 리뷰어: 안은남)
• 8/22 Gate 2 이후 신규 기능 PR 금지 (기능 프리즈)
• 흐름: feature/* → main (PR 필수)
• PR 절차 상세: docs/git_workflow.md

---

기준 커밋

gate0-service-v0.1 태그 — Gate 0(더미 모델 E2E 관통) 기준. 이후 실제 모델 연동 중 문제가 생기면 이 태그로 되돌릴 수 있습니다. 테스트 결과: docs/test_results_gate0.txt

---

---

협업일지

각자 Notion에 작성 후 팀 채널에 매일 링크 공유: Notion 협업일지

보고서 PDF

파트4_2팀_보고서.pdf