XVerse：通过DiT调制实现身份与语义属性的一致性多主体控制

🔥 最新消息

• 2025年9月19日：🎉 恭喜！XVerse已被NeurIPS 2025接收！🎉
• 2025年7月18日：支持量化扩散模型，并新增分组卸载功能，可在16GB显存下运行XVerse模型。
• 2025年7月10日：发布Hugging Face Space演示。
• 2025年7月8日：支持低显存推理，可在24GB显存下运行XVerse模型。
• 2025年6月26日：代码已公开！

📖 简介

XVerse提出了一种全新的多主体图像合成方法，能够在不破坏整体图像潜在空间或特征的情况下，对各个主体进行精确且独立的控制。我们通过将参考图像转换为针对特定标记的文本流调制偏移量来实现这一目标。

这一创新使得高保真、可编辑的图像生成成为可能，您可以稳健地控制个体主体特征（身份）及其语义属性。XVerse显著提升了个性化和复杂场景生成的能力。

⚡️ 快速入门

环境要求与安装

首先，安装必要的依赖项：

# 创建名为XVerse的conda环境，Python版本为3.10.16
conda create -n XVerse python=3.10.16 -y
# 激活XVerse环境
conda activate XVerse
# 安装适合您硬件的PyTorch版本
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124
# 使用pip安装requirements.txt中列出的依赖
pip install -r requirements.txt
# 安装flash-attn
pip install flash-attn==2.7.4.post1 --no-build-isolation
# 更新httpx版本
pip install httpx==0.23.3

接下来，下载所需的检查点文件：

cd checkpoints
bash ./download_ckpts.sh
cd ..

重要提示：您还需要从InsightFace_Pytorch下载人脸识别模型model_ir_se50.pth，并将其直接放置在./checkpoints/文件夹中。

之后，您可以将模型路径导出为环境变量。这一步骤确保后续的推理脚本能够正确找到所需的模型：

export FLORENCE2_MODEL_PATH="./checkpoints/Florence-2-large"
export SAM2_MODEL_PATH="./checkpoints/sam2.1_hiera_large.pt"
export FACE_ID_MODEL_PATH="./checkpoints/model_ir_se50.pth"
export CLIP_MODEL_PATH="./checkpoints/clip-vit-large-patch14"
export FLUX_MODEL_PATH="./checkpoints/FLUX.1-dev"
export DPG_VQA_MODEL_PATH="./checkpoints/mplug_visual-question-answering_coco_large_en"
export DINO_MODEL_PATH="./checkpoints/dino-vits16"

本地Gradio演示

要在本地运行交互式Gradio演示，请执行以下命令：

python run_gradio.py

输入设置说明

Gradio演示提供了多个参数来控制您的图像生成过程：

• Prompt：指导图像生成的文本描述。
• 生成高度/宽度：使用滑块设置输出图像的尺寸。
• Weight_id/ip：调整这些权重参数。较高的值通常能提升主体一致性，但可能会略微影响生成图像的自然度。
• latent_lora_scale和vae_lora_scale：控制LoRA比例。与Weight_id/ip类似，较大的LoRA值可以提高主体一致性，但可能降低图像自然度。
• vae_skip_iter_before和vae_skip_iter_after：配置VAE跳过迭代次数。跳过更多步骤可以使图像更自然，但可能会影响主体一致性。

输入图像

演示对输入图像提供了详细的控制选项：

• 展开面板：点击“Input Image X”以显示每张图像的选项。
• 上传图像：点击“Image X”上传您希望使用的参考图像。
• 图像描述：在“Caption X”输入框中输入描述。您也可以点击“Auto Caption”自动生成描述。
• 检测与分割：点击“Det & Seg”对上传的图像进行检测和分割。
• 裁剪人脸：使用“Crop Face”自动裁剪图像中的人脸。
• ID复选框：勾选或取消勾选“ID or not”，以决定是否对该输入图像使用与身份相关的权重。

⚠️ 重要使用说明：

• Prompt构建：主文本提示必须包含您为每个启用的图像在“Image Description”字段中输入的确切文本。如果提示中缺少该描述，生成将失败。
  • 示例：如果您上传两张图像，并分别设置其描述为“红发男子”（图像1）和“蓝眼睛女子”（图像2），那么您的主提示可能是：“一位 红发男子 在公园里与 蓝眼睛女子 并肩行走。”
  • 您随后只需简单地写下主提示：“ENT1 在公园里与 ENT2 并肩行走。”代码会在生成前将这些占位符自动替换为完整的描述文本。
• 启用的图像：只有处于展开状态（未折叠）的图像才会被送入模型。折叠的图像面板将被忽略。

单样本推理

要对单个样本进行推理，请运行以下命令。您可以通过调整提示词、种子值、输出尺寸等参数来自定义图像生成：

python inference_single_sample.py --prompt "ENT1戴着一顶小帽子" --seed 42 --cond_size 256 --target_height 768 --target_width 768 --weight_id 3 --weight_ip 5 --latent_lora_scale 0.85 --vae_lora_scale 1.3 --vae_skip_iter_s1 0.05 --vae_skip_iter_s2 0.8 --images "sample/hamster.jpg" --captions "一只仓鼠" --idips false --save_path "generated_image_1.png" --num_images 1

对于使用多张条件图像的推理，请使用下面的命令。这允许您在生成过程中纳入多张参考图像。请确保 --images、--captions 和 --ids 的数量一致：

python inference_single_sample.py --prompt "ENT1和ENT2一起站在公园里。" --seed 42 --cond_size 256 --target_height 768 --target_width 768 --weight_id 2 --weight_ip 5 --latent_lora_scale 0.85 --vae_lora_scale 1.3 --vae_skip_iter_s1 0.05 --vae_skip_iter_s2 0.8 --images "sample/woman.jpg" "sample/girl.jpg" --captions "一位女性" "一位女孩" --idips true true --save_path "generated_image_2.png" --num_images 1

⚡️ 低显存推理

将模块卸载到 CPU

• 在单样本推理或运行 Gradio 演示时，您可以通过添加参数 --use_low_vram True 或 --use_lower_vram True 来启用低显存模式。
• use_low_vram 允许在配备 24GB 显存的 GPU 上进行最多两张条件图像的推理。
• use_lower_vram 允许在配备 16GB 显存的 GPU 上进行最多三张条件图像的推理。
• 请注意，CPU 卸载会显著降低推理速度，因此仅在必要时才应启用。

量化扩散模型

• 您可以从 这里 下载量化模型，并将其放入 checkpoints 文件夹中。使用 bnb-nf4 量化模型，在 32GB 显存环境下可以进行单条件推理；而在 24GB 显存环境下，则可通过启用 CPU 卸载功能来实现三条件推理。您需要修改 FLUX_MODEL_PATH 环境变量，并添加参数 --dit_quant None。
• 您也可以从 这里 下载 GGUF 量化模型，并将其放入 checkpoints 文件夹中。使用此 GGUF 量化模型，在 32GB 显存环境下可进行两条件推理；而在 24GB 显存环境下，则可通过启用 CPU 卸载功能实现四条件推理。您可以使用以下命令进行推理：

export FLUX_TRANSFORMERS_PATH="./checkpoints/FLUX.1-dev-gguf/flux1-dev-Q3_K_S.gguf"
export FLUX_MODEL_PATH="./checkpoints/FLUX.1-dev"
python inference_single_sample.py --prompt "ENT1和ENT2一起站在公园里。" --seed 42 --cond_size 256 --target_height 768 --target_width 768 --weight_id 3 --weight_ip 5 --latent_lora_scale 0.7 --vae_lora_scale 1.2 --vae_skip_iter_s1 0.05 --vae_skip_iter_s2 0.8 --images "sample/woman.jpg" "sample/girl.jpg" --captions "一位女性" "一位女孩" --idips true true --save_path "generated_image_2-GGUF.png" --num_images 1 --dit_quant GGUF

注意：量化模型可能会在一定程度上降低模型性能，weight_id、weight_ip 和 lora_scale 等参数可能需要重新调整。

使用 XVerseBench 进行推理

首先，请根据 assets 文件夹中的内容下载 XVerseBench。然后，在运行推理时，请执行以下命令：

bash ./eval/eval_scripts/run_eval.sh

该脚本将自动在 XVerseBench 数据集上评估模型，并将结果保存到 ./results 文件夹中。

📌 待办事项

• 发布 GitHub 仓库。
• 发表 arXiv 论文。
• 发布模型检查点。
• 发布推理数据：XVerseBench。
• 发布 XVerseBench 的推理代码。
• 发布 Gradio 演示的推理代码。
• 发布单样本推理代码。
• 支持消费级 GPU 上的推理。
• 发布 Hugging Face Space 演示。
• 支持量化扩散模型。
• 发布基准排行榜。
• 发布 ComfyUI 实现。

许可证

本项目的代码采用 Apache 2.0 许可证；数据集采用 CC0 许可证，但受字节跳动拥有的知识产权约束。同时，该数据集改编自 dreambench++，您也应遵守 dreambench++ 的许可证。

致谢

我们衷心感谢 Alex Nasa 部署了基于 FLUX.1-schnell 模型的 Hugging Face 演示。您可以通过点击 这里 体验该在线演示。

引用

如果 XVerse 对您有所帮助，请为本仓库点赞（⭐）。

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

@article{chen2025xverse,
  title={XVerse: 通过 DiT 调制实现身份与语义属性的一致性多主体控制},
  author={Chen, Bowen and Zhao, Mengyi and Sun, Haomiao and Chen, Li and Wang, Xu and Du, Kang and Wu, Xinglong},
  journal={arXiv 预印本 arXiv:2506.21416},
  year={2025}


}

XVerse 快速上手指南

XVerse 是一个基于 DiT 调制技术的开源工具，支持在多主体图像生成中精确控制每个主体的身份（Identity）和语义属性（如姿态、风格、光照），且互不干扰。

环境准备

• 操作系统: Linux (推荐)
• Python 版本: 3.10.16
• GPU 要求:
  • 标准推理：建议 24GB+ VRAM
  • 低显存模式：支持 16GB VRAM (需开启 CPU Offload 或量化模型)
• CUDA 版本: 12.4 (对应 PyTorch 2.6.0)

安装步骤

1. 创建并激活 Conda 环境

conda create -n XVerse python=3.10.16 -y
conda activate XVerse

2. 安装 PyTorch 及依赖

请根据您的机器 CUDA 版本调整 PyTorch 安装命令（以下默认为 cu124）：

pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
pip install flash-attn==2.7.4.post1 --no-build-isolation
pip install httpx==0.23.3

3. 下载模型权重

运行脚本下载基础检查点：

cd checkpoints
bash ./download_ckpts.sh
cd ..

重要补充：需手动下载人脸识别模型 model_ir_se50.pth。

• 来源：InsightFace_Pytorch
• 操作：将下载好的 model_ir_se50.pth 直接放入 ./checkpoints/ 目录。

4. 配置环境变量

设置模型路径以便推理脚本正确加载：

export FLORENCE2_MODEL_PATH="./checkpoints/Florence-2-large"
export SAM2_MODEL_PATH="./checkpoints/sam2.1_hiera_large.pt"
export FACE_ID_MODEL_PATH="./checkpoints/model_ir_se50.pth"
export CLIP_MODEL_PATH="./checkpoints/clip-vit-large-patch14"
export FLUX_MODEL_PATH="./checkpoints/FLUX.1-dev"
export DPG_VQA_MODEL_PATH="./checkpoints/mplug_visual-question-answering_coco_large_en"
export DINO_MODEL_PATH="./checkpoints/dino-vits16"

基本使用

方式一：启动本地 Gradio 交互界面（推荐）

适合快速测试和调整参数。

python run_gradio.py

启动后在浏览器打开指定地址即可。

使用提示：

1. 图片上传：点击 "Input Image X" 展开面板，上传图片并填写描述（Caption）。
2. 提示词构建：主 Prompt 必须 包含图片描述或使用占位符。
   • 若图片描述为 "a man with red hair"，Prompt 可写为："ENT1 walking in a park." (代码会自动替换 ENT1)。
   • 或者直接写全："A a man with red hair walking in a park."
3. 生效条件：只有展开状态的图片面板会被模型处理，折叠的面板将被忽略。

方式二：命令行单样本推理

适合批量任务或集成到工作流中。

单主体生成示例：

python inference_single_sample.py --prompt "ENT1 wearing a tiny hat" --seed 42 --cond_size 256 --target_height 768 --target_width 768 --weight_id 3 --weight_ip 5 --latent_lora_scale 0.85 --vae_lora_scale 1.3 --vae_skip_iter_s1 0.05 --vae_skip_iter_s2 0.8 --images "sample/hamster.jpg" --captions "a hamster" --idips false --save_path "generated_image_1.png" --num_images 1

多主体生成示例：

python inference_single_sample.py --prompt "ENT1, and ENT2 standing together in a park." --seed 42 --cond_size 256 --target_height 768 --target_width 768 --weight_id 2 --weight_ip 5 --latent_lora_scale 0.85 --vae_lora_scale 1.3 --vae_skip_iter_s1 0.05 --vae_skip_iter_s2 0.8 --images "sample/woman.jpg" "sample/girl.jpg" --captions "a woman" "a girl" --idips true true --save_path "generated_image_2.png" --num_images 1

低显存优化（可选）

如果您的显存不足（16GB-24GB），可在上述命令中添加以下参数：

• 24GB 显存：添加 --use_low_vram True
• 16GB 显存：添加 --use_lower_vram True
• 量化模型：下载 GGUF 或 BNB 量化模型后，设置相应环境变量并添加 --dit_quant GGUF 参数（详见原文 Low-VRAM Inference 章节）。