从少到多的泛化：通过上下文生成解锁更强的可控性

吴绍进, 黄梦琪^*, 吴文旭, 程宇峰, 丁飞⁺, 何倩
字节跳动智能创作团队

🔥 新闻

• 2025.09.12 🔥 UMO 来了！它能够自由地将一对一的身份与任何场景中的任意主体相结合，输出具有高度主体和身份一致性的结果。你现在可以在这里体验更强大的 UNO 或 OmniGen2 UMO！你也可以访问我们的 项目页面 获取更多示例。🔥

• 2025.08.29 🔥 我们很高兴地分享我们的新开源项目 USO，它可以在任何场景中自由组合任意主体与任意风格，同时确保照片级逼真的效果。你还可以访问我们的 项目页面 或尝试 在线演示 以获取更多示例。🔥

• 2025.08.18 ✨ 我们开源了 UNO-1M 数据集，这是一个大规模高质量的数据集（约100万对图像）。我们希望它能进一步推动相关研究。

• 2025.06.26 🎉 恭喜！UNO 已被 ICCV 2025 接受！
• 2025.04.16 🔥 我们的配套项目 RealCustom 已发布。
• 2025.04.10 🔥 更新 fp8 模式作为主要的低显存使用支持。献给消费级 GPU 用户。目前峰值显存占用约为 16GB。我们可能会在后续尝试进一步的推理优化。
• 2025.04.03 🔥 UNO 的 demo 已发布。
• 2025.04.03 🔥 UNO 的 训练代码、推理代码 和 模型 已发布。
• 2025.04.02 🔥 UNO 的 项目页面 已创建。
• 2025.04.02 🔥 UNO 的 arXiv 论文 已发布。

📖 引言

在本研究中，我们提出了一种高度一致的数据合成流水线来应对这一挑战。该流水线充分利用扩散 Transformer 的内在上下文生成能力，生成高一致性多主体配对数据。此外，我们还推出了 UNO，它由渐进式跨模态对齐和通用旋转位置编码组成。UNO 是一种基于文本到图像模型迭代训练而成的多图像条件下的主体到图像模型。大量实验表明，我们的方法能够在单主体和多主体驱动的生成中实现高度一致性，同时保证可控性。

⚡️ 快速入门

🔧 要求与安装

安装依赖项

# pip install -r requirements.txt # 旧版安装命令

## 创建一个 Python >= 3.10 <= 3.12 的虚拟环境，例如：
# python -m venv uno_env
# source uno_env/bin/activate
# 或者
# conda create -n uno_env python=3.10 -y
# conda activate uno_env
# 然后根据需要安装依赖项

# !!! 如果你使用的是 AMD GPU/NV RTX 50 系列/macos MPS，你需要先自行安装正确的 PyTorch 版本

# !!! 然后运行安装命令
pip install -e .  # 仅用于运行演示或推理的用户
pip install -e .[train]  # 用于同时训练模型的用户

然后可以通过以下三种方式之一下载检查点：

1. 直接运行推理脚本，代码中的 hf_hub_download 函数会自动将检查点下载到你的 $HF_HOME 目录（默认值为 ~/.cache/huggingface）。
2. 使用 huggingface-cli download <repo name> 下载 black-forest-labs/FLUX.1-dev、xlabs-ai/xflux_text_encoders、openai/clip-vit-large-patch14、bytedance-research/UNO，然后运行推理脚本。你可以只下载所需的检查点，以加快设置并节省磁盘空间。例如，对于 black-forest-labs/FLUX.1-dev，可以使用 huggingface-cli download black-forest-labs/FLUX.1-dev flux1-dev.safetensors 和 huggingface-cli download black-forest-labs/FLUX.1-dev ae.safetensors，而忽略 black-forest-labes/FLUX.1-dev 模型仓库中的文本编码器（它们是为 diffusers 调用准备的）。所有检查点总共需要 37 GB 的磁盘空间。
3. 使用 huggingface-cli download <repo name> --local-dir <LOCAL_DIR> 将第 2 种方法中提到的所有检查点下载到你指定的目录。然后设置环境变量 AE、FLUX_DEV（或如果你使用 fp8 模式则设置 FLUX_DEV_FP8）、T5、CLIP、LORA，指向相应的路径。最后运行推理脚本。
4. 如果你已经拥有部分检查点，可以直接设置环境变量 AE、FLUX_DEV、T5、CLIP、LORA，指向对应的路径。最后运行推理脚本。

🌟 Gradio 演示

python app.py

为了降低显存占用，请传递 --offload 和 --name flux-dev-fp8 参数。峰值内存占用约为 16GB。仅供参考，在 RTX 3090 显卡上，使用 fp8 和 offload 模式时，端到端推理时间为 40 秒到 1 分钟。

python app.py --offload --name flux-dev-fp8

✍️ 推理

从下面的示例开始，探索并激发你的创造力。✨

python inference.py --prompt "海滩上的钟被红色太阳伞遮着" --image_paths "assets/clock.png" --width 704 --height 704
python inference.py --prompt "小雕像在水晶球里" --image_paths "assets/figurine.png" "assets/crystal_ball.png" --width 704 --height 704
python inference.py --prompt "杯子上印着标志" --image_paths "assets/cat_cafe.png" "assets/cup.png" --width 704 --height 704

可选准备工作：如果你想第一次在 dreambench 上测试推理，需要克隆子模块 dreambench 来下载数据集。

git submodule update --init

然后运行以下脚本：

# 在 dreambench 上进行推理
## 单主体
python inference.py --eval_json_path ./datasets/dreambench_singleip.json
## 多主体
python inference.py --eval_json_path ./datasets/dreambench_multiip.json

🔍 评估

# 在 dreambench 上评估
## 单主体
python eval/evaluate_clip_dino_score_single_subject.py --result_root <your_image_result_save_path> -save_dir <the_evaluation_result_save_path>
## 多主体
python eval/evaluate_clip_dino_score_multi_subject.py --result_root <your_image_result_save_path> -save_dir <the_evaluation_result_save_path>

🚄 训练

如果你想在 UNO-1M 数据集上进行训练，需要从 HuggingFace 下载该数据集，解压后放入 ./datasets/UNO-1M 目录。目录结构如下：

├── datasets
│   └── UNO-1M
│       ├── images
│       │   ├── split1
│       │   │   ├── object365_w1024_h1536_split_Bread_0_0_1_725x1024.png
│       │   │   ├── object365_w1024_h1536_split_Bread_0_0_2_811x1024.png
│       │   │   └── ...
│       │   └── ...
│       └── uno_1m_total_labels.json

然后运行训练脚本：

# 过滤和格式化数据集
python uno/utils/filter_uno_1m_dataset.py ./datasets/UNO-1M/uno_1m_total_labels.json ./datasets/UNO-1M/uno_1m_total_labels_convert.json 4

# 训练
accelerate launch train.py --train_data_json ./datasets/UNO-1M/uno_1m_total_labels_convert.json

📌 提示与注意事项

我们将在一个统一的模型中集成单主体和多主体生成。对于单主体场景，默认将参考图像的最长边设置为 512；而对于多主体场景，则设置为 320。得益于在多尺度数据集上的训练，UNO 在各种宽高比下都表现出极高的灵活性。尽管是在 512 桶内训练的，它仍能处理更高的分辨率，包括 512、568 和 704 等。

UNO 在主体驱动的生成方面表现出色，但由于数据集的限制，在泛化能力上仍有提升空间。我们正在积极开发增强版模型，请持续关注更新。您的反馈对我们非常重要，欢迎随时提出建议。

🎨 应用场景

📄 免责声明

我们开源此项目是为了学术研究。本项目中使用的绝大多数图像要么是自动生成的，要么已获得授权。如果您有任何疑虑，请联系我们，我们将立即移除任何不当内容。我们的代码采用 Apache 2.0 许可证发布。任何使用的基础模型必须遵守其原始许可条款。

本研究旨在推动生成式 AI 领域的发展。用户可以自由使用此工具生成图像，但需遵守当地法律并负责任地使用。开发者对用户滥用该工具不承担任何责任。

🚀 更新

为了促进研究和开源社区的发展，我们计划开源整个项目，包括训练、推理、权重等。感谢您的耐心与支持！🌟

• 发布 GitHub 仓库。
• 发布推理代码。
• 发布训练代码。
• 发布模型检查点。
• 发布 arXiv 论文。
• 发布 HuggingFace Space 演示。
• 发布上下文数据生成管道（说明见 ./template）。
• 发布数据集（UNO-1M）。

相关资源

ComfyUI

• https://github.com/jax-explorer/ComfyUI-UNO 由 jax-explorer 实现的 UNO ComfyUI 节点。
• https://github.com/HM-RunningHub/ComfyUI_RH_UNO 由 HM-RunningHub 实现的 UNO ComfyUI 节点。
• https://github.com/ShmuelRonen/ComfyUI-UNO-Wrapper 由 ShmuelRonen 实现的 UNO ComfyUI 节点。
• https://github.com/Yuan-ManX/ComfyUI-UNO 由 Yuan-ManX 实现的 UNO ComfyUI 节点。
• https://github.com/QijiTec/ComfyUI-RED-UNO 由 QijiTec 实现的 UNO ComfyUI 节点。

我们感谢热情的社区贡献者，因为收到了许多关于 ComfyUI 的请求，但我们没有足够的时间来亲自完成这么多适配工作。如果您想在 ComfyUI 中尝试我们的工作，可以试试上述仓库。请记住，这些实现略有不同，您可能需要一些试错才能找到最适合您的仓库。

引用

如果 UNO 对您有所帮助，请为本仓库点亮星标。

如果您认为本项目对您的研究有帮助，请考虑引用我们的论文：

@article{wu2025less,
  title={Less-to-More Generalization: Unlocking More Controllability by In-Context Generation},
  author={Wu, Shaojin and Huang, Mengqi and Wu, Wenxu and Cheng, Yufeng and Ding, Fei and He, Qian},
  journal={arXiv preprint arXiv:2504.02160},
  year={2025}
}

UNO 快速上手指南

UNO 是一个基于扩散 Transformer 的多图像条件主体生成模型，支持单主体及多主体的高一致性图像生成。本指南将帮助你快速在本地部署并运行 UNO。

环境准备

• 操作系统: Linux / macOS / Windows
• Python 版本: 3.10 - 3.12 (推荐 3.10)
• 硬件要求:
  • NVIDIA GPU: 推荐显存 24GB+ (FP8 模式 + 卸载模式下峰值显存约 16GB，可在 RTX 3090 等消费级显卡运行)。
  • 其他硬件: 如使用 AMD GPU、NVIDIA RTX 50 系列或 macOS MPS，需自行安装对应版本的 PyTorch。
• 依赖管理: 推荐使用 venv 或 conda 创建独立虚拟环境。

安装步骤

1. 创建并激活虚拟环境

使用 Conda:

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

使用 venv:

python -m venv uno_env
# Linux/macOS
source uno_env/bin/activate
# Windows
uno_env\Scripts\activate

2. 安装项目依赖

注意: 如果你使用的是 AMD GPU、RTX 50 系列或 macOS，请先手动安装适配的 torch 版本，然后再执行以下命令。

仅用于推理/演示:

pip install -e .

用于训练模型:

pip install -e .[train]

3. 下载模型权重

模型权重会在首次运行推理脚本时通过 hf_hub_download 自动下载到 ~/.cache/huggingface。若需手动下载以节省空间或使用特定路径，可参考以下方式：

方式 A：自动下载（推荐） 直接运行下方的推理命令，程序会自动拉取所需模型（包括 FLUX.1-dev, UNO, CLIP, T5 等），总大小约 37GB。

方式 B：手动指定路径 使用 huggingface-cli 下载到指定目录，并设置环境变量：

# 示例：下载 FLUX 主模型
huggingface-cli download black-forest-labs/FLUX.1-dev flux1-dev.safetensors --local-dir ./models/flux
huggingface-cli download black-forest-labs/FLUX.1-dev ae.safetensors --local-dir ./models/flux

# 设置环境变量 (根据实际路径修改)
export AE="./models/flux/ae.safetensors"
export FLUX_DEV="./models/flux/flux1-dev.safetensors"
export LORA="./models/uno/unet.safetensors" 
# 其他 T5, CLIP 等同理设置

基本使用

1. 启动 Web 演示界面 (Gradio)

最简单的体验方式是启动本地 Gradio 服务。

标准模式:

python app.py

低显存模式 (推荐显存 < 24GB 用户): 启用 --offload 和 --name flux-dev-fp8 参数，峰值显存可降至 ~16GB。

python app.py --offload --name flux-dev-fp8

启动后在浏览器访问显示的本地地址（通常为 http://127.0.0.1:7860）即可上传参考图并生成图像。

2. 命令行推理

你可以直接使用命令行进行单主体或多主体生成。

单主体生成示例: 将时钟图片合成到海滩场景中。

python inference.py --prompt "A clock on the beach is under a red sun umbrella" --image_paths "assets/clock.png" --width 704 --height 704

多主体生成示例: 将小雕像放入水晶球中。

python inference.py --prompt "The figurine is in the crystal ball" --image_paths "assets/figurine.png" "assets/crystal_ball.png" --width 704 --height 704

复杂组合示例: 将 Logo 印在杯子上。

python inference.py --prompt "The logo is printed on the cup" --image_paths "assets/cat_cafe.png" "assets/cup.png" --width 704 --height 704

使用提示

• 分辨率: 单主体场景参考图最长边默认为 512，多主体场景为 320。模型支持多种宽高比，推理时可设置 512, 568, 704 等分辨率。
• 数据集测试: 如需在 DreamBench 数据集上进行评估，请先初始化子模块：git submodule update --init，然后运行对应的 eval 脚本。