IP-Adapter：文本兼容的图像提示适配器，用于文生图扩散模型

---

简介

我们提出了IP-Adapter，这是一种高效且轻量级的适配器，能够为预训练的文生图扩散模型赋予图像提示能力。仅需2200万参数的IP-Adapter，便能实现与经过微调的图像提示模型相当甚至更优的效果。IP-Adapter不仅可推广到基于同一基础模型微调的其他自定义模型，还能与现有的可控生成工具结合，实现可控生成任务。此外，图像提示还可以与文本提示协同工作，完成多模态图像生成。

发布

• [2024/01/19] 🔥 添加IP-Adapter-FaceID-Portrait，更多信息请见这里。
• [2024/01/17] 🔥 为SDXL添加IP-Adapter-FaceID-PlusV2实验版本，更多信息请见这里。
• [2024/01/04] 🔥 为SDXL添加IP-Adapter-FaceID实验版本，更多信息请见这里。
• [2023/12/29] 🔥 添加IP-Adapter-FaceID-PlusV2实验版本，更多信息请见这里。
• [2023/12/27] 🔥 添加IP-Adapter-FaceID-Plus实验版本，更多信息请见这里。
• [2023/12/20] 🔥 添加IP-Adapter-FaceID实验版本，更多信息请见这里。
• [2023/11/22] 感谢Diffusers团队，IP-Adapter现已在Diffusers中可用。
• [2023/11/10] 🔥 添加更新版IP-Adapter-Face。演示请见[ip_adapter-full-face_demo.ipynb]。
• [2023/11/05] 🔥 添加使用IP-Adapter和Kandinsky 2.2 Prior的文生图演示。
• [2023/11/02] 支持safetensors。
• [2023/9/08] 🔥 更新了适用于SDXL_1.0的新版IP-Adapter。更多信息请见[#sdxl_10]。
• [2023/9/05] 🔥🔥🔥 IP-Adapter已在WebUI和ComfyUI（或ComfyUI_IPAdapter_plus）中得到支持。
• [2023/8/30] 🔥 添加以人脸图像作为提示的IP-Adapter。演示请见[ip_adapter-plus-face_demo.ipynb]。
• [2023/8/29] 🔥 发布训练代码。
• [2023/8/23] 🔥 添加带有细粒度特征的IP-Adapter代码及模型。演示请见[ip_adapter-plus_demo.ipynb]。
• [2023/8/18] 🔥 添加针对SDXL 1.0的代码和模型。演示请见[ip_adapter_sdxl_demo.ipynb]。
• [2023/8/16] 🔥 我们发布了代码和模型。

安装

# 安装最新版diffusers
pip install diffusers==0.22.1

# 安装ip-adapter
pip install git+https://github.com/tencent-ailab/IP-Adapter.git

# 下载模型
cd IP-Adapter
git lfs install
git clone https://huggingface.co/h94/IP-Adapter
mv IP-Adapter/models models
mv IP-Adapter/sdxl_models sdxl_models

# 然后你就可以使用notebook了

下载模型

你可以从这里下载模型。要运行演示，你还需下载以下模型：

• runwayml/stable-diffusion-v1-5
• stabilityai/sd-vae-ft-mse
• SG161222/Realistic_Vision_V4.0_noVAE
• ControlNet模型

使用方法

SD_1.5

• ip_adapter_demo: 基于图像提示的图像变体、图像到图像生成以及修复。
• 

• ip_adapter_controlnet_demo, ip_adapter_t2i-adapter: 基于图像提示的结构化生成。
• 

• ip_adapter_multimodal_prompts_demo: 多模态提示下的生成。
• 

• ip_adapter-plus_demo: 具有细粒度特征的IP-Adapter演示。

• ip_adapter-plus-face_demo: 以人脸图像为提示的生成。

最佳实践

• 如果仅使用图像提示，可以将scale设置为1.0，并将text_prompt留空（或使用一些通用文本提示，例如“最佳质量”），也可以使用任何负面文本提示。如果降低scale值，可以生成更多样化的图像，但这些图像可能与图像提示的一致性较差。
• 对于多模态提示，可以通过调整scale来获得最佳效果。在大多数情况下，将scale设置为0.5即可获得不错的效果。对于SD 1.5版本，我们建议使用社区模型来生成高质量图像。

非正方形图像的IP-Adapter

由于CLIP默认的图像处理器会对图像进行中心裁剪，因此IP-Adapter最适合处理正方形图像。对于非正方形图像，中心区域之外的信息可能会丢失。不过，您可以将非正方形图像调整为224x224像素，对比效果如下：

SDXL_1.0

• ip_adapter_sdxl_demo: 基于图像提示的图像变体。
• ip_adapter_sdxl_controlnet_demo: 基于图像提示的结构化生成。

以下是IP-Adapter_XL与Reimagine XL的对比：

新版本改进（2023年9月8日）：

• 切换至CLIP-ViT-H：我们使用OpenCLIP-ViT-H-14而非OpenCLIP-ViT-bigG-14训练了新的IP-Adapter。尽管ViT-bigG比ViT-H大得多，但我们的实验结果并未显示出显著差异，且较小的模型可以在推理阶段减少内存占用。
• 更快速、更优的训练方案：在之前的版本中，直接以1024x1024分辨率进行训练效率极低。而在新版本中，我们实施了一种更为有效的两阶段训练策略。首先，我们在512x512分辨率下进行预训练，随后采用多尺度策略进行微调。（这种训练策略或许也可用于加速ControlNet的训练）。

如何训练

进行训练时，您需要安装accelerate，并将自己的数据集转换为JSON文件。

accelerate launch --num_processes 8 --multi_gpu --mixed_precision "fp16" \
  tutorial_train.py \
  --pretrained_model_name_or_path="runwayml/stable-diffusion-v1-5/" \
  --image_encoder_path="{image_encoder_path}" \
  --data_json_file="{data.json}" \
  --data_root_path="{image_path}" \
  --mixed_precision="fp16" \
  --resolution=512 \
  --train_batch_size=8 \
  --dataloader_num_workers=4 \
  --learning_rate=1e-04 \
  --weight_decay=0.01 \
  --output_dir="{output_dir}" \
  --save_steps=10000

训练完成后，您可以使用以下代码转换权重：

import torch
ckpt = "checkpoint-50000/pytorch_model.bin"
sd = torch.load(ckpt, map_location="cpu")
image_proj_sd = {}
ip_sd = {}
for k in sd:
    if k.startswith("unet"):
        pass
    elif k.startswith("image_proj_model"):
        image_proj_sd[k.replace("image_proj_model.", "")] = sd[k]
    elif k.startswith("adapter_modules"):
        ip_sd[k.replace("adapter_modules.", "")] = sd[k]

torch.save({"image_proj": image_proj_sd, "ip_adapter": ip_sd}, "ip_adapter.bin")

第三方应用

• WebUI版IP-Adapter [发布说明]
• ComfyUI版IP-Adapter [IPAdapter-ComfyUI 或 ComfyUI_IPAdapter_plus]
• InvokeAI版IP-Adapter [发布说明]
• AnimateDiff提示旅行版IP-Adapter
• Diffusers_IPAdapter: 提供更多功能，如支持多张输入图像。
• 官方Diffusers
• InstantStyle: 基于IP-Adapter的风格迁移。

免责声明

本项目致力于对AI驱动的图像生成领域产生积极影响。用户可以自由地使用此工具创作图像，但应遵守当地法律法规，并以负责任的方式使用。开发者不对用户的任何潜在滥用行为承担责任。

引用

如果您发现IP-Adapter对您的研究和应用有所帮助，请使用以下BibTeX格式引用：

@article{ye2023ip-adapter,
  title={IP-Adapter: 文本兼容的图像提示适配器，适用于文生图扩散模型},
  author={Ye, Hu and Zhang, Jun and Liu, Sibo and Han, Xiao and Yang, Wei},
  booktitle={arXiv预印本 arxiv:2308.06721},
  year={2023}
}

IP-Adapter 快速上手指南

IP-Adapter 是一个轻量级适配器，能让预训练的文本到图像扩散模型（如 Stable Diffusion）具备强大的“图像提示”（Image Prompt）能力。仅需 22M 参数，即可实现与微调模型相当甚至更优的效果，支持图像变体、重绘、结构控制及多模态生成。

环境准备

• 系统要求：Linux / Windows / macOS
• Python 版本：建议 Python 3.8+
• GPU：推荐 NVIDIA GPU（显存建议 8GB 以上，SDXL 需更大显存）
• 前置依赖：
  • git 和 git-lfs（用于下载大模型文件）
  • pip 包管理工具

注意：国内用户建议在 pip 命令后添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 以加速下载。

安装步骤

1. 安装核心依赖

首先安装指定版本的 diffusers 库，然后安装 IP-Adapter 源码。

# install latest diffusers
pip install diffusers==0.22.1

# install ip-adapter
pip install git+https://github.com/tencent-ailab/IP-Adapter.git

2. 下载模型文件

使用 git lfs 克隆模型仓库并整理目录结构。

cd IP-Adapter
git lfs install
git clone https://huggingface.co/h94/IP-Adapter
mv IP-Adapter/models models
mv IP-Adapter/sdxl_models sdxl_models

3. 下载基础底模

运行 Demo 前，还需确保本地已下载以下基础模型（可通过 Hugging Face 或国内镜像站下载）：

• runwayml/stable-diffusion-v1-5
• stabilityai/sd-vae-ft-mse
• (可选) ControlNet 模型或其他社区微调模型（如 Realistic_Vision_V4.0）

基本使用

以下是最基础的 SD 1.5 图像变体生成示例。请确保已在当前目录下准备好 models 文件夹及对应的底模。

代码示例 (ip_adapter_demo.py)

import torch
from PIL import Image
from diffusers import StableDiffusionPipeline
from ip_adapter import IPAdapter

# 1. 加载基础 SD 模型
base_model_path = "runwayml/stable-diffusion-v1-5"
image_encoder_path = "models/image_encoder"
ip_ckpt = "models/ip-adapter_sd15.bin" # 根据实际下载的文件名调整

device = "cuda" if torch.cuda.is_available() else "cpu"

# 初始化 Pipeline
pipe = StableDiffusionPipeline.from_pretrained(
    base_model_path,
    torch_dtype=torch.float16,
).to(device)

# 2. 加载 IP-Adapter
ip_adapter = IPAdapter(pipe, image_encoder_path, ip_ckpt, device)

# 3. 准备输入
prompt = "best quality, high resolution" # 文本提示词可为空或通用词
negative_prompt = "monochrome, lowres, bad anatomy, worst quality, low quality"
image = Image.open("assets/demo/source_image.jpg").convert("RGB") # 替换为你的参考图路径

# 4. 生成图像
# scale: 控制图像提示词的权重。仅使用图像提示时设为 1.0；多模态混合时可尝试 0.5
generator = torch.Generator(device=device).manual_seed(42)
images = ip_adapter.generate(
    pil_image=image,
    num_samples=1,
    num_inference_steps=30,
    seed=42,
    prompt=prompt,
    negative_prompt=negative_prompt,
    scale=1.0, 
    generator=generator
)

# 5. 保存结果
images[0].save("output_result.jpg")
print("生成完成！")

使用建议

• 纯图像提示：设置 scale=1.0，text_prompt 可留空或使用 "best quality" 等通用词。
• 多模态提示（图 + 文）：建议调整 scale 参数（例如 0.5），以平衡图像特征与文本描述。
• 非正方形图片：IP-Adapter 默认对图像进行中心裁剪。若参考图非正方形，建议先手动 Resize 至 224x224 再传入，以保留完整信息。