WebUI Stable Diffusion模型加载失败怎么办？

Question

**问题：WebUI Stable Diffusion模型加载失败，提示“Unknown model format”怎么办？** 在启动WebUI时，加载自定义模型出现“Unknown model format”错误，导致模型无法识别。常见原因包括模型文件损坏、格式不兼容（如非.ckpt或.safetensors格式），或存放路径错误。此外，部分模型需依赖特定版本的Stable Diffusion WebUI或相关插件。如何正确放置模型文件并确保文件完整性，是解决该问题的关键步骤。

Answer 1

WebUI Stable Diffusion模型加载失败：解决“Unknown model format”错误的深度指南

1. 问题现象与初步排查

当用户在启动Stable Diffusion WebUI时，尝试加载自定义模型（如LoRA、Checkpoint等），系统报错“Unknown model format”，表明模型文件无法被识别。此问题常见于新手用户或升级环境后未适配新版本。

• 错误日志通常出现在控制台输出中，例如：[ERROR] Unknown model format: model.safetensors
• 可能原因包括：文件扩展名不正确、模型存放路径错误、文件损坏或格式不被当前WebUI支持。

2. 模型文件格式标准与兼容性分析

Stable Diffusion WebUI 支持的主要模型格式为：

格式	扩展名	安全性	是否推荐	依赖插件	典型大小	加载速度	社区支持度	可编辑性	防篡改机制
SafeTensors	.safetensors	高	✅ 强烈推荐	无（原生支持）	2-7GB	快	极高	否	是
Checkpoint	.ckpt	低	⚠️ 可用但风险高	无	2-7GB	中等	高	是	否
Pickle Binary	.bin	极低	❌ 不推荐	部分旧版支持	1-5GB	慢	低	是	否
Diffusers	目录结构	中	✅ 需转换	transformers库	多文件	较快	高	是	部分
GGUF	.gguf	高	✅ 实验性支持	llama.cpp集成	1-4GB	极快	上升中	否	是
ONNX	.onnx	中	⚠️ 需额外工具链	onnxruntime	3-6GB	中等	中	否	否
TensorRT	.engine	高	✅ 生产级部署	NVIDIA TensorRT	压缩后小	极快	企业级	否	是
Kandinsky	.pt	低	⚠️ 特定架构	kandinsky-video	4-8GB	中	有限	是	否
ControlNet	.ckpt/.safetensors	高	✅ 推荐使用SafeTensors	ControlNet扩展	0.5-2GB	快	极高	否	是
LoRA	.safetensors	高	✅ 主流选择	无（原生支持）	几十MB	极快	极高	否	是

3. 文件完整性验证流程

即使文件扩展名为.safetensors，仍可能因下载中断或传输错误导致头部信息损坏。可通过以下Python脚本进行校验：

import torch
def check_safetensor(file_path):
    try:
        with open(file_path, 'rb') as f:
            header = f.read(16)
        if b'PTF' in header or b'ggml' in header:
            print(f"[WARN] {file_path} may be corrupted or not a valid safetensors file.")
            return False
        state_dict = torch.load(file_path, map_location='cpu')
        print(f"[OK] Model loaded successfully: {list(state_dict.keys())[:3]}...")
        return True
    except Exception as e:
        print(f"[ERROR] Failed to load {file_path}: {str(e)}")
        return False

# 使用示例
check_safetensor("models/Stable-diffusion/my_model.safetensors")
    

4. 正确的模型存放路径规范

Stable Diffusion WebUI遵循严格的目录结构，模型必须放置在指定子目录下：

• 主模型（Checkpoints）: models/Stable-diffusion/
• LoRA模型: models/Lora/
• Textual Inversion embeddings: embeddings/
• VAE models: models/VAE/
• ControlNet models: models/ControlNet/
• Hypernetworks: models/hypernetworks/

注意：路径中不应包含中文字符、空格或特殊符号（如#, %），否则可能导致解析失败。

5. WebUI版本与插件依赖关系图

不同版本的AUTOMATIC1111 WebUI对模型格式的支持存在差异，尤其是早期版本不原生支持.safetensors。

graph TD A[Stable Diffusion WebUI v1.0.0+] --> B{模型格式} B --> C[.ckpt → 原生支持] B --> D[.safetensors → 需安装safe-tensors库] D --> E[safe-tensors Python包] A --> F[WebUI v1.4.0+] F --> G[默认启用.safetensors支持] F --> H[可禁用pickle以提升安全] A --> I[第三方扩展] I --> J[ControlNet] J --> K[需匹配模型类型与扩展版本] I --> L[Tag Autocomplete] L --> M[不影响模型加载]

6. 安全策略与反序列化风险规避

从v1.4.0起，WebUI引入了防止恶意.ckpt文件执行代码的机制。建议在webui-user.bat中添加启动参数：

set COMMANDLINE_ARGS=--no-half --skip-pickle-check --disable-safe-unpickle
# 更安全的做法是：
set COMMANDLINE_ARGS=--safe-unpickle --disable-all-controlnets --listen
    

通过启用--safe-unpickle，系统将拒绝加载潜在危险的pickle对象，仅允许SafeTensors格式运行。

7. 日志分析与调试技巧

开启详细日志有助于定位问题根源。可在启动命令中加入：

python launch.py --verbose --log-startup --api
    

查看输出中的关键线索，例如：

[DEBUG] Loading model from: my_model.ckpt
[WARNING] Unrecognized magic number in header: 0x12345678
[ERROR] Unknown model format: unable to determine type
    

其中“magic number”异常说明文件头非预期值，极可能是损坏或伪装成ckpt的非模型文件。

8. 自动化检测与修复脚本

可编写批处理脚本来扫描并报告所有模型状态：

import os
from pathlib import Path

model_dirs = {
    "Checkpoints": "models/Stable-diffusion",
    "LoRA": "models/Lora",
    "VAE": "models/VAE",
    "ControlNet": "models/ControlNet"
}

for name, path in model_dirs.items():
    if os.path.exists(path):
        print(f"\n🔍 Scanning {name} in {path}:")
        for f in Path(path).glob("*"):
            if f.suffix.lower() in ['.ckpt', '.safetensors']:
                size_mb = f.stat().st_size / (1024*1024)
                print(f"  ✅ {f.name} | Size: {size_mb:.2f} MB | Format: {f.suffix}")
            else:
                print(f"  ⚠️  {f.name} | Unsupported extension: {f.suffix}")
    else:
        print(f"📁 Directory not found: {path}")