TRENDSHIFT 딥다이브 · 일간 #22 · 2026-06-05

Ideogram 4 딥다이브
— 폐쇄형 명가가 처음 공개한 '글자를 제대로 그리는' 오픈 이미지 모델

Ideogram 4(아이디어그램 4)는 텍스트(글자)를 이미지 안에 정확히 그려 넣는 능력으로 유명한 회사 Ideogram이 처음으로 가중치를 공개(open-weight)한 텍스트→이미지(text-to-image) 모델이다. 다른 모델을 미세조정한 게 아니라 밑바닥부터 새로 학습한 9.3B(93억 파라미터) 파운데이션 모델로, 단일 스트림 DiT(Diffusion Transformer) 구조 위에서 플로우 매칭(flow matching)으로 그림을 만든다. 가장 큰 특징은 평범한 문장 대신 구조화된 JSON 캡션으로 레이아웃·색·타이포그래피를 정밀 제어한다는 점. (저장소: ideogram-oss/ideogram4 · Python 100% · 코드 Apache-2.0 · 모델 가중치 비상업 라이선스 · ⭐ 약 1.0k · 2026-06-03 공개 · 제작 Ideogram AI)
목차
  1. 프로젝트 한줄 요약
  2. 왜 주목받는가
  3. 기술 스택 전체 지도
  4. 아키텍처 심화 분석
  5. 디렉토리 구조 해부
  6. 학습 포인트 (기술별)
  7. 하드웨어 / 시스템 요구사항
  8. 직접 해볼 수 있는 실습 과제
  9. 관련 기술 심화 학습 로드맵
  10. 핵심 키워드 사전
  11. 참고 링크

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

Ideogram 4 = "글자(타이포그래피)와 디자인 레이아웃을 가장 잘 그리는 회사가, 그 비밀 모델의 추론 코드와 가중치를 통째로 풀어버린 오픈소스 이미지 생성기". 보통 최첨단 이미지 모델(예: GPT Image, Gemini의 Nano Banana)은 회사 서버 안에 갇혀 있어 API로만 쓸 수 있다. Ideogram 4는 발상을 뒤집어, "모델 정의 + 가중치 + 추론 파이프라인을 공개해, 누구나 자기 GPU에서 직접 돌려보고 뜯어볼 수 있게" 했다. 게다가 평범한 문장 대신 이미지의 모든 요소를 좌표·색·스타일로 명시하는 JSON 캡션을 쓰면, "포스터의 제목은 여기, 그 색은 이 빨강, 배경은 저 그라데이션"처럼 디자이너가 시안을 지시하듯 그림을 통제할 수 있다.

🎨 한 줄 비유

"말로 대충 부탁하는 화가가 아니라, 설계도를 받아 그리는 간판 장인"

대부분의 이미지 AI는 "노을 지는 바다에 돛단배 그려줘"라고 말하면 알아서 그려주는 감각 좋은 화가다. 분위기는 잘 잡지만, "제목 글자를 정확히 'SUMMER SALE'로, 위쪽 3분의 1 지점에, 이 주황색으로"처럼 깐깐한 주문에는 약하다 — 글자를 뭉개거나 위치를 제멋대로 잡는다.

Ideogram 4는 설계도(JSON 캡션)를 받아 그리는 간판 장인에 가깝다. "배경은 이것, 1번 요소는 이 좌표 박스 안에 이 모양, 거기 들어갈 글자는 정확히 이 문장, 색은 이 헥스값"이라고 적어 주면 그대로 시공한다. 그래서 로고·포스터·배너처럼 '글자와 배치가 곧 품질'인 디자인 작업에서 특히 빛난다.

용어
텍스트→이미지 (Text-to-Image, T2I)
글(프롬프트)을 입력하면 그에 맞는 그림을 만들어 내는 생성 AI의 한 갈래. DALL·E, Midjourney, Stable Diffusion, FLUX 등이 같은 계열이다. Ideogram 4도 이 T2I 모델이며, 그중에서도 이미지 안의 글자 렌더링디자인 감각을 핵심 강점으로 내세운다.
용어
오픈 웨이트 (Open-weight)
모델을 굴리는 데 필요한 학습된 가중치(weights) 파일을 공개한다는 뜻. 코드만 공개(open-source)하고 가중치는 숨기는 경우와 구분된다. Ideogram 4는 코드를 Apache-2.0으로, 가중치를 비상업(Non-Commercial) 라이선스로 공개했다 — 즉 연구·개인용으로 내 컴퓨터에서 돌릴 수 있지만, 상업적 재배포에는 별도 조건이 붙는다.

핵심을 한 번 더 못 박자. Ideogram 4가 파는 가치는 "또 하나의 그림 AI"가 아니라 ① 폐쇄형 고품질 모델의 내부를 코드로 열어 보여준 점, ② 글자/디자인이라는 약점 영역을 정조준한 점, ③ JSON이라는 '프로그래밍 가능한 프롬프트' 인터페이스다. 9.3B라는 비교적 작은 몸집으로 20B~80B급 대형 오픈 모델들의 텍스트 렌더링을 앞선다는 점도, "크기가 전부가 아니다"라는 메시지를 던진다.

한눈에 그림

평범한 T2I = 주문서 한 줄("귀여운 고양이 마법사") → 모델이 알아서 해석 → 매번 조금씩 다른 결과, 글자는 운에 맡김.

Ideogram 4 = 시방서 한 장(배경·요소·좌표·글자·색을 JSON으로 명시) → 모델이 항목을 하나하나 대조하며 그림 → 의도한 배치·글자가 안정적으로 재현됨.

2왜 주목받는가

TrendShift 일간 22위 — 공개 직후 급부상한 배경.

2026년 6월 3일 가중치와 추론 코드가 공개되자마자 트렌딩에 올랐다. 이미지 생성 모델은 이미 차고 넘치는데 왜 이 모델이 화제일까? 다섯 가지로 정리한다.

① 폐쇄형 명가의 '첫 오픈' — 희소성

Ideogram은 그동안 웹·API로만 서비스하던 회사다. 그 회사가 "openness drives innovation(개방이 혁신을 이끈다)"을 내걸고 자체 학습한 최신 파운데이션 모델을 통째로 풀었다. FLUX(Black Forest Labs), Qwen-Image(알리바바)에 이어 '상업 명가가 직접 연 오픈 모델' 계보가 하나 더 늘어난 셈이라, 연구·창작 커뮤니티가 즉시 반응했다.

② 글자(타이포그래피) 렌더링의 압도적 우위

이미지 AI의 오랜 약점이 "이미지 안 글자가 깨진다"는 것. Ideogram 4는 이 영역의 강자로, 제3자 평가에서 두각을 보였다. ContraLabs의 전문 디자이너 블라인드 타이포그래피 평가에서 '4개 모델 중 최고'로 47.9% 선택(Gemini 3.1 Flash Image/Nano Banana 2는 30.0%, FLUX.2 max 15.5%, Grok Imagine 1.0 15.0%)되었고, "실제 클라이언트 작업에 쓰겠는가" 점수도 3.55/5로 1위였다.

③ '디자인'에 특화된 벤치마크 1위

디자인 전용 Elo 리더보드인 Design Arena에서 오픈웨이트 모델 중 1위(전체로는 GPT·Gemini 같은 폐쇄 모델 바로 다음), 오픈 모델만 추리면 2위와 큰 격차로 선두다. LMArena에서도 오픈 진영 1위·전체 톱5 랩에 들었다 — "훨씬 큰 예산을 가진 거대 기업만 위에 있다"는 게 저자들의 설명.

④ 9.3B '경량'으로 거함들을 이기는 효율

텍스트 렌더링 효율(파라미터당 성능)에서, Ideogram 4(9.3B)가 Qwen-Image(20B)·FLUX.2 dev(32B)·HunyuanImage 3.0(80B MoE)을 앞섰다. 작은 몸집은 곧 소비자급 GPU에서도 돌릴 여지를 뜻해, "API 없이 내 손으로"를 원하는 사람에게 매력적이다.

⑤ JSON 프롬프트 — '프로그래밍 가능한 그림 주문서'

Ideogram 4는 오로지 구조화된 JSON 캡션으로만 학습됐다. 덕분에 좌표 기반 레이아웃(bbox), 색 팔레트 헥스값, 요소별 스타일을 코드처럼 지정할 수 있다. 손으로 JSON 짜기 싫으면 매직 프롬프트(magic prompt)가 LLM으로 평문을 JSON으로 자동 확장해 준다. "감"이 아니라 "사양"으로 그림을 다루는 이 인터페이스가 개발자·디자이너 모두의 흥미를 끌었다.

구분일반 폐쇄형 T2I (API)Ideogram 4 (오픈웨이트)
접근 방식회사 서버, API 호출만가중치 다운로드 후 내 GPU에서 직접
강점편의성, 최신성글자 렌더링·디자인·세밀한 제어
프롬프트대개 평문구조화된 JSON(+매직 프롬프트)
내부 공개블랙박스아키텍처·파이프라인·시스템 프롬프트까지
제일 잘 맞는 곳가볍게 빠르게 한 장로고·포스터·배너, 레이아웃 통제, 연구
냉정하게 보기
"오픈"이라고 다 자유는 아니다 — 코드와 가중치의 라이선스가 다르다

이 레포의 추론 코드는 Apache-2.0(자유)이지만, 모델 가중치는 'Ideogram 4 Non-Commercial' 라이선스로 따로 묶여 있고 Hugging Face에서 게이트(gated) 처리되어 있다. 즉 상업적 사용·재배포에는 제약이 있으니, 회사 제품에 넣기 전 라이선스 원문을 반드시 확인해야 한다. 또 9.3B라 해도 고품질·고해상도(2K) 생성에는 만만찮은 VRAM이 필요하고(7절 참고), 안전 필터(Hive)를 켜려면 별도 API 키가 든다. "공개됐다 = 공짜로 뭐든 된다"가 아니라, "내부를 학습·연구할 수 있게 열렸다"로 받아들이는 게 정확하다.

3기술 스택 전체 지도

pyproject.toml · src/ideogram4 소스 트리에서 뽑아낸 실제 구성.

Ideogram 4는 웹 서버가 있는 풀스택 앱이 아니라 "PyTorch 위에 올라탄 순수 추론 라이브러리"다(언어 구성도 Python 100%). 그래서 의존성이 단출하고, 모두 머신러닝/딥러닝 표준 스택이다. 크게 ⓐ 딥러닝 코어 ⓑ 모델 로딩·양자화 ⓒ 텍스트 인코더(외부 모델) ⓓ 매직 프롬프트(외부 LLM) ⓔ 안전 필터(외부 API) 다섯 축으로 읽으면 된다.

ⓐ 딥러닝 코어 — PyTorch + Transformers

구성요소버전역할
torch≥ 2.11전체 신경망 연산의 토대. DiT 트랜스포머·VAE·플로우 매칭 적분이 전부 PyTorch 텐서 연산으로 돈다. CUDA(NVIDIA) GPU에서 가속.
transformers≥ 4.49텍스트 인코더로 쓰는 Qwen3-VL-8B-Instruct를 불러오고 토크나이즈하는 데 사용. 이미지 모델 본체가 아니라 '말을 숫자로 바꾸는 두뇌'를 빌려 오는 통로.
einops≥ 0.7rearrange 등으로 텐서 차원을 직관적으로 재배열. 패치↔그리드 변환, 멀티헤드 분해 같은 모양 바꾸기를 읽기 쉽게.
accelerate≥ 1.0큰 모델을 여러 디바이스에 효율적으로 올리고 메모리를 관리하는 헬퍼.

ⓑ 디스크 포맷 · 양자화 · 다운로드

구성요소무엇역할
safetensors안전·고속 텐서 포맷가중치를 .safetensors로 저장/로딩. 메모리 매핑으로 빠르고, 임의 코드 실행 위험이 없는 안전한 포맷.
bitsandbytes≥ 0.49.2 / 양자화 엔진nf4·fp8 양자화 가중치를 GPU에서 로딩·복원. 9.3B 모델을 더 작은 메모리에 욱여넣는 핵심.
huggingface_hub모델 다운로더게이트된 ideogram-ai/ideogram-4-nf4 가중치를 토큰 인증 후 받아온다. hf auth login 필요.
sentencepiece서브워드 토크나이저Qwen3-VL 토크나이저가 의존하는 토큰화 라이브러리.
pillow (PIL)이미지 입출력VAE가 디코딩한 텐서를 최종 PIL.Image(PNG 등)로 저장.
requestsHTTP 클라이언트매직 프롬프트(Ideogram API)·안전 필터(Hive API) 같은 외부 호출에 사용.

ⓒ 텍스트 인코더 — Qwen3-VL-8B-Instruct (외부 모델)

이미지 모델인데 텍스트 인코더로 '비전-언어 모델(VLM)'을 쓴다는 게 핵심 선택이다. CLIP·T5 같은 텍스트 전용 인코더 대신, 시각 개념까지 이해하는 Qwen3-VL을 텍스트 전용 모드로 돌려 프롬프트의 의미를 훨씬 풍부하게 뽑아낸다. 이 모델은 프리징(freeze)되어 학습되지 않고, 추론 시 가중치만 빌려 쓴다.

ⓓ 매직 프롬프트 — 외부 LLM (선택)

평문을 JSON 캡션으로 확장하는 단계. 기본값은 Ideogram이 호스팅하는 무료 서버 API(ideogram-4-v1)이고, 원하면 OpenRouter를 통해 Claude Sonnet/Opus으로 돌릴 수도 있다. 시스템 프롬프트는 src/ideogram4/magic_prompt_system_prompts/에 오픈소스로 포함돼 있어, 아무 LLM에나 붙여 써도 된다.

ⓔ 안전 필터 — Hive (외부 API, 선택)

프롬프트와 생성물의 유해성 검사를 Hive의 텍스트/비주얼 모더레이션 API로 수행. HIVE_TEXT_MODERATION_KEY·HIVE_VISUAL_MODERATION_KEY 키가 필요하며, 켜지 않을 수도 있다.

ⓕ 개발 도구

빌드는 hatchling, 린트/포맷은 ruff(2-스페이스 들여쓰기), 타입체크는 mypy, 커밋 훅은 pre-commit. Python 3.10~3.12 지원.

스택을 한 문장으로

"PyTorch라는 작업대 위에서, Qwen3-VL이 말을 읽어 주고, DiT 트랜스포머가 그림의 설계를 잡고, VAE가 픽셀로 인화하고, bitsandbytes가 이 모든 걸 작은 GPU에 맞게 압축한다." — 외부에 빌려 쓰는 건 '언어 이해(Qwen3-VL)'와 '프롬프트 확장(LLM)'·'안전 검사(Hive)'뿐, 이미지 생성의 본체는 이 레포 안에 다 들어 있다.

4아키텍처 심화 분석

docs/pipeline.md · model_architecture.md 기반 — 그림 한 장이 만들어지는 전 과정.

Ideogram 4의 추론 파이프라인은 네 개의 큰 부품으로 이뤄진다. 텍스트 인코더(Qwen3-VL) → DiT 트랜스포머(+샘플러) → VAE 디코더, 그리고 이 셋을 잇는 노이즈 적분 루프다. 학습 가능한(trainable) 부분은 가운데 DiT 하나뿐이고, 양옆의 텍스트 인코더와 VAE는 얼어 있다(frozen).

┌─────────────┐ ┌──────────────────────┐ ┌──────────────┐ ┌───────────┐ │ Qwen3-VL │ │ Ideogram4 │ │ KL VAE │ │ │ │ Text ├──►│ Transformer (DiT) ├──►│ Decoder ├──►│ Image │ │ Encoder │ │ + Euler Sampler │ │ │ │ │ └─────────────┘ └──────────────────────┘ └──────────────┘ └───────────┘ frozen trainable frozen (말→숫자) (노이즈→그림 설계) (잠재값→픽셀)

① 텍스트 인코더 — 13개 층을 한꺼번에 뽑아 쓰는 트릭

프롬프트는 먼저 Qwen3-VL-8B-Instruct(36층 트랜스포머)를 통과한다. 그런데 마지막 출력만 쓰지 않고, 0·3·6·9·…·33·35번 총 13개 층의 은닉 상태(hidden state)를 뽑아 특징 차원으로 이어 붙인다. 왜? 얕은 층은 '표면적인 토큰 정보', 깊은 층은 '깊은 의미'를 담기 때문에, 이걸 다 합치면 모델이 표층부터 구성적 이해까지 다중 스케일(multi-scale)로 받게 된다.

용어
은닉 상태 (Hidden State)
트랜스포머가 각 층을 지날 때마다 내부에 들고 있는 중간 표현(벡터). "문장을 이만큼 이해한 상태"의 스냅샷이다. 여러 층의 스냅샷을 모으면 '얕은 이해'와 '깊은 이해'를 동시에 활용할 수 있다.

② DiT 백본 — 텍스트와 이미지를 한 줄에 섞는 '단일 스트림'

핵심 생성 모델은 34층짜리 단일 스트림(single-stream) Diffusion Transformer다. 무슨 뜻이냐면, 텍스트 토큰과 이미지(잠재) 토큰을 하나의 시퀀스로 이어 붙여 같은 셀프 어텐션 층에 통과시킨다는 것. 텍스트 전용 가지, 이미지 전용 가지를 따로 두지 않아서, 모든 층에서 글과 그림이 깊게 상호작용한다.

한 샘플의 시퀀스 배치: ┌───────────────────┬────────────────────────┐ │ 텍스트 토큰 │ 이미지 잠재 토큰 │ │ (최대 2048개) │ (grid_h × grid_w) │ └───────────────────┴────────────────────────┘ ▲ ▲ Qwen3-VL 특징 노이즈 낀 잠재값 z_t

각 블록 안에는 세 가지 장치가 있다.

장치무엇역할
QK-RMSNorm + 3D MRoPE셀프 어텐션위치 인코딩이 3차원(시간·높이·너비). 텍스트 토큰은 1D 위치를 3축에 펴서, 이미지 토큰은 (t,h,w) 좌표로 — 글과 그림이 같은 위치 공간을 공유한다. mrope_section=(24,20,20).
SwiGLU MLP피드포워드SiLU 게이트가 달린 선형 유닛. 표준 MLP보다 표현력이 좋아 최신 LLM·DiT가 즐겨 쓴다. 중간 차원 12288.
AdaLN시간 조건화현재 노이즈 단계 t를 임베딩해 블록별 스케일·게이트를 만든다 → 모든 층이 "지금 얼마나 노이즈가 낀 단계인지"에 맞춰 동작.

모델 스펙을 한 표로 모으면 이렇다.

항목
임베딩 차원 (emb_dim)4608
층 수 (num_layers)34
어텐션 헤드 (num_heads)18
MLP 중간 차원12288
AdaLN 차원512
RoPE theta5,000,000
잠재 채널32 × 2² = 128
최대 텍스트 토큰2048
총 파라미터약 9.3B

③ 플로우 매칭 — '노이즈를 제거'가 아니라 '속도장을 따라 흐르기'

기존 확산 모델(DDPM)이 매 단계 '노이즈를 예측해 빼는' 방식이라면, Ideogram 4는 플로우 매칭으로 학습됐다. 모델은 노이즈가 아니라 속도장(velocity field) v(z_t, t)를 예측하는데, 이건 "지금 이 점이 깨끗한 이미지 쪽으로 어느 방향·속도로 움직여야 하나"를 알려주는 화살표다. 추론은 순수 가우시안 노이즈 z₁에서 출발해 이 화살표를 따라 오일러(Euler) 적분으로 z₀(깨끗한 그림)까지 거꾸로 흘러간다.

미분방정식: dz/dt = v(z_t, t) 오일러 한 스텝: z_{t-dt} = z_t + v(z_t, t) · dt 순수 노이즈(t=1) ──화살표 따라 적분──► 깨끗한 잠재 이미지(t=0)
용어
플로우 매칭 (Flow Matching)
노이즈에서 데이터로 가는 경로를 '속도장'으로 직선적으로 정의하고, 모델이 그 속도를 맞추도록 학습하는 최신 생성 기법. 확산(diffusion)보다 수식이 단순하고 적은 스텝으로도 좋은 품질을 내는 경향이 있어, 요즘 이미지/영상 모델의 주류 선택지다.

노이즈 스케줄은 로짓-정규(logit-normal) 분포를 따르며 평균 mu·표준편차 std로 조절한다. 중요한 건 해상도에 따라 스케줄이 자동 조정된다는 것 — 고해상도일수록 높은 노이즈 단계에 스텝을 더 배분한다.

mu_조정 = mu_기본 + 0.5 · log(픽셀수 / 기준픽셀수) (기준 = 512×512)

④ 비대칭 CFG — 긍정·부정 두 번 보고 차이를 증폭

매 샘플링 스텝마다 DiT를 두 번 돌린다. ① 조건부(긍정): 텍스트 특징 + 노이즈 이미지. ② 무조건(부정): 텍스트를 0으로 비우고 이미지 토큰만. 그리고 둘을 가중 결합한다.

v_guided = gw · v_조건부 + (1 - gw) · v_무조건 gw > 1 이면 → 텍스트를 따르는 신호를 증폭, 안 따르는 예측을 억제

비대칭(asymmetric)인 이유: 부정 패스는 텍스트 패딩 없이 이미지 토큰만 처리해 계산이 더 싸다. 또 gw(가이던스 가중치)는 스텝마다 바뀔 수 있어, V4_QUALITY_48 프리셋은 앞 45스텝을 gw=7로 강하게 밀고 마지막 3스텝을 gw=3으로 '광택(polish)'을 낸다.

용어
CFG (Classifier-Free Guidance)
프롬프트를 '얼마나 강하게 따를지'를 조절하는 핵심 손잡이. 프롬프트 있는 예측과 없는 예측의 차이를 증폭해, 값이 높으면 프롬프트에 충실하지만 다양성·자연스러움이 줄고, 낮으면 그 반대. Ideogram 4는 이 손잡이를 스텝마다 다르게 잡는다.

⑤ VAE 디코더 — 작은 잠재 격자를 큰 픽셀 그림으로

마지막으로 깨끗해진 잠재값 z₀를 KL 오토인코더(VAE)가 픽셀로 펼친다. DiT는 2×2 패치 단위로 일하므로 디코더는 먼저 언패칭(unpatching)으로 모양을 되돌리고, 채널별 정규화를 역으로 풀고, RGB로 디코딩한 뒤 0~255로 클리핑한다.

압축비를 보면 직관이 잡힌다. VAE가 각 축 8배, DiT의 2×2 패치가 추가로 2배 → 합쳐서 16배 압축. 그래서 1024×1024 이미지는 64×64 잠재 토큰 격자(각 토큰 128채널 = 32기본채널 × 2²)로 표현된다. "작은 격자에서 무겁게 생각하고, 마지막에 크게 인화"하는 구조라 연산이 효율적이다.

⑥ 전체를 한 덩어리 의사코드로

# 한 번의 생성 호출(개념 코드)

# 1. 텍스트 인코딩
text_features = qwen3_vl.encode(prompt)        # (B, L_text, D)

# 2. 노이즈 초기화 (t=1, 순수 가우시안)
z = randn(B, grid_h * grid_w, 128)

# 3. t=1 → t=0 오일러 적분
for step in reversed(range(num_steps)):
    t = schedule(step); s = schedule(step - 1)
    v_cond   = dit(text_features, z, t)        # 조건부(텍스트+이미지)
    v_uncond = dit(zeros, z, t)                # 무조건(이미지만)
    v = gw[step] * v_cond + (1 - gw[step]) * v_uncond   # CFG 결합
    z = z + v * (s - t)                        # 오일러 스텝

# 4. 픽셀로 디코딩
image = vae.decode(z)

5디렉토리 구조 해부

src/ideogram4/ 안의 13개 모듈이 각각 파이프라인의 어느 부품인지.

레포 루트는 단출하다 — README.md, pyproject.toml, run_inference.py(CLI 진입점), docs/(문서 6종), assets/(샘플·벤치마크 이미지), model_licenses/(비상업 라이선스), src/ideogram4/(본체). 진짜 알맹이는 src/ideogram4/에 있고, 파일명만 봐도 4절의 파이프라인과 1:1로 맞아떨어진다.

ideogram4/ ├─ run_inference.py ← CLI 진입점(--prompt, --quantization 등) ├─ pyproject.toml ← 의존성·빌드 설정 ├─ docs/ ← prompting · inference · architecture · pipeline · safety · development ├─ assets/ ← 샘플 이미지, 벤치마크 그래프, 로고 ├─ model_licenses/ ← Ideogram 4 Non-Commercial 라이선스 └─ src/ideogram4/ ├─ __init__.py ← 공개 API (PRESETS, MAGIC_PROMPTS, pipe 등 노출) ├─ pipeline_ideogram4.py ← ★오케스트레이터(가장 큰 파일, 22KB). 전 과정을 엮음 ├─ modeling_ideogram4.py ← ★DiT 본체: Transformer/Block/Attention/MLP/FinalLayer ├─ autoencoder.py ← KL VAE(잠재값→픽셀 디코딩) ├─ scheduler.py ← 플로우 매칭 오일러 스케줄러, 로짓-정규 노이즈 스케줄 ├─ sampler_configs.py ← PRESETS(V4_QUALITY_48 / DEFAULT_20 / TURBO_12) ├─ latent_norm.py ← 잠재 채널 정규화/역정규화 ├─ quantized_loading.py ← nf4/fp8 양자화 가중치 로딩(bitsandbytes) ├─ caption_verifier.py ← JSON 캡션 스키마 검증(키 순서·필수 키 경고) ├─ magic_prompt.py ← 평문→JSON 확장(Ideogram API / Claude via OpenRouter) ├─ magic_prompt_system_prompts/ ← 오픈소스 시스템 프롬프트(.txt) ├─ safety.py ← Hive 텍스트/비주얼 모더레이션 호출 └─ constants.py ← 공통 상수
파일크기한 줄 역할
pipeline_ideogram4.py22 KB인코딩→샘플링→디코딩 전체를 묶는 Ideogram4Pipeline.__call__. 여기가 "지휘자".
modeling_ideogram4.py12 KBDiT 트랜스포머 정의. 어텐션(QK-RMSNorm·MRoPE)·SwiGLU·AdaLN이 여기.
autoencoder.py13 KBKL VAE 디코더. 언패칭·역정규화·RGB 변환.
caption_verifier.py11 KBJSON 캡션이 학습 스키마에 맞는지 검사하고 경고를 띄움.
magic_prompt.py12 KB매직 프롬프트 3종 구성(ideogram-4-v1, claude-opus-v1, claude-sonnet-v1).
quantized_loading.py9.8 KBnf4/fp8 가중치를 GPU에 효율적으로 올림.
scheduler.py2.2 KB오일러 적분 + 로짓-정규 스케줄(해상도 자동 조정).
safety.py2.7 KBHive 모더레이션. NSFW면 회색 화면 반환.
sampler_configs.py0.8 KB프리셋(스텝수·CFG 스케줄·mu·std)을 이름으로 묶음.
읽는 순서 추천
코드를 처음 연다면 이 길로

run_inference.py → pipeline_ideogram4.py → modeling_ideogram4.py → scheduler.py → autoencoder.py 순서로 따라가면, "CLI 인자 → 파이프라인이 부품을 어떻게 호출 → DiT가 한 스텝을 어떻게 계산 → 노이즈 스케줄이 어떻게 t를 정함 → VAE가 어떻게 픽셀로 펼침"이 자연스럽게 이어진다. JSON 프롬프트가 궁금하면 caption_verifier.pymagic_prompt_system_prompts/를 곁들여 보면 된다.

6학습 포인트 (기술별)

이 레포를 교재 삼아 무엇을, 어떻게 배울 수 있나.

📐 ① 단일 스트림 DiT 구조

최신 이미지/영상 모델(SD3, FLUX 등)의 공통 뼈대가 바로 DiT다. 이 레포는 텍스트·이미지 토큰을 한 시퀀스로 합치는 단일 스트림 구현을 깔끔하게 보여준다.

실습 아이디어: modeling_ideogram4.py에서 시퀀스가 어떻게 concat되는지 추적하고, "왜 텍스트/이미지 가지를 나누지 않았을까"를 SD3의 'MM-DiT(이중 스트림)'와 비교해 정리해 보기.

🌊 ② 플로우 매칭 vs 확산(DDPM)

속도장을 예측하고 오일러로 적분하는 방식은 요즘 생성 모델의 표준이 돼 가고 있다. scheduler.py가 매우 짧으니(2KB), 로짓-정규 스케줄과 해상도 자동 조정 공식을 직접 읽어볼 만하다.

실습 아이디어: 노트북에서 toy 2D 데이터(두 가우시안 분포)로 플로우 매칭을 구현해, 노이즈→데이터로 점이 흐르는 걸 애니메이션으로 보기.

🧭 ③ 3D MRoPE — 멀티모달 위치 인코딩

텍스트(1D)와 이미지(2D 격자)를 같은 위치 공간에 넣는 트릭은 멀티모달 모델의 핵심 난제다. mrope_section=(24,20,20)이 무슨 뜻인지, 회전 위치 인코딩(RoPE)이 어떻게 3축으로 확장되는지 파보면 멀티모달의 깊은 이해가 열린다.

🎚️ ④ 비대칭 CFG와 스텝별 스케줄

"프롬프트를 얼마나 따를지"를 단일 숫자가 아니라 스텝마다 다른 스케줄로 잡는 설계는 품질 튜닝의 정수다. sampler_configs.py의 세 프리셋을 비교하며 "스텝 수와 gw가 결과에 어떻게 영향을 주나"를 실험으로 확인할 수 있다.

📦 ⑤ 양자화 로딩(nf4/fp8)

9.3B 모델을 소비자 GPU에 욱여넣는 실전 기술. quantized_loading.py에서 bitsandbytes로 nf4(4비트)·fp8(8비트) 가중치를 어떻게 디바이스에 올리는지 보면, '큰 모델을 작은 메모리에 담는' 일반적인 노하우를 배운다.

🧩 ⑥ 구조화 프롬프트 엔지니어링

JSON 캡션 + 매직 프롬프트는 "프롬프트를 데이터 구조로 다루는" 새로운 패러다임이다. caption_verifier.py가 검사하는 키 순서·필수 키 규칙은 그 자체로 좋은 스키마 설계 예제다. LLM으로 평문→구조화 출력을 만드는 패턴(magic prompt)은 다른 분야에도 그대로 응용된다.

7하드웨어 / 시스템 요구사항

두 가지 양자화 빌드와 현실적인 VRAM 감각.

모델은 두 가지 양자화 버전으로 배포된다. 어떤 GPU를 가졌느냐에 따라 선택이 갈린다.

모델파라미터양자화지원 하드웨어Diffusers 지원
ideogram-4-nf49.3Bnf4 (4비트)CUDA(NVIDIA) 전용O
ideogram-4-fp89.3Bfp8 (8비트)모든 하드웨어X

9.3B를 4비트로 누르면 가중치만 대략 5GB 안팎이지만, 실제로는 텍스트 인코더(Qwen3-VL-8B)도 함께 메모리에 올라가고, 2K 해상도 생성 시 활성값(activation)·KV가 추가로 들기 때문에 여유 있는 12GB 이상 VRAM을 권장 수준으로 보면 안전하다. fp8 빌드는 더 넉넉한 메모리를 요구한다.

프리셋스텝CFG 스케줄mustd
V4_QUALITY_48 (기본)4845스텝 gw=7 → 3스텝 gw=30.01.5
V4_DEFAULT_202018스텝 gw=7 → 2스텝 gw=30.01.75
V4_TURBO_121211스텝 gw=7 → 1스텝 gw=30.51.75

스텝이 적을수록 빠르지만 품질이 떨어진다. 해상도는 가로·세로 모두 16의 배수면 256~2048 자유롭게, 종횡비는 최대 6:1까지(정사각 1024², 와이드 1920×1088, 울트라와이드 2048×768, 폰 배경 1024×1792, 배너 1600×400 등). 최고 품질은 --height 2048 --width 2048 --sampler-preset V4_QUALITY_48.

용어
양자화 (Quantization)
가중치를 32/16비트 같은 큰 숫자 대신 4·8비트의 작은 숫자로 표현해 메모리·속도를 아끼는 기법. nf4는 정규분포에 최적화된 4비트, fp8은 8비트 부동소수점. 약간의 정밀도를 내주고 큰 모델을 작은 GPU에 담는다.
설치 시 함정
가중치는 '게이트'되어 있다 — 그냥 받으면 404

HF 가중치는 게이트(gated) 상태라, 모델 페이지에서 "Agree and access repository"로 라이선스에 동의하고 hf auth login(또는 HF_TOKEN 환경변수)으로 인증해야 다운로드된다. 인증 없이 받으면 404 / GatedRepoError로 실패한다. 안전 필터를 켜려면 Hive 키 2종도 별도로 발급해야 한다.

8직접 해볼 수 있는 실습 과제

난이도별 5개 — 클론만으로 끝내지 말고 손을 움직여 보자.

난이도 ★ — 첫 생성

1. 평문 프롬프트로 첫 이미지 뽑기 초급

pip install . 후, HF 로그인과 IDEOGRAM_API_KEY를 세팅하고 run_inference.py --prompt "..." --quantization nf4로 첫 그림을 만든다. 같은 프롬프트를 세 프리셋(48/20/12 스텝)으로 돌려 속도·품질 차이를 눈으로 비교한다.

난이도 ★★ — JSON 입문

2. JSON 캡션 직접 짜서 글자 박아 넣기 초중급

매직 프롬프트를 끄고, compositional_deconstructiontype:"text" 요소로 특정 문장을 정확한 위치(bbox)에 넣어 본다. "포스터 제목을 상단 3분의 1에"처럼. 같은 그림을 평문으로도 만들어, 글자 정확도가 얼마나 차이 나는지 확인.

힌트: bbox는 [y_min, x_min, y_max, x_max]를 0~1000 정규 좌표로. 키 순서를 지켜야 CaptionVerifier 경고가 안 뜬다.
난이도 ★★★ — 색 통제

3. 컬러 팔레트 조건화 실험 중급

style_description.color_palette에 헥스값(예: 브랜드 컬러 5개)을 넣어, 같은 장면을 서로 다른 팔레트로 여러 장 생성한다. 배경색·하이라이트·그림자 색을 모두 포함했을 때와 일부만 넣었을 때 결과가 어떻게 달라지는지 표로 기록.

난이도 ★★★★ — 코드 개조

4. 나만의 샘플러 프리셋 추가 중상급

sampler_configs.pyPRESETS에 새 항목을 추가해 본다. 예: 30스텝에 gw 스케줄을 직접 설계(앞부분은 강하게, 끝부분 5스텝은 gw=2로 부드럽게). run_inference.py에서 --sampler-preset로 호출해 효과를 검증.

난이도 ★★★★★ — LLM 연동

5. 커스텀 매직 프롬프트 LLM 붙이기 고급

magic_prompt_system_prompts/의 오픈소스 시스템 프롬프트를 가져다 로컬 LLM(Ollama 등)이나 다른 API에 연결해, 평문→JSON 확장을 직접 구현한다. 회사 기본 API(ideogram-4-v1) 또는 Claude Sonnet/Opus 옵션 결과와 품질을 비교하고, 어떤 캡션 필드에서 차이가 큰지 분석.

9관련 기술 심화 학습 로드맵

이 레포를 제대로 씹어먹기 위한 4주 코스.

주차주제구체적 목표
1주차확산/플로우 매칭 기초DDPM → DDIM → 플로우 매칭의 흐름을 잡는다. "노이즈 예측 vs 속도장 예측"의 차이를 toy 코드로 구현. scheduler.py를 줄별로 읽기.
2주차트랜스포머 & DiT셀프 어텐션·RoPE·RMSNorm·SwiGLU·AdaLN 각각을 복습. modeling_ideogram4.py에서 한 블록의 순전파를 손으로 따라가며 텐서 모양을 적어 보기.
3주차VAE & 잠재 공간오토인코더·KL 정규화·패치/언패치·잠재 압축비(16×)를 이해. autoencoder.py·latent_norm.py 분석. "왜 픽셀이 아니라 잠재 공간에서 생성하나"를 설명할 수 있게.
4주차멀티모달 인코더 & 프롬프트VLM(Qwen3-VL)을 텍스트 인코더로 쓰는 의미, 다층 은닉 상태 concat, JSON 캡션 스키마/매직 프롬프트. 직접 캡션을 설계해 생성 품질을 끌어올리기.
곁다리로 보면 좋은 것

비교 대상으로 Stable Diffusion 3(MM-DiT), FLUX, Qwen-Image의 기술 보고서를 함께 읽으면 "단일 스트림 vs 이중 스트림", "텍스트 인코더 선택(T5 vs VLM)", "플로우 매칭 스케줄 설계"의 설계 분기점이 선명해진다. 텍스트 렌더링이 왜 어려운 문제인지도 자연히 이해된다.

10핵심 키워드 사전

이 문서·레포에 등장한 용어를 한자리에.

용어
DiTDiffusion Transformer. 확산/플로우 매칭 생성을 트랜스포머로 수행하는 아키텍처. 최신 이미지·영상 모델의 표준 뼈대.
단일 스트림텍스트·이미지 토큰을 한 시퀀스로 합쳐 같은 어텐션 층에 통과시키는 방식. 이중 스트림(가지 분리)과 대비.
플로우 매칭노이즈→데이터 경로를 '속도장'으로 정의하고 모델이 그 속도를 맞추도록 학습. 확산보다 단순하고 효율적.
속도장 (velocity field)각 지점에서 "데이터 쪽으로 어디로 얼마나 움직일지"를 알려주는 화살표 함수 v(z,t).
CFGClassifier-Free Guidance. 프롬프트 충실도를 조절하는 손잡이. 긍정/부정 예측의 차이를 증폭.
비대칭 CFG부정(무조건) 패스가 이미지 토큰만 처리해 계산을 아끼는 변형.
AdaLNAdaptive Layer Norm. 노이즈 단계 t로부터 블록별 스케일·게이트를 만들어 시간 조건화.
MRoPEMultimodal Rotary Position Embedding. 텍스트·이미지를 3축(시간·높이·너비) 위치 공간에 함께 인코딩.
SwiGLUSiLU 게이트가 달린 MLP. 표준 피드포워드보다 표현력이 좋음.
VAEVariational Autoencoder. 픽셀↔잠재값을 오가는 인코더/디코더. 여기선 잠재값을 픽셀로 푸는 디코더로 사용.
잠재 공간 (latent)이미지를 16배 압축한 작은 격자. 생성 연산은 여기서 벌어지고, 마지막에 픽셀로 인화.
로짓-정규 스케줄노이즈 단계 분포를 로짓-정규로 잡아 mu·std로 조절. 해상도에 따라 자동 조정.
매직 프롬프트평문을 구조화 JSON 캡션으로 확장해 주는 LLM 단계. 기본은 Ideogram 무료 API.
JSON 캡션high_level_description·style_description·compositional_deconstruction 3필드로 구성된 구조화 프롬프트.
bbox요소의 위치 상자. [y_min, x_min, y_max, x_max]를 0~1000 정규 좌표로 표기.
오픈웨이트학습된 가중치 파일을 공개. (단, 여기선 비상업 라이선스 + 게이트.)
nf4 / fp84비트(정규분포 최적)·8비트 부동소수점 양자화. 큰 모델을 작은 메모리에.
Qwen3-VL텍스트 인코더로 쓰인 비전-언어 모델. 텍스트 전용 모드로 프롬프트 의미를 풍부하게 추출.

11참고 링크

원문으로 더 깊이 파고들 때.