이미지 생성¶
mlxcel은 mlxcel generate-image 서브명령어와 OpenAI 호환 서버 경로인 POST /v1/images/generations 및 POST /v1/images/edits를 통해 디퓨전 체크포인트로 이미지를 생성하고 편집합니다. 디퓨전 모델은 토큰이 아니라 픽셀을 만들므로, 이미지 생성은 generate와 serve -m과는 별도의 표면입니다. detect가 박스를 위해 별도로 존재하는 것과 같은 방식입니다.
로더가 이미지 모델로 인식하는 체크포인트는 mlxcel generate와 mlxcel serve -m에서 generate-image를 안내하는 메시지와 함께 거부됩니다. 프로브가 인식하지만 이 빌드에서 구현하지 않은 체크포인트는 image generation family <family> is not supported by this build 오류로 실패합니다.
지원 패밀리¶
| 패밀리 | 체크포인트 | 태스크 | 기본 스텝 / 가이던스 |
|---|---|---|---|
flux2 | FLUX.2 Klein 4B, 9B, base-4B, base-9B, 9b-kv, 그리고 mlx-community 4비트 변환 | 생성, 편집(참조 이미지) | 증류 4 / 1.0; base 50 / 4.0 |
z_image | Tongyi-MAI Z-Image-Turbo, Z-Image | 생성, 편집(img2img) | Turbo 8 / 0; base 50 / 4 |
bonsai | Prism Bonsai ternary 2비트 FLUX.2 Klein 4B | 생성 | 4 / 1.0 |
ernie_image | Baidu ERNIE-Image-Turbo, ERNIE-Image | 생성, 편집(SDEdit img2img) | Turbo 8 / 1.0(편집 8 / 3.0); base 50 / 4.0 |
mage_flow | Mage-Flow, Mage-Flow-Base, Mage-Flow-Turbo, Mage-Flow-Edit, Mage-Flow-Edit-Base, Mage-Flow-Edit-Turbo | 변형에 따라 생성 또는 편집 | Turbo 4 / 1.0; Mage-Flow 20 / 5.0; Base와 Edit 30 / 5.0 |
qwen_image | Qwen-Image-2.1 | 생성, 편집(참조 이미지 하나 이상, RGBA 유지) | 생성 30 / 1.0; 편집 40 / 1.0 |
ideogram4 | ideogram-ai/ideogram-4-fp8(라이선스 제한) | 생성 | 20 / 7.0(마지막 두 스텝은 3.0) |
ming_image | Ming-Image-0.1-Design 및 그 MLX 8비트, 4비트 변환 | 생성(RGBA 출력) | 12 / 1.0 |
llada_image | LLaDA-Image-Turbo, LLaDA-Image | 생성(텍스트 또는 VQ prior), 편집(소스 이미지 하나) | Turbo 4 / 1.0; base 50 / 5.0 |
패밀리는 체크포인트 디렉터리의 manifest.json, model_index.json, 컴포넌트 설정, 트랜스포머 가중치 맵에서 감지합니다. 감지는 JSON만 읽고 가중치는 절대 로드하지 않으므로, 잘못된 디렉터리나 아직 포팅하지 않은 패밀리는 메모리를 쓰기 전에 실패합니다.
CLI¶
mlxcel generate-image -m models/flux2-klein -p "a watercolor fox"
mlxcel generate-image -m models/flux2-klein -p "a fox" --size 768x512 --seed 7 -n 2 -o fox.png
mlxcel generate-image -m models/flux2-klein --task edit --image fox.png -p "make it night"
| 플래그 | 기본값 | 설명 |
|---|---|---|
-m, --model <PATH> | 필수 | 체크포인트 디렉터리(Diffusers 레이아웃). |
-p, --prompt <TEXT> | 필수 | 프롬프트 또는 편집 지시문. |
--negative-prompt <TEXT> | 모델 기본값 | 네거티브 프롬프트. |
--task <generate\|edit> | generate | 텍스트-투-이미지 또는 참조 이미지 편집. |
--image <PATH> | - | 참조 이미지. 여러 장은 반복 지정합니다. edit에는 필수이고 generate에는 거부됩니다. |
--size <WxH> | 생성 시 512x512; 편집 시 첫 번째 참조 이미지의 크기, 또는 패밀리가 그로부터 유도한 크기 | 출력 크기. 가로와 세로는 모두 패밀리의 그리드(대부분의 패밀리는 16)의 배수여야 합니다. |
--steps <N> | 모델 기본값 | 디노이징 스텝 수. |
--guidance <F> | 모델 기본값 | classifier-free guidance 스케일. |
--seed <N> | 무작위 32비트 | 시드. 항상 출력됩니다. |
-n <N> | 1 | 이미지 수(1~10). 이미지 i는 시드 seed + i를 사용합니다. FLUX.2 생성은 예외입니다. |
-o, --output <PATH> | outputs/image-<seed>.png | 출력 경로. 확장자는 .png로 강제됩니다. -n이 1보다 크면 이름은 <stem>-01.png, <stem>-02.png 등이 됩니다. |
--gen-kwargs <JSON> | - | 모델별 옵션을 JSON 객체로 지정하며, extra로 모델에 전달됩니다. |
이 명령은 패밀리를 분류하거나 가중치를 로드하기 전에 모델 디렉터리, 인자, 참조 이미지, 출력 디렉터리를 검증합니다. 모델이 프롬프트를 재작성하는 경우(ERNIE-Image의 프롬프트 인핸서) CLI는 저장한 이미지마다 그 경로를 알리는 줄 다음에 revised prompt: <text>를 출력합니다.
FLUX.2 생성은 업스트림 mlx-vlm을 따릅니다. n장의 이미지는 seed에서 뽑은 하나의 노이즈 텐서를 공유하고 한 번의 프롬프트 인코딩에서 나오므로, 모든 이미지가 같은 시드를 보고하며 이미지 i는 seed + i로 단독 실행했을 때 나오는 이미지가 아닙니다. 편집과 다른 패밀리는 이미지마다 시드 seed + i로 한 번씩 실행합니다.
--gen-kwargs는 모델별 설정을 전달합니다. FLUX.2와 Bonsai는 max_sequence_length와 tiled_vae를 받습니다. Z-Image, ERNIE-Image 및 다른 패밀리의 옵션은 docs/image-generation.md에 문서화되어 있습니다.
서버¶
--image-model(mlxcel-server와 mlxcel serve 모두에서 MLXCEL_IMAGE_MODEL 환경 변수로도 지정)은 --embedding-model과 같은 방식으로 사이드 작업자를 로드합니다. 전용 스레드가 모델을 소유하고, 크기가 제한된 큐가 요청을 받아들이며, 요청별 타임아웃이 호출자를 풀어 줍니다. 로드 실패는 시작 시 치명적이므로, 이미지 경로를 요청한 명령줄이 해당 경로에 501로 응답하는 일은 없습니다. 디퓨전 실행은 수 초 동안 GPU를 점유하므로 요청은 한 번에 하나씩 실행됩니다. 큐가 가득 차면 503으로, 타임아웃이면 504로 응답합니다.
이미지 전용 모드¶
-m 없이 실행하면 이미지 체크포인트가 사이드 모델이 아니라 서빙 모델이 됩니다.
mlxcel-server --image-model <image checkpoint> --port 8080
mlxcel serve --image-model <image checkpoint>
서빙 id는 --alias 첫 항목이 있고 그 값을, 없으면 체크포인트 디렉터리 이름을 씁니다. /v1/models는 그 id를 image 기능만 붙여 보고하고 completion은 붙이지 않습니다. /health는 이미지 작업자를 따릅니다. 채팅과 토크나이저 경로, 즉 /tokenize, /detokenize, /apply-template은 --image-model과 no -m을 안내하는 구조화된 501로 응답합니다. 이미지 전용 모드는 --models-dir, --models-preset, --webui, --embedding-model, --reranker-model, --embeddings, --reranking과 함께 쓸 수 없고, 함께 지정하면 두 플래그를 모두 지목하며 시작에 실패합니다. -m도 함께 주면 위의 두 모델 동작이 유지됩니다.
| 메서드 | 경로 | 비고 |
|---|---|---|
| POST | /v1/images/generations | 별칭 /images/generations. |
| POST | /v1/images/edits | 별칭 /images/edits. JSON 본문만 지원합니다. |
--image-model이 없으면 두 경로 모두 해당 플래그를 안내하는 501로 응답합니다. 패밀리가 실행 전에 거부하는 요청은 400이고, 모델이 실행 중에 던지는 InvalidImageRequest도 400입니다. 생성 중의 다른 모든 실패는 500입니다.
요청¶
generations는 prompt, model, n(1~10), size(WxH) 또는 width와 height, steps, seed, guidance, negative_prompt, response_format, output_format을 받습니다. edits는 여기에 image를 추가하며, 문자열 하나 또는 목록입니다. 그 밖의 필드는 extra로 모델에 전달됩니다.
width와height는 함께 지정하거나 함께 생략해야 하며,size보다 우선합니다.size의 기본값은 생성 시512x512이고, 편집 시에는 첫 번째 참조 이미지의 크기 또는 패밀리가 그로부터 유도한 크기입니다.- 가로와 세로는 패밀리의 그리드의 배수여야 하며, 오류 메시지가 그 배수를 알려 줍니다.
response_format은b64_json만 받습니다.url과path는400입니다.output_format은png만 받습니다. 서버는 클라이언트를 대신해 파일을 절대 쓰지 않으므로output_path와output_dir은400입니다.model은 비어 있지 않으면 제공 중인 모델 ID와 같아야 합니다.- 각
image는 데이터 URL 또는 URL이며, 채팅 이미지와 같은 제한을 거쳐 읽습니다.file://URL은--media-path안에 있어야 합니다. 원시 파일 시스템 경로는400입니다. 멀티파트 업로드는 지원하지 않습니다.
응답¶
{
"created": 1790000000,
"data": [
{"b64_json": "iVBORw0KGgo...", "mime_type": "image/png",
"width": 512, "height": 512, "seed": 7, "revised_prompt": null}
],
"output_format": "png",
"size": "512x512"
}
RGB와 RGBA 이미지는 모두 그대로 인코딩되므로 RGBA 결과는 알파 채널을 유지합니다. revised_prompt는 항상 존재하며, 모델이 프롬프트를 재작성하지 않았다면 null입니다.