简介这份PDF文档面向想入门AI绘画的开发者与爱好者系统讲解Stable Diffusion的安装与使用全流程帮助读者从零搭建可运行的图文生成环境解决环境配置、依赖安装与出图调参等常见问题。整个压缩包仅含1个PDF文件体积约814KB内容以步骤说明与命令行代码片段为主按环境准备、依赖安装、代码与模型下载、运行出图等模块依次编排便于对照操作。已有945人学习下载。文档在讲解中给出了Python 3.7以上版本、PyTorch及相关库的安装命令虚拟环境创建方式CompVis仓库克隆与预训练模型获取途径并演示txt2img命令的调用同时说明了prompt提示词、plms与ddim算法、steps步数等参数的调节思路以及噪声调度、采样步数与GPU资源对生成速度和质量的影响适合作为快速上手与参数对照的参考手册。1. 一条命令跑完却出黑图Stable Diffusion 装不起来的三类卡点第一次装 Stable Diffusion 的人八成会卡在同一个画面命令敲完进度条走满outputs/txt2img-samples里躺着一堆纯黑方块。这套人工智能绘画软件的门槛从来不在会不会敲命令而在版本矩阵、权重路径、显存预算这三件事上错一位就全盘失效。它是把文本描述映射成图像的开源模型能离线跑、能改代码、能批量出图适合想自己掌控生成流程的开发者、需要批量产素材的设计岗以及想把模型嵌进自己工具链的工程师。下面按真实安装顺序拆环境怎么钉版本、权重放哪个目录、参数怎么联动以及那些说明书上不会写的翻车点。2. 环境准备先把 CUDA 版本钉死再谈 Python 依赖装 Stable Diffusion 最反直觉的一点是Python 版本不是第一优先级显卡驱动和 CUDA 才是。很多人上来就pip install torch装完发现torch.cuda.is_available()返回 False于是退回 CPU 跑一张 512×512 图要十几分钟跑两次就放弃了。正确顺序是反过来的——先确认驱动支持的 CUDA 上限再选对应的 PyTorch 轮子最后才创建虚拟环境。这个顺序搞反后面所有报错都是连锁反应。2.1 版本矩阵比安装顺序更重要原文写的是 Python 3.7 或更高这句话在实践中会把人坑到。3.7 早就停止维护很多依赖的新版本已经不提供对应轮子3.12 又太新pytorch-lightning和taming-transformers这类老依赖容易在编译阶段失败。我一般把 Python 锁在 3.10这是目前兼容性最稳的一档既满足模型代码对 f-string、类型注解的要求又能让绝大多数预编译轮子直接命中。CUDA 这边先做一件事打开终端敲nvidia-smi看右上角那行CUDA Version: 12.x。这是驱动能支持的最高运行时版本不是已安装版本但足够用来选轮子——只要 PyTorch 自带的 CUDA 运行时不高于这个数就能跑。常见的对应关系是这样的驱动显示上限建议装的 PyTorch 轮子说明11.8cu118覆盖最广老卡新卡都能用12.1cu121新驱动首选12.4 及以上cu124注意老依赖是否兼容提示不要为了追新驱动去装最新的 CUDA 运行时。Stable Diffusion 的官方脚本对 CUDA 12 之后的部分算子兼容性一般先用 11.8 跑通再考虑升级。显存也要在这一步心里有数。nvidia-smi右下角那个 MiB 数字就是硬上限它直接决定后面能不能开高分辨率、能不能一次出多张。4GB 卡能跑但必须降分辨率6GB 是 512×512 单张的舒适线8GB 以上才谈得上批量。2.2 虚拟环境创建与 PyTorch 安装的完整命令虚拟环境这步原文标了可选但推荐我的看法是不是推荐是必须。Stable Diffusion 会往环境里塞transformers、pytorch-lightning、open_clip这些版本敏感度极高的包一旦和你机器上其他项目的环境混在一起后面出现的AttributeError: module numpy has no attribute float这类报错能查一整天。# 创建虚拟环境名字随意建议带上项目标识 python -m venv sd-env # Linux / macOS 激活 source sd-env/bin/activate # Windows 激活cmd 或 PowerShell sd-env\Scripts\activate # 确认当前解释器路径落在虚拟环境里这一步别省 python -c import sys; print(sys.executable)激活成功的标志是命令行前面出现(sd-env)并且sys.executable指向sd-env目录下的 python。如果打印出来还是系统路径说明激活没生效后面的包会全装到全局环境里。接着装 PyTorch 三件套。这里不要直接pip install torch默认源拉的是 CPU 版本或者是和驱动不匹配的版本一定要走官方给的 index-url# 以 CUDA 11.8 为例替换成和自己驱动匹配的版本 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 顺手把 pip 升级掉老版本 pip 会在解析依赖时给出误导性报错 python -m pip install --upgrade pip参数说明--index-url指定轮子来源官方为不同 CUDA 版本维护了独立目录写错版本号会直接 404torchvision和torchaudio必须和torch同版本混装会出现RuntimeError: operator torchvision::nms does not exist。三个包版本不一致是新手最常踩的坑装的时候盯一眼输出里三个版本号是否同源即可。2.2.1 xformers 要不要装xformers是个可选项作用是替换注意力实现实测能把显存占用降三成左右、单张图快 20% 到 30%。但它对版本极其挑剔装错版本的表现是生成时直接段错误或者全黑图比不装还麻烦。我的建议是环境刚通、能出图之前别碰它等跑通了再回头加。真要装就按官方说明匹配 PyTorch 版本别用pip install xformers这种不带版本约束的写法。2.3 装完先自检三段验证脚本依赖装完先别急着下模型。模型文件好几个 GB,下完发现环境有问题时间全白费。我习惯跑三段自检每段对应一层PyTorch 能不能看见卡、半精度算不算得动、依赖能不能导入。# check_env.py import torch print(torch 版本:, torch.__version__) print(CUDA 可用:, torch.cuda.is_available()) print(CUDA 版本:, torch.version.cuda) if torch.cuda.is_available(): print(设备名:, torch.cuda.get_device_name(0)) print(显存总量 GB:, round(torch.cuda.get_device_properties(0).total_memory / 1024**3, 2)) # 半精度自检NaN 说明这张卡不适合 autocast a torch.randn(512, 512, devicecuda, dtypetorch.float16) b torch.randn(512, 512, devicecuda, dtypetorch.float16) c (a b) print(半精度矩阵乘 NaN 数量:, torch.isnan(c).sum().item())这段代码的价值在最后两行。is_available()返回 True 只说明驱动和运行时对上了不代表半精度算子能正常工作。部分显卡在 fp16 下会溢出成 NaN而 Stable Diffusion 默认就用 autocast结果就是你看到的那张纯黑图。NaN 数量大于 0后面启动时必须加--precision full这一点在第 5 章还会展开。# 第二段把 requirements 里的关键包一次性导入看谁先炸 python -c import pytorch_lightning, transformers, omegaconf import einops, kornia, PIL from PIL import Image print(pytorch_lightning, pytorch_lightning.__version__) print(transformers, transformers.__version__) print(全部关键依赖导入成功) 第三段留给模型侧等仓库克隆完再执行python -c from ldm.models.diffusion.ddpm import LatentDiffusion; print(ok)能打印 ok 说明代码路径和依赖都通再去下载几 GB 的权重。三层全过再进下一章能省掉至少一半的排查时间。3. 代码与权重落地目录结构、ckpt 格式与显存预算环境通了之后最容易翻车的地方是路径。Stable Diffusion 的脚本默认在固定位置找权重文件你把 ckpt 随便丢在项目根目录它会给你一句FileNotFoundError: No such file or directory而这行报错通常被前面几百行日志淹没很多人根本没看到。这一章把目录约定、权重格式和显存估算讲清楚装完就能跑出第一张正常的图。3.1 克隆仓库后先看 requirements.txt 再动手克隆命令本身没难度难的是仓库里那份 requirements。原文说pip install -r requirements.txt,实际执行时有相当概率卡住——里面有几个依赖是从 git 仓库直接安装的网络稍有不稳就超时报错信息还写得含糊。# 克隆到本地目录名保持 stable-diffusion git clone https://github.com/官方仓库/stable-diffusion.git cd stable-diffusion # 先看不先装把依赖列出来重点看有没有 githttps 开头和带版本锁的行 cat requirements.txt看完再决定怎么装。我的做法是分两步# 第一步先装带明确版本号的常规包 pip install -r requirements.txt --timeout 120 --retries 5 # 第二步如果卡在某个 git 依赖上单独拎出来装并加上 --no-deps 避免它顺手改动已装好的包 pip install --no-deps githttps://github.com/依赖仓库.git--timeout 120把单包超时从默认 15 秒拉到 2 分钟--retries 5让失败自动重试这两个参数在拉 git 依赖时能救回大部分偶发失败。--no-deps的意义是那个 git 依赖声明的子依赖可能和你刚装好的 PyTorch 版本冲突跳过依赖解析、只装它本体反而是更安全的做法。装完立刻验证一遍pip check这命令会列出所有版本冲突。输出No broken requirements found.才继续只要出现一行X requires Y, but you have Z就先把那一条处理掉。带着冲突往下走报错会出现在完全不相干的地方。3.2 权重文件的三种格式和它们的放置路径代码不带模型。权重文件是几 GB 的独立下载项仓库 README 里会给入口。网络能直连就用页面上的下载按钮不能直连就用下载工具断点续传——4GB 以上的文件下到 90% 断掉重来是很常见的事浏览器自带的下载器在这件事上不太靠得住。格式上有三种选错会浪费很多时间格式典型文件名大小量级说明完整 ckptsd-v1-4.ckpt4GB 上下含优化器状态兼容性最好剪枝 ckptv1-5-pruned.ckpt2GB 上下去掉训练态权重推理够用ema onlyv1-5-pruned-emaonly.ckpt4GB 上下只保留指数滑动平均权重出图更稳注意推理场景优先选emaonly版本。它的权重是训练过程中平滑过的同样的 prompt 和种子出图稳定性明显好于非 ema 版本尤其在低步数下差距更明显。放置路径是这一步的核心。scripts/txt2img.py的--ckpt参数有默认值实际指向类似models/ldm/stable-diffusion-v1/model.ckpt的层级。最省事的做法是不改默认路径直接把权重改名为model.ckpt放进那个目录# 目录不存在就先建出来 mkdir -p models/ldm/stable-diffusion-v1 # 把下载好的权重放进去并改名注意文件名必须是 model.ckpt mv ~/Downloads/v1-5-pruned-emaonly.ckpt models/ldm/stable-diffusion-v1/model.ckpt # 确认文件完整对比文件大小和下载页标注的字节数差太多就是没下完 ls -lh models/ldm/stable-diffusion-v1/model.ckpt不放默认路径也行每次启动显式传--ckpt指向真实位置。但我不建议这么干命令行参数一多--ckpt很容易复制漏掉然后你会在报错日志里找半天。固定路径一次配好后面所有命令都省一个参数。3.3 按显存反推分辨率与 batch显存决定你能开多大的图。这里有三个相互拉扯的变量分辨率、单批数量--n_samples、迭代批次--n_iter。前两个吃显存第三个不吃——--n_iter是串行跑多批显存占用和跑一批一样只是时间长。经验数值大致如下都是单张 512×512、--precision autocast的前提显存512×512 单张512×512 批量768 单张4GB勉强需降步数不可行不可行6GB可行n_samples2 会 OOM高风险8GB轻松n_samples4可行但慢12GB 以上轻松n_samples8轻松反推逻辑很简单分辨率翻倍显存需求大约翻四倍注意力是平方复杂度。512 到 768 不是 1.5 倍而是约 2.25 倍所以 6GB 卡开 768 基本必炸。命令行的--H和--W必须同时给且最好是 64 的整数倍否则模型内部的卷积下采样会对不齐报维度不匹配。# 第一次跑用最保守的组合先确认能出图 python scripts/txt2img.py \ --prompt a stone bridge over a calm river, morning fog, matte painting \ --ckpt models/ldm/stable-diffusion-v1/model.ckpt \ --H 512 --W 512 \ --n_samples 1 --n_iter 1 \ --ddim_steps 30 \ --plms \ --seed 42 \ --outdir outputs/first-run参数说明--n_samples是单批同时生成的数量直接乘在显存上--n_iter是外层循环次数每个 iter 存一次结果--seed 42固定种子便于复现不传就是随机--outdir指定输出目录不存在会自动创建。这条命令能在 6GB 卡上稳定跑完跑通了再往上加参数。4. txt2img 参数联动prompt、采样器、steps 与 CFG 怎么配能出图之后问题就变成怎么出好图。Stable Diffusion 的参数不是各自独立的旋钮它们之间存在明显的耦合步数不够时调高 CFG 只会让画面变糊CFG 太低时加步数也只是在噪声里多绕几圈。这一章按 prompt、采样器、CFG、种子的顺序拆开讲每个参数都说清楚它影响什么、边界在哪。4.1 prompt 不是关键词堆砌是权重分配文本提示通过一个文本编码器转成条件向量再注入到去噪过程。这意味着 prompt 里的每个词不是加分项而是在 77 个 token 的窗口里争夺注意力权重。堆二十个形容词的结果是每个词分到的权重都很低画面变成四不像。我常用的结构是三段式主体 环境/构图 风格/画质。a fantasy landscape, floating islands above a sea of clouds, wide angle, volumetric light, matte painting, high detail第一段定主体第二段定镜头和光线第三段定画风。逗号分隔的短语比自然语言长句更有效因为编码器对短语边界的处理更干净。wide angle、volumetric light这类是构图和光照控制词matte painting是材质风格词两者作用层不同可以叠加。关于负向提示这里有个必须说清楚的事实官方那套命令行脚本scripts/txt2img.py原生没有--negative_prompt参数负向条件是在代码里通过uncond实现的。想要负向提示得改脚本或者换社区维护的 WebUI 前端。不要在命令行里硬塞一个不存在的参数脚本会直接报 unrecognized arguments 退出。步数和 prompt 长度的关系也值得注意。77 个 token 是硬上限超出的部分会被截断而且不会有任何提示。写了一大段描述发现效果不对先数一下是不是超了。4.2 PLMS 和 DDIM 的实际差别原文提到--plms和--ddim是两种生成算法这个说法对但不完整。DDIM 是默认采样器不传参数就是它PLMS 是后来加的多步线性采样方法在相同步数下收敛更快。对比项DDIMPLMS默认状态不传参数即启用需显式加--plms20 步效果结构基本成型细节偏糊细节明显更完整50 步效果收敛充分与 20 步差距不大单步耗时略低略高适合场景快速试构图正式出图实测结论20 到 30 步这个区间PLMS 的优势最明显过了 50 步两者差距被抹平再往上加步数收益极低纯属烧时间。我一般试构图用 DDIM 20 步定稿用 PLMS 30 到 40 步。--ddim_steps是两者共用的步数参数脚本里还提供了--steps作为别名两个写哪个都行但别同时写容易让人误以为有两个不同的东西。另外还有一个--ddim_eta参数控制随机性注入默认 0.0 表示完全确定性。想在同一 prompt 下要一点变化可以调到 0.2 到 0.5但超过 0.7 画面会明显发散不建议在出定稿时用。4.3 CFG scale 与 seed 的复现逻辑--scale就是 CFG scale无分类器引导系数控制模型多大程度上听 prompt 的话。默认 7.5这是个相当合理的起点。3 到 5构图自由度高但经常偏离描述画面偏意境7 到 9描述还原和画面质量的平衡区绝大多数场景用这个区间12 以上颜色开始过饱和边缘出现明显光晕和高对比伪影很多人以为 CFG 越高越准实际上超过 15 之后画面会在视觉上崩掉——高饱和、硬边、重复纹理。这是引导强度过大导致的过拟合不是模型能力问题。种子是复现的唯一钥匙。--seed不传时日志里会打印一个随机数那个数就是本次结果的真实种子记下来下次传同样的值、同样的 prompt、同样的步数和采样器能出几乎一致的图。注意几乎——不同显卡的半精度实现有细微差别跨设备复现做不到逐像素一致同设备同参数是可以的。# 定稿参数PLMS 35 步 CFG 8.0 固定种子 python scripts/txt2img.py \ --prompt a fantasy landscape, floating islands above a sea of clouds, wide angle, volumetric light, matte painting, high detail \ --ckpt models/ldm/stable-diffusion-v1/model.ckpt \ --H 512 --W 512 \ --n_samples 1 --n_iter 4 \ --ddim_steps 35 \ --scale 8.0 \ --plms \ --seed 20240517 \ --outdir outputs/final参数说明--n_iter 4串行跑四批每批存一次配合固定种子能拿到四张同一风格、构图微变的候选图--scale 8.0比默认略高用于强化描述还原--outdir换成独立目录避免和试构图混在一起。跑完在outputs/final下能看到grid-0000.png这类汇总图以及逐张原图。4.4 输出目录与文件命名输出这块没什么技术含量但不规范会给自己挖坑。每次跑完默认会同时存汇总网格图和单张图文件多了根本分不清哪组是哪个 prompt。我的习惯是让目录名带上参数摘要OUToutputs/$(date %m%d)-plms35-cfg8-seed20240517 python scripts/txt2img.py \ --prompt your prompt here \ --ddim_steps 35 --scale 8.0 --plms --seed 20240517 \ --outdir $OUT这样做的好处是一周后再翻结果光看文件夹名就知道当时的完整配置不用去翻 shell 历史。生成时间单张 512×512 在 6GB 卡上约 25 到 40 秒30 步 PLMS四张串行两分钟左右还算可接受。5. 避坑与排查黑图、OOM、依赖冲突的五条现场记录前面几章讲的都是顺利情况下的路径。真实装机过程中出问题的概率远高于一次成功。这一章列的五个坑全部来自实际复现现场每条按现象、原因、解决三段写遇到对得上的直接照方抓药。5.1 五条踩坑记录第一条进度条走完输出全是纯黑图。现象命令正常退出日志里 loss 那一行也没报错但outputs里的 png 打开是全黑或全灰。原因半精度溢出。模型默认用--precision autocast在部分显卡上注意力层的 fp16 计算出 NaNNaN 经过后续层传播最终解码出来就是黑图。第 2 章那段自检脚本里的isnan计数就是提前发现这个问题的。解决启动参数加--precision full走 fp32。速度会慢 30% 左右、显存多占一到两成但结果是正确的。确定显卡不支持 fp16 之后这条参数就长期挂着别反复试。第二条CUDA out of memory但显存明明够。现象torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate 2.00 GiB而nvidia-smi显示还有 3GB 空闲。原因显存碎片。PyTorch 的缓存分配器在多次大小不一的分配后会留下无法复用的空洞。或者是你机器上还有别的进程浏览器硬件加速、其他 Python 进程占着显存没释放。解决先nvidia-smi看Processes那一栏有没有残留进程有就杀掉。确认没有之后把--n_samples降到 1用--n_iter串行替代批量显存峰值能降一大截。再不行就设环境变量PYTORCH_CUDA_ALLOC_CONFmax_split_size_mb:128限制单次分配块大小减少碎片。第三条pip install -r requirements.txt卡在 git 依赖上。现象输出停在Collecting githttps://...几分钟不动最后ReadTimeoutError。原因requirements 里有几个包是从源码仓库直接拉的不走 PyPI 镜像速度完全看网络状况而且默认超时只有 15 秒。解决加--timeout 120 --retries 5或者把那个 git 依赖单独拎出来用--no-deps装装完再跑一次pip check确认没引入冲突。实在拉不动就把那一行注释掉先保证主流程能走缺的包在导入报错时再补。第四条权重放对了却一直报找不到 ckpt。现象FileNotFoundError: [Errno 2] No such file or directory: models/ldm/stable-diffusion-v1/model.ckpt但ls看文件明明在那儿。原因相对路径问题。脚本用的是相对当前工作目录的路径你在scripts/目录里执行python txt2img.py相对路径就变成了scripts/models/...。解决要么统一在仓库根目录执行python scripts/txt2img.py要么每次显式传绝对路径的--ckpt。我一般选前者并把cd写进启动脚本里避免手动切换目录时忘了。第五条改了--steps却发现效果和没改一样。现象把--steps从 30 调到 50出图质量毫无变化日志里的步数还是 30。原因--steps和--ddim_steps是同一个参数的两个名字如果你在别处被人塞了一份包含--ddim_steps 30的配置两个同时出现在命令行里后者覆盖前者的行为取决于解析顺序很容易出现改了没生效。解决整条命令里只保留一个步数参数统一用--ddim_steps。启动前把命令完整打印一遍肉眼确认没有重复参数。5.2 报错日志怎么定位到具体模块Stable Diffusion 的报错日志很长但真正有用的信息集中在最后 15 行和第一个Traceback。我一般的读法是倒着看# 只留最后 30 行去掉 tqdm 进度条刷屏 python scripts/txt2img.py --prompt test --plms 21 | tail -n 3021把 stderr 合并到 stdout否则错误信息可能被进度条冲掉。看的时候找三样东西异常类型RuntimeError/FileNotFoundError/OutOfMemoryError、最后一行提到的文件名、以及文件名所在的那个模块。异常类型决定大方向文件名决定具体位置。异常类型高概率原因先查哪里FileNotFoundError路径或权重缺失--ckpt、--outdir、当前工作目录OutOfMemoryError显存超限分辨率、--n_samples、残留进程RuntimeError: expected scalar type精度不一致--precision与半精度开关ModuleNotFoundError依赖没装全pip check输出KeyError: model权重结构和代码版本不匹配ckpt 与仓库分支是否同代KeyError这一类最隐蔽通常是把新版权重喂给了旧版代码或者反过来。解决办法只有一条权重和代码版本对齐别混搭。6. 进阶用 --from-file 批量出图并让种子可追溯单条命令试参数还行一旦要做风格探索就得批量跑上百条 prompt。这时候手写循环很蠢scripts/txt2img.py自带--from-file参数读一个每行一条 prompt 的文本文件配合--n_iter可以一次性跑完整个列表。# prompts.txt 每行一条空行会被跳过 cat prompts.txt EOF a fantasy landscape, floating islands, volumetric light, matte painting a stone bridge over a calm river, morning fog, high detail a deserted lighthouse on a cliff, stormy sky, dramatic light EOF python scripts/txt2img.py \ --from-file prompts.txt \ --ckpt models/ldm/stable-diffusion-v1/model.ckpt \ --H 512 --W 512 \ --n_samples 1 --n_iter 2 \ --ddim_steps 30 --scale 7.5 --plms \ --seed 1000 \ --outdir outputs/batch-01--n_iter 2表示每条 prompt 出两张总共 3×2 共 6 张。有个细节必须注意--seed只设了起始值脚本内部会按批次递增所以在outputs/batch-01里每张图的真实种子是从 1000 往上数的顺序对应生成顺序。想要精确追溯某一张的种子得人工对照文件名和顺序这是命令行版的局限。我的做法是写一层薄包装把每次配置落成 JSONimport json, subprocess, itertools from pathlib import Path configs list(itertools.product( [7.0, 8.0, 9.0], # CFG 三档 [25, 35], # 步数两档 )) run_id sweep-01 base Path(foutputs/{run_id}) base.mkdir(parentsTrue, exist_okTrue) manifest [] for i, (cfg, steps) in enumerate(configs): seed 4000 i out base / fcfg{cfg}-step{steps} cmd [ python, scripts/txt2img.py, --prompt, a fantasy landscape, floating islands, volumetric light, --H, 512, --W, 512, --n_samples, 1, --n_iter, 1, --ddim_steps, str(steps), --scale, str(cfg), --plms, --seed, str(seed), --outdir, str(out), ] subprocess.run(cmd, checkTrue) manifest.append({cfg: cfg, steps: steps, seed: seed, dir: str(out)}) (base / manifest.json).write_text(json.dumps(manifest, ensure_asciiFalse, indent2))这段脚本的价值不在省事在于manifest.json把每组参数和输出目录绑死了。跑完直接翻 JSON 就能比对哪一档 CFG 配哪一档步数效果最好不需要回忆或翻 shell 历史。checkTrue保证任何一组失败时立刻抛错停下而不是默默跳过——批量任务里跳过失败是最难排查的状态。最后说一句我踩过的教训。刚开始做参数扫描时,我图省事所有组共用一个--outdir,结果几百张图全混在一个目录里后来想对比 CFG 7 和 CFG 9 的差别只能靠回忆生成顺序手工挑血的教训。从那以后我每次批量跑图目录名、manifest、种子三样必须同时落盘缺一样就不开跑。希望帮到你。本文还有配套的精品资源点击获取