网站导航
> 技术文档 > 手把手搭建SDWebUI：从源码到运行，完整指南

手把手搭建SDWebUI：从源码到运行，完整指南

网友: 技术文档 2025-07-30 13:52:18

笔者在2025.4手动搭建了SDWebUI，方便后续二次开发。本项目基于Gradio实现。

项目原地址：Github Star 151K；参考教程：Stable Diffusion]webui部署(Linux)

笔者使用的版本：

  • CUDA 11.8、torch 2.0.1、xformers 0.0.23.post1（自动安装无需指定版本）

一、Stable-Diffusion-WebUI（下面简称SDWebUI）

#1. SDWebUI的概念

SDWebUI是一个基于StableDiffusion扩散模型的开源WebUI，旨在简化和增强使用Stable Diffusion模型进行图像生成的体验。

  • 简化：让用户无需代码，直接与生成模型交互。
  • 增强：结合了超分重建、ControNet、Lora等模型来增强生成效果。

笔者的搭建界面如下图所示：

手把手搭建SDWebUI：从源码到运行，完整指南

#2. 搭建流程图

#mermaid-svg-ZBp3MwC3kxRgK8yb {font-family:\"trebuchet ms\",verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-svg-ZBp3MwC3kxRgK8yb .error-icon{fill:#552222;}#mermaid-svg-ZBp3MwC3kxRgK8yb .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ZBp3MwC3kxRgK8yb .edge-thickness-normal{stroke-width:2px;}#mermaid-svg-ZBp3MwC3kxRgK8yb .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ZBp3MwC3kxRgK8yb .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ZBp3MwC3kxRgK8yb .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ZBp3MwC3kxRgK8yb .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ZBp3MwC3kxRgK8yb .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ZBp3MwC3kxRgK8yb .marker.cross{stroke:#333333;}#mermaid-svg-ZBp3MwC3kxRgK8yb svg{font-family:\"trebuchet ms\",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ZBp3MwC3kxRgK8yb .label{font-family:\"trebuchet ms\",verdana,arial,sans-serif;color:#333;}#mermaid-svg-ZBp3MwC3kxRgK8yb .cluster-label text{fill:#333;}#mermaid-svg-ZBp3MwC3kxRgK8yb .cluster-label span{color:#333;}#mermaid-svg-ZBp3MwC3kxRgK8yb .label text,#mermaid-svg-ZBp3MwC3kxRgK8yb span{fill:#333;color:#333;}#mermaid-svg-ZBp3MwC3kxRgK8yb .node rect,#mermaid-svg-ZBp3MwC3kxRgK8yb .node circle,#mermaid-svg-ZBp3MwC3kxRgK8yb .node ellipse,#mermaid-svg-ZBp3MwC3kxRgK8yb .node polygon,#mermaid-svg-ZBp3MwC3kxRgK8yb .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ZBp3MwC3kxRgK8yb .node .label{text-align:center;}#mermaid-svg-ZBp3MwC3kxRgK8yb .node.clickable{cursor:pointer;}#mermaid-svg-ZBp3MwC3kxRgK8yb .arrowheadPath{fill:#333333;}#mermaid-svg-ZBp3MwC3kxRgK8yb .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ZBp3MwC3kxRgK8yb .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ZBp3MwC3kxRgK8yb .edgeLabel{background-color:#e8e8e8;text-align:center;}#mermaid-svg-ZBp3MwC3kxRgK8yb .edgeLabel rect{opacity:0.5;background-color:#e8e8e8;fill:#e8e8e8;}#mermaid-svg-ZBp3MwC3kxRgK8yb .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ZBp3MwC3kxRgK8yb .cluster text{fill:#333;}#mermaid-svg-ZBp3MwC3kxRgK8yb .cluster span{color:#333;}#mermaid-svg-ZBp3MwC3kxRgK8yb div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\"trebuchet ms\",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ZBp3MwC3kxRgK8yb :root{--mermaid-font-family:\"trebuchet ms\",verdana,arial,sans-serif;} Download Project Download sub-projects Download Checkpoints Test Start Create Env Install torch Install other lib Config && Install Plug-in

二、开发环境搭建

Step1.下载源码：SDWebUI

git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.gitmv stable-diffusion-webui sd-webuicd sd-webui && mkdir repositories

SDWeb仅仅是外层界面，核心功能存放在repositories中进行管理

Step2.下载SDWebUI的依赖项目

1️⃣StableDiffusion
git clone https://github.com/Stability-AI/stablediffusion.git ./repositories/stable-diffusion-stability-aigit -C ./repositories/stable-diffusion-stability-ai checkout cf1d67a6fd5ea1aa600c4df58e5b47da45f6bdbf# 切换到合适的版本，预防兼容性问题
2️⃣generative-models
git clone https://github.com/Stability-AI/generative-models.git ./repositories/generative-modelsgit -C ./repositories/generative-models checkout 45c443b316737a4ab6e40413d7794a7f5657c19f
3️⃣k-diffusion
git clone https://github.com/crowsonkb/k-diffusion.git ./repositories/k-diffusiongit -C ./repositories/k-diffusion checkout ab527a9a6d347f364e3d185ba6d714e22d80cb3c
4️⃣CodeFormer
git clone https://github.com/sczhou/CodeFormer.git ./repositories/CodeFormergit -C ./repositories/CodeFormer checkout c5b4593074ba6214284d6acd5f1719b6c5d739af
5️⃣BLIP
git clone https://github.com/salesforce/BLIP.git ./repositories/BLIPgit -C ./repositories/BLIP checkout 48211a1594f1321b00f14c9f7a5b4813144b2fb9
6️⃣stable-diffusion-webui-assets
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui-assets.git ./repositories/stable-diffusion-webui-assets

Step3.创建虚拟环境

conda create -n sd-webui python=3.10conda activate sd-webuipip install torch==2.0.1 torchvision==0.15.2 --extra-index-url https://download.pytorch.org/whl/cu118pip install tb-nightlypip install -r requirements_versions.txtpip install https://github.com/openai/CLIP/archive/d50d76daa670286dd6cacf3bcd80b5e4823fc8e1.zip # 将CLIP项目安装成python库包pip install https://github.com/mlfoundations/open_clip/archive/bb6e834e9c70d9c27d0dc3ecedeebeaeb1ffad6b.zippip install xformers --index-url https://download.pytorch.org/whl/cu118pip install ngrokpip install -r repositories/CodeFormer/requirements.txt# 后续Bug的处理pip install open-clip-torch==2.20.0

三、配置预训练权重

#1. 下载预训练权重（需要翻墙）

1️⃣v1.5版本的权重

https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5

2️⃣v2版本的权重

https://huggingface.co/stabilityai/stable-diffusion-2-1

#2. 下载后放到./models/Stable-diffusion/下即可在webui中调用

如下图所示：

手把手搭建SDWebUI：从源码到运行，完整指南

四、测试运行WebUI

# 进入项目根路径cd sd-webui# 测试启动python webui.py# 默认只允许本地访问(127.0.0.1/localhost)
其他参数介绍：（仅介绍笔者常用的）
  • --listen：监听所有网络接口(0.0.0.0)
  • --port：端口
  • --xformers：使用 xformers 优化时间和空间，推荐使用
  • --enable-insecure-extension-access：运行网络中所有用户安装插件（后面“安装常用扩展”中有用到）
启动后的网页如下图所示：

手把手搭建SDWebUI：从源码到运行，完整指南

五、SDWebUI的基础模块配置

#1.高清修复模块Hires.fix的了解

该模块额外增加了一个类超分重建的过程。

  • 上采样放大图片：使用上采样算法如 R-ESRGAN对SD生成图片进行上采样放大到目标尺寸（如1024×1024）。
  • 局部重绘：扩散模型（U-Net）对上采样图片进行去噪，补充细节（受 Denoising strength 控制）。
  • 最终解码：修复后的潜变量通过 VAE 解码器输出高清图像（如 1024×1024）。
关键参数 作用 推荐值 Hires steps 第二阶段的重绘步数（细节优化强度） 10~20（过高可能过拟合） Denoising strength 重绘时的噪声强度（值越高，改动越大） 0.3~0.5（平衡细节与稳定） Upscaler 上采样算法（选择不同算法影响细节风格） R-ESRGAN 4x+（通用） Upscale by 放大倍数（如2x表示512→1024） 1.5~2.0（视显存而定）
  • Hires steps,Denoising strength,Upscale by的值极大程度影响处理速度，值越大速度越慢。
  • Hires steps若设置为0，则程序默认为20（猜测是这样，还得看看代码）
  • Denoising strength=0 => 普通超分（仅放大，无重绘）。
    Denoising strength>0.6 => 大幅度改变原图内容（类似图生图）。

#2. 如何开启VAE选项卡？

Step1. 将VAE权重文件放到项目根目录下的models/VAE
Step2. Setting - User interface，在Quicksettings list中加入sd_vae，如下图所示。

手把手搭建SDWebUI：从源码到运行，完整指南

Step3. 重启命令行服务，然后就可以在网页中选择vae

如下图所示：
手把手搭建SDWebUI：从源码到运行，完整指南

六、安装常用扩展

#1.安装ControlNet扩展（通过“Extensions”）

1️⃣安装
增加启动参数--enable-insecure-extension-access（知晓风险再使用,该参数是允许网络中所有用户安装插件），然后：

  1. Extensions - Install from URL

  2. 将项目路径https://github.com/Mikubill/sd-webui-controlnet粘贴到URL for extension\'s git repository并安装（建议该浏览器进行翻墙）

  3. 等待消息\"Installed into sd-webui\\extensions\\sd-webui-controlnet. Use Installed tab to restart\"即安装完成，然后在Installed选项卡中，点击\"Check for updates\"与Apply and quit

  4. 最后，重启sd-webui包括命令行界面。当命令行出现以下信息即启动成功：

    ControlNet preprocessor location: /home/xx/sd-webui/extensions/sd-webui-controlnet/annotator/downloads2025-04-09 10:01:30,189 - ControlNet - INFO - ControlNet v1.1.455Loading weights [7c819b6d13] from /home/xx/sd-webui/models/Stable-diffusion/majicmixRealistic_v7.safetensors2025-04-09 10:01:30,361 - ControlNet - INFO - ControlNet UI callback registered.

​ 下载好的controlnet插件位于./extensions/sd-webui-controlnet

然后就可以在网页中选择ControlNet了，如下图所示：

手把手搭建SDWebUI：从源码到运行，完整指南

2️⃣添加ControlNet的预处理器文件和模型文件

预处理器文件的路径：sd-webui/extensions/sd-webui-controlnet/annotator（默认有几十个了）

模型文件的路径：sd-webui/models/ControlNet

#2. 安装model-converter扩展

增加启动参数--enable-insecure-extension-access（谨慎使用,该参数是允许网络中所有用户安装插件），然后：

  1. Extensions - Install from URL

  2. 将项目路径https://github.com/Mikubill/sd-webui-controlnet粘贴到URL for extension\'s git repository并安装（建议该浏览器进行翻墙）

  3. 等待消息\"Installed into sd-webui\\extensions\\sd-webui-controlnet. Use Installed tab to restart\"即安装完成，然后在Installed选项卡中，点击\"Check for updates\"与Apply and quit

  4. 最后，重启sd-webui包括命令行界面。

七、Bug汇总处理

Bug处理#1.

现象：运行中，在控制台跳出无法启用xformers

/home/xx/anaconda3/envs/sd-webui/lib/python3.10/site-packages/timm/models/layers/__init__.py:48: FutureWarning: Importing from timm.models.layers is deprecated, please import via timm.layers warnings.warn(f\"Importing from {__name__} is deprecated, please import via timm.layers\", FutureWarning)No module \'xformers\'. Proceeding without it.

原因：版本冲突引起的，该问题会导致无法启用xformers，引起模型推理训练效率变低。

解决：xformers要同时与torch版本和cuda版本相匹配，才能安装成功。所以直接一起安装了，让pip处理依赖关系。

如下面笔者安装的命令：

# 先卸载现有版本pip uninstall torch torchvision torchaudio xformers# 安装（笔者是cuda 11.8，所以cu118）pip install torch torchvision torchaudio xformers --index-url https://download.pytorch.org/whl/cu118

Bug处理#2.

现象：增加了XL模型文件后，读取该模型文件在控制台出现Model config for ViT-bigG-14 not found.

原因：缺少依赖库。

解决：pip install open-clip-torch==2.20.0

Bug处理#3.

现象：控制台跳出找不到模块controlnet_aux

from controlnet_aux import “SamDetector”ModuleNotFoundError: No module named \'controlnet_aux\'

原因：缺少依赖库。

解决：pip install controlnet-aux

Bug处理#4：

现象：

在WebUI上生成图片时，控制台出现：NansException: A tensor with all NaNs was produced in Unet

解决：

  • 在WebUI的Settings里，勾上Upcast cross attention layer to float32
    手把手搭建SDWebUI：从源码到运行，完整指南

Bug处理#5

现象：在WebUI上加载模型权重时，出现：

OSError: Can\'t load tokenizer for \'openai/clip-vit-large-patch14\'. If you were trying to load it from \'https\\://huggingface.co/models\', make sure you don\'t have a local directory with the same name. Otherwise, make sure \'openai/clip-vit-large-patch14\' is the correct path to a directory containing all relevant files for a CLIPTokenizer tokenizer.

解决：

  1. 在huggingface点击Clone repository下载库
    手把手搭建SDWebUI：从源码到运行，完整指南

  2. 将下载到的clip-vit-large-patch14放到项目的新建文件夹openai下

  3. 重启webui.py并重新加载模型权重文件即可。

到底咯，如果这篇文章对您有些许帮助，请帮忙点个赞👍或收个藏📃。您的支持是我继续创作的动力💪！

当暴风雨⚡️过去，你不会记得自己是如何度过的，你甚至不确定暴风雨是否真的结束了。但你已经不再是当初走进暴风雨的那个人了，这就是暴风雨的意义💪。

网络标签：

相关问题