发布

• [2024/12/10] 🎉 ResAdapter 被 AAAI 2025 接收。
• [2024/04/07] 🔥 我们在 Huggingface 上发布了官方 gradio space。
• [2024/04/05] 🔥 我们发布了 resadapter_v2 权重。
• [2024/03/30] 🔥 我们发布了 ComfyUI-ResAdapter。
• [2024/03/28] 🔥 我们发布了 resadapter_v1 权重。
• [2024/03/04] 🔥 我们发布了 arxiv 论文。

快速入门

我们提供了一个独立的 示例代码，帮助您快速使用 resadapter 与扩散模型结合。

# pip install diffusers, transformers, accelerate, safetensors, huggingface_hub
import torch
from torchvision.utils import save_image
from safetensors.torch import load_file
from huggingface_hub import hf_hub_download
from diffusers import AutoPipelineForText2Image, DPMSolverMultistepScheduler

generator = torch.manual_seed(0)
prompt = "穿着破旧机甲服的肌肉发达、留着胡子的男子人像照片，浅景深散景，细节丰富，钢铁质感，优雅，焦点锐利，柔和光线，色彩鲜艳"
width, height = 640, 384

# 加载基线管道
model_name = "lykon-models/dreamshaper-xl-1-0"
pipe = AutoPipelineForText2Image.from_pretrained(model_name，torch_dtype=torch.float16，variant="fp16").to("cuda")
pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config，use_karras_sigmas=True，algorithm_type="sde-dpmsolver++")

# 基线管道推理
image = pipe(prompt，width=width，height=height，num_inference_steps=25，num_images_per_prompt=4，output_type="pt").images
save_image(image，f"image_baseline.png"，normalize=True，padding=0)

# 加载 resadapter 用于基线
resadapter_model_name = "resadapter_v1_sdxl"
pipe.load_lora_weights(
    hf_hub_download(repo_id="jiaxiangc/res-adapter"，subfolder=resadapter_model_name，filename="pytorch_lora_weights.safetensors")，
    adapter_name="res_adapter"，
) # 加载 lora 权重
pipe.set_adapters(["res_adapter"]，adapter_weights=[1.0])
pipe.unet.load_state_dict(
    load_file(hf_hub_download(repo_id="jiaxiangc/res-adapter"，subfolder=resadapter_model_name，filename="diffusion_pytorch_model.safetensors"))，
    strict=False，
) # 加载 norm 权重

# resadapter 管道推理
image = pipe(prompt，width=width，height=height，num_inference_steps=25，num_images_per_prompt=4，output_type="pt").images
save_image(image，f"image_resadapter.png"，normalize=True，padding=0)

下载

模型

我们已发布所有 resadapter 权重，您可以从 Huggingface 下载 resadapter 模型。以下是我们的 resadapter 模型卡片：

模型	参数	分辨率范围	宽高比范围	链接
resadapter_v2_sd1.5	0.9M	128 <= x <= 1024	0.28 <= r <= 3.5	下载
resadapter_v2_sdxl	0.5M	256 <= x <= 1536	0.28 <= r <= 3.5	下载
resadapter_v1_sd1.5	0.9M	128 <= x <= 1024	0.5 <= r <= 2	下载
resadapter_v1_sd1.5_extrapolation	0.9M	512 <= x <= 1024	0.5 <= r <= 2	下载
resadapter_v1_sd1.5_interpolation	0.9M	128 <= x <= 512	0.5 <= r <= 2	下载
resadapter_v1_sdxl	0.5M	256 <= x <= 1536	0.5 <= r <= 2	下载
resadapter_v1_sdxl_extrapolation	0.5M	1024 <= x <= 1536	0.5 <= r <= 2	下载
resadapter_v1_sdxl_interpolation	0.5M	256 <= x <= 1024	0.5 <= r <= 2	下载

提示1：我们根据 controlnet 更新了 resadapter 的命名格式。

提示2：如果您想将 resadapter 与个性化扩散模型一起使用，应从 CivitAI 下载。

提示3：如果您想将 resadapter 与 ip-adapter、controlnet 和 lcm-lora 一起使用，应从 Huggingface 下载。

提示4：这里有一份 安装指南，用于准备环境和下载模型。

推理

如果您想在我们的推理脚本中生成图像，应按照安装指南安装依赖库并下载相关模型。填写完示例配置文件后，即可直接运行此脚本。

python main.py --config /path/to/file

基于ResAdapter与个性化模型的文生图

基于ResAdapter与ControlNet的图生图

基于ResAdapter与ControlNet-XL的图生图

基于ResAdapter与IP-Adapter的人脸风格化

基于ResAdapter与LCM-LoRA的加速

社区资源

Gradio

• Replicate网站：由@Chenxi提供的bytedance/res-adapter
• Huggingface空间：
  • jiaxiangc/res-adapter（官方空间）
  • ameerazam08/Res-Adapter-GPU-Demo，由@Ameer Azam提供

Huggingface空间中关于ResAdapter的文生图示例。更多信息请参见jiaxiangc/res-adapter。

ComfyUI

• jiaxiangc/ComfyUI-ResAdapter（官方ComfyUI节点）
• blepping/ComfyUI-ApplyResAdapterUnet，由@blepping提供

ComfyUI-ResAdapter的文生图示例。更多关于lcm-lora、controlnet和ipadapter的示例可在ComfyUI-ResAdapter中找到。

https://github.com/jiaxiangc/ComfyUI-ResAdapter/assets/162297627/82453931-23de-4f72-8a9c-1053c4c8d81a

WebUI

我正在学习如何制作WebUI扩展。

本地Gradio演示

运行以下脚本：

# 使用pip安装peft、gradio以及httpx==0.23.3
python app.py

使用技巧

1. 如果对插值生成的图像不满意，可尝试将ResAdapter的alpha值调至1.0。
2. 若对外推生成的图像不甚满意，建议将ResAdapter的alpha值设为0.3至0.7之间。
3. 如发现生成图像存在风格冲突，可适当降低ResAdapter的alpha值。
4. 若发现ResAdapter与其他加速LoRA不兼容，可将ResAdapter的alpha值调整至0.5至0.7之间。

致谢

• ResAdapter 由字节跳动公司的 AutoML 团队开发，版权所有。
• 感谢 HuggingFace Gradio 团队提供的免费 GPU 支持！
• 感谢 IP-Adapter、ControlNet、LCM-LoRA 的优秀工作。
• 感谢 @Chenxi 和 @AMEERAZAM08 提供 Gradio 演示。
• 感谢 @fengyuzzz 在 ComfyUI-ResAdapter 中支持视频演示。

星标历史

引用

如果您在研究和应用中发现 ResAdapter 非常有用，请使用以下 BibTeX 格式引用我们：

@inproceedings{cheng2025resadapter,
  title={Resadapter: 面向扩散模型的领域一致性分辨率适配器},
  author={Cheng, Jiaxiang and Xie, Pan and Xia, Xin and Li, Jiashi and Wu, Jie and Ren, Yuxi and Li, Huixia and Xiao, Xuefeng and Wen, Shilei and Fu, Lean},
  booktitle={AAAI 人工智能会议论文集},
  volume={39},
  number={3},
  pages={2438--2446},
  year={2025}
}

如有任何问题，请随时通过 jiaxiangcc@gmail.com 或 xiepan.01@bytedance.com 与我们联系。

ResAdapter 快速上手指南

ResAdapter 是一个即插即用的分辨率适配器，能够让任何扩散模型（Diffusion Models）生成与分辨率无关的高质量图像。它无需额外训练、无需增加推理步骤，也不会改变原有模型的风格。

1. 环境准备

系统要求

• 操作系统: Linux / Windows / macOS
• GPU: 推荐 NVIDIA GPU (支持 CUDA)
• Python: 3.8 或更高版本
• 显存: 建议 8GB 及以上（取决于基础模型大小）

前置依赖

请确保已安装以下 Python 库：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install diffusers transformers accelerate safetensors huggingface_hub

提示: 国内用户可使用清华或阿里镜像源加速安装，例如： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple diffusers transformers accelerate safetensors huggingface_hub

2. 安装步骤

ResAdapter 无需单独安装软件包，主要通过加载预训练权重文件（LoRA 和 UNet 权重）集成到现有的 Diffusers 流程中。

1. 克隆仓库（可选，仅用于获取示例代码）：

   git clone https://github.com/bytedance/res-adapter.git
   cd res-adapter
   

2. 模型下载： 程序运行时会自动从 Hugging Face 下载所需权重。若网络受限，可手动下载模型文件至本地。

   主要模型地址：jiaxiangc/res-adapter

   常用模型选择参考：

   • SDXL 模型: resadapter_v2_sdxl (推荐，支持分辨率 256-1536)
   • SD 1.5 模型: resadapter_v2_sd1.5 (支持分辨率 128-1024)

3. 基本使用

以下是最简单的 Python 脚本示例，展示如何在 SDXL 模型上加载并使用 ResAdapter。

代码示例

# pip install diffusers, transformers, accelerate, safetensors, huggingface_hub
import torch
from torchvision.utils import save_image
from safetensors.torch import load_file
from huggingface_hub import hf_hub_download
from diffusers import AutoPipelineForText2Image, DPMSolverMultistepScheduler

# 设置随机种子和提示词
generator = torch.manual_seed(0)
prompt = "portrait photo of muscular bearded guy in a worn mech suit, light bokeh, intricate, steel metal, elegant, sharp focus, soft lighting, vibrant colors"
width, height = 640, 384  # 任意非标准分辨率

# 1. 加载基础模型 (以 DreamShaper XL 为例)
model_name = "lykon-models/dreamshaper-xl-1-0"
pipe = AutoPipelineForText2Image.from_pretrained(model_name, torch_dtype=torch.float16, variant="fp16").to("cuda")
pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config, use_karras_sigmas=True, algorithm_type="sde-dpmsolver++")

# 2. 加载 ResAdapter 权重
# 选择对应的模型版本，此处为 SDXL v1 (v2 版本用法类似，只需更改 repo_id 和 subfolder)
resadapter_model_name = "resadapter_v1_sdxl"

# 加载 LoRA 权重
pipe.load_lora_weights(
    hf_hub_download(repo_id="jiaxiangc/res-adapter", subfolder=resadapter_model_name, filename="pytorch_lora_weights.safetensors"), 
    adapter_name="res_adapter",
) 

# 激活 Adapter
pipe.set_adapters(["res_adapter"], adapter_weights=[1.0])

# 加载 UNet 归一化权重
pipe.unet.load_state_dict(
    load_file(hf_hub_download(repo_id="jiaxiangc/res-adapter", subfolder=resadapter_model_name, filename="diffusion_pytorch_model.safetensors")),
    strict=False,
)

# 3. 开始推理
image = pipe(prompt, width=width, height=height, num_inference_steps=25, num_images_per_prompt=4, output_type="pt").images

# 保存结果
save_image(image, f"image_resadapter.png", normalize=True, padding=0)
print("生成完成！")

使用说明

• 分辨率自由: 修改 width 和 height 为任意数值（需在模型支持的范围内），ResAdapter 会自动适配，避免画面崩坏或风格漂移。
• 兼容性强: 该方法同样适用于配合 ControlNet、IP-Adapter 或 LCM-LoRA 使用，只需在加载这些插件后，按上述步骤加载 ResAdapter 即可。
• 模型版本: 请根据你使用的基础模型（SD 1.5 或 SDXL）选择对应的 resadapter_model_name 文件夹。