故障排除

相关源文件

• .gitignore
• launch.py
• modules/cmd_args.py
• modules/devices.py
• requirements.txt
• requirements_versions.txt

本页面提供了运行 Stable Diffusion Web UI 时遇到常见问题的解决方案。有关安装和设置的信息，请参阅安装和设置。有关配置选项，请参阅启动选项。

通用故障排除方法

遇到 Stable Diffusion Web UI 问题时，请遵循此通用故障排除流程

来源：launch.py

VRAM相关问题

VRAM问题是 Stable Diffusion Web UI 中最常见的问题之一。

VRAM问题症状

• “CUDA out of memory”错误
• 生成图像期间系统崩溃
• 生成大型图像时出现意外行为
• 性能下降

VRAM优化选项

以下命令行参数可用于减少 VRAM 使用量

参数	效果	何时使用
--lowvram	在不使用时将模型部分移至 CPU	极低的 VRAM (≤4GB)
--medvram	仅卸载部分模型	有限的 VRAM (4-8GB)
--medvram-sdxl	仅将 medvram 应用于 SDXL 模型	使用 SDXL 模型时
--no-half	保持模型为全精度	遇到精度错误
--no-half-vae	保持 VAE 为全精度	VAE 特定问题
--precision full	对操作使用全精度	与精度相关的伪影

来源：modules/devices.py39-43 modules/cmd_args.py30-43

交叉注意力优化方法

交叉注意力有几种优化方法，它们可以极大地影响 VRAM 用量和性能

优化	参数	效果
xFormers	--xformers	高效的注意力机制（可用时最佳选项）
Split Attention	--opt-split-attention	内存高效的注意力
Sub-Quadratic	--opt-sub-quad-attention	超大图像的内存高效
SDP Attention	--opt-sdp-attention	PyTorch 2.0+ 缩放点积注意力

来源：modules/cmd_args.py59-72

精度和 NaN 问题

NaN 值检测

Web UI 会检查 NaN（非数字）值，这通常表示数值不稳定。检测到时，您会看到类似如下的错误：

• "Unet 中生成了包含 NaN 的张量。"
• "VAE 中生成了包含 NaN 的张量。"

来源：modules/devices.py238-265

修复精度问题

问题	解决方案	命令
UNet 中的 NaN	使用全精度	--no-half
VAE 中的 NaN	对 VAE 使用全精度	--no-half-vae
全精度导致的性能下降	尝试过采样	--upcast-sampling
用于测试或问题仍然存在时	禁用 NaN 检查	--disable-nan-check

来源：modules/devices.py242-265 modules/cmd_args.py30-32

模型加载问题

常见模型问题

• 模型加载失败
• VAE 问题（模糊或失真的图像）
• 模型兼容性问题

模型加载故障排除

来源：modules/cmd_args.py24-29 modules/cmd_args.py76

模型加载解决方案

问题	解决方案
未找到检查点	使用 --ckpt-dir 验证路径或使用 --ckpt 指定模型
VAE 问题	使用 --vae-path 或 --vae-dir 指定 VAE
模型 RAM 加载问题	使用 --lowram 或 --disable-model-loading-ram-optimization
CLIP 加载问题	如有需要，请使用 --do-not-download-clip
模型加载缓慢	使用 --no-hashing 跳过完整性验证

来源：modules/cmd_args.py22-29 modules/cmd_args.py118

安装和依赖项问题

Python 环境问题

依赖项问题通常表现为导入错误或版本冲突。

来源：requirements.txt requirements_versions.txt

故障排除的关键依赖项

这些依赖项最常导致问题

依赖项	所需功能	常见问题
torch	核心功能	CUDA/GPU 兼容性
xformers	内存优化	安装失败
safetensors	模型加载	版本兼容性
gradio	Web 界面	网络/显示问题
transformers	CLIP/文本编码	版本兼容性

来源：requirements_versions.txt3-36

安装解决方案

问题	解决方案	命令
依赖项安装失败	跳过环境准备	--skip-prepare-environment
需要特定版本	使用版本文件	pip install -r requirements_versions.txt
xFormers 问题	强制重新安装	--reinstall-xformers
Torch CUDA 问题	强制重新安装	--reinstall-torch

来源：launch.py17-24 modules/cmd_args.py12-13 modules/cmd_args.py17-18

GPU 和硬件兼容性问题

CUDA/GPU 问题

来源：modules/devices.py15-43 modules/cmd_args.py106

平台特定问题

平台	常见问题	解决方案
Windows	CUDA 初始化、路径问题	检查 PATH，更新驱动程序
Mac (Apple Silicon)	MPS 加速	确保正确设置 MPS，不稳定时使用 --use-cpu
Linux	库依赖项	安装系统库，检查 CUDA 安装
Intel XPU	兼容性	使用 --use-ipex 标志

来源： modules/devices.py8-13 modules/cmd_args.py74-75

生成系统信息以获取帮助

如果您需要向社区寻求帮助，请生成系统信息文件

python launch.py --dump-sysinfo

这将创建一个包含详细系统信息的 JSON 文件，有助于诊断问题。

来源： launch.py28-33

常见错误消息及解决方案

错误消息	可能的原因	解决方案
“CUDA 显存不足”	显存不足	使用 --lowvram 或 --medvram
“生成了包含 NaN 的张量”	精度问题	使用 --no-half 或 --no-half-vae
“RuntimeError: CUDA error”	GPU/驱动程序问题	更新驱动程序或使用 --use-cpu
“ModuleNotFoundError”	缺少依赖项	使用 pip install -r requirements.txt 进行安装
“无法加载检查点”	模型路径或文件损坏	检查路径或重新下载模型
“TypeError: ...got an unexpected keyword argument”	版本不匹配	使用 requirements_versions.txt

来源： modules/devices.py242-265

高级故障排除

对于上述解决方案无法解决的持续性问题

1. 检查控制台输出：完整的错误堆栈跟踪会出现在运行服务器的终端窗口中
2. 测试最小配置：尝试使用 --ui-debug-mode 运行，以快速启动 UI 而无需加载模型
3. 安全模式启动：使用 --disable-all-extensions 来排除与扩展相关的故障
4. 检查文件权限：确保对输出目录有写入权限
5. 版本检查：使用 --skip-version-check 来绕过版本兼容性检查

来源： modules/cmd_args.py105 modules/cmd_args.py116 modules/cmd_args.py123

清理和重新开始

如果以上方法都无效，您可能需要从干净的安装开始

1. 备份您的模型和重要输出
2. 删除或重命名 config.json 和 ui-config.json 文件
3. 删除缓存目录
4. 使用最少的参数重新启动 Web UI

.gitignore 文件显示了可以安全删除以干净启动的目录

• /cache 和 /cache.json*
• /config.json
• /ui-config.json
• /config_states/

来源： .gitignore11-37