InstanceAssemble：开源布局感知图像生成框架，精准匹配稀疏/密集布局约束

1. InstanceAssemble是什么

InstanceAssemble是一款面向布局到图像（Layout-to-Image）生成的开源轻量级框架，对应NeurIPS 2025收录的论文《InstanceAssemble: Layout-Aware Image Generation via Instance Assembling Attention》的官方实现。该项目聚焦解决传统图像生成技术中“空间布局控制不精准”的核心痛点——无论是稀疏布局（少量目标物体）还是密集布局（多目标物体重叠/紧邻），传统方法常出现物体位置偏移、类别混淆、语义不符等问题，而InstanceAssemble通过创新的注意力机制设计，实现了对输入布局的精准匹配，同时保持生成图像的视觉质量。

InstanceAssemble并非从零构建新的扩散模型，而是基于工业界和学术界主流的SD3、Flux扩散模型进行轻量化拓展，兼顾“高精度控制”和“易用性”。此外，项目团队还针对性提出了DenseLayout密集布局数据集和Layout Grounding Score（LGS）评估指标，填补了密集布局场景下图像生成评估的空白，形成“生成模型+数据集+评估体系”的完整解决方案。

2. 功能特色

InstanceAssemble的核心优势体现在布局匹配精度、模型兼容性、评估完备性等方面，其核心功能特色如表1所示：

表1：InstanceAssemble核心功能特色

2.1 核心特色补充说明

• 稀疏/密集布局通吃：传统方法在密集布局（如客厅场景，包含沙发、茶几、电视、绿植等多个紧邻物体）下易出现物体重叠、位置偏移，InstanceAssemble通过“实例级注意力分配”，为每个目标物体独立计算注意力权重，确保空间约束精准落地；

• 无侵入式模型拓展：无需修改SD3/Flux的核心代码，仅通过插件式集成Instance Assembling Attention模块，即可实现布局控制能力，降低二次开发成本；

• 可量化的评估能力：LGS指标替代传统“人工主观评分”，从“位置匹配度”“类别准确率”“语义一致性”三个维度给出客观分数，便于算法迭代和横向对比。

3. 技术细节

3.1 核心机制：Instance Assembling Attention

Layout-to-Image生成的核心挑战是“将文本/布局的空间约束映射到图像生成的注意力机制中”。传统扩散模型的自注意力机制仅关注全局语义，缺乏对“实例级空间位置”的精准控制，InstanceAssemble提出的Instance Assembling Attention（IAA）机制解决了这一问题：

IAA将输入布局拆解为“多个实例单元”（每个单元包含：bbox目标框、category类别、caption实例描述），并执行以下三步操作：

1. 实例编码：对每个实例单元的位置（bbox坐标归一化）、类别、描述进行独立编码，生成实例特征向量；

2. 注意力分配：在扩散模型的注意力层中，为每个实例特征向量分配独立的注意力权重，确保注意力聚焦于对应空间区域；

3. 实例组装：将所有实例的注意力结果与全局语义注意力融合，生成同时满足“全局语义”和“局部实例空间约束”的特征图。

该机制的核心创新在于“实例级解耦+空间约束嵌入”，既保留了扩散模型的高质量图像生成能力，又实现了对布局的精准控制。

3.2 模型架构

InstanceAssemble的架构基于SD3/Flux进行拓展，整体分为三层：

• 输入层：解析JSON格式的布局文件，提取prompt（全局描述）、image_size（图像尺寸）、bbox（目标框）、category_name（实例类别）、caption（实例描述）；

• 中间层：集成IAA模块，对SD3/Flux的注意力层进行增强，将实例级空间约束嵌入特征计算过程；

• 输出层：生成符合布局约束的图像，并支持导出LGS评估所需的中间结果（如实例位置掩码）。

3.3 数据集与评估指标

为解决Layout-to-Image领域“密集布局数据集缺失”和“评估指标不统一”的问题，项目配套推出以下资源：

• DenseLayout数据集：包含10000+张密集布局场景（客厅、厨房、街道、办公室等）的标注数据，每个场景包含5-15个实例物体，标注信息包括bbox、类别、实例描述，填补了密集布局数据集的空白；

• LGS评估指标：该指标从三个维度量化生成图像与输入布局的匹配度，具体维度如表2所示：

表2：LGS评估指标维度说明

LGS总分 = L×0.4 + G×0.3 + S×0.3，分值越高表示匹配度越好（满分1分）。

4. 应用场景

4.1 电商商品图像生成

电商平台商家可通过输入“商品布局”（如服装模特+配饰的位置、家电组合的摆放方式），快速生成符合平台规范的商品详情图，无需专业摄影和修图。例如：输入“左侧冰箱（宽300px，高600px）+右侧微波炉（宽200px，高300px）”的布局，生成厨房场景下的家电组合图，且物体位置、尺寸精准匹配。

4.2 虚拟场景搭建

游戏、元宇宙、虚拟现实（VR）领域可利用InstanceAssemble快速生成场景原型：输入“客厅场景布局（沙发100,300,500,400、茶几200,400,400,450、电视500,200,700,300）”，生成符合布局的客厅渲染图，大幅降低场景设计的时间成本。

4.3 视觉内容创作

广告设计、插画创作、影视分镜等领域，设计师可通过布局文件定义画面元素的位置和内容，快速生成初稿。例如：广告设计中，输入“左上角品牌logo+中间产品主体+右下角促销文案”的布局，生成符合视觉设计规范的广告图，提升创作效率。

4.4 学术研究与基准测试

Layout-to-Image领域的研究者可利用InstanceAssemble的DenseLayout数据集和LGS指标，开展算法对比实验：通过将自研模型与InstanceAssemble在同一数据集上测试LGS分数，客观评估算法的布局控制能力，推动领域技术迭代。

5. 使用方法

InstanceAssemble的使用流程分为“环境配置→权重下载→推理/演示→基准测试”四步，操作简单，兼容Windows/Linux/macOS系统（需NVIDIA GPU支持CUDA）。

5.1 环境配置

步骤1：克隆仓库

git clone https://github.com/FireRedTeam/InstanceAssemble
cd InstanceAssemble

步骤2：创建并激活conda环境

conda create -n instanceassemble python=3.10 -y
conda activate instanceassemble

步骤3：安装依赖

首先安装PyTorch（适配CUDA 12.1，其他版本可调整）：

pip install torch==2.3.0 torchvision==0.18.0 --index-url https://download.pytorch.org/whl/cu121

然后安装项目依赖：

pip install -r requirements.txt

5.2 预训练权重下载

InstanceAssemble的预训练权重托管在Hugging Face，需下载至./pretrained目录：

huggingface-cli download FireRedTeam/InstanceAssemble --local-dir ./pretrained

若下载速度慢，可手动从Hugging Face仓库下载后解压至该目录。

5.3 核心使用方式

方式1：命令行推理（生成单张图像）

支持SD3、Flux（fluxdev/fluxschnell）两种模型类型，输入为JSON格式的布局文件（项目demo目录下有示例）：

# 使用SD3模型生成
python inference.py --model_type sd3 --input_json ./demo/bigchair.json

# 使用Flux-dev模型生成
python inference.py --model_type fluxdev --input_json ./demo/cabin_in_trees.json

生成的图像会保存至./output目录，默认分辨率为1024×1024（可在JSON文件中修改image_size字段调整）。

方式2：交互式演示（可视化操作）

通过Streamlit搭建的可视化界面，可手动调整布局、修改prompt，实时生成图像：

streamlit run demo.py

运行后会自动打开浏览器页面，界面包含“布局编辑区”“模型选择区”“生成结果展示区”，无需编写代码即可完成操作。

5.4 基准测试（批量生成+LGS评分）

步骤1：批量生成DenseLayout数据集图像

python benchmark/generate_denselayout.py --model_type fluxdev --outdir ./output/fluxdev

步骤2：计算LGS分数（需先安装GroundingDINO）

# 安装GroundingDINO依赖
pip install git+https://github.com/IDEA-Research/GroundingDINO.git
# 计算LGS分数
python benchmark/score_LGS.py --imgdir ./output/fluxdev

运行完成后会生成lgs_score.csv文件，包含每张图像的L、G、S维度分数及总分。

5.5 布局JSON文件格式说明

示例（demo/bigchair.json）：

{
 "prompt": "a big red chair in a white room, minimalist style",
 "image_size": [1024, 1024],
 "bbox": [[200, 200, 800, 800]],
 "category_name": ["chair"],
 "caption": ["a big red chair"]
}

• prompt：全局图像描述；

• image_size：[宽, 高]，单位像素；

• bbox：目标框列表，每个框为[左上x, 左上y, 右下x, 右下y]；

• category_name：实例类别列表，与bbox一一对应；

• caption：实例描述列表，与bbox一一对应。

6. 常见问题解答

Q1：权重下载失败/速度极慢怎么办？

A1：可通过以下方式解决：

1. 手动访问Hugging Face仓库（https://huggingface.co/FireRedTeam/InstanceAssemble），下载权重文件后解压至`./pretrained`；

2. 使用国内镜像源（如阿里云、腾讯云的Hugging Face镜像）；

3. 检查网络环境，确保可访问Hugging Face（或配置代理）。

Q2：推理时提示“显存不足”（CUDA out of memory）？

A2：解决方案：

1. 降低图像分辨率（将image_size改为512×512）；

2. 使用Flux-schnell模型（轻量化变体）替代fluxdev；

3. 启用梯度检查点（修改inference.py中enable_gradient_checkpointing=True）；

4. 在命令行添加--low_vram参数（适配低显存GPU）。

Q3：运行score_LGS.py时提示“GroundingDINO模型未找到”？

A3：需手动下载GroundingDINO的预训练权重：

mkdir -p ./pretrained/groundingdino
wget -O ./pretrained/groundingdino/GroundingDINO_SwinT_OGC.pth https://github.com/IDEA-Research/GroundingDINO/releases/download/v0.1.0-alpha/GroundingDINO_SwinT_OGC.pth

并修改score_LGS.py中GROUNDING_DINO_WEIGHT路径为该文件路径。

Q4：生成的图像中实例位置偏移？

A4：检查以下点：

1. bbox坐标是否为[左上x, 左上y, 右下x, 右下y]格式（非归一化，单位为像素）；

2. 实例数量是否与bbox、category_name、caption列表长度一致；

3. 更换Flux模型（相比SD3，Flux在布局控制上精度更高）。

Q5：如何自定义布局文件？

A5：参考demo目录下的JSON文件，确保：

1. 所有列表（bbox、category_name、caption）长度一致；

2. bbox坐标不超出image_size范围；

3. 实例描述（caption）与类别（category_name）语义一致。

7. 相关链接

8. 总结

InstanceAssemble作为NeurIPS 2025收录的开源布局感知图像生成框架，以创新的Instance Assembling Attention机制为核心，适配SD3、Flux等主流扩散模型，实现了稀疏和密集布局下的高精度图像生成，同时配套DenseLayout数据集和LGS评估指标形成完整解决方案；该项目兼顾易用性与轻量化，支持命令行推理和交互式演示，无需复杂开发即可快速部署，可广泛应用于电商、虚拟场景、内容创作、学术研究等领域，既解决了传统Layout-to-Image生成的空间控制痛点，又降低了行业落地的技术门槛，是布局感知图像生成领域兼具学术价值和实用价值的优质开源项目。