跳到主要内容

stable-diffusion-webui-操作手册

核对日期：2026-05-15
官方仓库：https://github.com/AUTOMATIC1111/stable-diffusion-webui

1. 适用范围​

这份手册面向本地部署和日常使用 AUTOMATIC1111/stable-diffusion-webui 的用户，覆盖安装、模型管理、启动参数、基础生图、扩展、API、安全和故障处理。

WebUI 本质上是一个基于 Gradio 的 Stable Diffusion 图形界面。它适合本地实验、提示词调试、模型/LoRA/ControlNet 工作流搭建和轻量自动化调用，不建议直接作为无鉴权的公网生产服务暴露。

2. 机器与软件准备​

2.1 推荐硬件​

场景建议配置说明
SD 1.5 基础生图NVIDIA GPU，6GB+ VRAM，16GB RAM512x512、少量 LoRA、基础高清修复较稳
SDXLNVIDIA GPU，8GB-12GB+ VRAM，16GB-32GB RAM推荐 1024x1024 起步，显存压力更高
低显存卡4GB VRAM可用 --medvram / --lowvram，速度会下降
纯 CPU不推荐官方 Wiki 明确说明可运行但非常慢
Mac / AMD / Intel可运行但路径不同需要参考对应平台安装页，NVIDIA CUDA 路径不能直接套用

2.2 必需依赖​

官方依赖页列出的核心依赖是：

  • Python 3.10.6。
  • Git。
  • 仓库代码，推荐通过 git clone 获取，便于后续 git pull 更新。

Windows 安装 Python 时勾选 Add Python to PATH。Linux 发行版应安装 python3-venv 或等价包。不要优先使用系统里更高版本的 Python，官方 Troubleshooting 明确建议以 Python 3.10.6 为主。

3. 安装方式​

3.1 Windows + NVIDIA，推荐快速包​

适合不想手动处理 Python、Git 和依赖细节的用户。

  1. 从官方说明中的 v1.0.0-pre 下载 sd.webui.zip。
  2. 解压到英文路径，例如 D:\AI\sd.webui。
  3. 双击 update.bat 更新 WebUI 到最新版本。
  4. 双击 run.bat 启动。
  5. 首次启动会下载大量依赖和模型。看到类似 Running on local URL: http://127.0.0.1:7860 后，用浏览器打开该地址。

注意：官方 NVIDIA 安装页提到 50 系列 GPU 当前需要切换到 dev 分支以使用 PyTorch 2.7 相关支持。若你是 RTX 50 系列，优先按官方 50XX 讨论帖和安装页处理。

3.2 Windows + NVIDIA，Git 克隆方式​

适合希望长期维护、自己控制更新的用户。

git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
cd stable-diffusion-webui
webui-user.bat

首次启动时脚本会创建 venv 虚拟环境并安装依赖。后续启动继续双击 webui-user.bat。

如果启动窗口一闪而过，编辑 webui-user.bat，在最后加一行：

pause

这样可以看到真实报错。

3.3 Linux + NVIDIA​

Ubuntu 24.04 示例：

sudo apt install git software-properties-common -y
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt install python3.10-venv -y
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui
cd stable-diffusion-webui
python3.10 -m venv venv
./webui.sh

如果系统已有多个 Python 版本，编辑 webui-user.sh，指定：

python_cmd="python3.10"

不要用 sudo ./webui.sh 常规启动。确实要以 root 启动时才加 -f，但这不推荐。

3.4 macOS / Apple Silicon​

Apple Silicon 不是 CUDA 路径，安装和性能参数与 NVIDIA 不同。建议单独参考官方 Wiki 的 Installation on Apple Silicon 页面。常见原则：

  • 确认 Python 版本。
  • 使用 macOS 对应依赖管理方式。
  • 不使用 NVIDIA 专用参数如 --xformers 作为默认方案。
  • 遇到 CUDA 检测错误时，按非 NVIDIA 平台说明处理，而不是硬套 Windows NVIDIA 教程。

3.5 AMD / Intel / CPU​

AMD、Intel GPU、CPU 都不是主线 NVIDIA CUDA 路径。官方 README 将 AMD、Intel、Ascend 等列为单独安装入口。CPU 可运行，但需要：

--use-cpu all --precision full --no-half --skip-torch-cuda-test

这只适合功能验证、放大/打标等低频任务，不适合正常高效出图。

4. 模型文件放置​

常用目录如下：

类型默认目录文件类型
Checkpointmodels/Stable-diffusion/.safetensors、.ckpt
VAEmodels/VAE/.safetensors、.pt
LoRAmodels/Lora/.safetensors
Embedding / Textual Inversionembeddings/.pt、.safetensors
ESRGANmodels/ESRGAN/.pth
ControlNet 扩展模型通常在扩展自己的 models 目录视扩展而定

优先使用 .safetensors 模型，降低 pickle 反序列化风险。不要从不可信来源下载模型、LoRA、VAE 或扩展。模型本身也可能携带安全风险或触发不符合预期的生成风格。

如果已有模型，可以在首次启动前放进 models/Stable-diffusion/，避免自动下载默认 SD 1.5 模型。

5. 模型去哪里找​

模型下载优先级建议是：官方来源 > Hugging Face 模型页 > Civitai 社区模型。不要只看预览图下载，必须确认模型类型、基础模型版本、文件格式、许可证和使用说明。

5.1 官方与权威来源​

来源地址适合找什么注意点
Stability AI on Hugging Facehttps://huggingface.co/stabilityaiSDXL、官方 VAE、官方基础模型注意许可证和 gated model 访问要求
RunwayML SD 1.5https://huggingface.co/runwayml/stable-diffusion-v1-5SD 1.5 基础模型较老但生态兼容性强
Hugging Face Modelshttps://huggingface.co/modelsCheckpoint、VAE、LoRA、ControlNet 模型用筛选器找 Text-to-Image、Safetensors，读 model card
Civitaihttps://civitai.com/models社区 Checkpoint、LoRA、Embedding、VAE、工作流样例质量差异大，必须检查基础模型、许可和安全提示

如果你是新手，建议先从这几类开始：

  • SD 1.5：生态最成熟，LoRA、ControlNet、插件兼容性最好，适合 6GB 显存左右机器。
  • SDXL：画质和理解能力更好，推荐 8GB-12GB+ 显存。
  • LoRA：不要一开始下载太多，先围绕一个 checkpoint 建立稳定参数。

5.2 在 Civitai 怎么筛选​

Civitai 是最常用的社区模型站，但也最需要筛选。下载前看这几项：

页面字段你要确认什么
Model typeCheckpoint 放 models/Stable-diffusion/；LoRA 放 models/Lora/；Textual Inversion 放 embeddings/；VAE 放 models/VAE/
Base modelSD 1.5、SDXL 1.0、Pony、Illustrious 等。基础模型不一致时，Prompt 和 LoRA 往往不能通用
File format优先 .safetensors，谨慎使用 .ckpt / .pt
License是否允许商用、再分发、生成服务、合并模型
Trigger wordsLoRA / Embedding 常需要触发词
Recommended settings推荐采样器、步数、CFG、分辨率、VAE
User images看真实用户返图，不只看作者精选图
Version下载明确版本，不要混淆 v1、v2、inpainting、fp16、pruned 等文件

Civitai 下载后的常见放置方式：

stable-diffusion-webui/
  models/
    Stable-diffusion/
      realistic-xxx-v1.safetensors
    Lora/
      clothing-style-v2.safetensors
    VAE/
      vae-ft-mse-840000-ema-pruned.safetensors
  embeddings/
    bad-hands-5.pt

放好后在 WebUI 顶部 checkpoint 下拉框旁点刷新，或重启 WebUI。

5.3 在 Hugging Face 怎么下载​

Hugging Face 更适合找官方模型、研究模型、ControlNet 模型和许可证更清晰的模型。下载前看：

  • Model card：用途、限制、许可证、基础模型。
  • Files and versions：是否有单文件 .safetensors。
  • License：例如 OpenRAIL、OpenRAIL++、CreativeML OpenRAIL-M 或作者自定义协议。
  • 模型结构：有些是 Diffusers 目录结构，不是 WebUI 可直接选择的单文件 checkpoint。

WebUI 最省事的是下载单文件：

*.safetensors
*.ckpt

如果页面只有这些目录：

unet/
vae/
text_encoder/
tokenizer/
scheduler/
model_index.json

那通常是 Diffusers 格式，不能简单复制整个目录到 models/Stable-diffusion/ 当 checkpoint 用。你需要找该模型是否提供 .safetensors checkpoint 版本，或者使用转换脚本/其他支持 Diffusers 的工具链。

5.4 推荐先下载哪些模型​

不要一开始囤几十个模型。建议按用途各选一个稳定模型：

用途推荐类型说明
通用练习SD 1.5 checkpoint速度快、教程多、LoRA 兼容性好
高质量通用图SDXL checkpoint适合更高分辨率和更自然的画面
人像摄影Realistic checkpoint + 对应 VAE注意肖像权和许可
二次元Anime checkpoint + 少量 LoRA强依赖模型推荐参数
局部风格/角色/服装LoRA必须匹配基础模型版本
结构控制ControlNet 模型需要安装 ControlNet 扩展

如果你只想马上跑通，最小集合是：

  1. 一个 SD 1.5 或 SDXL checkpoint。
  2. 一个匹配的 VAE，若模型说明写明“内置 VAE”则可以先不下载。
  3. 暂时不装 LoRA，先确认基础出图稳定。

5.5 下载安全检查​

下载模型后建议做这几件事：

  1. 优先选择 .safetensors。
  2. 对照页面提供的 SHA256 / hash，确认文件没有损坏或被替换。
  3. 不从网盘搬运、论坛附件、二次转载链接下载高风险模型。
  4. 不运行模型包里附带的未知脚本。
  5. 商用前确认许可证，尤其是人物、品牌、艺术家风格、NSFW、训练素材来源相关限制。
  6. 模型文件很大，建议单独建立 models-library/ 归档，并用 --ckpt-dir、--lora-dir 指向共享目录，避免重复占用磁盘。

示例：

./webui.sh --ckpt-dir /data/sd-models/checkpoints --lora-dir /data/sd-models/loras

Windows 可在 webui-user.bat 中写：

set COMMANDLINE_ARGS=--ckpt-dir D:\AI\models\checkpoints --lora-dir D:\AI\models\loras

6. 启动与配置​

6.1 启动入口​

系统启动脚本
Windowswebui-user.bat 或快速包里的 run.bat
Linux / macOS./webui.sh

启动成功后默认访问：

http://127.0.0.1:7860

6.2 推荐配置位置​

不要直接改主启动脚本里的复杂逻辑。官方推荐通过：

  • Windows：webui-user.bat
  • Linux/macOS：webui-user.sh

配置环境变量和启动参数。

Windows 示例：

set COMMANDLINE_ARGS=--autolaunch --update-check

Linux/macOS 示例：

export COMMANDLINE_ARGS="--autolaunch --update-check"

6.3 常用启动参数​

参数用途使用建议
--autolaunch启动后自动打开浏览器本机使用推荐
--update-check启动时检查 WebUI 更新长期使用推荐
--xformers启用 xFormers 优化NVIDIA 部分显卡可尝试
--opt-sdp-attentionPyTorch 2 的注意力优化xFormers 不稳定时可试
--medvram中等低显存优化4GB-6GB 显存常用
--lowvram极低显存优化更省显存但明显变慢
--no-half-vaeVAE 不用半精度遇到黑图/NaN 可试
--ckpt-dir PATH指定模型目录多项目共享模型时推荐
--lora-dir PATH指定 LoRA 目录多项目共享 LoRA 时推荐
--listen监听局域网地址只在可信网络使用
--port 7861指定端口多实例运行时使用
--share创建 Gradio 公网链接临时演示可用，必须加鉴权
--gradio-auth user:passUI 鉴权远程访问必须配置
--api启用 API自动化调用时使用
--api-auth user:passAPI 鉴权API 远程访问必须配置
--nowebui只启动 API服务化调用时使用

安全建议：

  • 不要把 --listen、--share、--api 无鉴权暴露到公网。
  • 不要长期启用 --enable-insecure-extension-access。
  • 不要在公开环境启用 --allow-code。
  • 远程访问至少配置 --gradio-auth / --api-auth，更稳妥的方式是放在 VPN 或反向代理鉴权后面。

7. 基础使用流程​

7.1 txt2img 文生图​

  1. 打开 txt2img。
  2. 在 Prompt 输入你想要的画面。
  3. 在 Negative prompt 输入不想出现的内容。
  4. 选择模型 Checkpoint。
  5. 设置采样器、步数、尺寸、Batch size、CFG Scale、Seed。
  6. 点击 Generate。
  7. 满意后保存图片或把参数发送到 img2img / inpaint。

常用起步参数：

Steps: 20-30
Sampler: DPM++ 2M Karras 或 Euler a
CFG Scale: 5-8
Size: SD1.5 用 512x512 / 512x768；SDXL 用 1024x1024 起步
Seed: -1 表示随机；固定 Seed 可复现

7.2 img2img 图生图​

适合在已有图片基础上重绘风格、构图或细节。

关键参数是 Denoising strength：

数值效果
0.2-0.4保留原图结构，轻微改动
0.45-0.65平衡保留和重绘
0.7-1.0大幅重绘，接近重新生成

7.3 Inpaint 局部重绘​

适合修脸、修手、替换背景局部元素。

推荐流程：

  1. 进入 img2img 的 Inpaint。
  2. 上传图片。
  3. 涂抹需要重绘区域。
  4. Prompt 只描述重绘区域和整体风格，不要写太泛。
  5. Denoising strength 从 0.35-0.6 试起。
  6. 小范围多次迭代，不要一次性大面积重绘。

7.4 Highres Fix 高清修复​

txt2img 中打开 Highres Fix，用于先低分辨率构图，再二次放大细化。

建议：

  • SD1.5 常用 512x768 起步，放大 1.5-2 倍。
  • SDXL 常用 1024x1024 起步，谨慎放大。
  • 低显存机器降低放大倍率或启用 --medvram。

7.5 PNG Info 参数复现​

WebUI 会把生成参数写入 PNG 元数据。把图片拖入 PNG Info，可读取 Prompt、Seed、Sampler、Steps、模型等参数，再发送回 txt2img/img2img 尝试复现。

注意：模型版本、VAE、扩展、随机数来源、WebUI 版本变化都会影响复现结果。

8. Prompt 编写原则​

8.1 正向 Prompt​

建议按层次写：

主体, 场景, 构图, 光线, 镜头, 材质, 风格, 质量描述

示例：

a cinematic portrait of a young explorer, standing in a misty forest, soft rim light, 85mm lens, detailed fabric, natural skin texture, high detail

8.2 Negative Prompt​

负向提示词用于排除常见瑕疵：

low quality, blurry, bad anatomy, extra fingers, missing fingers, deformed hands, watermark, text, logo

不要无限堆叠负向词。负向过强可能压掉风格或让图像僵硬。

8.3 权重和组合​

WebUI 支持提示词权重和组合表达，例如：

(masterpiece:1.2), (cinematic lighting:1.1), [red dress:blue dress:0.5]

多个主体组合时可使用 AND，但多主体稳定性受模型能力影响，不应期待复杂关系总能准确生成。

9. LoRA、VAE 和扩展​

9.1 LoRA 使用​

  1. 将 LoRA 文件放入 models/Lora/。
  2. 在 UI 中刷新附加网络列表。
  3. 点击 LoRA 或在 Prompt 中写入：
<lora:name:0.8>

建议从 0.6-0.9 权重试起。多个 LoRA 叠加时，优先降低权重，避免风格污染、脸部崩坏或构图失控。

9.2 VAE 使用​

VAE 影响色彩、对比度和细节解码。常见问题：

  • 颜色灰、发雾：尝试匹配模型推荐 VAE。
  • 黑图或 NaN：尝试 --no-half-vae。
  • SDXL 和 SD1.5 的 VAE 不要随意混用。

9.3 扩展安装​

推荐在 UI 内：

Extensions -> Available -> Load from

或手动：

git clone <extension-repo-url> extensions/<extension-name>

安装后重启 WebUI。

安全边界：

  • 扩展等价于允许第三方 Python 代码在本机执行。
  • 官方 Extensions Wiki 明确提示远程可访问时会禁用扩展安装等风险操作。
  • 只有临时必要时才使用 --enable-insecure-extension-access，用完立刻移除。

9.4 常见扩展类型​

类型用途
ControlNet姿态、边缘、深度、线稿等结构控制
Regional Prompter区域提示词
Dynamic Prompts随机组合提示词
System Info性能和环境诊断
API Payload Display从 UI 操作反推出 API JSON

10. API 调用​

10.1 启用 API​

在启动参数中加入：

--api

启动后访问：

http://127.0.0.1:7860/docs

这里能看到当前实例真实可用的 API 文档。官方 API Wiki 也提示内部文档以 /docs 为准。

10.2 txt2img 示例​

import base64
import requests

url = "http://127.0.0.1:7860"
payload = {
    "prompt": "a cinematic portrait of a robot engineer, detailed, soft light",
    "negative_prompt": "low quality, blurry, watermark, text",
    "steps": 20,
    "width": 512,
    "height": 512,
}

response = requests.post(f"{url}/sdapi/v1/txt2img", json=payload, timeout=120)
response.raise_for_status()

data = response.json()
image_base64 = data["images"][0]

with open("output.png", "wb") as image_file:
    image_file.write(base64.b64decode(image_base64))

远程或多人使用时：

--api --api-auth username:strong-password

10.3 单次请求覆盖设置​

用 override_settings 临时指定模型或 CLIP skip：

payload = {
    "prompt": "a clean product photo of a futuristic headphone",
    "steps": 24,
    "override_settings": {
        "sd_model_checkpoint": "your-model-name",
        "CLIP_stop_at_last_layers": 2,
    },
}

这只影响当前请求。若要持久修改，用 /sdapi/v1/options，但自动化系统里更推荐显式传参，避免全局状态污染。

11. 更新、备份与迁移​

11.1 更新 WebUI​

Git 克隆安装：

git pull

Windows 快速包：

运行 update.bat

更新后如果依赖冲突，优先查看启动日志。必要时删除 venv 让 WebUI 重建虚拟环境。

11.2 更新扩展​

可以用 UI 的 Extensions 页面更新，也可以进入扩展目录执行：

git pull

不要一次性更新所有扩展后马上用于重要任务。更稳妥的做法是更新前备份当前目录或记录扩展版本。

11.3 需要备份的内容​

内容路径
模型models/
LoRAmodels/Lora/
Embeddingembeddings/
扩展extensions/
输出图片outputs/
配置config.json、ui-config.json、styles.csv、webui-user.bat/sh

迁移机器时，不建议直接复制 venv。复制代码、模型、配置和输出，再让新机器重建依赖环境。

12. 常见故障处理​

12.1 Python 版本不对​

现象：

  • 安装依赖失败。
  • Torch、xFormers 或其他包版本冲突。
  • 启动报 Python 版本不支持。

处理：

  • 安装 Python 3.10.6。
  • Windows 在 webui-user.bat 中指定：
set PYTHON=C:\Users\you\AppData\Local\Programs\Python\Python310\python.exe
  • 删除 venv 后重新启动。

12.2 CUDA / Torch 不能使用 GPU​

现象：

Torch is not able to use GPU

处理：

  • NVIDIA 用户检查显卡驱动、CUDA 对应的 PyTorch 安装是否正常。
  • AMD / Mac / CPU 用户不要按 NVIDIA CUDA 路径排查，应使用对应平台安装教程，并按需加 --skip-torch-cuda-test。
  • 不要把 --skip-torch-cuda-test 当成修复 NVIDIA GPU 的第一选择，它只是跳过检测。

12.3 显存不足 / Out of Memory​

处理顺序：

  1. 降低宽高、Batch size、Highres Fix 放大倍率。
  2. 尝试 --medvram。
  3. 仍失败再尝试 --lowvram。
  4. 尝试 --opt-sdp-no-mem-attention 或 --xformers。
  5. 关闭不必要扩展。

4GB 显存机器可用，但要接受速度和分辨率限制。

12.4 黑图、NaN、VAE 异常​

处理：

  • 加 --no-half-vae。
  • 换匹配模型的 VAE。
  • 降低采样步数或换采样器。
  • 检查模型文件是否损坏。

12.5 扩展导致启动失败​

处理：

  1. 临时加：
--disable-extra-extensions
  1. 启动成功后逐个排查 extensions/。
  2. 更新或移除最近安装的扩展。

12.6 更新后无法启动​

处理：

  1. 保存启动日志。
  2. 删除 venv 后重启，让依赖重新安装。
  3. 暂停第三方扩展。
  4. 检查 Python 是否仍是 3.10.6。
  5. 回看最近 git pull 的提交或切回已知可用版本。

13. 日常工作流建议​

13.1 稳定出图流程​

  1. 固定模型、VAE、分辨率和基础参数。
  2. 先用小图快速探索 Prompt。
  3. 找到方向后固定 Seed。
  4. 微调 CFG、Steps、Prompt 权重。
  5. 用 Highres Fix 或 img2img 放大细化。
  6. 用 Inpaint 修局部问题。
  7. 保存最终 PNG 和参数。

13.2 模型管理规范​

建议文件命名：

模型名_版本_来源_用途.safetensors

建议维护一个简单表格记录：

模型类型来源推荐 VAE推荐分辨率备注
example-v1checkpointHugging Faceexample-vae512x768人像

13.3 安全使用底线​

  • 不下载不可信模型和扩展。
  • 不把无鉴权 WebUI 暴露到公网。
  • 不在公开环境启用代码执行、远程扩展安装。
  • 不把私有图片、客户图片、敏感素材上传到未知在线服务。
  • 生成内容要遵守模型许可证、素材版权和所在地区法规。

14. 参考资料​