AI 튜토리얼

MOSS-Image로 텍스트가 풍부한 이미지와 정밀한 레이아웃 생성

이 튜토리얼에서는 MOSS-Image 설정 방법, Base 및 SFT 모델 선택 방법, Python 또는 Gradio를 통한 이미지 생성 방법, 구조화된 레이아웃 프롬프트로 텍스트와 객체의 위치를 지정하는 방법을 설명합니다. 또한 권장 샘플링 설정, 메모리 모드, ComfyUI 지원, 프롬프트 개선 도구도 다룹니다.

2026년 10월 16일약 15분 소요

MOSS-Image란?

MOSS-Image는 OpenMOSS Team이 개발한 오픈 이미지 생성 프로젝트입니다. 기본 텍스트-이미지 모델과 지도 미세 조정 모델을 제공하며, 사용자 지정 Diffusers 파이프라인, Gradio 인터페이스, 네이티브 ComfyUI 플러그인, 상세한 프롬프트를 준비하기 위한 도구도 함께 제공합니다.

이 프로젝트는 시각적 요소와 읽을 수 있는 텍스트를 결합한 구성을 위해 설계되었습니다. 최대 4K 토큰의 프롬프트를 지원하며, 애니메이션 스타일에서 사실적인 이미지까지 다양한 스타일을 생성할 수 있습니다. 5B 백본은 비교적 작고 효율적인 이미지 생성을 목표로 합니다.

주요 기능

레이아웃 제어: 구조화된 JSON 입력과 바운딩 박스를 사용해 텍스트와 시각적 요소를 배치합니다.
텍스트 렌더링: 포스터, 메모, 화이트보드 및 기타 이미지 구성 안에 선명한 텍스트를 생성합니다.
긴 프롬프트: 최대 4K 토큰으로 구성된 텍스트 프롬프트를 입력합니다.
다양한 스타일: 애니메이션 스타일과 사실적인 이미지를 생성합니다.
미세 조정 지원: 기본 모델을 사용자 지정 작업과 도메인에 맞게 조정합니다.
효율적인 아키텍처: 5B 백본으로 이미지를 생성합니다.
다양한 인터페이스: Python, Gradio, ComfyUI 또는 별도의 프롬프트 개선 스킬을 사용할 수 있습니다.

모델 선택

MOSS-Image는 두 가지 변형으로 제공됩니다.

MOSS-Image-Base: 기본 텍스트-이미지 모델입니다. 가중치는 Hugging Face와 ModelScope에서 제공됩니다.
MOSS-Image-SFT: 엄선된 데이터로 기본 모델을 미세 조정한 버전입니다. 가중치는 Hugging Face와 ModelScope에서 제공됩니다.

프로젝트에서 제공한 비교 결과에 따르면 SFT 모델은 더 명확한 텍스트 그룹화와 더 정돈된 화이트보드 레이아웃을 생성합니다. 원래의 범용 체크포인트가 필요하거나 미세 조정할 계획이라면 Base 모델로 시작하세요. 구조화된 텍스트 표현이 특히 중요하다면 SFT를 고려하세요.

MOSS-Image 설치

저장소를 복제하고 해당 디렉터리로 이동한 다음, 가상 환경을 생성하고 활성화한 후 요구 사항을 설치합니다.

git clone https://github.com/OpenMOSS/MOSS-Image.git
cd MOSS-Image
python -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

예제에서는 CUDA를 사용하며 pipe.to("cuda")를 통해 파이프라인을 GPU로 이동합니다. 추론을 실행하려는 GPU 플랫폼에 맞게 PyTorch 환경이 구성되어 있는지 확인하세요.

Python으로 이미지 생성

MOSS-Image는 사용자 지정 파이프라인을 사용해 Diffusers를 통해 로드됩니다. 다음 예제는 손글씨 중국어 메모가 있는 주방 장면을 생성하도록 모델에 요청합니다.

import torch
from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained(
    "OpenMOSS-Team/MOSS-Image-Base",
    custom_pipeline="pipeline_moss_image",
    trust_remote_code=True,
    torch_dtype={"default": torch.bfloat16, "vae": torch.float32},
)
pipe.scheduler = type(pipe.scheduler).from_config(pipe.scheduler.config)
pipe.to("cuda")

prompt = (
    "A wide view of a refrigerator beside a kitchen counter with a fruit bowl. "
    "A small sticky note on the refrigerator door is handwritten in Chinese:“\n"
    "记得买牛奶和鸡蛋！\n牛奶两盒，鸡蛋一打。\n顺便带一袋面包。”"
)

image = pipe(
    prompt,
    height=1456,
    width=1456,
    num_inference_steps=50,
    guidance_scale=3.0,
    uncond_skip_layers=[22],
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]

image.save("refrigerator_note.png")

주요 인자 이해하기

custom_pipeline="pipeline_moss_image"은 MOSS-Image 파이프라인을 선택합니다.
trust_remote_code=True는 Diffusers가 모델의 사용자 지정 파이프라인 구현을 로드하도록 허용합니다.
torch_dtype는 기본적으로 bfloat16을 사용하고 VAE에는 float32를 유지합니다.
height와 width는 출력 크기를 결정합니다.
num_inference_steps=50은 프로젝트의 기본 샘플링 권장값을 따릅니다.
guidance_scale=3.0은 권장 classifier-free guidance 값을 적용합니다.
uncond_skip_layers=[22]는 22번째 레이어에서 네거티브 분기의 레이어 건너뛰기를 활성화합니다.
manual_seed(42)는 동일한 구성으로 반복 실행할 때 재현성을 높입니다.

Gradio 인터페이스 실행

선택적 사용자 인터페이스 의존성을 설치하고 포함된 애플리케이션을 실행합니다.

pip install -e '.[ui]'
python gradio_app.py --model OpenMOSS-Team/MOSS-Image-Base

Gradio가 표시한 로컬 주소를 열고, 긍정 프롬프트를 입력한 다음 이미지 크기를 선택하고 생성을 시작하세요. 대신 미세 조정된 체크포인트를 테스트하려면 모델 인자를 OpenMOSS-Team/MOSS-Image-SFT로 바꾸세요.

권장 샘플링 설정

샘플러: Flow-matching Euler
스텝: 50
CFG: 3
Shift: 5
레이어 건너뛰기: 22번째 레이어에서 네거티브 분기 건너뛰기
Python API 네거티브 프롬프트: 비어 있음

이는 프로젝트에 문서화된 기본값으로, 실용적인 시작점으로 활용할 수 있습니다. 추가 프롬프트 및 샘플링 권장 사항은 저장소의 영문 사용자 가이드를 참조하세요.

JSON 레이아웃으로 구성 제어

일반적인 프롬프트는 이미지에 무엇이 포함되어야 하는지 설명하지만 각 요소가 어디에 배치되는지는 정확히 정의하지 않습니다. 대신 MOSS-Image는 전체 장면, 개별 텍스트 또는 객체 요소, 그리고 해당 요소의 바운딩 박스를 설명하는 JSON 레이아웃을 입력으로 받을 수 있습니다.

다음 레이아웃은 미니멀한 1024 x 1024 여행 포스터를 설명합니다. Python에서 불러오려면 layout.json으로 저장하거나, Gradio의 Prompt 필드에 직접 붙여 넣으세요.

{
  "summary": {
    "meta": ["poster"],
    "canvas": "single",
    "caption": "크림색 배경, 파란 산 일러스트, 상단의 EXPLORE 제목으로 구성된 미니멀한 여행 포스터."
  },
  "items": [
    {
      "label": "text",
      "caption": "상단 중앙에 배치된 크고 진한 파란색 대문자 제목.",
      "text": "EXPLORE",
      "bbox": [-416, -384, -288, 384]
    },
    {
      "label": "object",
      "caption": "하단 중앙에 배치된 평면적인 파란색 산 일러스트.",
      "bbox": [-192, -288, 384, 288]
    }
  ],
  "bbox_coord_space": "abs_centralized",
  "bbox_format": "yxyx"
}

레이아웃 형식의 작동 방식

summary.caption은 전체 장면과 시각적 스타일을 설명합니다.
items에는 독립적으로 배치되는 텍스트 및 객체 요소가 포함됩니다.
label은 항목이 텍스트인지 객체인지 식별합니다.
caption은 항목의 외관과 역할을 설명합니다.
text에는 텍스트 항목에 표시할 정확한 문구가 들어갑니다.
bbox는 요소의 위치와 범위를 정의합니다.
bbox_format: "yxyx"는 각 박스가 [y_min, x_min, y_max, x_max] 순서임을 의미합니다.
bbox_coord_space: "abs_centralized"는 캔버스 중심을 기준으로 좌표를 측정한다는 의미입니다.

1024 x 1024 캔버스에서 두 축의 범위는 -512부터 +512까지입니다. x 좌표는 오른쪽으로 갈수록 증가하고, y 좌표는 아래쪽으로 갈수록 증가합니다. 일반적인 캔버스 좌표로 변환하려면 x 값에서 캔버스 너비의 절반을 빼고, y 값에서 캔버스 높이의 절반을 빼세요.

항상 레이아웃을 준비한 크기와 일치하는 생성 크기를 사용하세요. 크기가 일치하지 않으면 좌표계가 변경되어 요소가 의도한 위치에서 벗어날 수 있습니다.

Python으로 레이아웃 제출

JSON 파일을 불러와 문자열로 직렬화한 다음 해당 문자열을 파이프라인 프롬프트로 전달하세요.

import json
import torch

with open("layout.json", "r", encoding="utf-8") as file:
    layout = json.load(file)

layout_prompt = json.dumps(layout, ensure_ascii=False)

image = pipe(
    layout_prompt,
    height=1024,
    width=1024,
    num_inference_steps=50,
    guidance_scale=3.0,
    uncond_skip_layers=[22],
    generator=torch.Generator("cpu").manual_seed(42),
).images[0]

image.save("travel_poster.png")

전체 프롬프트를 다시 작성하지 않고도 구성을 수정할 수 있습니다. 항목의 텍스트, 캡션 또는 바운딩 박스를 편집한 뒤 이미지를 다시 생성하세요. README에서는 이 구조화된 접근 방식이 제어된 편집과 사용자 친화적인 레이아웃 도구도 지원할 수 있다고 설명합니다.

GPU 메모리 관리

Gradio 인터페이스의 Advanced 설정에는 세 가지 메모리 모드가 제공됩니다.

GPU resident: 전체 모델을 GPU에 유지하여 직접 액세스합니다.
Component: 필요에 따라 모델 구성 요소를 CPU와 GPU 사이에서 이동합니다.
Sequential fallback: 추론 속도를 낮추는 대신 메모리 사용량을 줄입니다.

사용 가능한 GPU 메모리에 모델이 들어가지 않으면 Sequential 모드를 선택하거나 출력 이미지 크기를 줄이세요. DiT 컴파일은 기본적으로 비활성화되어 있으며 Sequential 모드에서는 사용할 수 없습니다.

ComfyUI에서 MOSS-Image 사용

저장소에는 ComfyUI용 네이티브 MOSS-Image 플러그인이 포함되어 있습니다. 설치하려면 ComfyUI Manager에서 MOSS-Image를 검색하세요. 프로젝트에서는 시작점으로 가져올 수 있는 예제 워크플로도 제공합니다.

현재 프로젝트는 공식 ComfyUI 저장소에 통합하기 위한 작업을 진행하고 있습니다. 그때까지는 저장소의 ComfyUI 설치 및 사용 지침을 따르세요.

Prompt Enhancer를 활용한 고급 프롬프팅

함께 제공되는 MOSS-Image Prompt Enhancer는 기본적인 이미지 아이디어를 상세한 캡션 또는 공간 레이아웃 프롬프트로 변환합니다. 로컬 파일 및 Python 도구를 사용할 수 있는 GPT-6 계열 에이전트를 위해 설계되었습니다.

skills/moss-image-prompt-enhancer 폴더를 에이전트의 skills 디렉터리에 설치합니다.
이미지 아이디어와 함께 $moss-image-prompt-enhancer를 호출합니다.
상세한 캡션과 Layout 출력 중 원하는 형식을 지정합니다.
레이아웃을 생성할 때 사용할 캔버스 크기를 입력합니다.
컴파일된 출력을 MOSS-Image의 positive prompt에 붙여 넣습니다.
Layout 출력을 사용하는 경우 컴파일 중 사용한 것과 동일한 캔버스 크기로 이미지를 생성합니다.

포함된 스크립트는 픽셀 좌표 초안을 정수 기반의 중심 좌표를 사용하는 간결한 JSON으로 변환합니다. 이 스크립트는 프롬프트만 준비하며 이미지 생성 서비스를 호출하지 않습니다.

실용적인 팁

문서화된 기본값으로 시작하세요: 실험하기 전에 스텝 50, CFG 3, 시프트 5, 레이어 22에서 네거티브 브랜치 건너뛰기를 사용하세요.
요청한 텍스트를 명시적으로 입력하세요: 프롬프트에 정확한 문구를 넣거나 항목의 text 필드에 입력하세요.
복잡한 디자인에는 구조화된 레이아웃을 사용하세요: 포스터, 다이어그램, 텍스트가 많은 장면은 요소와 바운딩 박스를 각각 설명하면 효과적입니다.
크기를 주의 깊게 맞추세요: 레이아웃 좌표는 선택한 캔버스의 너비와 높이에 맞춰집니다.
반복 작업 중에는 시드를 고정하세요: 같은 시드를 유지하면 프롬프트, 모델, 레이아웃 변경 사항을 비교하기 쉽습니다.
메모리가 제한적이면 이미지 크기를 줄이세요: 이는 프로젝트에서 명시적으로 권장하는 해결 방법 중 하나입니다.
Base와 SFT를 비교하세요: 더 명확한 그룹화와 체계적인 텍스트 레이아웃이 중요하다면 SFT 체크포인트가 더 적합할 수 있습니다.

결론

MOSS-Image는 일반적인 텍스트-이미지 생성에 강력한 텍스트 렌더링과 구조화된 구성 제어 기능을 결합합니다. Python 파이프라인이나 Gradio 인터페이스로 시작한 다음, 정확한 배치가 중요할 때 JSON 레이아웃으로 전환할 수 있습니다. ComfyUI 통합, 메모리 모드, 프롬프트 강화 기능을 통해 모델을 시각적 워크플로에 맞게 활용하는 방법을 확장할 수 있습니다. 독립 실행형 파이프라인 코드는 Apache License 2.0에 따라 제공됩니다.