MOSS-Image 推理实战指南：从安装到 5B DiT 文字渲染与 Layout 布局控制

本文基于 MOSS-Image 官方仓库的中文 README 展开，系统讲解 MOSS-Image-Base / MOSS-Image-SFT 两个模型的安装、Python 与 Gradio 推理、采样参数推荐、显存模式选择，以及该模型最具特色的 JSON Layout 布局控制和提示词增强 Skill 的完整用法。读完本文，你可以独立完成一次可复现的 MOSS-Image 图像生成，并掌握用绝对像素坐标控制文字与物体位置、用官方脚本编译 Layout 提示词的全部细节。

模型家族：MOSS-Image-Base 与 MOSS-Image-SFT

MOSS-Image 是一个 5B 参数主干的 DiT（Diffusion Transformer）文生图模型，官方强调其核心能力包括：

• 布局控制：通过 JSON Layout 输入控制文字与视觉元素的位置；
• 文字渲染：在图像中生成清晰、准确的文字；
• 长提示词支持：支持最长 4K tokens 的文本提示词；
• 多样视觉风格：生成高质量的动漫风格与照片级写实图像；
• 易于微调：基础模型可适配自定义任务和领域；
• 紧凑高效：基于 5B 主干网络实现高效图像生成；
• 异构 GPU 训练：采用替代 GPU 平台训练。

仓库提供两个权重：

官方给出的对比示例中，SFT 版本的文字分组更清晰，白板内容的排版更有条理。左侧为 Base 输出（assets/comparison/base.webp），右侧为 SFT 输出：

注意：Base 是一个未经后训练蒸馏的纯基础模型（未做 CFG 蒸馏等），因此需要配合合适的推理参数才能发挥最佳效果，推荐参数见后文 采样参数建议。

快速开始

安装

git clone https://gitcode.com/gh_mirrors/mo/MOSS-Image cd MOSS-Image python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

requirements.txt 只包含一行-e .，实际依赖由 pyproject.toml 定义：要求 Python ≥ 3.10，核心依赖为torch>=2.9、diffusers>=0.38、transformers>=5.3、accelerate>=1.10、safetensors>=0.6、Pillow>=10。Gradio 界面是可选依赖ui（gradio>=6.30）。

Python 推理

官方推荐的调用方式是 Diffusers 的DiffusionPipeline+ 远端 pipeline 代码pipeline_moss_image：

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") image = pipe( "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顺便带一袋面包。”", 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")

各参数要点：

• torch_dtype={"default": torch.bfloat16, "vae": torch.float32}：DiT 主权重用 bfloat16，VAE 保持 float32 以保证解码精度，这是仓库 inference_runtime.py 中load_pipeline的固定加载策略；
• num_inference_steps=50、guidance_scale=3.0：对应官方推荐默认值；
• uncond_skip_layers=[22]：Skip Layer Guidance（SLG）的"负向分支跳层"，在负向分支中跳过第 22 层（0-indexed），官方认为 22、24、26 层对改善质量均有帮助；
• height/width必须是 16 的正整数倍（gradio_app.py 的validate中会做height % 16检查，Python API 直接传入非法尺寸会报错）；
• 中英文混排、带\n换行的手写体提示词，体现了该模型对文字渲染的支持。

仓库还提供了带完整命令行参数的入口脚本 scripts/gradio.sh，它等价于执行python gradio_app.py "$@"。

Gradio Web 界面

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

gradio_app.py 的main支持以下命令行参数：

界面细节（从源码结构看）：

• 生成参数由 GenerationConfig 数据类集中管理：steps=50、cfg=3.0、shift=5.0、seed=42、max_sequence_length=4096、uncond_skip_layers="22"；
• Prompt 输入框预填来自 assets/prompt_defaults.txt 的[prompt_prefix]段（best quality, masterpiece），Negative Prompt 预填[negative_prompt]段（nsfw, worst quality, bad anatomy, watermark, jpeg artifact）；
• 分辨率与长宽比滑块会自动对齐到 16 的倍数，像素预算档位为 gradio_presets.py 中的262144 / 1048576 / 1572864 / 2097152 / 4194304（即 0.25M～4M），常用比例含 9:16、16:9、1:1 等；
• 高级设置中的 Skip layer mode 支持 Off、Negative-branch skipping（默认，推荐值 22）与 Standard SLG（scale 3、区间 0.01–1.0），与用户指南中的描述一致；
• 每次生成后会在输出目录写入一张图片及parameters.json元数据（含 prompt、全部参数、seed、采样器、环境版本与配置文件的 SHA-256），例如 assets/images/001/parameters.json 就记录了Euler采样器、uncond_skip_layers: "22"等完整可复现信息。

采样参数建议

README 给出的默认采样参数如下：

配套的 中文用户指南 给出了更完整的推荐取值与适用说明：

• 分辨率：推荐 1M、1.5M、2M 总像素输出；模型可外推至 0.25M（512×512）到 4M（2K）的任意分辨率；
• 长宽比：支持任意比例，但宽高必须是 16 的正整数倍；
• 推理步数：≥ 50 步效果最佳；
• CFG：默认 3.0，推荐范围 3.0–6.0；常规长 Prompt 用 3.0 即可，短 Prompt 可适当调高；
• Shift：默认 5.0；
• 采样器：默认推荐 Euler；
• SLG（Skip Layer Guidance）提供两种方式：
  • 标准 SLG：scale 3，区间 0.01–1.0；
  • 二次采样 SLG（推荐）：使用uncond skip，skip layer 推荐 22（0-indexed），22、24、26 均有帮助；
  • 关闭 SLG 会使图像非常真实，但可能引起细节崩坏；
• 负面提示词（经验证有效的 tag）：

nsfw, worst quality, bad anatomy, watermark, jpeg artifact

• Tag 串推荐顺序：Quality → Score → Meta → Year → Character → Series → Artist → General，例如：

best quality, highres, hatsune miku, vocaloid, @foo bar, 1girl, blue hair

• 文字排版：模型支持文字生成与自动换行，但未必完全符合预期；若追求文字正确率或精确控制换行，请在 Prompt 中手动添加\n或直接换行。

用户指南还给出了一条中文实战 Prompt 示例（玻璃板上手写技术路线说明 + 负面提示词worst quality, bad anatomy），以及上文 Python 示例中的冰箱便签英文示例，两者都展示了模型的中英混排文字渲染能力。

显存与性能

Gradio 高级设置中的 Memory mode 对应 inference_runtime.py 的configure_pipeline：

从源码结构看，其自动选择逻辑为：offload="auto"时，若 CUDA 显存预算 ≥ 40 GiB 则使用 GPU resident，否则回落到 Component 模式（inference_runtime.py 的cuda_budget_gib按get_device_properties与 memory fraction 计算）。显存不足时官方建议选择 Sequential 或减小图像尺寸。

另外两条限制与 README 一致：Compile DiT 默认关闭，且与 Sequential 模式互斥——源码中直接抛出Compilation is incompatible with sequential offload（inference_runtime.py），启用编译时会对 transformer 各层与文本嵌入块做torch.compile(fullgraph=True, dynamic=True)。Gradio 端对torch.cuda.OutOfMemoryError有专门处理：自动卸载模型并提示降低尺寸或换用更低显存模式（gradio_app.py）。

Layout 布局生成

MOSS-Image 通过 JSON layout 输入控制复杂画面中的文字排版与物体布局，官方认为基于 layout 还可以进一步实现受控编辑、用户友好的排版工具等应用——通过修改文字、元素描述和边界框，用户可以结构化地调整画面内容与布局。

使用方式：将布局 JSON 直接粘贴到 Gradio 的 Prompt 输入框（或作为 Python API 的prompt字符串传入，见下），即可指定场景、文字、物体及其位置。官方示例使用summary/items格式，以1024×1024画布为例，将内容保存为layout.json：

{ "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：整体场景与风格描述（meta为媒介/类型标签，canvas取single/multi_panel/collage）；
• items：各元素的label、caption和bbox；需要生成文字时使用text指定内容，label取值为object、character或text；
• bbox_format: "yxyx"：框坐标顺序为[y_min, x_min, y_max, x_max]；
• bbox_coord_space: "abs_centralized"：以画布中心为原点的像素坐标。对于 1024×1024 画布，两轴范围均为 −512 到 +512，x 向右、y 向下递增。对于宽 W、高 H 的画布，将常规左上角原点的 x 坐标减去 W/2、y 坐标减去 H/2 即可转换。

使用注意：

1. 框坐标必须与指定输出尺寸一致。在 Gradio 中粘贴 JSON 后需设置对应的宽高；
2. Python API 传入方式：将json.dumps(layout, ensure_ascii=False)作为提示词字符串传入；
3. 用户指南特别说明：官方选择绝对像素坐标而非相对坐标做布局控制，认为这种表示更适合不同分辨率和长宽比下的布局；模型支持自然语言和结构化语言的混合输入。

用官方 Skill 自动编译 Layout

手算中心化坐标容易出错。仓库随附的 Prompt Enhancer Skill 提供了本地编译脚本 compile_prompt.py，可以把"人类友好的草稿"自动转换为模型输入格式：

python3 skills/moss-image-prompt-enhancer/scripts/compile_prompt.py draft.json --output prompt.txt

从 compile_prompt.py 的源码看，其工作方式是：

• 草稿使用左上角原点、绝对像素坐标（bbox_coord_space="abs"、bbox_format="xyxy"），width/height必须为 16 的正整数倍且等于最终生成尺寸；
• 编译器对分数像素边做"左/下取整、右/上取整"后再减去W/2、H/2，输出单行紧凑 JSON，坐标空间自动改为abs_centralized、格式改为yxyx；
• 对未知字段、越界框、非正宽高、text项缺少text字段等情况直接报错退出，而不是静默裁剪或丢弃；
• 草稿还支持纯 caption 模式（仅含{"caption": "..."}），输出即为纯文本提示词。

references/layout.md 中给出了一个 1536×1024 横版产品图的完整草稿示例：一个陶瓷杯物体项与两条中文文字项（含\n换行），其中杯子的草稿框[176, 224, 800, 864]经转换后得到[-288, -592, 352, 32]，与上文的手动换算规则完全一致。

将 skill 目录安装到代理的技能目录后，使用$moss-image-prompt-enhancer提供图像需求、caption 或 Layout 输出要求及画布尺寸，把编译结果粘贴到 MOSS-Image 的正向提示词中；使用 Layout 时，生成尺寸应与草稿一致。该 Skill 只做文字/坐标编译，不调用任何图像生成服务。

ComfyUI 原生插件

仓库内置 MOSS-Image 的 ComfyUI 原生插件（comfyui/README_ZH.md），插件可直接读取本地 Hugging Face / Diffusers 模型目录，输出标准 MODEL、CLIP、VAE，配合 ComfyUI 原生采样、SLG 与显存管理使用。三种安装方式：

1. 在ComfyUI Manager中搜索MOSS-Image安装；
2. 手动复制：将comfyui/moss-image/复制到ComfyUI/custom_nodes/moss-image/，重启 ComfyUI；或在仓库根目录执行python comfyui/install.py --comfy-root /path/to/ComfyUI建立链接；
3. 本地一键环境：

bash comfyui/local/setup.sh bash comfyui/local/run.sh

comfyui/local/setup.sh 会在目录不存在时克隆一个独立的 ComfyUI 到 Git 忽略的local/ComfyUI/，创建独立环境并安装依赖与节点，不覆盖已有同名文件；MOSS_PYTHON指定解释器，UV_INDEX_URL指定依赖源，COMFYUI_ROOT可指向已有 ComfyUI 安装。

工作流使用步骤：

1. 下载 moss-image.json 拖入 ComfyUI（另有 API 格式 JSON 供程序提交）；
2. 下载 MOSS-Image-Base 权重，在MOSS-Image HF Loader的model_path中填写本地模型目录（应包含transformer/、text_encoder/、tokenizer/、vae/）；
3. 修改正负向提示词后点击Run。

示例工作流已配置50 步、CFG 3、Shift 5、负向跳过第 22 层，使用 Euler / sgm_uniform 采样，分辨率 1024×1024。从 comfyui/moss-image/nodes.py 可见节点实现了MOSSImageUNETLoader、MOSSImageCLIPLoader（加载 Qwen3.5 文本编码器）、MOSSImageHFDiTLoader等，weight_dtype控制 DiT 精度、text_device控制文本编码设备，VAE 固定 FP32，文本编码最长 4096 tokens。

README 还提示了一个兼容性细节：ComfyUI 的 SLG 区间采用 sigma 百分比语义，其原生 scheduler 不包含独立 pipeline 的训练网格吸附，因此即使 seed 和参数相同，也不保证与 Python API 生成完全相同的图片。

引用与许可

如果你在研究中使用 MOSS-Image，官方建议引用：

@misc{mossimage2026, title = {MOSS-Image}, author = {{OpenMOSS Team}}, year = {2026}, howpublished = {\url{https://github.com/OpenMOSS/MOSS-Image}} }

推理代码采用 Apache License 2.0，官方感谢 Diffusers、Qwen 和 FLUX 团队。技术报告 PDF 位于 paper/MOSS_Image_Technical_Report.pdf。

小结

MOSS-Image 的实用主线可以概括为：用pipeline_moss_image加载 5B DiT（bf16 + FP32 VAE），按「50 步 / CFG 3 / Shift 5 / 跳第 22 层」的推荐参数出图；显存紧张时切换 Component 或 Sequential 模式；需要精确排版时把summary+items的 JSON Layout 作为提示词传入，并用绝对中心像素坐标描述文字与物体的位置；复杂草稿可借助 skills/moss-image-prompt-enhancer 的编译脚本完成坐标换算。配合 Gradio 界面、ComfyUI 插件与每次生成落盘的parameters.json元数据，整套流程在可复现性上形成了闭环。