使用 MOSS-Image 生成富文本图像并控制布局

什么是 MOSS-Image？

MOSS-Image 是 OpenMOSS 团队推出的开源图像生成项目。它提供基础文生图模型和监督微调模型，以及自定义 Diffusers 管线、Gradio 界面、原生 ComfyUI 插件和用于准备详细提示词的工具。

该项目专为将视觉元素与可读文本结合的构图而设计。它支持最多 4K token 的提示词，并能生成从动漫到写实的多种风格图像。其 5B 主干网络旨在实现相对紧凑、高效的图像生成。

主要功能

• 布局控制：使用结构化 JSON 输入和边界框放置文本及视觉元素。
• 文本渲染：在海报、便签、白板和其他图像构图中生成清晰文本。
• 长提示词：提交包含最多 4K token 的文本提示词。
• 多种风格：创建动漫风格和写实图像。
• 微调支持：将基础模型适配到自定义任务和领域。
• 高效架构：使用 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。请确保 PyTorch 环境已针对计划运行推理的 GPU 平台完成配置。

使用 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 使用推荐的无分类器引导值。
• 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。

推荐采样设置

• 采样器：流匹配 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": "A minimalist travel poster with a cream background, a blue mountain illustration, and the title EXPLORE at the top."
  },
  "items": [
    {
      "label": "text",
      "caption": "Large dark-blue uppercase title centered at the top.",
      "text": "EXPLORE",
      "bbox": [-416, -384, -288, 384]
    },
    {
      "label": "object",
      "caption": "A flat blue mountain illustration in the lower center.",
      "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 界面在高级设置中提供三种内存模式：

• 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 系列代理。

1. 将 skills/moss-image-prompt-enhancer 文件夹安装到代理的 skills 目录中。
2. 使用图像构想调用 $moss-image-prompt-enhancer。
3. 指定需要详细说明还是 Layout 输出。
4. 创建布局时提供目标画布尺寸。
5. 将编译后的输出粘贴到 MOSS-Image 的正向提示词中。
6. 对于 Layout 输出，使用编译时采用的相同画布尺寸生成图像。

随附脚本会将像素坐标草稿转换为使用整数中心坐标的紧凑 JSON。它只准备提示词，不会调用图像生成服务。

实用技巧

• 从文档中的默认值开始：先使用 50 步、CFG 3、shift 5，并在第 22 层跳过负分支，然后再进行尝试。
• 明确写出所需文本：将确切措辞放入提示词中，或放入项目的 text 字段。
• 为复杂设计使用结构化布局：海报、图表和文字密集型场景适合分别描述各个元素及其边界框。
• 仔细匹配尺寸：布局坐标与所选画布的宽度和高度相关。
• 迭代时固定种子：保持相同的种子有助于比较提示词、模型和布局的变化。
• 内存有限时缩小图像尺寸：这是项目明确推荐的解决方法之一。
• 比较 Base 和 SFT：如果更清晰的分组和更有条理的文字布局是优先事项，SFT 检查点可能更合适。

结语

MOSS-Image 将通用文本到图像生成、强大的文字渲染能力和结构化构图控制结合起来。你可以从 Python 流水线或 Gradio 界面开始，然后在需要精确定位时转向 JSON 布局。ComfyUI 集成、内存模式和提示词增强技能提供了更多方式，可将该模型融入视觉工作流。独立的流水线代码采用 Apache License 2.0 许可。