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

项目快照：CompVis/stable-diffusion，约 73,299 个 Star，10,579 个 Fork；最新推送时间 2024-06-18T01:53:49Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/CompVis/stable-diffusion · https://ommer-lab.com/research/latent-diffusion-models/

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

项目速览（TL;DR）

stable-diffusion 是 CompVis 发布的潜在文本到图像扩散模型（latent text-to-image diffusion model）实现。仓库 README 说明，该项目基于潜在扩散模型研究成果，面向文本条件图像生成，并提供 Stable Diffusion v1 的权重说明、参考采样脚本和 Diffusers 集成信息。

GitHub 仓库元信息显示：Star 数为 73299，Fork 数为 10579，默认分支为 main，仓库语言标注为 Jupyter Notebook，许可证元信息标注为 NOASSERTION。仓库内的 LICENSE 文件则明确写有 CreativeML Open RAIL-M，实际使用和分发应同时核对仓库元信息、权重说明以及 LICENSE 原文。

“Stable Diffusion is a latent text-to-image diffusion model.”
来源：README

主要输入：文本提示词（prompt），以及采样脚本支持的尺寸、采样步数、引导尺度等参数。
主要输出：由参考脚本生成的图像文件和可选的图像网格。
模型组成：下采样因子为 8 的自动编码器、860M 参数的 UNet，以及 CLIP ViT-L/14 文本编码器。
官方运行说明：README 给出了 Conda 环境创建方式、权重软链接方式和 txt2img.py 采样命令。
硬件信息：README 写明该模型可在至少 10GB VRAM 的 GPU 上运行；这属于仓库提供的运行参考，不构成所有提示词、尺寸和采样参数下的性能承诺。

定位与目标用户

该项目定位于研究和开发用途的文本到图像扩散模型，而不是一个完整的托管式图像服务。它把模型权重、采样代码、环境文件和模型卡放在同一仓库生态中，使用者需要自行准备运行环境、获取权重并承担输出审核责任。

目标用户需要能够处理 Conda 环境、PyTorch 依赖、模型检查点（checkpoint）和 GPU 运行资源。对于只需要一个现成网页界面、无需管理模型文件和推理进程的使用者，仓库资料没有提供相应的托管服务或完整产品化界面说明。

适合进行文本到图像生成实验、采样器参数验证和模型研究复现的开发者。
适合已经具备 CUDA GPU、Python 环境管理和本地文件系统操作能力的研究团队。
适合需要阅读模型卡、评估训练数据偏差并建立输出审核流程的应用开发团队。
不适合作为无需审查即可上线的通用内容生产后端；README 明确指出权重存在已知限制和偏差。

核心功能

仓库资料能够直接确认的核心能力是文本条件图像采样。用户通过提示词向 CLIP ViT-L/14 文本编码器提供文本条件，扩散模型在潜在空间中进行迭代采样，再由自动编码器将结果转换为图像。

文本到图像采样

文本到图像（text-to-image）流程的输入是提示词和采样参数，输出是生成图像。README 给出的参考脚本为 scripts/txt2img.py，默认生成尺寸为 512x512，默认引导尺度为 7.5，并使用 50 个采样步骤；命令示例显式指定了 --plms。

该流程依赖模型检查点、配置文件、文本编码器和扩散采样组件。参数改变会影响采样过程，例如 --scale 控制 classifier-free guidance 的引导尺度，--ddim_steps 控制 DDIM 采样步数，--H 与 --W 控制输出尺寸；具体支持项以脚本帮助信息为准。

潜在空间扩散

潜在扩散模型（latent diffusion model）并非直接在完整像素空间中进行所有扩散计算。README 对 Stable Diffusion v1 的描述是：模型使用下采样因子为 8 的自动编码器，并由 860M UNet 和 CLIP ViT-L/14 文本编码器构成扩散模型配置。

由此可以确认，图像编码与解码、潜在表示上的 UNet 去噪、文本条件编码是该模型链路中的关键阶段。仓库资料没有提供每个源码类、张量形状或完整数据流图，因此不对未列出的内部接口作进一步断言。

安全检查与不可见水印

参考采样脚本包含安全检查模块（Safety Checker Module），README 将其用途描述为降低生成显式内容的概率；脚本还包含不可见水印（invisible watermark）处理，用于帮助查看者识别图像是机器生成的。

这两个组件属于参考脚本中的处理环节，而不是对所有下游部署方式的自动保证。项目资料没有提供安全检查的召回率、误报率、绕过率、审计报告或服务级别协议，因此生产系统仍需在授权范围内增加人工审核、内容策略和日志留存。

多个 Stable Diffusion v1 检查点

README 列出了 sd-v1-1.ckpt 至 sd-v1-4.ckpt 的训练阶段和数据筛选信息。不同检查点的训练步数、训练数据子集和是否采用文本条件丢弃存在差异，sd-v1-3.ckpt 与 sd-v1-4.ckpt 的说明特别提到通过 10% 文本条件丢弃改进 classifier-free guidance sampling。

检查点选择应与复现实验目标、许可范围和模型卡限制结合判断。README 未给出一套独立于具体任务的质量排序，也未给出统一的吞吐量或延迟基准，因此不能仅依据检查点编号推导通用性能结论。

系统架构与关键模块

从 README 可核查的架构信息看，Stable Diffusion v1 由文本条件编码、潜在扩散去噪和自动编码器解码三个主要环节组成。仓库同时提供参考采样脚本和 Diffusers 集成入口，但资料没有完整列出所有源码目录及模块边界。

文本条件路径

输入提示词首先由冻结的 CLIP ViT-L/14 文本编码器转换为文本嵌入。README 明确指出，Stable Diffusion 使用该编码器的非池化文本嵌入作为潜在扩散模型的条件输入。

因此，提示词并不是直接作为 UNet 的字符串输入，而是经过文本编码后参与条件采样。资料没有说明中文提示词的覆盖范围、分词策略细节或特定语言质量，使用者应通过本地测试评估实际输出。

潜在扩散与 UNet

UNet 在潜在表示上执行扩散采样。采样器可以是 README 示例中使用的 PLMS，也可以使用脚本帮助信息列出的 DDIM 相关参数；不同采样方式的具体实现和适用条件应以仓库当前代码为准。

README 给出的默认参考配置是 50 个 PLMS 采样步骤、512x512 输出和 7.5 引导尺度。若修改尺寸、精度或采样步数，应同时关注显存占用和输出质量；仓库没有提供这些参数组合的完整性能矩阵。

自动编码器与图像输出

自动编码器（autoencoder）使用下采样因子 8 的配置，在潜在表示与图像空间之间进行转换。扩散过程完成后，潜在结果需要通过解码阶段生成最终图像，参考脚本负责保存单张样本以及可选的网格结果。

README 没有给出输出文件命名规则的完整说明，也没有提供图像格式、色彩空间或元数据字段的详细规范。需要固定产物格式的系统应在本地运行后检查实际输出，并将检查结果纳入测试。

依赖与运行环境

官方 README 提供的环境创建方式以 Conda 为基础，环境名称为 ldm。资料明确列出 PyTorch、torchvision、Transformers、Diffusers 和 invisible-watermark 等安装命令，但没有在给定材料中完整列出所有底层系统库、CUDA 版本或操作系统版本。

环境管理：Conda，环境文件为 environment.yaml。
深度学习框架：PyTorch 和 torchvision，README 提供通过 -c pytorch 安装的命令。
文本与扩散相关依赖：transformers==4.19.2、diffusers。
输出处理依赖：invisible-watermark。
项目安装方式：pip install -e .。
硬件参考：README 写明至少 10GB VRAM 的 GPU；CPU 推理、不同 GPU 型号和多卡配置未在资料中说明。

给定资料没有提供 Python 版本、CUDA 版本、cuDNN 版本、驱动版本和操作系统兼容矩阵。部署前应以仓库最新的 environment.yaml、安装报错和目标硬件测试结果为准。

快速开始

最小运行闭环包括创建环境、安装项目、准备检查点、调用参考脚本和使用帮助命令验证脚本可用性。以下命令均来自 README 中给出的用法，适用于本地或测试环境。

安装环境

conda env create -f environment.yaml
conda activate ldm

pip install -e .

如果已有 latent diffusion 环境，README 还给出了更新依赖的方式。该方式会安装 PyTorch、torchvision，并固定 transformers 为 4.19.2，然后安装 diffusers 和 invisible-watermark。

conda install pytorch torchvision -c pytorch
pip install transformers==4.19.2 diffusers invisible-watermark
pip install -e .

准备模型检查点

权重不应在未核对许可和模型卡的情况下直接用于公开服务。获得 stable-diffusion-v1-*-original 权重后，按照 README 将检查点软链接到仓库指定位置。

mkdir -p models/ldm/stable-diffusion-v1/
ln -s <path/to/model.ckpt> models/ldm/stable-diffusion-v1/model.ckpt

命令中的 <path/to/model.ckpt> 是本地检查点路径占位符，不是需要提交到仓库的固定文件名。实际使用时应替换为已经合法获取、且与当前配置相匹配的模型文件路径。

运行与验证

README 给出的最小采样示例使用英文提示词，并显式启用 PLMS。执行后，脚本会按参数将结果写入输出目录；未指定输出目录时的实际默认目录，应通过脚本帮助信息和当前代码确认。

python scripts/txt2img.py \
  --prompt "a photograph of an astronaut riding a horse" \
  --plms

python scripts/txt2img.py --help

第二条命令用于验证脚本能够启动并展示参数接口。README 说明默认设置为 512x512、50 个采样步骤和 7.5 引导尺度；若本地显存不足或依赖不匹配，应先记录完整错误信息，再核对环境文件、权重路径和当前分支代码。

配置说明

仓库 README 通过 txt2img.py --help 展示了采样参数，并明确说明部分默认行为。下表只记录资料中能够确认的字段、类型和默认值；帮助输出中没有展示默认值的字段不作推断。

字段名	类型	默认值	作用
`--prompt`	字符串	未提供	指定待生成的文本提示词。
`--plms`	布尔开关	未提供	启用 README 示例使用的 PLMS 采样器。
`--ddim_steps`	整数	未提供	设置 DDIM 采样步数。
`--H`	整数	512	设置输出图像高度；README 说明默认渲染尺寸为 512x512。
`--W`	整数	512	设置输出图像宽度；README 说明默认渲染尺寸为 512x512。
`--scale`	浮点数	7.5	设置 classifier-free guidance 的引导尺度。
`--ckpt`	路径字符串	未提供	指定模型检查点路径。
`--seed`	整数	未提供	设置采样随机种子。
`--precision`	枚举字符串	未提供	在 `full` 与 `autocast` 精度选项之间选择。
`--outdir`	路径字符串	未提供	指定结果写入目录。

帮助信息还列出了 --skip_grid、--skip_save、--ddim_eta、--n_iter、--C、--f、--n_samples、--n_rows、--from-file、--config、--fixed_code、--laion400m 和 --precision 等参数。给定资料未提供这些字段的完整默认值和约束说明，建议以当前脚本的 --help 输出为准。

进阶用法

进阶使用的重点不是简单增加命令参数，而是控制实验变量并保留可复现信息。对于同一提示词，应固定检查点、随机种子、采样器、采样步数、引导尺度、宽高和精度，否则不同运行结果不能直接作为单变量比较。

采样器与引导尺度

README 指出，参考脚本默认使用 Katherine Crowson 实现的 PLMS 采样器，并列出 DDIM 相关选项。README 的检查点评估采用不同 classifier-free guidance scale，并使用 50 个 PLMS sampling steps；这说明引导尺度和采样步数是仓库评估中明确关注的变量。

测试时可以先固定提示词和检查点，再改变 --scale 或采样步数，最后保存命令行参数与输出文件。项目资料没有给出适用于所有内容的最佳尺度，因此不应把单次实验参数写成普遍结论。

尺寸与精度

Stable Diffusion v1 在 512x512 图像上进行微调，README 也将 512x512 作为参考脚本默认尺寸。脚本同时暴露 --H、--W 和 --precision {full,autocast}，因此可以在实验中明确记录尺寸和精度选项。

对于非 512x512 的尺寸，仓库资料没有给出质量、显存或速度保证。根据本文作者的经验判断，改变尺寸时应先使用少量本地测试样本验证可运行性，再决定是否扩大批量，而不应直接据此推导生产容量。

Diffusers 集成

README 提供了 Diffusers 集成章节，并表示社区开发可能更加活跃；但给定材料没有提供完整的 Python API、模型加载代码、版本兼容矩阵或服务化接口签名。使用集成方案时，应以仓库当前 README 和对应集成项目文档为准。

如果目标是研究参考脚本本身，应优先使用仓库提供的 scripts/txt2img.py；如果目标是接入已有 Diffusers 工程，则需要单独验证权重格式、配置文件、依赖版本和安全处理链是否一致。这个选择是基于资料中明确提到的两种入口，不代表两者在所有场景下功能等价。

可观测性与运维

仓库资料主要聚焦模型和采样脚本，没有提供日志规范、指标系统、健康检查、队列、并发模型、SLA 或官方运维方案。因而，运行结果的可观测性需要由集成方在本地或授权部署环境中补充设计。

记录模型检查点名称、文件校验信息和实际加载路径，避免不同权重被误当作同一实验条件。
记录提示词、随机种子、采样器、采样步数、引导尺度、图像宽高和精度选项。
记录脚本退出状态、完整错误信息、GPU 型号、显存使用和生成耗时；仓库没有提供统一字段名，字段可按团队规范定义。
将安全检查结果和水印处理状态与输出文件关联，便于后续审查。
将模型文件、配置文件和代码提交版本分开归档，避免只保存图片而丢失生成条件。

并发量、吞吐量、最大队列长度和恢复策略均未在资料中提供。部署方不得把 README 中“至少 10GB VRAM”的硬件参考解释为某一固定并发或延迟承诺。

安全与合规边界

该项目直接生成图像，且训练数据来自 LAION 数据库的子集，因此安全边界同时涉及输出内容、训练数据偏差、版权与隐私评估。所有测试、部署和数据处理都应限定在已获授权的环境中，不能将参考脚本当作完整的内容安全系统。

输出安全

README 说明参考采样脚本集成 Safety Checker Module，用于降低显式输出的概率，并使用不可见水印帮助识别机器生成图像。该表述是风险降低功能，不是“保证无不当内容”的承诺；资料没有提供检测覆盖率和误判数据。

面向用户提供生成能力时，应根据业务所在地区和应用场景建立提示词处理、输出审核、申诉、人工复核和事故响应流程。不能通过修改或移除安全检查来规避内容治理要求，也不应把水印视作来源、版权或真实性的唯一证明。

数据、隐私与授权

README 写明模型在 LAION-5B 子集的 512x512 图像上训练，并进一步列出 laion2B-en、laion-high-resolution 和 laion-aesthetics v2 5+ 等训练阶段信息。使用者需要自行评估生成内容中的个人信息、肖像、商标、版权作品和敏感属性风险，仓库资料没有为具体国家或行业提供合规结论。

不得将未获授权的私密图片、个人敏感资料或受限制数据输入任何外部服务。本文讨论范围限定为本地或已授权的模型运行环境；对于公开 API、多人共享 GPU 或跨组织托管，访问控制、隔离、审计和数据删除策略需要由部署方负责制定。

许可证与商用条款

仓库根目录的 LICENSE 文件标题为 CreativeML Open RAIL-M，日期为 2022 年 8 月 22 日。LICENSE 对模型、模型衍生物和配套材料授予全球、非排他、免版税的版权许可，并规定了分发、再分发和基于用途的限制；具体权利义务必须以仓库 LICENSE 完整原文为准。

商用与分发

README 明确写明商业使用在该许可证条款下被允许，但同时不建议在没有额外安全机制和考量的情况下，将所提供权重直接用于服务或产品。README 将这些权重描述为研究产物，并要求使用者结合模型卡中的限制与偏差进行评估。

LICENSE 的分发条款要求，在分发模型或其衍生物时纳入第 5 条所述的用途限制作为可执行条款，向后续用户告知该模型或衍生物受第 5 条约束，并向第三方接收者提供该许可证副本。衍生模型的具体分发方式、托管服务和合同文本应由法务根据完整 LICENSE 审核。

版权声明与材料范围

仓库元信息将许可证标注为 NOASSERTION，而仓库文件提供了 CreativeML Open RAIL-M 文本。两者存在信息层级差异，不能仅凭 GitHub 元信息判断权重、代码和衍生物的全部许可范围。

局限性与已知限制

README 明确警告，Stable Diffusion v1 会反映训练数据中的偏见和错误观念。模型卡被指定为训练过程、数据、预期用途以及限制与偏差的进一步参考，部署前不应只阅读采样命令而跳过模型卡。

训练数据来自 LAION 数据库的子集，数据来源和筛选条件会影响模型表现与偏差。
模型是通用文本到图像模型，不能保证事实准确性、文化中立性或对所有人群和主题的公平表现。
安全检查模块只能降低显式输出概率，仓库没有给出完整安全评测指标。
不可见水印用于辅助识别机器生成图像，不能替代内容来源核验、版权审核和人工判断。
官方资料没有给出并发能力、延迟、吞吐量、生产可用性或长期维护承诺。
官方资料没有完整给出操作系统、Python、CUDA、驱动和多 GPU 的兼容性矩阵。

README 提供的训练步数、数据子集和评估设置只能用于理解已列出的检查点，不能扩展解释为所有输入分布上的质量保证。涉及医学、法律、新闻、身份识别或其他高影响决策的场景，需要独立的风险评估；仓库没有声明这些用途的适用性。

适合谁

是否适合采用该项目，关键取决于团队能否承担本地模型运行、许可审查和输出治理，而不只是能否生成一张图片。以下信号可以用于做初步判断。

技术栈匹配：团队已经使用 Conda、PyTorch 和 Python，并能够处理 environment.yaml、模型检查点和 GPU 依赖。
任务匹配：需求是研究文本条件图像生成，能够接受通过提示词和采样参数控制输出，而不是要求固定业务模板的确定性渲染。
资源匹配：团队可以提供 README 所述至少 10GB VRAM 的 GPU，并愿意针对实际尺寸、精度和采样参数进行本地验证。
治理能力匹配：团队能够审查模型卡、执行 CreativeML Open RAIL-M 条款，并为公开服务增加安全审核、访问控制和日志。
实验要求匹配：团队需要比较不同 v1 检查点、PLMS 或 DDIM 参数，并能够保存提示词、种子和配置以复现实验。

不适合谁

以下情形表明直接采用仓库参考实现的风险较高，或需要先补充工程层。它们不是对项目能力的否定，而是对资料中未覆盖的生产要求进行边界划分。

无 GPU 或资源受限：团队没有满足 README 硬件参考的 GPU，且不准备进行独立的资源测试；仓库没有提供 CPU 运行和云端托管方案。
零治理上线：产品要求用户直接获得输出，却没有内容审核、滥用响应、隐私处理和权限控制机制。
严格合规场景：业务要求对训练数据来源、肖像权、版权、敏感内容和输出可解释性提供现成保证，而仓库资料没有给出此类保证。
高并发服务：系统要求已验证的固定吞吐量、延迟、SLA 或弹性伸缩，而仓库没有提供性能基准、服务接口或运维承诺。
固定版本依赖：团队无法接受根据最新 README、环境文件和集成代码进行兼容性核对，或不具备处理检查点格式变化的能力。

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

排查顺序应从环境、权重、参数和输出处理四个层面进行。给定资料没有提供统一错误码，因此以下建议只围绕 README 中明确出现的安装和运行入口展开。

为什么脚本找不到模型

先确认目标目录 models/ldm/stable-diffusion-v1/ 已创建，并且 model.ckpt 是指向本地合法检查点的软链接。README 的做法是使用 ln -s <path/to/model.ckpt> models/ldm/stable-diffusion-v1/model.ckpt；实际路径、文件权限和检查点完整性需要在本地核验。

为什么安装依赖失败

先确认已经执行 conda activate ldm，再检查是否按 README 安装了 transformers==4.19.2、diffusers 和 invisible-watermark。Python、CUDA、驱动等版本信息未在给定资料中提供，遇到相关错误时应读取当前 environment.yaml 和最新 README，而不要凭经验固定一个未被资料确认的版本。

为什么输出与示例不同

图像生成受提示词、检查点、随机种子、采样器、采样步数、引导尺度、宽高和精度影响。应先固定这些变量，再逐项比较；README 的参考条件是 512x512、50 步和 7.5 引导尺度，但它没有承诺每次输出内容完全相同。

能否直接用于商业产品

README 说明商业使用在许可证条款下被允许，但同时不建议没有额外安全机制和考量就将提供的权重用于服务或产品。需要同时阅读模型卡和 LICENSE，落实分发通知、许可证副本、用途限制及其他适用义务；不确定时，以仓库 LICENSE 为准。

仓库是否提供生产服务接口

给定资料只提供参考采样脚本和 Diffusers 集成说明，没有提供 HTTP、RPC、端口、鉴权、队列或 SLA 定义。若要服务化，部署方需要自行设计接口和运维体系，并在授权和合规边界内进行隔离测试。

项目地址与资源

以下链接均来自仓库资料或 GitHub 仓库元信息，可用于核对源码、研究背景、模型卡和许可证。权重使用与再分发前，应优先阅读对应页面的当前条款，而不是只依据博客摘要。