IP-Adapter 详解:为文本到图像扩散模型注入图像提示能力的轻量级适配器
IP-Adapter 详解:为文本到图像扩散模型注入图像提示能力的轻量级适配器
IP-Adapter(Image Prompt Adapter)是腾讯 AI Lab 于 2023 年发布的一种轻量级适配器方案,以约 22M 参数为预训练文本到图像扩散模型(Stable Diffusion 1.5 / SDXL 等)带来「图像提示(image prompt)」能力,无需微调基础模型即可实现图像变体、图生图、局部重绘、结构可控生成与多模态提示等场景。本文以仓库 README.md 为骨架,结合
ip_adapter包源码(ip_adapter/ip_adapter.py、ip_adapter/attention_processor.py、ip_adapter/resampler.py)与各 Notebook 演示,系统讲解其原理、安装、推理、训练与调参实践。
一、IP-Adapter 是什么:问题背景与核心思路
文本到图像扩散模型(如 Stable Diffusion)的生成通常由**文本提示(text prompt)**驱动。要让模型根据参考图片生成内容,常见做法是微调出一个「图像提示模型」,但这种方式成本高、且难以在不同任务间迁移。
IP-Adapter 的出发点是:为预训练扩散模型新增一个轻量适配层,使其直接接受图像提示。据 README.md 所述,仅 22M 参数的 IP-Adapter 就能达到与微调图像提示模型相当甚至更好的效果,并且具备三个关键特性:
- 可泛化:不仅能作用于基础模型,还能迁移到基于同一基础模型微调出的各类自定义模型;
- 可控生成:可与现有可控生成工具(如 ControlNet、T2I-Adapter)直接组合使用;
- 多模态提示:图像提示可与文本提示同时工作,实现多模态条件生成。
技术报告对应论文 IP-Adapter: Text Compatible Image Prompt Adapter for Text-to-Image Diffusion Models(arXiv:2308.06721),完整 BibTeX 见文末引用一节。
二、核心架构:解耦交叉注意力与图像投影
从仓库源码结构看,IP-Adapter 的整体架构由三部分组成,这与 assets/figs/fig1.png 的架构图一致:
- CLIP 图像编码器(
CLIPVisionModelWithProjection):提取参考图像的视觉特征; - 图像投影模型(Image Projection Model):把图像特征映射为「图像 token」序列;
- 解耦的交叉注意力层(Decoupled Cross-Attention):把图像 token 以并行分支注入 UNet 的注意力机制,与原文本分支解耦。
2.1 图像特征 → 图像 token:三种投影实现
在 ip_adapter/ip_adapter.py 中,投影模型有三种实现,对应不同版本:
| 实现类 | 用途 | 结构要点 |
|---|---|---|
ImageProjModel |
基础版 IP-Adapter | 单层 nn.Linear 将 CLIP 投影维度映射为 num_tokens × cross_attention_dim,再接 LayerNorm,输出 clip_extra_context_tokens 个 token(默认 4 个) |
Resampler |
Plus 版(细粒度特征) | Perceiver 式可学习查询(learnable queries)机制,见 ip_adapter/resampler.py |
MLPProjModel |
Full 版 | 两层 Linear + GELU + LayerNorm 的 MLP |
以基础版 ImageProjModel 为例,其 forward 直接把图像嵌入投影为 clip_extra_context_tokens 个 token(源码 ip_adapter/ip_adapter.py):
class ImageProjModel(torch.nn.Module):
def __init__(self, cross_attention_dim=1024, clip_embeddings_dim=1024, clip_extra_context_tokens=4):
super().__init__()
self.proj = torch.nn.Linear(clip_embeddings_dim, self.clip_extra_context_tokens * cross_attention_dim)
self.norm = torch.nn.LayerNorm(cross_attention_dim)
def forward(self, image_embeds):
embeds = image_embeds
clip_extra_context_tokens = self.proj(embeds).reshape(
-1, self.clip_extra_context_tokens, self.cross_attention_dim
)
clip_extra_context_tokens = self.norm(clip_extra_context_tokens)
return clip_extra_context_tokens
Plus 版的 Resampler 则更精细:它维护一组可学习 latent 查询(self.latents,随机初始化并除以 dim**0.5 缩放),通过多层 PerceiverAttention + FeedForward 残差块,从 CLIP 倒数第二层隐藏状态(hidden_states[-2],见 IPAdapterPlus.get_image_embeds)中提取细粒度特征,最后经 proj_out + LayerNorm 输出固定数量的 token。
2.2 解耦交叉注意力:IPAttnProcessor
关键创新在 ip_adapter/attention_processor.py 的 IPAttnProcessor / IPAttnProcessor2_0(PyTorch 2.0 的 scaled_dot_product_attention 版本)。其前向流程如下:
- 把拼接后的
encoder_hidden_states按num_tokens切分为文本部分与图像部分; - 文本部分走原有
attn.to_k / to_v分支,与普通交叉注意力一致; - 图像部分走新增的独立投影
to_k_ip / to_v_ip(均为无 bias 的nn.Linear),计算ip_attention_probs; - 最终输出为
hidden_states = hidden_states + self.scale * ip_hidden_states,即用scale控制图像提示的权重。
# 摘要(完整实现见 ip_adapter/attention_processor.py#L82-L188)
class IPAttnProcessor(nn.Module):
def __init__(self, hidden_size, cross_attention_dim=None, scale=1.0, num_tokens=4):
self.to_k_ip = nn.Linear(cross_attention_dim or hidden_size, hidden_size, bias=False)
self.to_v_ip = nn.Linear(cross_attention_dim or hidden_size, hidden_size, bias=False)
...
def __call__(self, attn, hidden_states, encoder_hidden_states=None, ...):
# 1) 切分文本与图像 token
end_pos = encoder_hidden_states.shape[1] - self.num_tokens
encoder_hidden_states, ip_hidden_states = encoder_hidden_states[:, :end_pos, :], encoder_hidden_states[:, end_pos:, :]
# 2) 文本分支
key, value = attn.to_k(encoder_hidden_states), attn.to_v(encoder_hidden_states)
attention_probs = attn.get_attention_scores(query, key, attention_mask)
hidden_states = torch.bmm(attention_probs, value)
# 3) 图像分支(解耦)
ip_key, ip_value = self.to_k_ip(ip_hidden_states), self.to_v_ip(ip_hidden_states)
ip_attention_probs = attn.get_attention_scores(query, ip_key, None)
ip_hidden_states = torch.bmm(ip_attention_probs, ip_value)
# 4) 加权叠加
hidden_states = hidden_states + self.scale * ip_hidden_states
由于文本与图像两个注意力分支完全解耦,原模型的文本生成能力被完整保留,同时叠加了图像条件——这正是「Text Compatible」的含义,也解释了为何可以迁移到基于同一基础模型的社区微调模型上。
2.3 与 ControlNet 的兼容
在 IPAdapter.set_ip_adapter 中(ip_adapter/ip_adapter.py),若管道带有 ControlNet,会为 ControlNet 的注意力层设置 CNAttnProcessor。从源码看,CNAttnProcessor 在切分 token 后只取文本部分(encoder_hidden_states[:, :end_pos] # only use text),即 ControlNet 不参与图像分支,从而保持结构控制信号的纯粹性。这也为「图像提示 + 结构控制」的组合用法提供了实现基础。
三、环境安装与模型准备
3.1 安装依赖
按 README.md 的 Installation 一节,需要先安装与仓库配套版本的 diffusers,再安装 IP-Adapter 本身:
# 安装与仓库兼容的 diffusers 版本
pip install diffusers==0.22.1
# 安装 ip-adapter(从项目 Git 仓库安装)
pip install git+https://github.com/tencent-ailab/IP-Adapter.git
仓库的 pyproject.toml 表明项目以 poetry 管理,包体为 ip_adapter,__init__.py 对外导出 IPAdapter、IPAdapterPlus、IPAdapterXL、IPAdapterPlusXL、IPAdapterFull 五个类,安装后即可 from ip_adapter import IPAdapter。
3.2 下载模型
模型权重存放于 Hugging Face 模型仓库 h94/IP-Adapter(基础版 + Plus 版 + SDXL 版 + 人脸版)。README 给出的完整准备流程如下:
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
即把克隆下来的 models(SD 1.5 系列)与 sdxl_models(SDXL 系列)移动到仓库根目录,后续 Notebook 中的 models/image_encoder/、models/ip-adapter_sd15.bin、sdxl_models/ip-adapter_sdxl.bin 等路径即可直接使用。
3.3 推理所需的配套基础模型
除 IP-Adapter 权重外,运行演示还需要以下配套模型(来源见 README.md 的 Download Models 一节):
| 模型 | 用途 |
|---|---|
runwayml/stable-diffusion-v1-5 |
SD 1.5 基础模型(UNet / 文本编码器等) |
stabilityai/sd-vae-ft-mse |
高质量 VAE(官方演示中显式加载并替换默认 VAE) |
SG161222/Realistic_Vision_V4.0_noVAE |
社区写实模型(README 推荐用于 SD 1.5 版本生成更高质量图像) |
ControlNet 模型(lllyasviel 系列) |
结构可控生成(depth / openpose 等) |
stabilityai/stable-diffusion-xl-base-1.0 |
SDXL 演示的基础模型 |
四、快速上手:SD 1.5 基础推理
仓库提供了 ip_adapter_demo.ipynb,覆盖三类任务:图像变体(image variations)、图生图(image-to-image)、局部重绘(inpainting)。核心使用方式如下。
4.1 初始化 IPAdapter
import torch
from diffusers import StableDiffusionPipeline, StableDiffusionImg2ImgPipeline, StableDiffusionInpaintPipelineLegacy, DDIMScheduler, AutoencoderKL
from PIL import Image
from ip_adapter import IPAdapter
base_model_path = "runwayml/stable-diffusion-v1-5"
vae_model_path = "stabilityai/sd-vae-ft-mse"
image_encoder_path = "models/image_encoder/"
ip_ckpt = "models/ip-adapter_sd15.bin"
device = "cuda"
# 使用与 SD 1.5 匹配的 DDIM Scheduler 配置
noise_scheduler = DDIMScheduler(
num_train_timesteps=1000,
beta_start=0.00085,
beta_end=0.012,
beta_schedule="scaled_linear",
clip_sample=False,
set_alpha_to_one=False,
steps_offset=1,
)
vae = AutoencoderKL.from_pretrained(vae_model_path).to(dtype=torch.float16)
pipe = StableDiffusionPipeline.from_pretrained(
base_model_path,
torch_dtype=torch.float16,
scheduler=noise_scheduler,
vae=vae,
feature_extractor=None,
safety_checker=None,
)
ip_model = IPAdapter(pipe, image_encoder_path, ip_ckpt, device)
IPAdapter.__init__ 接受四个必填参数(源码 ip_adapter/ip_adapter.py):
| 参数 | 含义 |
|---|---|
sd_pipe |
已加载的 diffusers 管道(StableDiffusionPipeline 及其变体) |
image_encoder_path |
CLIP 图像编码器路径(models/image_encoder/) |
ip_ckpt |
IP-Adapter 权重文件(.bin 或 .safetensors) |
device |
运行设备(如 "cuda") |
num_tokens(可选) |
图像 token 数量,默认 4;Plus 版应为 16 |
初始化时 set_ip_adapter() 会把 UNet 的注意力处理器替换为 IPAttnProcessor,并加载图像编码器与投影模型;load_ip_adapter() 负责把权重加载到投影模型和 ModuleList(unet.attn_processors.values()) 上(详见下文「模型格式」一节)。
4.2 调用 generate 生成图像
num_samples = 4
image = Image.open("assets/images/girl.png") # 参考图,请按实际路径替换
images = ip_model.generate(
pil_image=image,
num_samples=num_samples,
num_inference_steps=30,
seed=420,
)
grid = image_grid(images, 1, num_samples) # image_grid 辅助函数见 Notebook
generate 的完整参数(源码 ip_adapter/ip_adapter.py):
| 参数 | 默认值 | 说明 |
|---|---|---|
pil_image |
None |
参考图,可为单张 PIL.Image 或列表(多图提示) |
clip_image_embeds |
None |
直接传入已提取的 CLIP 图像嵌入(与 pil_image 二选一) |
prompt |
"best quality, high quality" |
文本提示,可为字符串或列表 |
negative_prompt |
"monochrome, lowres, bad anatomy, worst quality, low quality" |
负面提示 |
scale |
1.0 |
图像提示权重 |
num_samples |
4 |
每张参考图生成的样本数 |
seed |
None |
随机种子(int 或 int 列表,控制可复现性) |
guidance_scale |
7.5 |
无分类器指导强度 |
num_inference_steps |
30 |
去噪步数 |
**kwargs |
— | 透传给底层管道(如 image、mask_image、width、height 等) |
从源码看,generate 内部会把图像提示嵌入与无条件的零图像嵌入分别拼接到文本嵌入与负面文本嵌入之后(torch.cat([prompt_embeds_, image_prompt_embeds], dim=1)),从而在单个批次内完成图像条件与文本条件的联合指导。
图生图与局部重绘只需要更换底层管道并传入额外参数,例如使用 StableDiffusionImg2ImgPipeline(传 image=)或 StableDiffusionInpaintPipelineLegacy(传 image= 与 mask_image=),IPAdapter 类无需改动,体现了「适配器与管道解耦」的设计。
五、最佳实践:scale 调节与文本提示配合
5.1 scale 与文本提示的取舍
README.md 明确给出了两条调参经验,可直接用于实战:
- 只使用图像提示时:设
scale=1.0,text_prompt=""(或使用"best quality"之类的泛化提示,也可配合任意负面提示)。若降低scale,生成更多样化,但与参考图的一致性会下降; - 多模态提示(图像 + 文本)时:调节
scale以获得最佳效果,多数情况下scale=0.5已能得到不错结果。对于 SD 1.5 版本,README 建议配合社区模型(如Realistic_Vision_V4.0)生成更高质量的图像。
从源码看,set_scale(scale) 会遍历 UNet 的所有注意力处理器并更新 IPAttnProcessor.scale(ip_adapter/ip_adapter.py),该值直接作用于前文 hidden_states + self.scale * ip_hidden_states 的加权公式,因此 scale 是控制图像提示「浓度」的最直接旋钮。
5.2 非方形图片的处理
由于 CLIP 默认图像处理器会对输入做中心裁剪(center crop),IP-Adapter 对方形图片效果最佳;非方形图片会丢失中心区域之外的信息。README 给出的建议是:将非方形图片直接 resize 到 224×224 再作为提示图使用,对比效果见 assets/demo/crop_and_resize_cmp.jpg。
六、结构可控生成:ControlNet 与 T2I-Adapter
ip_adapter_controlnet_demo_new.ipynb 展示了「图像提示 + 结构控制」的组合用法:用 ControlNet 提供深度图 / 姿态等结构约束,用 IP-Adapter 提供内容与风格参考。关键代码:
from diffusers import StableDiffusionControlNetPipeline, DDIMScheduler, AutoencoderKL, ControlNetModel
from ip_adapter import IPAdapter
controlnet_model_path = "lllyasviel/control_v11f1p_sd15_depth"
controlnet = ControlNetModel.from_pretrained(controlnet_model_path, torch_dtype=torch.float16)
pipe = StableDiffusionControlNetPipeline.from_pretrained(
base_model_path,
controlnet=controlnet,
torch_dtype=torch.float16,
scheduler=noise_scheduler,
vae=vae,
feature_extractor=None,
safety_checker=None,
)
ip_model = IPAdapter(pipe, image_encoder_path, ip_ckpt, device)
images = ip_model.generate(pil_image=image, image=depth_map, num_samples=4,
num_inference_steps=50, seed=42)
Notebook 中分别演示了 Depth(control_v11f1p_sd15_depth) 与 OpenPose(control_v11p_sd15_openpose) 两个 ControlNet 模型;OpenPose 示例还传入 width=512, height=768 生成非方形尺寸。此外,ip_adapter_t2i-adapter_demo.ipynb 演示了与 T2I-Adapter 的组合。其底层原理即 2.3 节所述的 CNAttnProcessor——ControlNet 分支只消费文本 token,图像提示由 UNet 主分支独立注入,两者互不干扰。
七、多模态提示与细粒度特征(IP-Adapter Plus)
7.1 多模态提示(Multimodal Prompts)
ip_adapter_multimodal_prompts_demo.ipynb 演示把多张参考图与文本组合成多模态提示:调用 generate(pil_image=[img1, img2, ...], prompt=..., scale=0.5~0.6),num_prompts 自动取图片数量,每张图的嵌入经投影后拼接到文本嵌入序列上。README 建议这类场景将 scale 设为 0.5 左右。
7.2 IP-Adapter Plus:细粒度特征版本
ip_adapter-plus_demo.ipynb 使用 IPAdapterPlus,初始化时需显式传入 num_tokens=16:
from ip_adapter import IPAdapterPlus
image_encoder_path = "models/image_encoder"
ip_ckpt = "models/ip-adapter-plus_sd15.bin"
ip_model = IPAdapterPlus(pipe, image_encoder_path, ip_ckpt, device, num_tokens=16)
images = ip_model.generate(pil_image=image, num_samples=4,
num_inference_steps=50, seed=42,
prompt="best quality, high quality, wearing a hat on the beach",
scale=0.6)
Plus 版的差异在于(源码 ip_adapter/ip_adapter.py):
- 投影模型由
ImageProjModel换为Resampler(dim=1024, depth=4, dim_head=64, heads=12, num_queries=num_tokens=16, ff_mult=4),可学习查询从 CLIP 倒数第二层隐藏状态中抽取细粒度特征; get_image_embeds使用output_hidden_states=True的hidden_states[-2]而非最后一层的 pooled 嵌入,保留更多空间细节;- 无条件分支同样基于零图像输入计算。
人脸提示版本见 ip_adapter-plus-face_demo.ipynb(models/ip-adapter-plus-face_sd15.bin),以人脸图像作为提示控制身份一致性;更新的人脸版本见 ip_adapter-full-face_demo.ipynb,对应 IPAdapterFull(使用 MLPProjModel,输入为 CLIP 隐藏状态)。
八、SDXL 支持:IP-Adapter XL 与新版改进
8.1 SDXL 推理
ip_adapter_sdxl_demo.ipynb 演示了 SDXL 1.0 上的图像变体:
from ip_adapter import IPAdapterXL
base_model_path = "stabilityai/stable-diffusion-xl-base-1.0"
image_encoder_path = "sdxl_models/image_encoder"
ip_ckpt = "sdxl_models/ip-adapter_sdxl.bin"
ip_model = IPAdapterXL(pipe, image_encoder_path, ip_ckpt, device)
images = ip_model.generate(pil_image=image, num_samples=num_samples,
num_inference_steps=30, seed=420,
prompt="best quality, high quality, wearing sunglasses on the beach",
scale=0.6)
从源码看,IPAdapterXL.generate 会额外获取 SDXL 特有的 pooled_prompt_embeds / negative_pooled_prompt_embeds 并传给底层管道(ip_adapter/ip_adapter.py)。SDXL 的 Plus 版本由 IPAdapterPlusXL 提供,其 Resampler 配置为 dim=1280, depth=4, dim_head=64, heads=20。SDXL 结构可控生成见 ip_adapter_sdxl_controlnet_demo.ipynb,README 还给出了与商业方案 Reimagine XL 的对比图(assets/demo/sdxl_cmp.jpg)。
8.2 2023.9.8 新版改进
README.md 在 SDXL 一节明确列出了新版的两次关键改进:
- 图像编码器切换为 CLIP-ViT-H:改用
OpenCLIP-ViT-H-14替代OpenCLIP-ViT-bigG-14。尽管 ViT-bigG 远大于 ViT-H,实验未发现显著差异,而更小的模型能降低推理阶段显存占用; - 更快更好的训练配方:旧版直接在 1024×1024 分辨率训练效率很低;新版采用两阶段策略——先在 512×512 分辨率预训练,再用多尺度策略微调(README 提示该思路或可加速 ControlNet 的训练)。
8.3 自定义 SDXL 管道
ip_adapter/custom_pipelines.py 提供了 StableDiffusionXLCustomPipeline(继承 diffusers 的 StableDiffusionXLPipeline),支持 control_guidance_start / control_guidance_end:在去噪循环中按步数比例动态 set_scale(0.0) 或恢复 conditioning_scale,用于精细控制结构条件与图像提示的作用区间。
九、训练自己的 IP-Adapter
9.1 数据准备与启动命令
仓库于 2023/8/29 发布训练代码(tutorial_train.py),SD 1.5 训练流程如下。训练需要安装 accelerate,并将自有数据集整理为 JSON 文件,格式为字典列表:
[{"image_file": "1.png", "text": "A dog"}, ...]
image_file 相对于 --data_root_path 指向的图片根目录。随后用 accelerate launch 启动多卡混合精度训练(命令原文见 README.md):
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
9.2 关键训练参数
结合 tutorial_train.py 的 parse_args,各参数含义与默认值如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--pretrained_model_name_or_path |
必填 | 基础模型路径或 Hugging Face 标识 |
--pretrained_ip_adapter_path |
None |
预训练 IP-Adapter 权重;不填则随机初始化 |
--data_json_file |
必填 | 训练数据 JSON 文件 |
--data_root_path |
必填 | 图片根目录 |
--image_encoder_path |
必填 | CLIP 图像编码器路径 |
--output_dir |
"sd-ip_adapter" |
输出目录 |
--resolution |
512 |
输入图像分辨率 |
--learning_rate |
1e-4 |
学习率 |
--weight_decay |
1e-2 |
权重衰减 |
--num_train_epochs |
100 |
训练轮数 |
--train_batch_size |
8 |
每设备批大小 |
--dataloader_num_workers |
0 |
数据加载进程数 |
--save_steps |
2000 |
每 N 步保存一次 checkpoint |
--mixed_precision |
None |
no / fp16 / bf16(bf16 需 PyTorch ≥1.10 与 Ampere GPU) |
--report_to |
"tensorboard" |
日志平台(tensorboard / wandb / comet_ml / all) |
9.3 训练原理:只训新增参数
从 tutorial_train.py 的 main 可以看出,训练时冻结 UNet、VAE、文本编码器与图像编码器(requires_grad_(False)),优化器只覆盖 image_proj_model 与 adapter_modules 两组新增参数(itertools.chain(...)),这正是「适配器」方法的低成本所在。
值得注意的细节:
- 随机丢弃策略:
MyDataset按t_drop_rate / i_drop_rate / ti_drop_rate(默认均 0.05)随机丢弃文本或图像条件(置空文本 / 图像嵌入置零),与训练 CLIP 时类似,用于增强条件解耦与泛化; - 初始化对齐:新建的
IPAttnProcessor会用原 UNet 对应层的to_k / to_v权重初始化to_k_ip / to_v_ip("to_k_ip.weight": unet_sd[layer_name + ".to_k.weight"]); - IPAdapter 前向:
forward中把image_proj_model(image_embeds)得到的ip_tokens与文本encoder_hidden_states在序列维拼接,再送入 UNet 预测噪声,损失为 MSE; - checkpoint 校验:
load_from_checkpoint通过参数和的变化断言权重确实被更新。
Plus 版训练(tutorial_train_plus.py)额外提供 --num_tokens(默认 16),投影模型使用 Resampler(num_queries=args.num_tokens, ...),并将 IPAttnProcessor 的 num_tokens 同步设为该值。SDXL 训练(tutorial_train_sdxl.py)则引入第二个分词器/文本编码器(tokenizer_2、CLIPTextModelWithProjection),并处理 SDXL 的 micro-conditioning 元数据(original_size、crop_coords_top_left、target_size),默认分辨率为 1024。
9.4 权重转换:从训练 checkpoint 到推理格式
训练完成后,checkpoint(如 checkpoint-50000/pytorch_model.bin)的键名前缀是 unet.、image_proj_model. 与 adapter_modules.。推理格式需要转换为只含 image_proj 与 ip_adapter 两个键的 ip_adapter.bin(代码见 README.md):
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")
转换后的 ip_adapter.bin 可直接交给 IPAdapter(pipe, image_encoder_path, ip_ckpt, device) 使用。
十、模型格式与加载细节
IPAdapter.load_ip_adapter(ip_adapter/ip_adapter.py)根据扩展名区分两种格式:
.safetensors:用safetensors.safe_open读取,自动剥离image_proj./ip_adapter.前缀(仓库于 2023/11/02 起支持 safetensors);- 其他(
.bin):用torch.load(map_location="cpu")加载。
两种格式的状态字典结构一致,均包含 image_proj(加载进 self.image_proj_model)与 ip_adapter(加载进 ModuleList(self.pipe.unet.attn_processors.values()))两个键,因此官方发布权重同时提供 .bin 与 .safetensors 两种形式时可互换使用。
十一、生态集成与版本演进
README.md 记录了 IP-Adapter 的生态落地与版本时间线:
- 2023/8/16 首发代码与模型;8/18 支持 SDXL 1.0;8/23 发布 Plus(细粒度)版;8/29 开源训练代码;8/30 发布人脸提示版;
- 2023/9/05 起被 WebUI(sd-webui-controlnet)与 ComfyUI 生态支持;9/08 更新 SDXL 新版(ViT-H + 两阶段训练);
- 2023/11/02 支持 safetensors;11/05 支持与 Kandinsky 2.2 Prior 结合的文本到图像演示(ip_adapter_t2i_demo.ipynb);11/10 更新人脸版(ip_adapter-full-face_demo.ipynb);
- 2023/11/22 官方整合进 Diffusers 库;
- 2023/12 起 陆续发布实验性 FaceID 系列(FaceID / FaceID-Plus / FaceID-PlusV2 / SDXL 版 / Portrait),对应 ip_adapter_faceid.py、ip_adapter_faceid_separate.py 与 attention_processor_faceid.py。
此外,第三方生态(WebUI、ComfyUI 及其 Plus 插件、InvokeAI、AnimateDiff prompt travel、Diffusers_IPAdapter 多图扩展、InstantStyle 风格迁移等)均已接入该适配器,进一步印证了其「轻量、可组合、可迁移」的设计目标。
引用
若 IP-Adapter 对你的研究或应用有帮助,请按以下 BibTeX 引用(来源 README.md):
@article{ye2023ip-adapter,
title={IP-Adapter: Text Compatible Image Prompt Adapter for Text-to-Image Diffusion Models},
author={Ye, Hu and Zhang, Jun and Liu, Sibo and Han, Xiao and Yang, Wei},
booktitle={arXiv preprint arxiv:2308.06721},
year={2023}
}
使用提示:本项目鼓励合法合规地使用 AI 图像生成能力,使用者需遵守当地法律法规并负责任地使用工具,开发者不对用户的潜在滥用行为承担责任。




