Z-Image-Turbo를 gcube에 올려서 이미지 자동 대량 생성하기

이미지 생성 API를 쓰다 보면 장수가 늘어날수록 비용이 무섭게 올라갑니다. 학습 데이터셋용으로 수백 장, 시안용으로 수십 장씩 뽑다 보면 "이거 그냥 GPU 빌려서 직접 돌리는 게 낫지 않나?" 싶은 순간이 옵니다.

이번 글에서는 오픈소스 이미지 생성 모델 Z-Image-Turbo를 gcube 워크로드로 배포해서, 프롬프트 목록만 넣으면 알아서 대량 생성하고 웹 화면으로 모니터링까지 되는 서비스를 운영하는 방법을 소개합니다. 저장소 연결부터 화면 사용법까지, 바로 쓸 수 있는 수준으로 정리했습니다.

환경 정보 — 모델: Z-Image-Turbo uint4 양자화(Disty0/Z-Image-Turbo-SDNQ-uint4-svd-r32) · 컨테이너: 이미지 약 14GB(모델 내장), 포트 8000, 최소 CUDA 12.8 · 검증 GPU: RTX 5090(Tier2), RTX 5060(Tier3, 8GB) · 기본 생성 조건: 768×576, 8 step

Z-Image-Turbo가 뭔가요?

Z-Image-Turbo는 적은 스텝(8 step)으로 이미지를 뽑는 경량 지향 이미지 생성 모델입니다. 이번 배포에는 uint4(4비트) 양자화 버전을 사용하는데, 모델이 차지하는 메모리가 크게 줄어서 8GB 소비자 GPU에서도 돌아간다는 게 핵심입니다.

배포하는 컨테이너는 이렇게 구성되어 있습니다.

• 이미지 생성 REST API + 웹 UI(생성 / 대시보드 / 이미지 탭)를 FastAPI 하나로 서빙
• 모델을 컨테이너 이미지에 내장 — 런타임 다운로드가 없어 재배포가 빠릅니다
• 레플리카 N개로 분산 — 각 레플리카가 자기 GPU와 모델을 갖고 독립적으로 생성
• 외부 API 비용 없음 — 전부 gcube GPU에서 직접 추론

레플리카가 여러 개여도 화면은 하나로 보입니다. 모든 레플리카가 같은 저장소를 마운트해서 결과를 한곳에 쓰기 때문에, 어느 레플리카가 응답하든 동일한 갤러리와 대시보드가 표시됩니다.

배포 준비 — 저장소와 conditions.json

저장소 연결

먼저 gcube 저장소 관리에서 저장소를 하나 만들어 둡니다(최초 1회). 이 저장소가 컨테이너의 /workspace로 마운트되고, 필요한 하위 폴더는 컨테이너가 처음 뜰 때 자동으로 만들어집니다. 미리 만들 폴더는 없습니다.

/workspace                        ← gcube 저장소 마운트 지점
├─ conditions.json                ← 자동 생성용 프롬프트 목록 (직접 업로드)
├─ outputs/
│   ├─ auto/                      ← 자동 생성 PNG (보존)
│   └─ manual/                    ← 화면에서 수동 생성한 PNG
└─ current/<워크로드>/<RUN_ID>/    ← UI 렌더링용 메타데이터 (실행별 격리)

생성된 PNG 원본은 outputs/에 한 번만 저장되고, 화면 표시용 메타데이터는 current/ 아래 실행(RUN_ID)별로 분리됩니다. 그래서 새 실행을 시작해도 이전 실행 결과와 섞이지 않습니다.

conditions.json 준비

자동 대량 생성에 사용할 프롬프트 목록입니다. 저장소 루트에 conditions.json으로 올려두면 컨테이너가 /workspace/conditions.json으로 읽습니다. 형식은 JSON 배열이고, 각 항목에서 prompt만 필수입니다.

[
  { "prompt": "a serene mountain lake at sunrise, cinematic" },
  { "prompt": "a futuristic city skyline, neon lights", "width": 768, "height": 576, "steps": 8 },
  { "prompt": "a cute corgi puppy running in a field" }
]

• prompt만 있으면 나머지는 기본값을 사용합니다 (seed는 랜덤)
• RANDOM_PICK=true면 목록에서 무작위 추출로 GEN_COUNT장을 생성하고, false(기본)면 순서대로 순환합니다

⚠️ 8GB GPU라면 해상도는 768×576을 권장합니다. 1024로 올리면 생성 중 VRAM 피크(약 8.5GB)가 8GB를 넘어 시스템 RAM으로 흘러넘치고(스필), 속도가 6~8배 급락합니다. 768×576이면 피크 약 7GB로 안전하게 들어갑니다. 각 항목에 width/height를 명시하거나, 아래 환경변수 ZIMG_WIDTH/ZIMG_HEIGHT로 지정하세요.

워크로드 설정

컨테이너 설정

환경변수

💡 자동 생성은 GEN_COUNT와 CONDITIONS_FILE이 둘 다 설정됐을 때만 시작됩니다. 하나라도 비우면 수동 모드로 떠서, 화면에서 프롬프트를 입력해 테스트할 수 있습니다.

저장소 마운트

GPU 설정

💡 GPU 티어별 예상 시간 (100장 · 768×576 기준) — RTX 5090은 약 3분(분당 34장), RTX 5060은 약 30분(분당 3.3장)입니다. 5060도 기동과 추론 안정성은 검증되어 있으니, 대량 작업이라면 레플리카를 늘려 분산하는 쪽이 경제적입니다. GPU별 실측 비교는 아래에서 다시 다룹니다.

배포하고 확인하기

배포하면 이 순서로 진행됩니다.

1. 컨테이너 기동 → 모델 로드 (이미지 내장형이라 다운로드 없이 바로)
2. 자동 모드라면 GEN_COUNT장 생성 시작
3. 웹 UI 준비 완료 → 서비스 URL로 접속 가능

워크로드 Logs 탭에서 이렇게 보이면 정상입니다.

[ MODEL ] loading Disty0/Z-Image-Turbo-SDNQ-uint4-svd-r32 ... (MEM_MODE=VRAM)
[ MODEL ] ready
[ AUTO ] 자동화 시작: 100장 / conditions.json / random=True

수동 모드로 배포했다면 마지막 줄 대신 [ AUTO ] 수동 모드가 나옵니다.

💡 최초 배포 시 노드에 이미지 캐시가 없으면 대용량 이미지(약 14GB) pull 때문에 수 분 걸릴 수 있습니다. 같은 노드에 한 번 적재된 뒤에는 캐시로 빠르게 재배포됩니다.

⚠️ 두 가지는 미리 알아두세요.

• 재배포하면 서비스 URL이 바뀝니다. 이전 URL은 404가 되니 항상 새 URL로 접속하세요.
• 레플리카는 각자 GEN_COUNT만큼 생성합니다. 레플리카 3대 × GEN_COUNT=100이면 총 300장입니다. 목표 장수에 맞춰 레플리카 수와 GEN_COUNT를 함께 조절하세요.

화면 사용법

서비스 URL로 접속하면 생성 탭이 나타납니다.

작업 제어는 Job Status의 버튼으로 합니다. 버튼을 누르면 대상 레플리카를 고르는 팝업이 뜨고, 체크한 레플리카에만 명령이 전달됩니다.

• 멈춤(pause) — 자동 생성을 일시 정지
• 재개(resume) — 멈춘 지점부터 다시 생성
• 취소(cancel) — 이번 실행 세션을 종료

대시보드 탭에서는 레플리카 수, 총 생성 장수, 평균 GPU 사용률 요약과 레플리카별 카드(클릭 시 게이지·시계열 그래프·미니 갤러리)를 볼 수 있습니다. 이미지 상세 모달에서는 프롬프트·seed·해상도 확인, 다운로드, 그리고 "이 설정으로 다시 생성"이 됩니다.

💡 화면 읽는 법 — 레플리카 표시가 유색이면 활성, 흰색이면 응답 두절(Dead)입니다. LOADING 칩은 모델 로드 중이라는 뜻이고, AUTO/MANUAL 뱃지는 각각 자동 생성분과 수동 생성분을 구분합니다.

생성이 끝난 결과물은 저장소의 outputs/에서 그대로 가져가면 되고, 검증이 끝난 뒤의 정리도 저장소에서 직접 하면 됩니다 (conditions.json은 지우지 마세요).

GPU는 뭘 골라야 하나요?

같은 컨테이너를 GPU 6종에 올려 동일 조건(768×576 · 8 step)으로 실측한 결과입니다.

읽는 법은 간단합니다. 급하면 5090, 싸게 많이 뽑으려면 저가 카드 + 레플리카입니다.

• 8GB 카드도 장당 14~18초로, 시간 여유가 있는 대량 생성에는 충분히 실용적입니다. 시간당 요금이 백 원대라 장당 비용으로는 오히려 유리합니다.
• 한 GPU에 컨테이너를 여러 개 띄우는 건 의미가 없습니다. 이미지 생성은 요청 하나로 GPU 연산이 포화되어, 실측 이득이 10% 남짓이었습니다. 처리량을 늘리려면 레플리카(GPU 수)를 늘리세요 — 이쪽은 선형으로 늘어납니다.
• 8GB 카드에서 성능이 이상하게 낮다면 십중팔구 해상도 때문입니다. 위의 스필 경고(768×576 권장)를 다시 확인하세요. GPU 사용률이 100%인데도 느리다면 그게 스필입니다.

마무리

프롬프트 목록 하나와 저장소 마운트만 준비하면, Z-Image-Turbo 대량 생성 파이프라인이 gcube 위에서 그대로 돌아갑니다. 외부 API 비용 없이, 8GB GPU로도요. 먼저 GEN_COUNT를 비운 수동 모드로 배포해서 화면에서 몇 장 뽑아보고, 감이 오면 conditions.json과 레플리카로 스케일을 키우는 순서를 추천합니다.

참고 링크

• 모델: huggingface.co/Disty0/Z-Image-Turbo-SDNQ-uint4-svd-r32