stable-diffusion-webui 详细介绍：开源项目架构、功能与实践指南

项目快照：AUTOMATIC1111/stable-diffusion-webui，约 164,521 个 Star，30,551 个 Fork；最新推送时间 2026-03-02T07:00:53Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/AUTOMATIC1111/stable-diffusion-webui

stable-diffusion-webui 从代码、运行环境到实践流程的项目封面 — stable-diffusion-webui 的项目能力与实践流程示意。

项目速览（TL;DR）

stable-diffusion-webui 是一个使用 Gradio（用于构建 Web 界面的 Python 库）实现的 Stable Diffusion Web UI。仓库资料显示，项目主要提供文本生成图像、图像生成图像、局部重绘、图像外扩、模型管理、训练入口、扩展机制以及 API 等能力。

仓库默认分支为 master，主要语言为 Python，许可证标识为 AGPL-3.0。GitHub 元信息显示该仓库有 164521 个 Star 和 30551 个 Fork；这些数字是仓库资料中的快照，不应视为持续更新的统计结果。

项目属性	资料中的值
项目名称	Stable Diffusion web UI
仓库	AUTOMATIC1111/stable-diffusion-webui
主要语言	Python
许可证标识	AGPL-3.0
默认分支	`master`
测试基地址	`http://127.0.0.1:7860`，来自 `pyproject.toml` 的 pytest 配置

定位与目标用户

该项目的定位不是单一的图像生成命令行工具，而是为 Stable Diffusion 提供浏览器交互界面。用户可以在界面中输入提示词、选择采样方法、设置种子与尺寸，并对生成结果继续进行图像处理或恢复生成参数。

README 同时列出了本地安装、不同硬件后端、在线服务和社区扩展等使用路径。因此，它的目标用户覆盖需要可视化创作流程的个人用户、需要本地模型实验环境的开发者，以及需要通过脚本或 API 接入生成流程的技术团队；具体部署规模和并发能力，官方仓库资料未提供。

核心功能

核心功能可以按“生成、编辑、参数控制、模型与扩展、训练和接口”划分。每一类能力都围绕图像生成结果展开，但输入形式、触发方式和依赖的模型组件并不相同。

文本生成图像与图像生成图像

txt2img（文本生成图像）以提示词、负面提示词、采样方法、尺寸和种子等参数作为输入，输出生成图像。img2img（图像生成图像）则在输入图像的基础上进行重绘，README 还列出了批量处理、Loopback（循环处理）和 Img2img Alternative 等相关能力。

用户可以通过 Negative Prompt（负面提示词）描述不希望出现的内容，通过 Styles（样式）保存可复用的提示词片段。生成参数会写入 PNG 的文本块或 JPEG 的 EXIF；将图像拖入 PNG info 标签页后，界面可以读取这些参数并恢复到控件中，前提是该功能未在设置中关闭。

局部重绘、图像外扩与高分辨率处理

Inpainting（局部重绘）依赖输入图像和遮罩区域，只对指定区域进行生成；Outpainting（图像外扩）则用于扩展原图边界。README 还明确提到对 RunwayML 专用局部重绘模型的支持，但未在给定资料中说明该模型的下载位置、文件名或权重配置方式。

Highres Fix（高分辨率修复）提供了在较高分辨率下生成图像的便捷入口，目标是减少常见失真。Stable Diffusion Upscale、RealESRGAN、ESRGAN、SwinIR、Swin2SR、LDSR 等能力用于放大或超分辨率处理；实际可用性取决于对应模型和组件是否已正确安装，官方资料未给出统一的权重清单。

提示词控制与生成探索

Attention（注意力权重）允许用户提高提示词某一部分的影响程度，例如 ((tuxedo)) 或 (tuxedo:1.21)。选中文本后，可以使用 Ctrl+Up、Ctrl+Down，在 macOS 上使用相应的 Command 组合键调整权重。

Prompt Matrix（提示词矩阵）和 X/Y/Z plot（X/Y/Z 参数图）用于批量比较提示词或多个参数组合。Prompt Editing（提示词编辑）可以在生成过程中改变提示词，Variations（变体）和 Seed resizing（种子尺寸调整）则用于在保留部分生成条件的情况下探索不同结果。README 声明提示词没有原始 Stable Diffusion 的 75 token 限制，但没有在资料中提供新的长度上限。

模型、嵌入与扩展

项目支持动态重新加载 checkpoints（模型检查点），也提供 Checkpoint Merger（模型合并）标签页，可将最多三个检查点合并为一个。README 还列出 safetensors 格式检查点、不同 VAE 的加载、Clip skip、Hypernetworks、LoRAs 和 Textual Inversion 等能力。

Textual Inversion（文本反演）允许使用自定义 embedding（嵌入），并支持多个嵌入、不同 token 向量数量和半精度浮点数。LoRA、Hypernetwork 和 embedding 可以通过独立的选择界面加入提示词；这些功能的实际输入格式、权重文件布局和兼容性规则，给定资料没有完整展开，应以仓库 Wiki 和当前版本 README 为准。

Custom Scripts（自定义脚本）和扩展机制将社区功能接入界面。README 以 History tab（历史标签页）和 Aesthetic Gradients（审美梯度）为例说明扩展能力，但扩展的维护状态、权限范围和数据处理行为需要逐项审查，不能因为能够在界面中加载就默认其安全。

训练、标签和辅助分析

Training tab（训练标签页）包含 Hypernetworks 和 embeddings 相关选项，并支持图像预处理。预处理过程可以进行裁剪、镜像和自动标注，README 指出自动标注可使用 BLIP 或 DeepDanbooru，后者还用于生成适合动漫提示词的 danbooru 风格标签。

CLIP interrogator（CLIP 图像提示词分析器）尝试从图像反推提示词；GFPGAN 和 CodeFormer 用于人脸修复。此类功能会读取用户提供的图像并调用相应神经网络，图像是否离开本机、模型是否来自可信来源以及输出是否保留敏感信息，取决于具体部署和扩展配置。

系统架构与关键模块

根据 README，用户界面层使用 Gradio 实现，核心运行语言为 Python。给定资料没有提供完整的源码目录树、模块依赖图或稳定的 API 签名，因此下面只描述可由功能资料确认的逻辑边界，并对推断部分明确标注。

交互界面层：承载 txt2img、img2img、Extras、设置、训练和信息读取等标签页。
生成参数层：处理提示词、负面提示词、种子、采样方法、尺寸、注意力和批量参数。
模型处理层：负责检查点、VAE、embedding、Hypernetwork、LoRA 和相关模型的加载或切换。
图像处理层：承载局部重绘、图像外扩、放大、人脸修复、平铺纹理和高分辨率修复。
扩展与脚本层：提供 Custom Scripts 和社区扩展的接入点。
接口层：README 明确列出 API，但给定资料未提供端点、认证方式、请求体或响应格式。

根据本文作者的经验判断，这种分层更适合交互式实验和参数探索，而不是直接把未审计的扩展集合部署到不受信任的公共网络。该判断属于工程使用建议，不是仓库对架构或部署规模的官方承诺。

依赖与运行环境

README 要求先满足项目依赖，并分别提供 NVIDIA、AMD、Intel CPU/GPU、Ascend NPU 和在线服务的安装说明入口。资料明确指出 Windows 10/11 的 NVIDIA 安装流程需要 Python 3.10.6 和 Git；README 同时写明较新的 Python 版本不支持对应的 torch，这一表述属于该安装路径的说明。

NVIDIA GPU：README 标记为推荐路径，并提供独立安装说明。
AMD GPU：仓库提供 AMD GPU 安装说明链接。
Intel：覆盖 Intel CPU、集成 GPU 和独立 GPU，但资料指向外部 Wiki。
Ascend：提供 Ascend NPU 安装与运行说明，资料指向外部 Wiki。
在线服务：README 提供在线服务列表，并以 Google Colab 作为示例类别。

README 列出 4GB 显存支持，并记录了 2GB 显存工作的报告；这不是完整的硬件兼容性矩阵，也不是性能保证。资料没有给出 CPU、GPU 型号、驱动版本、磁盘空间、生成耗时、并发数或生产环境资源基线。

快速开始

给定资料中最完整的最小路径是 Windows 10/11 加 NVIDIA GPU 的发布包方式。它依赖 Python 和 Git，使用发布页中的 sd.webui.zip，随后执行更新和运行脚本。

安装

安装 Python 3.10.6，并在安装程序中勾选将 Python 加入 PATH。
安装 Git。
从 README 指向的 v1.0.0-pre 发布页下载 sd.webui.zip 并解压。

运行

cd <解压后的 stable-diffusion-webui 目录>
update.bat
run.bat

上述命令只适用于 README 描述的 Windows 发布包路径。路径中的尖括号是占位符，不是需要原样输入的目录名；命令不会访问未授权的远程目标，也不包含 API 密钥。

验证

run.bat 启动后，应以终端输出和本地 Web UI 是否可访问为准。pyproject.toml 将 pytest 的 base_url 配置为 http://127.0.0.1:7860，因此该地址可作为资料中明确出现的本地测试基地址；README 给定片段没有提供健康检查端点或完整验证命令。

python --version
git --version
npm run lint

前两条用于确认 Python 和 Git 命令可用；第三条来自 package.json，执行 ESLint 检查。它不是启动 Web UI 的必要步骤，且资料未说明是否要求在发布包目录中安装 Node.js 或其他前端工具，因此运行失败时应以仓库当前文档为准。

配置说明

给定资料没有提供单独的环境变量示例或完整运行参数配置文件。可核查的配置主要来自 pyproject.toml 和 package.json，以下表格只列出这些文件中实际出现的字段，不把 README 中的命令行选项臆造为配置项。

字段名	类型	默认值	作用
`tool.ruff.target-version`	字符串	`py39`	Ruff 静态检查的目标 Python 版本
`tool.ruff.lint.extend-select`	字符串数组	`["B", "C", "I", "W"]`	额外启用 Ruff 的检查规则集合
`tool.ruff.lint.exclude`	字符串数组	`["extensions", "extensions-disabled"]`	从 Ruff 检查范围中排除扩展目录
`tool.ruff.lint.ignore`	字符串数组	`["E501", "E721", "E731", "I001", "C901", "C408", "W605"]`	忽略指定的 Ruff 规则
`tool.pytest.ini_options.base_url`	字符串	`http://127.0.0.1:7860`	pytest 配置使用的本地测试基地址
`scripts.lint`	字符串	`eslint .`	通过 npm 执行 ESLint 检查
`scripts.fix`	字符串	`eslint --fix .`	通过 npm 执行 ESLint 自动修复
`devDependencies.eslint`	字符串	`^8.40.0`	`package.json` 声明的开发依赖

webui.py 的文件级例外为忽略 E402；Ruff 还允许 FastAPI 的 Depends 和 HTTPBasic 作为不可变调用。上述内容是代码质量工具配置，不等同于 Web UI 的业务运行配置。

进阶用法

进阶使用的重点是组合参数和管理模型，而不是简单增加提示词长度。README 提供了多种组合机制，但每种机制都应在固定种子、固定模型和可记录参数的前提下单独验证结果。

参数扫描：使用 X/Y/Z plot 比较采样方法、提示词或其他参数，适合观察单个变量变化。
组合提示词：使用大写 AND 分隔多个提示词，并可写入权重，例如 a cat :1.2 AND a dog AND a penguin :2.2。
纹理生成：启用 Tiling，生成可平铺的图像，用于纹理场景。
性能选项：README 指出可通过 --xformers 为部分显卡提升速度，但没有给出适用硬件清单或统一收益数据。
批处理：使用 Batch Processing 对一组文件执行 img2img 处理。
自动化：使用 API 或 Generate forever 进行连续生成，但 API 的具体协议和长期运行策略未在给定资料中提供。

训练标签页还涉及嵌入、Hypernetwork、图像裁剪、镜像和自动标注。训练前应固定数据集来源、检查图像授权和清理敏感元数据；仓库资料没有提供训练质量指标、显存与数据量对应关系之外的完整实验规范。

可观测性与运维

README 提供了进度条、预计完成时间和实时图像预览，这些能力可以帮助操作者观察单次任务状态。实时预览还可以使用独立神经网络生成，并且 README 描述其显存或计算需求几乎不增加，但没有给出量化指标。

任务过程：通过进度条和实时预览观察生成是否继续推进。
结果追溯：从 PNG 文本块或 JPEG EXIF 读取生成参数，或在设置中关闭参数保存。
错误定位：保留启动终端输出，分别核对 Python、Git、模型文件和硬件后端。
版本维护：发布包路径使用 update.bat 更新；更新前应保留可回滚的工作副本。
扩展运维：对 Custom Scripts 和社区扩展建立单独清单，避免无法区分核心项目问题与扩展问题。

官方仓库资料未提供日志格式、指标端点、任务队列、审计日志、备份策略、容器编排、SLA 或高可用方案。生产运维方案需要根据实际部署自行设计，并以当前仓库文档和代码行为验证。

安全与合规边界

该项目处理图像、提示词、模型文件和生成参数，扩展还可能改变运行行为。安全使用的边界应限定在用户拥有授权的数据、模型和计算环境内，不应把本地界面、API 或任意代码能力暴露给不受信任的访问者。

输入授权：只处理拥有使用权或获得明确授权的图像、训练数据和提示词。
个人信息：检查 PNG 文本块、JPEG EXIF、提示词和输出目录中是否包含不应共享的内容。
扩展隔离：安装扩展前审查来源、代码和网络访问行为；不要把未知扩展与敏感数据放在同一运行环境。
任意代码：README 写明从 UI 运行任意 Python 代码必须使用 --allow-code 启用，应仅在隔离、受控和获授权的测试环境中使用。
网络边界：本地测试地址不应被误当作公共服务接口；资料未提供认证、授权、限流或 TLS 配置细节。
内容合规：生成内容应遵守适用法律、平台规则、版权许可和组织内部审核要求。

资料没有列出 CVE、渗透测试结论或安全审计报告，不能据此推断项目不存在安全风险。本文不提供针对未授权目标的攻击教程、绕过检测技巧、账号自动化方案或模型安全限制规避方法。

许可证与商用条款

是否商用不能只由“开源”二字判断。对于商业部署、修改后分发、通过网络向用户提供修改版服务、再分发模型或集成第三方扩展等情形，应逐项核对 AGPL-3.0、第三方模型许可证、扩展许可证和素材授权；需要保留哪些版权与许可声明、何时触发源代码提供义务，也应以仓库 LICENSE 及相关组件条款为准。

“A web interface for Stable Diffusion, implemented using Gradio library.”
来源：README

局限性与已知限制

项目功能丰富并不等于所有后端、模型和扩展在每台机器上都具有相同表现。官方资料明确列出若干环境要求，也记录了 4GB 显存支持和 2GB 显存工作的报告，但没有提供完整兼容矩阵、性能基准或任务容量承诺。

Windows NVIDIA 路径要求 Python 3.10.6；给定资料没有提供所有平台统一的 Python 版本策略。
README 的 4GB 显存支持说明不构成对所有模型、分辨率、批量大小和扩展组合的保证。
部分功能依赖额外神经网络、检查点、VAE、embedding 或扩展，资料没有给出一份完整的统一下载清单。
API 已被列为功能，但端点、认证、错误码、兼容性和版本策略在给定资料中缺失。
社区扩展的质量、维护周期、权限范围和许可证不由核心 README 的功能清单自动保证。
运行任意 Python 代码需要显式启用 --allow-code，这说明该能力不应在默认信任边界之外使用。
给定资料没有提供生产级并发、容灾、可用性、成本或 SLA 数据。

适合谁

以下信号同时出现时，选择该项目具有较明确的理由。判断依据来自仓库功能和安装资料；具体项目仍需先做小规模验证。

团队需要通过浏览器操作 txt2img、img2img、局部重绘和图像外扩，而不是只调用命令行程序。
使用者需要在同一界面中比较采样方法、种子、提示词和尺寸，并恢复历史生成参数。
已有 Python 和 Git 环境，并能根据 NVIDIA、AMD、Intel 或 Ascend 的说明准备对应运行环境。
需要使用检查点、VAE、embedding、LoRA、Hypernetwork 或社区扩展进行本地实验。
团队能够自行承担模型文件授权、扩展审查、输出审核和 AGPL-3.0 合规工作。

不适合谁

以下信号表明需要谨慎评估，或者先选择资料中列出的在线服务、专用模型方案或其他满足组织要求的工具。这里不对未在资料中出现的替代项目作比较。

组织要求现成的生产级 SLA、审计日志、统一认证、限流和高可用，但当前资料没有提供这些能力的实现说明。
团队无法安装 Python、Git、硬件后端或模型依赖，也没有能力处理不同平台的安装差异。
业务需要稳定、可核验的高并发容量、耗时和成本数据，而仓库资料没有提供 Benchmark 或容量承诺。
数据包含严格受监管的个人信息或机密内容，但团队不能隔离扩展、控制输出目录和管理元数据。
项目需要闭源网络服务或与许可证要求冲突的分发方式，却无法完成 AGPL-3.0 和第三方组件条款评估。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分安装问题、模型问题、硬件问题和扩展问题。下面的顺序只使用给定资料中可以核验的线索，不假设未提供的日志字段或接口。

为什么运行脚本后无法使用

先确认 Python 3.10.6 和 Git 已安装，并检查 Python 安装时是否加入 PATH。Windows NVIDIA 发布包流程要求先执行 update.bat，再执行 run.bat；如果使用的是其他平台，应切换到 README 对应的安装说明。

如何确认本地地址

pyproject.toml 中 pytest 的 base_url 是 http://127.0.0.1:7860。这能确认资料中的本地测试基地址，但不能据此推导所有启动参数、反向代理配置或公网访问方式。

显存不足时应检查什么

README 列出 4GB 显存支持，并记录了 2GB 显存工作的报告；实际占用还会受模型、尺寸、批量和启用的处理组件影响。应先降低实验规模并关闭不必要的扩展或预览功能，再根据当前 README 的硬件说明核对环境；官方仓库未提供完整的显存计算公式。

为什么某个模型或扩展不可用

先区分核心检查点、VAE、embedding、LoRA、Hypernetwork 和社区扩展。README 只确认支持这些类别，未在给定资料中规定所有文件名、目录布局和兼容性要求，因此应查看对应版本的 Wiki、扩展文档和启动日志。

如何处理 lint 问题

package.json 提供 npm run lint 和 npm run fix，分别对应 ESLint 检查和自动修复。Python 侧的规则在 pyproject.toml 中由 Ruff 配置，但资料没有提供仓库级 Ruff 执行脚本，不能把未列出的命令当作项目官方入口。

是否可以在 UI 中执行 Python

README 明确写明该能力必须通过 --allow-code 启用。它只应在已授权、隔离的本地或测试环境中使用；若无法确认访问者和扩展的信任边界，应保持关闭。

项目地址与资源

以下链接均来自仓库资料或 README 中出现的项目页面。安装前应优先阅读与当前分支和当前发布版本匹配的说明。