Stable Diffusion WebUI (A1111) 詳細教學

§1. 專案定位與適用情境

stable-diffusion-webui (常稱 A1111 / WebUI) 是 stable diffusion (SD; 穩定擴散) 模型的本地圖形化操作介面，以 gradio (Gradio; 一個快速 web UI 框架) 為前端、PyTorch 為後端推論引擎。

核心定位：

個人 / 工作室在本地 GPU 跑 text-to-image (T2I; 文生圖) / image-to-image (I2I; 圖生圖) 的標準工具
是社群分享 checkpoint / LoRA / textual inversion (TI; 文字反轉) embedding 的事實上 (de-facto) 平台
提供 RESTful API 模式，可作為下游服務 (Discord bot / 自動化管線) 的推論伺服器

適合用本工具的情境：

想擁有完整本機控制、不上雲、不送資料給第三方
需要 batch 出圖、批次參數掃描 (X/Y/Z plot)
要實驗多種 sampler / scheduler / 自訂 prompt 工程
整合 ControlNet (CN; 控制網) / IP-Adapter / regional prompter 等擴充套件

不適合的情境：

完全沒 GPU 環境 (CPU 推論極慢)
需要 node-based workflow → 建議改用 ComfyUI
要部署到雲端多人共用 → 建議用其衍生 fork (Forge) 或 ComfyUI 配 backend

§2. 安裝與環境前置

硬體需求：

NVIDIA GPU 顯存 (VRAM) ≥ 4 GB (SD 1.5)，≥ 8 GB (SDXL)，建議 ≥ 12 GB
系統 RAM ≥ 16 GB
硬碟空間 ≥ 30 GB (含模型)

軟體需求：

Python 3.10.x (非常重要：3.11 / 3.12 / 3.13 / 3.14 都會失敗，社群多次回報)
git ≥ 2.30
NVIDIA driver + CUDA toolkit (Windows 內建 driver 即可，Linux 視發行版而定)

Linux 安裝：

1# 1. 拉取 repo
2git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
3cd stable-diffusion-webui
4
5# 2. 確認 Python 3.10
6python3.10 --version
7
8# 3. 一鍵啟動 (會自動建 venv、下載依賴與基礎模型)
9./webui.sh

Windows 安裝：

雙擊 webui-user.bat。第一次啟動會建 venv/、下載 ~2 GB SD 1.5 基礎權重。

常見坑：

ModuleNotFoundError: pkg_resources (CLIP 安裝失敗) → 手動 pip install --no-build-isolation CLIP，再執行 webui.sh (見 issue #17398)
RTX 50 系列 (Blackwell) 需切到 dev 分支才會抓 nightly PyTorch 含 sm_120 (見 issue #17390)
launch_utils.py 在某些舊版本指向已下架的 git repo → 升級到 master 最新版

§3. 系統架構與資料流

WebUI 採三層架構：Gradio 前端 ↔ FastAPI 中間層 ↔ PyTorch + diffusers 推論層。


flowchart TD
    User["使用者瀏覽器"] -->|HTTP/WebSocket| Gradio["Gradio UI
(modules/ui.py)"]
    Gradio -->|callbacks| API["FastAPI
(modules/api/api.py)"]
    API -->|queue_lock| Pipeline["Processing Pipeline
(modules/processing.py)"]
    Pipeline --> Models["Model Loader
(modules/sd_models.py)"]
    Pipeline --> Samplers["Sampler
(modules/sd_samplers_*.py)"]
    Models --> Disk[("models/Stable-diffusion/
*.safetensors / *.ckpt")]
    Samplers --> UNet["UNet + VAE + CLIP
(PyTorch on GPU)"]
    UNet --> Output["生成圖片"]
    Output --> Save[("outputs/")]
    Output --> Gradio

    Extensions["extensions dir
arbitrary code"] -.->|hook| Pipeline
    Extensions -.->|register UI| Gradio

關鍵入口：

launch.py → 環境準備、安裝依賴、git_clone 依賴 repo
webui.py → 啟動 FastAPI + Gradio，呼叫 initialize.initialize() 載入主模型
modules/api/api.py → REST API，路由如 /sdapi/v1/txt2img、/sdapi/v1/img2img、/sdapi/v1/options

單次出圖資料流：


sequenceDiagram
    participant U as User
    participant G as Gradio UI
    participant P as processing.py
    participant S as sampler
    participant M as UNet

    U->>G: 輸入 prompt + 參數
    G->>P: StableDiffusionProcessingTxt2Img(...)
    P->>P: prompt parsing + emphasis
    P->>S: sampler.sample(noise, conditioning)
    loop steps × N
        S->>M: forward(x_t, t, c)
        M-->>S: predicted noise
        S->>S: scheduler step → x_(t-1)
    end
    S-->>P: latent
    P->>P: VAE decode → image
    P-->>G: PIL.Image
    G-->>U: 回傳圖片

§4. 目錄結構與核心模組

 1stable-diffusion-webui/
 2├── launch.py              # 入口 1：環境準備 + start()
 3├── webui.py               # 入口 2：FastAPI + Gradio 主迴圈
 4├── modules/               # 核心程式 (>100 個 .py)
 5│   ├── api/api.py         # REST API 路由
 6│   ├── processing.py      # T2I / I2I 主處理流程
 7│   ├── sd_models.py       # checkpoint 載入 / 切換
 8│   ├── sd_samplers_*.py   # Euler / DPM++ / DDIM 等
 9│   ├── safe.py            # RestrictedUnpickler (防惡意 ckpt)
10│   ├── extensions.py      # 第三方 extension 載入
11│   ├── shared.py          # 全域狀態 / opts
12│   ├── ui.py              # Gradio UI 主版面
13│   └── launch_utils.py    # 依賴管理
14├── scripts/               # 內建 script (loopback / X/Y/Z plot / custom_code)
15├── extensions-builtin/    # 隨 repo 出貨的官方 extension (LoRA / ControlNet hook 等)
16├── extensions/            # 使用者自行 git clone 安裝的第三方 extension
17├── models/
18│   ├── Stable-diffusion/  # 主 checkpoint (*.safetensors)
19│   ├── Lora/              # LoRA 權重
20│   ├── VAE/               # 自訂 VAE
21│   └── ControlNet/        # ControlNet 模型
22├── embeddings/            # textual inversion embeddings
23├── outputs/               # 生成圖片預設輸出位置
24└── configs/               # SD model yaml 設定

模組三大類：

核心推論：sd_models.py / sd_samplers_*.py / processing.py — 模型載入、採樣、後處理
介面 / API：ui.py / api/api.py / call_queue.py — Gradio UI 與 REST 端點
生態系：extensions.py / scripts.py — 動態載入第三方程式碼

§5. 常用功能與工作流範例

5.1 基本 txt2img

UI: txt2img 頁籤 → 填 prompt + negative prompt → 設 sampler (DPM++ 2M Karras 為 SD1.5 推薦) → steps 20-30 → CFG 7 → Generate。

5.2 LoRA / Hypernetwork 使用

把 .safetensors LoRA 檔丟進 models/Lora/ → 在 prompt 加 <lora:檔名:0.7> (0.7 為權重)。

5.3 ControlNet (需安裝 sd-webui-controlnet 擴充)

1cd extensions
2git clone https://github.com/Mikubill/sd-webui-controlnet.git
3# 重啟 webui，下載 ControlNet 模型到 models/ControlNet/

5.4 API 模式 (headless server)

1./webui.sh --api --listen --port 7860 --api-auth user:pass

呼叫：

1import requests, base64
2r = requests.post(
3    "http://localhost:7860/sdapi/v1/txt2img",
4    auth=("user", "pass"),
5    json={"prompt": "a cat", "steps": 20, "width": 512, "height": 512}
6)
7img_b64 = r.json()["images"][0]
8open("out.png", "wb").write(base64.b64decode(img_b64))

5.5 X/Y/Z plot 參數掃描

txt2img → Script 下拉 → X/Y/Z plot → X 設 Steps 10,20,30、Y 設 Sampler Euler a, DPM++ 2M → 批次出多張對照圖。

§6. 資安掃描

整體判定：🟡 中度風險 — 自身代碼有合理防禦設計，但生態系是主要攻擊面。

項目	等級	說明
`eval/exec` (核心)	🟢	僅出現在 `scripts/custom_code.py`，預設關閉，需 `--allow-code` 旗標才啟用
`pickle / torch.load`	🟡	已透過 `modules/safe.py` 的 `RestrictedUnpickler` 白名單化 (只允許 `collections.OrderedDict` 等)，但仍可能被繞過；建議只用 safetensors
`shell=True`	🟢	主要程式碼未發現未過濾的 subprocess shell=True
API 認證	🟡	`--api` 預設無認證，啟用 `--listen` 暴露到 LAN 時必須加 `--api-auth user:pass`
Extension 生態系	🔴	extension 是任意 Python，啟動時 `import` 即執行；第三方 extension 是最大供應鏈攻擊面，務必只裝知名來源
模型檔來源	🔴	從 civitai / huggingface 下載的 `.ckpt` 仍可能藏惡意 pickle；強烈建議只下載 `.safetensors`
依賴 repo	🟡	`launch_utils.py` 在啟動時會 git clone 多個第三方 repo (CLIP / BLIP / LDM)，repo 失蹤或被劫持都會影響供應鏈 (見 issue #17401)
路徑遍歷	🟢	API `verify_url` 有過濾，未發現明顯 `../` 注入

部署建議：

不要暴露到公網：若需遠端使用，前面加 reverse proxy + TLS + 額外認證層
強制 safetensors：在 webui-user.sh 加 COMMANDLINE_ARGS="--disable-nan-check --no-half-vae --safetensors-only" (如有支援)
不要用 --allow-code：除非你完全信任所有 prompt 來源
Extension 沙箱化：商業環境建議用容器 + 唯讀檔案系統隔離

§7. 與相近工具比較

工具	優勢	劣勢	適合誰
A1111 WebUI	生態系最大、extension 最齊、社群文件多	主分支更新緩慢、不支援 node-based workflow	一般使用者、藝術創作者
ComfyUI	node-based 工作流、極度可控、效能優	學習曲線陡峭、UI 對新手不友善	進階使用者、要做複雜 pipeline
Forge	A1111 fork，效能優化、VRAM 友善	與部分 extension 不相容	低 VRAM 顯卡使用者
InvokeAI	UI 美觀、商業化路線	extension 較少、自由度低	工作室、商業團隊
diffusers (HF)	Python library、可程式化	無內建 UI、需自寫前端	開發者、整合到自家服務

§8. 與本知識庫工作流的整合點

paper-tutorial：研究 SD / Diffusion 相關 paper 時，可把 Methods 提到的 sampler / scheduler 對應到 modules/sd_samplers_*.py 實際實作
graphify：對 modules/ 目錄做知識圖譜可快速理解模組依賴
gh-tutorial-qd：研究第三方 extension 時直接套用本流程
docling：CHANGELOG.md (97 KB) 太大時用 docling 抽出特定版本變更
與 API 整合：可作為下游 meeting-intel / patent-creator 流程的圖像生成 backend (但機密 session 內不可呼叫外部 SD 服務)

§9. 學習路徑建議

入門 (1 天)：

安裝、跑通第一張 SD 1.5 圖片
理解 prompt / negative prompt / CFG / steps / sampler 五要素
試 img2img + inpainting

中階 (1 週)：

學 LoRA / textual inversion 使用
玩 ControlNet (openpose / canny / depth)
用 X/Y/Z plot 做參數掃描
嘗試 SDXL + refiner

進階 (1 個月)：

讀 modules/processing.py 理解 pipeline
自己寫一個簡單 script (scripts/) 或 extension (extensions/)
透過 API 整合到自己的應用
評估升級到 ComfyUI 或 Forge

§10. 常見問題 (FAQ)

Q1: 為什麼一定要 Python 3.10？ A: 依賴的 xformers / torch wheel 預編譯只到 3.10；3.11+ 缺 wheel 會嘗試從原碼編譯然後失敗。

Q2: VRAM 不夠怎麼辦？ A: 加 --medvram 或 --lowvram；或改用 Forge fork。

Q3: 主分支死了嗎？ A: 不算死，dev 分支仍有零星更新，但節奏顯著放慢；活躍開發已轉到 Forge / Reforge / ComfyUI。

Q4: 模型放哪？ A: models/Stable-diffusion/ 放主 checkpoint；models/Lora/ 放 LoRA；models/VAE/ 放 VAE；embeddings/ 放 TI。

Q5: 怎麼批次出圖？ A: 設 batch count (序列張數) + batch size (同步張數)；或用 --api 後寫腳本呼叫。

Q6: 商業使用可以嗎？ A: WebUI 本身是 AGPLv3，若整合到 SaaS 必須開源；但生成的圖片版權取決於底層 model 的授權 (SD 1.5 為 CreativeML OpenRAIL-M)。

§11. 參考資源

官方 wiki：https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki
官方 feature list：README.md §Features
Discussion 區：https://github.com/AUTOMATIC1111/stable-diffusion-webui/discussions
社群論壇：https://www.reddit.com/r/StableDiffusion/
ComfyUI (相近工具)：https://github.com/comfyanonymous/ComfyUI
Forge (主要 fork)：https://github.com/lllyasviel/stable-diffusion-webui-forge
diffusers (HuggingFace library 版)：https://github.com/huggingface/diffusers
模型站：https://civitai.com / https://huggingface.co/models?other=stable-diffusion

本教學基於 2026-05-22 版 repo (master @ 82a973c, v1.10.1)。若主分支已大幅更新，請以 README.md 與 CHANGELOG.md 為準。

Stable Diffusion WebUI (A1111) 詳細教學

Contents

Stable Diffusion WebUI (A1111) 詳細教學

§1. 專案定位與適用情境

§2. 安裝與環境前置

§3. 系統架構與資料流

§4. 目錄結構與核心模組

§5. 常用功能與工作流範例

5.1 基本 txt2img

5.2 LoRA / Hypernetwork 使用

5.3 ControlNet (需安裝 sd-webui-controlnet 擴充)

5.4 API 模式 (headless server)

5.5 X/Y/Z plot 參數掃描

§6. 資安掃描

§7. 與相近工具比較

§8. 與本知識庫工作流的整合點

§9. 學習路徑建議

§10. 常見問題 (FAQ)

§11. 參考資源

Comments

Stable Diffusion WebUI (A1111) 詳細教學

Contents

Stable Diffusion WebUI (A1111) 詳細教學

§1. 專案定位與適用情境

§2. 安裝與環境前置

§3. 系統架構與資料流

§4. 目錄結構與核心模組

§5. 常用功能與工作流範例

5.1 基本 txt2img

5.2 LoRA / Hypernetwork 使用

5.3 ControlNet (需安裝 sd-webui-controlnet 擴充)

5.4 API 模式 (headless server)

5.5 X/Y/Z plot 參數掃描

§6. 資安掃描

§7. 與相近工具比較

§8. 與本知識庫工作流的整合點

§9. 學習路徑建議

§10. 常見問題 (FAQ)

§11. 參考資源

Related Posts

Comments