# FLUX 3 Prompt Upsampler
> Models: FLUX 3 Image Klein Prompt Upsampler (9B)
>
> Developer: Black Forest Labs
>
> License: Apache-2.0
## 개요
FLUX 3 Prompt Upsampler는 **FLUX 3 Image Klein 앞에 두고 쓰는 프롬프트 전용 LLM**입니다. "노을 지는 바닷가의 개"처럼 짧은 요청을 받아, FLUX 3 Image Klein이 가장 잘 그리는 형태의 **자세한 영어 설명문(캡션) 한 개**로 바꿔 줍니다. 매체·스타일, 장면, 조명과 카메라, 대상마다의 색·재질·화면 속 위치까지 모두 정해서 씁니다.
제작사는 FLUX 3 Image Klein이 **프롬프트 업샘플러 없이 쓰도록 만들어지지 않았다**고 밝힙니다. 짧은 요청을 그대로 넣으면 평범한 이미지가 나오기 때문입니다. 이 모델은 Qwen3.5 9B를 바탕으로, FLUX 3 Image Klein이 실제로 그린 결과를 기준으로 학습되었습니다.
동작 방식(모드)은 **시스템 프롬프트로 고릅니다.** 제작사가 공개한 시스템 프롬프트는 4가지입니다.
| 모드 | 용도 |
|-|-|
| `t2i` | 텍스트 → 이미지용 캡션 |
| `i2i` | 참조 이미지 편집용 지시문 |
| `t2i_bbox` | 텍스트 → 이미지 + 요소 위치(바운딩 박스) 표 |
| `i2i_bbox` | 참조 이미지 편집 + 바운딩 박스 표 |
## 주요 특징
* 짧은 요청을 FLUX 3 Image Klein에 맞춘 100~350단어 영어 캡션으로 확장
* 요청은 어떤 언어로 써도 되고, 결과는 영어로 나옴(이미지 안에 넣을 글자는 원래 언어 그대로 따옴표 안에 유지)
* 요청에 적힌 대상·개수·위치·스타일은 빠뜨리거나 바꾸지 않고, 정해지지 않은 부분만 하나의 구체적인 계획으로 채움
* 텍스트→이미지, 참조 이미지 편집, 바운딩 박스 배치를 시스템 프롬프트로 전환
* FlameBox에서는 일반 LLM과 같은 `messages` API로 호출
## 모델 사양
|항목|FLUX 3 Image Klein Prompt Upsampler|
|-|-|
|기반 모델|Qwen3.5 9B (전체 파인튜닝, 비전 타워 고정)|
|파라미터|약 9B|
|구조|Dense, 하이브리드 어텐션 — 32층 중 일반 어텐션 8층 / 선형 어텐션 24층|
|Hidden Dimension|4,096|
|Attention Heads (Q / KV)|16 / 4|
|컨텍스트|262,144 tokens (업샘플링에는 8K 정도면 충분)|
|입력|텍스트 + 참조 이미지(최대 10장)|
|출력|영어 캡션 1개 (bbox 모드는 캡션 + 박스 표 JSON)|
|License|Apache-2.0|
> 학습: 짧은 요청과 확장된 프롬프트 쌍으로 지도 학습한 뒤, 같은 seed로 FLUX 3 Image Klein이 그린 결과를 비교해 선호도 학습을 했습니다(제작사 설명).
## 권장 파라미터
제작사 권장 디코딩은 greedy(가장 확률 높은 단어만 선택), `top_p` 0.95, `top_k` 20이고, 생각 과정은 끕니다. FlameAI에서는 Cortex를 만들 때 설정합니다.
### Cortex 생성 시
```text
temperature = 0 # greedy
top_p = 0.95
top_k = 20
repeat_penalty = 1.0
n_ctx = 8192 # 시스템 프롬프트(약 800 tokens) + 요청 + 캡션이면 충분
n_predict = 4096 # 제작사 예시 최대 3,584 tokens
n_gpu_layers = 100
```
* 제작사는 텍스트→이미지 모드에 `presence_penalty` 1.5를 권장하지만, FlameAI Cortex에는 아직 이 설정이 없습니다. 같은 문장이 반복되면 `repeat_penalty`를 1.05 정도로 조금만 올려 보세요.
### 요청 시
* `options.think` = `0` — 생각 과정 없이 바로 캡션을 씁니다(제작사 설정과 같음).
* `options.cortex_reset` = `true` — 요청마다 이전 캡션을 지우고 새로 시작합니다. 캡션은 서로 독립적이라 이어 쓸 필요가 없고, 이전 내용이 쌓이면 컨텍스트만 차지합니다.
* 화면 비율을 정하려면 요청 첫 줄에 `TARGET CANVAS: 16:9`처럼 씁니다. 업샘플러가 그 비율에 맞게 구도를 짭니다.
## 최소 실행 조건
양자화 수준별 모델 파일 크기와 필요한 메모리입니다. **GPU로 실행할 때는 VRAM, CPU로만 실행할 때는 RAM — 둘 중 하나만 만족하면 됩니다.**
### FLUX 3 Image Klein Prompt Upsampler (9B)
|구분|원본 (BF16)|Q8|Q5|Q4|Q2|
|-|-|-|-|-|-|
|파일 크기|17.9 GB|9.5 GB|6.5 GB|5.6 GB|3.8 GB|
|GPU 실행 — VRAM|22 GB 이상|12 GB 이상|8 GB 이상|7 GB 이상|5 GB 이상|
|CPU 실행 — RAM|20 GB 이상|12 GB 이상|8 GB 이상|7 GB 이상|5 GB 이상|
> * **GPU 실행 — VRAM**: 모든 레이어를 GPU에 올렸을 때(`n_gpu_layers = 100`) 필요한 VRAM입니다. 컨텍스트 32K 기준이며, 권장값 `n_ctx = 8192`로 쓰면 약 0.4 GB 줄어듭니다.
> * **CPU 실행 — RAM**: GPU 없이 시스템 RAM만으로 실행할 때(`n_gpu_layers = 0`) 필요한 메모리입니다. 컨텍스트 8K 기준이며, 운영체제가 쓰는 메모리는 별도입니다.
> * VRAM이 조금 모자라면 `n_gpu_layers`를 줄여 일부 레이어만 GPU에 올릴 수 있습니다. 이때는 필요한 메모리를 VRAM과 RAM이 나눠 맡으며, 속도는 그만큼 느려집니다.
> * 모든 값은 파일 크기에 KV 캐시와 여유분(약 10%)을 더한 추정치입니다. 양자화 칸은 Q8 = Q8_0, Q5 = Q5_K_M, Q4 = Q4_K_M, Q2 = Q2_K 기준입니다.
> * 하이브리드 구조라 KV 캐시가 작습니다(32K에 약 0.5 GB).
> * **FLUX 3 Image Klein과 같은 PC에서 함께 돌린다면** 두 모델의 메모리를 더해야 합니다(FLUX 3 패밀리 설명 참고).
**PC 기준 예시**
* Q4 — 8 GB GPU (예: RTX 4060, RTX 3070)
* Q8 — 12 GB GPU (예: RTX 3060 12GB, RTX 4070)
* FLUX 3 Image Klein Q8과 업샘플러 Q4를 한 PC에서 — 12 ~ 16 GB GPU + RAM 32 GB PC
* GPU 없이 — Q4 기준 RAM 16 GB PC (캡션 1개에 시간이 걸림)
OS는 FlameBox 지원 OS(Windows / Linux / macOS)면 됩니다.
## FlameAI에서 사용하기
1. **FlameBox 설치 및 등록** — FlameBox를 설치하고 내 계정에 등록합니다.
2. **모델 다운로드** — My AI Console의 FlameBox 상세 화면에서 PC 메모리에 맞는 양자화된 모델을 내려받습니다. 이미지를 그릴 FLUX 3 Image Klein도 함께 내려받습니다.
3. **AI API 만들기** — 업샘플러로 LLM AI API를 만듭니다(위 권장 파라미터 참고).
4. **캡션 만들기** — `messages` API에 아래 `t2i` 시스템 프롬프트와 짧은 요청을 보냅니다.
```bash
curl -s -X POST "https://api-N.flameai.im/{my_base_path}/cortex/{cortexId}/messages" \
-H "Authorization: Bearer {Secret Key}" \
-H "Content-Type: application/json" \
-d '{
"conversationId": "flux-prompt-001",
"options": { "think": 0, "cortex_reset": true },
"messages": [
{ "role": "system", "content": "{아래 t2i 시스템 프롬프트 전문}" },
{ "role": "user", "content": "TARGET CANVAS: 16:9\n비 오는 밤, 네온 간판이 빛나는 좁은 골목" }
]
}'
```
5. **이미지 그리기** — 응답의 `text` 블록(영어 캡션)을 FLUX 3 Image Klein AI API의 `imageGenerate` `prompt`로 그대로 넣습니다. 사용법은 FLUX 3 패밀리 설명을 참고하세요.
### `t2i` 시스템 프롬프트 (제작사 공개, 텍스트 → 이미지용)
```text
You are the prompt upsampler of a text-to-image model. Expand the user's short request into ONE detailed, self-contained caption: the exact text the image model receives. Output only the caption, with no greetings, explanations, refusals, questions, Markdown, headings, JSON, coordinates, ids or angle-bracket tokens, and no quotes around it. If the input is not clearly an image request, caption a visualization of its concept. The request may begin with a "TARGET CANVAS: W:H" line: compose for that canvas (wide spreads content sideways, tall stacks it) and never mention the ratio or the canvas.
Fidelity and planning: keep every explicit subject, attribute, count, spatial constraint, style cue and piece of wording; never contradict, substitute, drop or narrow the request, and keep an abstract concept abstract. Decide everything left open as ONE concrete, consistent plan; never offer alternatives or hedge. Never re-express a stated constraint through another mechanism; add camera optics (depth of field, bokeh, blur) only when asked for or implied. Without a stated style, plan an actual photograph and open with the medium convention ("Full-color outdoor photograph, ...", "Full-color indoor photograph, ...", "Studio photograph, ...", "Close-up photograph, ..."); keep "Photorealistic" for renders, and turn "photorealistic" or "realistic" requests for photos into the photograph convention. Give a photograph a few ordinary, non-ideal specifics drawn from the scene's own objects instead of the stock-photo ideal. Do not invent names, brands, logos or celebrities; keep user-named ones. A long request keeps its content but not its wording: drop appraisal and sales vocabulary, turn moods into observable physical facts, and add only new concrete content with positions. Time of day is lighting, not rendered text.
Caption format: one continuous prose block in the generative voice, never "this image shows", "we can see" or "is visible". Lead with medium and style, then scene, lighting and camera, then the subjects with concrete colors, materials and state. Every person in focus gets an observable profile: ethnicity, gender, age range, skin tone ("fair skin", "brown skin"), hair and clothing. Make the layout reconstructable from words: frame-relative positions (frame-left, frame-right, upper, lower, foreground, midground, background), sentence-initial anchors ("On the left, ...", "In the background, ..."), relations (holds, faces, behind) and a consistent order; describe up to about ten instances one by one, beyond that give the exact count and arrangement. Out-of-focus or distant planes are shapes, colors and silhouettes, never identities or readable text, and the background takes about a sixth of the caption. Be definite: no hedging adverbs, no quality or emotion judgments, no closing sentence about mood; state negations as what is present. Rendered text: transcribe every wording verbatim inside double quotes in its original language and script, keep the line breaks of multi-line text, and give its typography, color and placement; author concrete, domain-correct wording when the request needs text it does not supply, and name canonical structures (calendar, keyboard, periodic table) exactly with their full layout. All prose is English; only quoted text keeps its language. Typical length is 100 to 350 words, more for complex scenes.
Output only the caption.
```
* JSON 요청에 넣을 때는 줄바꿈(`\n`)과 따옴표(`\"`)를 이스케이프해야 합니다. 코드에서 문자열로 읽어 넣는 것을 권장합니다.
* 나머지 모드(`i2i`, `t2i_bbox`, `i2i_bbox`)의 프롬프트는 제작사 저장소의 `system_prompts.json`에 있습니다("참고" 링크).
## 활용 분야
* FLUX 3 Image Klein으로 이미지를 만드는 모든 경우의 앞단 — 짧은 요청을 고품질 프롬프트로
* 한국어 등 영어가 아닌 요청을 영어 이미지 프롬프트로 바꾸기
* 블로그·상품 설명 같은 긴 글을 이미지 프롬프트로 요약하기
* 다른 이미지 모델용 프롬프트 초안 만들기(제작사 학습 대상은 FLUX 3 Image Klein뿐이라 결과는 직접 확인 필요)
## 제한 사항
* **출력은 영어입니다.** 요청은 어떤 언어로 써도 됩니다.
* **FLUX 3 Image Klein 전용으로 학습되었습니다.** 다른 이미지 모델용으로는 학습하지 않았습니다.
* **FlameAI에서는 현재 텍스트 요청(`t2i`)만 쓸 수 있습니다.** 참조 이미지 모드(`i2i`, `i2i_bbox`)는 비전 인코더 파일이 필요해 아직 지원하지 않고, 바운딩 박스 표(`*_bbox`)를 이미지 생성에 넘기는 기능도 아직 없습니다.
* 요청을 거절하지 않습니다. 제작사 추론 코드는 별도의 안전 검사 옵션을 두고 있으니, 서비스에 쓸 때는 입력·출력 검사를 따로 두세요.
* 참조 이미지는 모델이 보기 전에 축소되므로(1장일 때 최대 약 1MP) 작은 부분은 잘못 묘사될 수 있습니다.
* FlameAI에서 아직 실측하지 않았습니다(같은 구조의 Qwen 3.5 9B 기준으로 안내).
## 참고
* Hugging Face — FLUX 3 Image Klein Prompt Upsampler (모델 카드, `system_prompts.json`): https://huggingface.co/black-forest-labs/flux-3-image-klein-pup
* GitHub — FLUX 3 Image Klein 추론 코드(`flux3/pup.py`): https://github.com/black-forest-labs/flux-3-image-klein
* Black Forest Labs 블로그 — FLUX 3 Image Klein: https://bfl.ai/blog/flux-3-image-klein
* 기반 모델 Qwen3.5 9B: https://huggingface.co/Qwen/Qwen3.5-9B
* GGUF 양자화: https://huggingface.co/prithivMLmods/flux-3-image-klein-prompt-upsampler-GGUF
