Next Js on ICE-ICE-BEAR-BLOG

hybrid-image-search 개발일지 #18 — OpenAI gpt-image-2 합류, 모델/제품 라이브러리, 그리고 내부 권한 분리

Thu, 07 May 2026 00:00:00 +0900

개요

이전 글: #17 — 톤 풀 swap, 모델 인젝션 prompt v2을 쓴 이래 73개 커밋이 들어갔다. 가장 큰 변화는 인젝션 모드 자체를 버린 것 — 한 화면에 여러 톤 모드를 펼쳐놓던 UX를 모델/제품 탭 두 개로 단순화했다. 동시에 비교용 사이드 B를 OpenAI gpt-image-2로 라우팅하기 시작했다.

graph LR
 Old["dev #17 까지 <br/> injection-mode pills (5톤)"] --> Refactor["pills 제거 <br/> model/product 탭"]
 Refactor --> A["Side A: Gemini 3.1 Flash <br/> (메인)"]
 Refactor --> B["Side B: OpenAI gpt-image-2 <br/> (비교)"]
 Library["per-user library <br/> model + product"] --> A
 Library --> B
 Internal["internal 권한 게이트 <br/> tone-lock + S3 admin"] --> A

73개 커밋을 다섯 흐름으로 묶었다.

OpenAI gpt-image-2를 사이드 B로 합류

지금까지 hybrid는 Gemini 단일 백엔드였다. dev #18에서는 비교 평가를 위해 사이드 B를 OpenAI gpt-image-2로 라우팅하기 시작했다.

graph TD
 UI["프런트엔드 generate"] --> Backend["FastAPI /generate"]
 Backend --> Gather["asyncio.gather()"]
 Gather --> SideA["Side A <br/> Gemini 3.1 Flash"]
 Gather --> SideB["Side B <br/> OpenAI gpt-image-2"]
 SideA --> CompareUI["frontend a/b 키보드 비교"]
 SideB --> CompareUI

핵심 커밋:

AsyncOpenAI 클라이언트와 OpenAI image-gen config 와이어링 (052d42f) — 환경 변수, 타임아웃, retry 정책을 backend config에 추가.
공유 image IO helper와 OpenAI image service (1fb9b43) — Gemini와 OpenAI 응답을 공통 포맷으로 변환하는 어댑터.
5톤 → side A/B 의미론으로 리팩터링 (d91067e, ec38fa8) — tone3, tone5 같은 필드명을 side_a, side_b로 교체. 더 이상 톤 종류가 아니라 비교용 측면이라는 의미.
gather에서 cancellation 차단 + unsupported quality 파라미터 제거 (8759a78) — asyncio.gather는 한쪽 task가 raise하면 다른 쪽이 cancel될 수 있다. 둘 다 살리려면 return_exceptions=True로 shield하고 따로 처리.

코너 케이스 두 개:

aspect ratio 매핑 — gpt-image-2는 1024x1024, 1024x1792, 1792x1024만 지원 (97f7204). UI에서 입력한 임의 비율을 가장 가까운 지원 사이즈로 매핑.
B 실패 메시지 surface (7d31f62) — 비교용 사이드라도 실패하면 UI에 알려줘야 한다. 조용히 빠지면 비교 결과가 한쪽만 나와서 혼란.

인젝션 모드 폐기, 모델/제품 라이브러리 도입

dev #17까지는 “tone injection mode"라는 추상화가 있었다. 5톤 × 사용자 업로드 모델 × 옵션 매트릭스가 화면에 펼쳐져서 학습 비용이 높았다. dev #18에서 정면으로 갈아치웠다 — 모델 탭과 제품 탭 두 개.

graph TD
 Lib["LibraryTab"] --> ModelTab["모델 (인물 사진)"]
 Lib --> ProductTab["제품 (오브젝트 사진)"]
 ModelTab --> ModelUpload["직접 업로드"]
 ModelTab --> ModelGen["Gemini ID-photo로 재생성"]
 ProductTab --> ProductUpload["업로드 + 자동 전처리"]
 ProductUpload --> AutoPick["ready 시 자동 픽"]
 ModelGen --> Generate["generate 호출"]
 ProductUpload --> Generate

흐름:

사용자별 자산 라이브러리 (b933191) — 업로드한 모델/제품을 사용자 계정에 저장. 다른 톤 만들 때 재사용 가능.
인젝션 모드 pill을 모델/제품 탭으로 교체 (1450767) — UI 단순화. “어떤 모드를 쓸지” 정하는 단계가 사라졌다.
모델 ID-photo 재생성 (db64b05) — 업로드한 인물 사진을 Gemini로 ID 사진 스타일로 정제. 일관성 있는 모델 슬롯을 만들기 위함.
role-aware prompt directives (ffb8ccf) — 모델/제품 레퍼런스가 프롬프트에 들어갈 때 역할이 명시된다. “이 사람을 모델로”, “이 오브젝트를 제품으로”.
제품 업로드 자동 전처리 + ready 시 자동 픽 (69db8c2) — 업로드 → 백그라운드 전처리 → 끝나면 자동으로 활성화. 사용자가 한 단계 덜 누른다.
processing state surfacing + toast (f3ff587) — 전처리 중인 자산은 별도 상태로 표시. 어색한 silent wait 제거.

중간에 한 번 후퇴가 있었다. 모델 자동 인젝션을 켰다 껐다 다시 켰다:

bdf0aae — auto model injection 끄고 직접 업로드만 (label wrap 버그도 같이 픽스)
394f91f — auto model injection 다시 복원, generated-image drop도 받게

직접 업로드 only일 때 사용자가 이미지를 한 장씩 올려야 해서 마찰이 컸다. 결국 자동 인젝션이 default가 되고, 직접 업로드는 옵션으로 남았다.

톤 풀 큐레이션: 0428 → 0429 → 0504

생성 품질의 8할은 톤 레퍼런스 풀에서 나온다. 풀이 너무 다양하면 결과가 뒤죽박죽되고, 너무 좁으면 모든 결과가 비슷해진다.

이번 사이클의 큐레이션 작업:

0428 모델 셀렉션 풀로 model_image_ref 스왑 (c1e5d39) — 0428 셋이 더 일관된 lighting을 보여줘서 메인 모델 풀 교체.
two-category tones + person-aware model slot (cb3a260) — 톤을 2개 카테고리(natural/film, studio/clean)로 나누고, 인물이 있는 톤일 때만 모델 슬롯 활성화.
0429 subfolder로 auto-pick 스코프 제한 (27d335d) — 자동으로 톤을 고를 때 0429 큐레이션 셋만 후보로 둠. 노이즈 컷.
slug-named tone refs를 generation_logs에 rewrite (76a1a64) — S3 corpus를 swap하면서 path naming이 바뀌어서 기존 로그를 다시 매핑.
a(natural,film) 톤 풀 0429 → 0504 reseed (c43214e, 마지막 커밋) — 가장 자주 쓰이는 톤 카테고리를 최신 셋으로 교체.

scripts/에 S3 corpus swap 유틸리티들을 기록으로 남겼다 (f169dd4). 다음 큐레이션 사이클에서 같은 작업을 반복할 때 쓸 수 있게.

nginx 한 줄 픽스도 의외로 컸다 (9f252ff). 백엔드 타임아웃과 nginx의 /api/ 타임아웃이 어긋나서, OpenAI 응답이 느릴 때 nginx가 먼저 502를 던지고 백엔드의 retry까지 trigger하는 이상한 상황이 있었다. 정렬 + upstream retry 비활성화로 해결.

Internal vs External: 권한 분리

이 사이클에서 처음으로 internal 사용자(팀 내부) 개념이 들어왔다. 데모 데이/외부 베타에서는 보여주면 안 되는 기능들이 있었기 때문.

graph TD
 User["로그인 사용자"] --> Check{"is_internal?"}
 Check -- "yes" --> Internal["Internal 기능 노출"]
 Check -- "no" --> External["External (default)"]
 Internal --> ToneLock["tone refs pin <br/> 다음 generation에 잠금"]
 Internal --> Admin["S3 image manager <br/> 톤/모델/제품 큐레이션"]
 External --> Generate["일반 generate flow"]

세 PR로 분리해서 머지:

PR #16 — internal-vs-external user tiers + UI gating (f33e9d0) — DB에 is_internal 컬럼 추가, UI에서 internal-only 컴포넌트는 plain <></>로 단락.
PR #17 — internal-only tone-lock (199a405) — 같은 톤 레퍼런스를 여러 generation에 고정해서 비교 evaluation을 깨끗하게.
PR #18 — internal-only S3 image manager (8096425) — 웹 UI에서 톤/모델/제품 corpus를 직접 관리. 이전엔 S3 콘솔로 직접 들어가야 했다.

feat/admin-s3-manager 브랜치는 main을 두 번 머지해야 했다 (9d5fa1e, a35bf53). 다른 흐름들이 동시에 들어가서 conflict가 누적됐다 — 큰 흐름 머지 직후에 admin 브랜치를 sync해두는 게 좋다는 교훈.

카메라/렌즈 피커 UX 다듬기

카메라/렌즈 선택 UX를 한 사이클 동안 한 줄씩 다듬었다.

커밋	내용
`2439c98`	angle picker dropdown에 thumbnail 표시 (선택 전 미리보기)
`4f615a7`	레퍼런스 이미지 hover 시 zoom 버튼 노출
`5be9daa`	“카메라 & 렌즈"로 이름 변경, 렌즈 random default, 모델 creator 추가
`b4aeed3`	None 옵션 명시 표시 + LensPicker에 None 선택지
`228ff9f`	LensPicker가 선택 후 자동 닫힘
`024253e`	angle/lens default가 none일 때도 picker 클릭 가능
`bb13dd3`	하단 바 정리 — General + Edit 우측 + 활성 상태 강화
`020c509`	generation prompt 입력창에 여백 추가 (multiline 친화)
`8208a11`	library tab + prompt area zoom + transparent overlay
`349d142`	preview 모달에서 auto-pick 필터 re-roll, dead label 제거
`a-z 단축키`	A/B 비교용 화살표 + ‘a’,‘b’ 키보드 비교 (`fad542e`)

마지막 키보드 비교 단축키가 의외로 좋았다. 마우스로 두 결과 사이를 왔다갔다 하다가 ‘a’/‘b’ 키만 누르면 토글 — 비교 평가 속도가 체감 2배.

인사이트

dev #17에서 #18로 오면서 추상화를 줄이는 게 진보였다. “tone injection mode"라는 5축짜리 추상화는 사용자에게 코드 모델을 강요하는 거였고, 실제 mental model은 “사람을 넣을지 / 물건을 넣을지” 둘 중 하나다. 모델/제품 두 탭으로 줄인 게 정답.

OpenAI 사이드 B 라우팅도 같은 결의 결정. 단일 모델로 evaluation을 추측하는 것보다 두 모델 응답을 나란히 보고 키보드로 토글하는 게 빠르다. asyncio.gather shield 같은 디테일이 신경 쓰이지만, 한쪽이 죽었을 때 어떻게 처리할지 명시적으로 정해두면 같은 패턴을 재사용할 수 있다.

권한 게이트는 의외로 작은 변화로 큰 효과를 본 케이스. is_internal 컬럼 하나 + UI에서 conditional rendering, 그러면 internal-only S3 admin이나 tone-lock 같은 기능을 메인 코드베이스에 두면서도 외부 사용자에게는 안 보이게 할 수 있다. 별도 admin 앱으로 빼지 않은 게 비용을 크게 아꼈다.

다음 dev #19에서 다룰 것: gpt-image-2의 quality A/B 결과 정리, 모델 라이브러리에 group 개념(여러 사람 한 번에) 추가, internal tone-lock을 external로 풀어줄 조건.

popcon 개발일지 #11 — 크레딧 시스템, R2 마이그레이션, ToonOut, 그리고 Brutal 리디자인

Thu, 07 May 2026 00:00:00 +0900

개요

이전 글: #10 — 베타 모집, 풍선 인디케이터, 카운트다운을 쓴 뒤로 보름 동안 popcon에는 dev10 한 편으로 묶기 어려운 변화가 들어갔다. 매팅 모델 교체, 결제 인프라(크레딧), Cloudflare R2 스토리지 컷오버, brutal 리디자인, 한국어 i18n까지 — 156개 커밋이 사실상 다섯 개의 독립 마일스톤이다.

graph TD
 Start["popcon dev #10 (594cceb)"] --> M1["매팅 모델 스왑 <br/> ToonOut on gray bg"]
 Start --> M2["크레딧 시스템 <br/> Credits/CreditCode/CreditLedger"]
 Start --> M3["D1 brutal 리디자인 <br/> 토큰/폰트/프리미티브 재작성"]
 Start --> M4["Cloudflare R2 컷오버 <br/> dual-write → backfill → drop"]
 Start --> M5["한국어 i18n <br/> next-intl + locale prefix"]
 M1 --> End["popcon dev #11 (411c5ec)"]
 M2 --> End
 M3 --> End
 M4 --> End
 M5 --> End

이번 글은 다섯 개를 한 번에 다루지만, 각 흐름을 따라가면 결국 같은 질문이 반복된다 — “기존 시스템을 멈추지 않고 어떻게 새 레일로 갈아탈까.”

매팅 모델: BiRefNet → ToonOut

popcon은 캐릭터 이미지에서 배경을 분리해 12개 이모티콘 액션으로 합성한다. 기존 매팅 모델은 일반 사진 기준이라 애니 캐릭터의 머리카락/투명 영역에서 자주 무너졌다.

ToonOut은 BiRefNet을 1,228장의 애니 이미지로 fine-tuning한 모델이다. 픽셀 정확도가 95.3% → 99.5%로 올라간다.

# gpu_worker — ToonOut에 입력하기 전 회색 배경에 합성
# (ToonOut training-time gray = #808080)
def _swap_bg_to_gray(rgba: np.ndarray) -> np.ndarray:
 """Soft white-key compositor: alpha-blend onto #808080."""
 alpha = rgba[..., 3:4] / 255.0
 rgb = rgba[..., :3]
 gray = np.full_like(rgb, 128)
 return (rgb * alpha + gray * (1 - alpha)).astype(np.uint8)

전후 처리에서 두 가지 디테일이 잡혔다.

회색 배경 단일 소스 — bg_color를 백엔드 단일 진리원(single source of truth)으로 만들고 #808080으로 통일 (commit 430f985). 이전에는 프런트엔드와 워커가 각자 다른 톤의 회색을 쓰고 있었다.
Pylette로 캐릭터별 회색 픽 — Rec.709 luminance 규칙으로 캐릭터의 평균 밝기에 맞는 회색을 골라준다 (commit 94544df). Pylette 글에서 다뤘던 라이브러리를 실제로 import해서 쓰게 됐다.

리팩터링 중 동적 indirection을 cargo-cult로 판정해서 걷어냈고, mask-fill threshold도 이름을 줬다 (081ddd6).

크레딧 시스템: 결제 인프라 한 사이클

베타 끝나고 유료화 전환을 위해 크레딧 시스템을 처음부터 깔았다. SQLAlchemy ORM부터 프런트엔드 402 핸들러까지 5일 안에 한 바퀴를 돌렸다.

graph TD
 Code["관리자 CLI mint <br/> CreditCode (POPxxxxx)"] --> Redeem["redeem 모달 <br/> 코드 → 잔액"]
 Redeem --> Ledger["CreditLedger <br/> charge / refund / grant"]
 Action["editor 액션 <br/> (generate/refine/animate)"] --> Quote["pre-flight quote <br/> 잔액 부족 시 gate"]
 Quote --> Ledger
 Ledger -- "402 emit" --> Pill["header 잔액 pill <br/> 글로벌 redeem 모달"]
 Ledger --> Account["/account 페이지 <br/> 잔액/redeem/이력"]

핵심 결정 셋:

Ledger 패턴 — CreditLedger에 모든 변동을 append-only로 기록하고, Credits 테이블의 balance 컬럼은 캐시. 모든 charge/refund는 strict transaction (e28b100).
402 글로벌 이벤트 — 백엔드가 잔액 부족 시 HTTP 402를 던지면, 프런트엔드 useCredits() 훅이 자동으로 잔액을 새로고침하고 글로벌 redeem 모달을 띄운다 (d25739e, 1a32900).
실패 단계 환불 — 이모티콘 생성 중간에 에러가 나면 그 단계의 크레딧을 자동 환불 (6d7cc7f). 사용자가 환불을 직접 요청하지 않게.

중간에 작은 사고가 있었다. Gemini의 image_size 파라미터를 가격 체계와 맞추려고 "0.5K"로 보냈는데, 이건 Gemini가 거부하는 값이다 (b1ac23f revert → 55eda01에서 "512"로 정정). API 요금 계산용 표기와 API 입력 표기가 다른 케이스 — 둘이 같다고 가정한 게 문제였다.

또 360115e 커밋이 흥미롭다. 코드 리팩터링 중에 브랜드 prefix POP을 P0P (영문 O를 0으로)으로 잘못 바꿨던 걸 되돌렸다. AI가 “스타일 통일"을 너무 적극적으로 한 사례.

D1 brutal 리디자인: 토큰부터 페이지까지

기존 popcon은 generic Tailwind 룩이었다. 플라이어/브랜딩과 맞추기 위해 brutal 스타일로 전면 교체했다 — 두꺼운 검정 보더, 강한 그림자, 5색 톤 시스템, 굵은 산세리프.

새 폰트 스택:

Archivo Black — 영문 헤드라인
Black Han Sans — 한글 헤드라인
Jua — 한글 본문
JetBrains Mono — 코드/숫자
Pretendard — 한글 폴백

/* tokens.css — 5톤 brutal 팔레트 */
:root {
 --paper: #fafaf7; /* 본문 배경 */
 --ink: #1a1a1a; /* 본문 텍스트 + border */
 --violet: #7c3aed; /* 브랜드 (P logo, 액션) */
 --yellow: #fbbf24; /* 활성 강조 (ZIP 버튼 등) */
 --pink: #ec4899; /* erase / 경고 */
 --mint: #10b981; /* success */
}

프리미티브를 새로 짰다 — Card, Chip (5톤×2사이즈), StatusDot, Input, Textarea, Button (5 variants × 3 sizes), StepIndicator. 모두 brutal 스타일로 다시 작성 (769df10 ~ 0e013a8).

페이지를 한 장씩 갈아끼우는 방식으로 진행했다 — landing → editor 패널들 → archive → account → auth 모달 → header. 각 commit이 한 페이지/패널이라 리뷰가 쉬웠다.

가장 까다로웠던 건 scrim/모달 배경 처리였다. 기존엔 흰색 베일을 깔았는데 brutal 스타일에선 ink scrim(검정 반투명)이 맞았다. 그런데 SAM2/matte refine 모달에선 ink scrim이 너무 강해서 레퍼런스 이미지가 안 보임 → 모달별로 scrim을 분기 (99b1908, 4096ba7).

WCAG AA 점검도 한 번 돌렸다. 핑크 배경 위 흰색 텍스트가 contrast 미달이어서 ink로 교체 (4827ed4).

Cloudflare R2 컷오버: 4단계 phase 분리

popcon은 생성된 이모티콘 zip/APNG/video를 fly.io 머신의 로컬 디스크에 쓰고 있었다. 머신이 늘면 자산이 분산돼서 다운로드 라우팅이 깨진다. R2(Cloudflare의 S3 호환 객체 스토리지)로 옮기기로 결정.

다운타임 없이 옮기려고 4 phase로 쪼갰다:

Phase	내용	PR
A	R2 클라이언트 + `blob_key` DB 컬럼 추가	#5
B	Worker dual-write — 로컬 디스크 + R2 둘 다 기록	#6
C	백필 스크립트 + 프런트엔드가 R2 URL을 absolute로 패스스루	#7
D	레거시 파일 라우트 제거 + `/download_job` 302 리다이렉트 + scratch GC	#8

각 phase 사이에 트래픽이 정상인지 확인하고 다음으로 넘어갔다. dual-write 단계에선 디스크와 R2 둘 다 쓰니까 비용은 잠깐 늘었지만, 컷오버 안전성을 샀다.

후속 정리 두 개:

Rehydrate URLs from R2 keys (b43e802) — DB에 R2 URL을 그대로 박지 않고 blob_key에서 매번 derive. R2 endpoint가 바뀌어도 마이그레이션 없이 따라간다.
레거시 자산 라우트 복구 (1e08937) — 이전에 시작한 작업물을 가진 사용자를 위해 file 라우트 일부를 다시 살림. R2 URL을 filesystem path 컬럼에 잘못 미러링한 버그도 같이 잡았다 (83d62c4).

한국어 i18n: next-intl + locale-prefixed routes

graph LR
 URL1["/editor"] --> Proxy["proxy.ts <br/> Next 16-style"]
 URL2["/ko/editor"] --> Proxy
 URL3["/en/editor"] --> Proxy
 Proxy --> Locale{"locale 추출"}
 Locale --> Layout["[locale]/layout.tsx <br/> getMessages()"]
 Layout --> Page["페이지 렌더 <br/> useTranslations()"]

next-intl + locale-prefixed routes로 한국어를 추가했다. 핵심 결정 두 개:

page를 [locale] 세그먼트 아래로 이동 — app/page.tsx → app/[locale]/page.tsx. layout도 root layout과 locale layout으로 분리 (fe1eaa3).
Next 16 proxy.ts로 locale 라우팅 — middleware 대신 proxy 패턴 (4f322e2). 정적 라우팅이 가능해서 캐시가 잘 먹는다.

번역은 namespace별로 dictionary 파일을 쪼갰다 — home, editor, archive, account, redeem, actions, picker, … 각 페이지/패널별 commit이 하나씩 있어서 grep 가능하다.

언어 스위처에서 한 가지 버그가 잡혔다. 언어 전환 시 search params가 사라져서 editor에서 진행 중인 job이 끊기는 문제 — Link/router 모두 locale-aware 래퍼로 교체해서 search params 보존 (d644b1b, PR #12).

또 in-app browser(KakaoTalk, Instagram 등)에서 Google 로그인이 차단되는 문제도 발견했다. iab=1 같은 쿼리로 외부 브라우저로 이스케이프하는 가드를 추가 (29cd743).

운영: SKIP_RUNPOD 가드와 sync-pod-id 스크립트

배포는 fly.io(API/프런트엔드) + RunPod(GPU 워커) + GitHub Actions cron 스케줄러 조합이다. 새벽 시간대 RunPod 비용을 줄이려고 스케줄러로 pod를 끄고 켜는데, 수동으로 pod를 띄워두면 스케줄러가 같이 끄는 사고가 났다.

해결: SKIP_RUNPOD 환경 변수 가드 (e3fa9fa). 이 플래그가 켜져 있으면 스케줄러가 pod를 건드리지 않는다. 수동 운영용 escape hatch.

sync-pod-id 스크립트도 추가 (783238b) — 새 RunPod ID를 fly secret에 자동으로 동기화한다. 이전엔 수동으로 fly.io 환경변수를 업데이트해서 까먹기 쉬웠다.

fly(frontend) 한 줄도 의외로 중요했다 (edf3d18, PR #9). frontend 머신을 1대 warm으로 유지하고 메모리 512MB로 고정. 콜드 스타트 1.5초 → 200ms.

인사이트

156개 커밋을 한 글에 묶고 보니 흐름이 직렬이 아니라 병렬이었다. 매팅 모델 교체와 R2 마이그레이션은 백엔드/워커 쪽, brutal 리디자인은 프런트엔드, 크레딧과 i18n은 풀스택. 같은 시간대에 다섯 트랙이 동시에 굴러갔는데 서로 머지 충돌이 거의 없었던 건 모듈 경계가 또렷해서다.

특히 R2 컷오버를 4 phase로 쪼갠 게 회고감이 좋다. dual-write phase에서 비용 잠깐 더 쓰는 대신 롤백 가능성을 샀다 — 만약 phase B에서 문제가 생겼어도 디스크가 truth로 남아 있어서 R2 코드만 끄면 됐다.

크레딧 시스템 ledger 패턴은 다시 써도 같은 선택을 할 것 같다. Credits.balance를 캐시로 두고 CreditLedger를 append-only로 기록하면, 잔액에 의심이 갈 때 ledger를 재연산해서 검증할 수 있다. Stripe도 이 패턴이다.

리디자인은 토큰/프리미티브를 먼저 새로 짠 뒤에 페이지를 한 장씩 갈아끼운 게 결정적이었다. 페이지를 먼저 손대면 새 토큰이 안 박히는 옛 컴포넌트가 계속 남는다.

다음 dev #12에서 다룰 것: 결제 게이트(KG이니시스/PortOne) 연동, ToonOut 매팅 품질 A/B(전 모델 vs ToonOut), 한국어 i18n에서 빠진 미세 영역(에러 토스트, 관리자 CLI 메시지).