이전 글: PopCon 개발기 #1

개요

오늘은 PopCon의 “겉모습"과 “안정성"을 모두 다듬은 세션이었다. 오전에는 Gemini가 생성한 이미지를 로고와 파비콘으로 변환하고, GitHub에 공개할 수 있는 수준의 README를 작성했다. 오후에는 Docker에서 API 키 오류가 터졌고, 파이프라인 전체를 점검하며 재시도 로직과 이모지별 에러 핸들링까지 구현했다.

1. 로고 & 파비콘 — Gemini 이미지를 브랜드 에셋으로

첫 번째 작업은 Gemini가 생성한 2880×1440 이미지를 PopCon 브랜드 에셋으로 만드는 것이었다. 이미지를 중앙 기준 1:1 정사각형으로 크롭한 뒤, 여러 크기로 변환했다.

Docker에서 파비콘이 안 보이는 문제

파비콘을 교체했는데 브라우저에 반영이 안 됐다. 원인이 두 가지였다.

1. Next.js App Router 우선순위: app/favicon.ico가 public/favicon.ico보다 우선한다. 이미 기본 파비콘이 app/ 디렉토리에 있었고, 이 파일을 교체해야 했다.
2. Docker 이미지 캐시: COPY . .로 빌드 시점에 파일을 굽기 때문에, 파일을 수정해도 컨테이너를 재빌드하지 않으면 반영되지 않는다.

docker compose build frontend && docker compose up -d frontend

재빌드 후 curl -I localhost:3000/favicon.ico로 HTTP 200을 확인하고 마무리했다.

2. 전체 제품 README 작성

다음은 GitHub에 공개할 README를 제품 개요 수준으로 작성하는 작업이었다.

처음에는 영어·한국어를 하나의 파일에 넣었는데, “두 언어가 구분이 안 된다"는 피드백이 나왔다. 결과적으로 파일을 분리했다.

• README.md — 영어, 상단에 English | [한국어](README.ko.md) 토글
• README.ko.md — 한국어, 상단에 [English](README.md) | 한국어 토글

README 내용이 코드와 달랐던 부분들

첫 커밋 후 실제 코드를 확인하니 README와 다른 점이 여러 곳 있었다.

두 README 파일 모두 업데이트 후 푸시했다.

3. Docker 디버깅 — API 키와 씨름한 오후

오후 세션은 Docker 로그부터 시작했다. 서비스가 전혀 동작하지 않았는데, 원인은 .env 파일의 API 키 값 뒤에 venv가 붙어 있었던 것이다.

POPCON_GOOGLE_API_KEY=AIzaSy...-mAcuv venv

아마 터미널에서 복사할 때 venv 활성화 명령어가 함께 딸려온 것으로 추정된다. .env에서 venv를 제거하고 재시작했지만, 이번엔 키 자체가 만료된 것으로 확인됐다. Google AI Studio에서 새 키를 발급받아 해결했다.

이 과정에서 파이프라인을 실제로 돌려보면서 여러 품질 문제를 발견했다.

발견한 문제들과 수정

flowchart TD
    A["파이프라인 실행"] --> B["출력 검토"]
    B --> C["문제 발견"]
    C --> D["구름 효과 <br/> 배경 노이즈"]
    C --> E["중복 캐릭터 <br/> 스프라이트 시트"]
    C --> F["체커보드 배경 <br/> NB2 가짜 투명"]
    C --> G["VEO 엣지 라인 <br/> 좌우 경계선"]
    D --> H["rembg 완전 제거 <br/> 밝기 기반 크롭으로 대체"]
    E --> I["프롬프트에 <br/> 단일 캐릭터 강제"]
    F --> J["#FFFFFF 명시 <br/> NOT checkerboard 프롬프트"]
    G --> K["ffmpeg 2% 엣지 크롭"]

가장 큰 결정은 rembg 라이브러리를 완전히 제거한 것이다. 배경 제거를 시도할수록 문제가 생겼다 — isnet-general-use 모델이 구름 같은 아티팩트를 남겼고, u2net으로 바꿔도 마찬가지였다. 결국 VEO가 흰 배경으로 영상을 생성하도록 프롬프트를 강화하고, 밝기 기반 크롭으로 콘텐츠 영역만 추출하는 방향으로 전환했다.

# processor.py — 밝기 기반 콘텐츠 감지
brightness = arr.astype(float).mean(axis=2)
content_mask = (brightness > 10) & (brightness < 245)

pyproject.toml에서 rembg[cpu]>=2.0.0을 제거하고 numpy>=1.26.0으로 교체하면서 Docker 이미지도 가벼워졌다.

LINE 규격 파일 명명 수정

LINE Creators Market 가이드라인을 확인하니 파일명이 001.png~040.png 형식이어야 했다. 기존 코드는 액션 이름으로 저장하고 있었다.

# packager.py
for i, emoji_path in enumerate(emoji_paths):
    line_name = f"{i + 1:03d}.png"
    zf.write(emoji_path, line_name)

4. 재시도 로직 & API 스로틀링

마지막 커밋은 안정성 강화였다. 풀 세트(24개)를 생성하다 보면 VEO나 Gemini API가 간헐적으로 503이나 429를 반환했다. 하나가 실패하면 전체 작업이 멈추는 구조를 개선했다.

이모지별 독립적인 에러 처리

기존 구조는 하나의 이모지가 예외를 던지면 전체 run_emoji_generation 태스크가 실패했다. 이를 각 이모지별로 try/except를 적용해서 실패한 것만 "error" 상태로 기록하고 나머지는 계속 진행하도록 변경했다.

# worker.py — 이모지별 에러 핸들링
failed_indices = set()
for i, action in enumerate(actions):
    try:
        # ... 포즈 생성, 애니메이션, 후처리
    except Exception as e:
        logger.error(f"Emoji {i} ({action.name}) failed: {e}")
        failed_indices.add(i)
        status.results[i].status = "error"
        save_job(status)

작업 완료 상태도 세분화했다. "done" 외에 "done_with_errors" 상태를 추가해서 일부 실패해도 ZIP을 다운로드할 수 있도록 했다.

API 재시도 로직

Gemini Image와 VEO 모두 지수 백오프 재시도를 추가했다.

# pose_generator.py — 재시도 로직
async def _generate_image(self, prompt, reference_image_path=None, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = await asyncio.to_thread(
                self.client.models.generate_content, ...
            )
            return ...
        except (ServerError, ClientError) as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1s, 2s, 4s
            logger.warning(f"Attempt {attempt+1} failed, retrying in {wait}s: {e}")
            await asyncio.sleep(wait)

타입 시스템 동기화

모델 상태 타입을 백엔드와 프론트엔드 모두 업데이트했다.

정리

오늘 작업한 커밋 4개의 흐름을 요약하면 이렇다.

Docker 디버깅을 하다 보니 파이프라인 품질 문제들도 많이 잡았다. 특히 rembg 제거 결정은 “뭔가를 빼는 게 더 나은 경우"의 전형적인 사례였다 — 복잡성도 줄고, Docker 이미지도 가벼워지고, 결과물도 오히려 더 깔끔해졌다.

다음 세션에서는 실제 LINE Creators Market 제출을 목표로 최종 품질 검증을 할 예정이다.