简介面向希望上手人工智能绘画的开发者与创作者这份 Stable Diffusion 安装与使用详解以单份 PDF 形式呈现压缩包约 814KB共 1 个文件适合作为入门到初步实践的桌面参考。内容围绕环境准备、Python 与 PyTorch 依赖配置、代码库与预训练模型获取、文本生成图像命令及参数调节展开并补充 GPU 资源需求、采样步骤与图像优化思路能帮助读者理解从搭建运行环境到完成首轮出图的完整链路。已有 945 人学习说明其在同类入门资料中具备一定参考价值。读者可据此梳理安装前的软硬件检查项、虚拟环境与依赖安装顺序、常见命令参数的含义以及生成质量与耗时之间的取舍减少在环境配置和首次运行阶段反复试错。PDF 体量轻便便于按章节查阅和对照操作适合需要快速建立 Stable Diffusion 使用框架、并希望后续自行扩展实践的学习者。1. 显卡明明在torch 却说没有Stable Diffusion 安装最先栽的一步nvidia-smi能正常打出显卡型号torch.cuda.is_available()却回一个False这是我见过最多人卡住的地方。Stable Diffusion 安装这件事真正麻烦的不是代码克隆也不是模型放错目录而是 Python、PyTorch、CUDA 三层版本在暗处对不上装成 CPU 版的 torch 一样能跑只是把一张 512×512 的图从十几秒拖到半小时还不报错。这套环境现在几乎是人工智能绘画的入门标配做美术参考、做素材草图、做模型微调前的前置验证都要先把它跑起来。下文按一台带独显的机器从零走一遍装什么版本、参数怎么选、炸了怎么救都写清楚适合第一次搭这类绘画软件环境、又不想反复重装系统的人。2. 环境先列清Python、PyTorch、CUDA 三者的版本对照动手前先把机器盘一遍比装完再返工省事。Stable Diffusion 的推理链路对版本并不算苛刻但对“三者互相匹配”很敏感Python 版本决定能装到哪些轮子PyTorch 版本决定它自带哪一档 CUDA 运行时显卡驱动版本决定这一档运行时能不能被拉起。任何一层越级表现往往不是报错而是回落到 CPU 或者直接抛出设备不匹配。2.1 先量硬件显存决定你装哪一档不是越新越好打开终端先跑一条命令看驱动和显存# 右上角那列 CUDA Version 是驱动支持的上限不是你已经安装的 CUDA 版本 nvidia-smi # 只想要的显存数字可以走这条 nvidia-smi --query-gpuname,memory.total,driver_version --formatcsv这里有个特别容易误解的点nvidia-smi显示的 CUDA Version 是驱动能兼容的最高运行时版本它不代表本机装了 CUDA。装 PyTorch 的时候只要选对应通道的 wheel运行时是打包在轮子里的本地不需要再单独装一套完整的 CUDA Toolkit。很多人照着老教程把 Toolkit 装了一遍结果和驱动版本打架反而多花两小时排查。显存和能跑什么大致是这么个对应关系我一般按这张表先给机器定档显存可跑的尺寸与批量实际体感建议4GB 及以下512×512--n_samples 1半精度单张几十秒到数分钟容易爆显存先跑通链路别追求出图速度6GB512×512单张半精度可用批量必须为 1关掉其他占显存的进程再跑8GB512×512 单张宽松可尝试 640日常够用推荐的最低舒服档位12GB 及以上512×512 批量 24768 尺寸出图顺手可以把--n_samples提上去没有独显、只有集显的机器也能装torch.cuda.is_available()会是False走 CPU 推理能出图但慢得离谱。如果只是想验证流程通不通CPU 版完全可以先跑一遍最小尺寸确认代码、模型、参数都没问题再换到有卡的机器上。2.2 版本对照Python 3.10 PyTorch 2.x CUDA 11.8 是我常用的组合原始说明里写的是 Python 3.7 或更高这句话没错但“更高”是有边界的。Python 3.11、3.12 上部分依赖的预编译轮子跟不上pip install -r requirements.txt会退回到源码编译编译又需要额外的编译器和头文件新手在这里翻车的概率极高。常见做法是把解释器压在 3.83.10 之间我自己固定用 3.10兼容面最宽。组件建议版本为什么是它越级会怎样Python3.10.x依赖轮子齐全虚拟环境工具链成熟3.11 部分包无轮子转源码编译PyTorch2.02.3带 cu 后缀与 11.8 运行时配套API 稳定混装 CPU 版静默降速CUDA 运行时11.8 或 12.1由 torch 的 index 通道决定本地另装 Toolkit 易与驱动冲突显卡驱动支持上述运行时的较新版本驱动向下兼容升级成本低驱动过旧运行时报初始化失败git任意较新版本只用来拉仓库版本过旧对 HTTPS 拉取不友好表格里最需要盯的是第二行和第三行的绑定关系cu118的 torch 只能在支持 CUDA 11.8 运行时的驱动上工作cu121同理。判断办法很简单nvidia-smi右上角的版本号大于等于你要装的那一档就可以走。2.3 驱动与运行时的边界装到哪一步就该停手我一般的顺序是升级显卡驱动 → 不装本地 CUDA Toolkit → 直接装带 cu 后缀的 torch。这样整条链路上只有两样东西可能出问题驱动太旧或者 torch 装错通道。排查面窄出问题好定位。如果你已经装过本地 Toolkit也不用卸只要保证PATH里那套和 torch 自带的运行时不打架就行。判断有没有打架看一条命令的输出# 列出当前环境里 torch 自带的运行时版本和 nvidia-smi 的上限做对比 python -c import torch; print(torch.version.cuda)输出是11.8这类数字说明 torch 自带运行时已经就位输出None说明装的是 CPU 版后面所有出图都会慢到怀疑人生。这一步建议在装完 torch 之后立刻做不要等到跑模型时才发现。提示驱动升级属于系统级操作动之前先确认这台机器上没有别的深度学习项目依赖旧驱动多项目共存的机器更推荐用虚拟环境隔离 Python 侧驱动侧尽量保持一份。3. 虚拟环境与 PyTorch 安装几条命令里的参数取舍环境隔离这一步被人跳过的概率很高理由通常是“我就装一个东西”。但 Stable Diffusion 的依赖里对numpy、transformers、torch的版本都有隐性要求装到全局环境里很容易把机器上其他项目的依赖顶掉事后想回滚都找不到原始版本。虚拟环境是这儿的后悔药成本一分钟。3.1 创建并激活 venvWindows 和 Linux 的激活命令别抄错# 创建虚拟环境目录名固定成 stable-diffusion-env后面所有操作都在这个环境里 python -m venv stable-diffusion-env # Linux / macOS 激活路径用正斜杠 source stable-diffusion-env/bin/activate # Windows PowerShell 激活路径用反斜杠别和上面混 stable-diffusion-env\Scripts\activate激活成功的标志是命令行提示符前面多出(stable-diffusion-env)。这个括号很重要它是你判断“当前 pip 装到哪去了”的唯一依据。我见过有人pip install装了一堆结果括号没出现全部装进全局虚拟环境里空空如也跑脚本时一直报缺模块。Windows 上还有一个坑PowerShell 默认执行策略会拦住激活脚本报“无法加载文件因为在此系统上禁止运行脚本”。解决办法是给当前用户放开策略不需要管理员权限# 只对当前用户放开脚本执行比改全局策略安全 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned放开之后再执行激活命令就正常了。Linux 侧对应的问题是python命令指向 Python 2这时候把上面的python换成python3并且确认python3 -V输出的是 3.10 那一档。3.2 装 torchindex-url 决定你拿到的是 GPU 版还是 CPU 版这是整篇里最关键的一条命令。默认源上的pip install torch在部分平台会给你 CPU 版轮子装完不报错is_available()却是False。指定官方 wheel 通道可以避免这个玄学# 先确认 pip 是最新的旧版 pip 解析 wheel 标签会出错 python -m pip install --upgrade pip # 带 CUDA 11.8 运行时的三件套cu118 后缀是判断 GPU 版的关键 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118参数逐个说清楚torch是主框架torchvision提供图像相关的算子与变换torchaudio在纯出图场景用不上但它和另外两个的版本是绑定的一起装能避免后续被依赖项顶成不匹配的组合。--index-url把包源整体指向官方 wheel 通道注意它会覆盖默认源所以这条命令要单独执行不要和requirements.txt混在一条里。如果你的驱动只支持到 CUDA 12.1把cu118换成cu121其余不变。没有独显、只想先跑通流程就用 CPU 通道# CPU 版体积小、装得快出图慢只适合验证链路 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu装完别急着往下走看一眼版本号后缀# 期望输出类似 2.1.2cu118带 cu 说明是 GPU 版 pip show torch | grep -i versioncu118这个后缀是黑匣子里的关键线索。没有后缀、或者后缀是cpu说明通道选错了卸载重装比在现有环境上打补丁快得多。3.3 验证 torch 是否真的认到卡别只看 is_availableimport torch # 版本号带 cu 才算装对通道 print(torch.__version__) # 必须是 TrueFalse 说明拿到的是 CPU 版轮子或者驱动不匹配 print(torch.cuda.is_available()) # 多卡机器会大于 1单卡是 1 print(torch.cuda.device_count()) # 确认拿到的是哪张卡多卡机器要留意编号 print(torch.cuda.get_device_name(0)) # 真跑一次矩阵乘法比只看 is_available 更能说明运行时是否可用 a torch.randn(1024, 1024, devicecuda) b torch.randn(1024, 1024, devicecuda) c a b print(c.device, c.dtype, c.shape)这段脚本我一般存成check_env.py放在仓库外面每次重装环境都跑一遍。is_available()返回True只说明驱动和运行时握手成功真正做一次张量运算才能确认显存分配、内核加载都没问题。如果is_available()是True但矩阵乘法报CUDA error: no kernel image is available for execution on the device那就是显卡算力和这档运行时对不上通常是卡太老、或者装到了不匹配的架构版本换cu118/cu121通道重装一般能解决。4. 代码、依赖与模型落地CompVis 仓库的目录约定到这一步环境已经干净了接下来是把代码拉下来、把依赖补齐、把模型放到脚本认死的位置。这三件事的顺序不能乱乱了之后最典型的症状是“明明装了 torch装依赖时又被降级成 CPU 版”。4.1 clone 与 requirements先 torch 后依赖顺序反了要重装# 拉代码目录名保持默认后面脚本里的相对路径都按它算 git clone https://github.com/CompVis/stable-diffusion.git cd stable-diffusion # 依赖清单注意这一步会读取仓库里钉死的版本约束 pip install -r requirements.txt这里的顺序是有讲究的。仓库里的requirements.txt往往会钉住某个 torch 版本范围如果你先装依赖它可能把刚装好的cu118版本顶成另一个不带后缀的版本正确做法是先在 3.2 里把 torch 三件套装好再来装其余依赖装完再回头确认一次版本后缀。装依赖的过程中最常见的两类输出要会读一类是Requirement already satisfied说明这条已经满足不用管另一类是Building wheel for xxx说明这个包没有现成轮子正在本地编译这种通常会卡很久甚至因为缺编译器失败。遇到编译失败先升级 pip再确认 Python 版本没有越到 3.11 以上两条都排掉还失败才去考虑单独装那个包的老版本。装完之后再跑一遍 3.3 的验证脚本。这一步别省依赖装完 torch 被降级的情况我遇到不止一次。4.2 模型权重放哪目录名和文件名都是写死的代码仓库本身不含权重权重需要按仓库说明单独获取。放的位置有严格约定脚本默认按这个相对路径去找stable-diffusion/ ├── models/ │ └── ldm/ │ └── stable-diffusion-v1/ │ ├── model.ckpt # 权重文件体积很大放之前先确认磁盘空间 │ └── config.yaml # 与权重配套的配置文件缺了会直接报错 ├── scripts/ │ └── txt2img.py └── requirements.txt目录名stable-diffusion-v1和文件名model.ckpt都不是随便起的脚本里默认值就是它。有人把权重改名成sd-v1-4.ckpt丢进去然后一直报找不到文件翻半天文档才发现是名字的问题。想用别的名字也可以运行时用--ckpt显式指过去就行但配置文件得一起用--config指过去两个参数要成对出现。权重文件通常有几个 GB下载完建议校验一次大小和发布说明里给的对得上再放进目录。半截断掉的权重不会在加载时报错而是在生成阶段输出一片噪声图这种问题最难查。注意权重和配置文件必须来自同一份发布。只换权重不换 yaml会出现加载成功但结构对不上的情况表现为运行到一半抛张量维度错误。4.3 第一次跑 txt2img最小命令与参数逐个拆# 在仓库根目录执行不要在 scripts 目录里跑相对路径会全错 python scripts/txt2img.py \ --prompt a fantasy landscape, wide shot \ --plms \ --ddim_steps 20 \ --n_samples 1 \ --n_iter 1 \ --H 512 --W 512 \ --seed 42 \ --precision autocast \ --outdir outputs/first-run这段是首次验证用的最小命令下面把每个参数交代清楚--prompt文本提示决定画面内容。第一次跑用英文短语更稳分词器对英文的处理路径最短。--plms采样器开关是个不带值的旗标。原始说明里把它和--ddim并列两者二选一都不写就走默认的 DDIM。--ddim_steps采样步数。这里要特别注意原始示例里写的是--steps但 CompVis 这套脚本的参数名是--ddim_steps直接抄--steps会报unrecognized arguments。--steps是另一些封装工具的叫法别混。--n_samples一次生成几张显存不够就固定 1。--n_iter跑几轮调试阶段固定 1避免一次跑太久。--H/--W出图高宽必须能被 64 整除起步就 512×512。--seed随机种子固定住才能复现同一张图排查问题时必用。--precision autocast半精度自动混合省显存的主要开关6GB 卡必须带上。--outdir输出目录脚本会自动创建。跑通之后输出目录里会出现grid-*.png和单张图终端会打印每轮的耗时。第一次的耗时数字记下来后面调参、换卡、换驱动都拿它当基线。低于 512 的尺寸不建议试模型训练分辨率就在 512 附近压太小出图会糊成一团反而不利于判断环境是否正常。5. 避坑与排查五条血泪记录对着症状找原因这一节按“现象 → 原因 → 解决”写都是我实际踩过或者帮人定位过的。排在前面的是出现频率最高的。5.1 依赖装完torch 掉回 CPU 版现象第 3 章验证时is_available()还是True装完requirements.txt再跑一次变成False或者版本号后缀的cu118消失了。原因requirements.txt里钉了 torch 的版本范围pip 在解析时把已经装好的 GPU 轮子替换成了默认源上的通用版本。pip 的依赖解析器只看版本号是否满足约束不看轮子来自哪个通道。解决先pip show torch确认当前版本然后重装 GPU 通道那一条命令装完立刻再跑一次验证脚本。如果反复被顶掉可以给依赖安装加--no-deps跳过传递依赖再手动补装缺的包代价是要自己盯报错。更省事的办法是把 torch 那条命令放到最后执行让它在依赖解析之后覆盖掉。5.2 运行时报 numpy 相关的属性错误现象脚本刚启动就抛AttributeError: module numpy has no attribute float或类似的别名缺失错误堆栈指向某个第三方库。原因环境里装到了 numpy 2.x而这套仓库以及部分依赖仍在用 numpy 1.x 的旧别名。两者接口不兼容属于版本越级。解决把 numpy 压回 1.x 系列命令是pip install numpy2装完重新跑脚本。这类问题的通用判断方法是看报错里的包名如果是numpy、pillow这类基础库的别名或常量找不到九成是版本越级降版本比改源码靠谱。5.3 显存明明够却抛 CUDA out of memory现象8GB 的卡跑 512×512 单张仍然 OOMnvidia-smi里却显示显存占用不高。原因最常见的是--n_samples或--n_iter没改成 1一次申请了多份显存其次是没带--precision autocast全程全精度推理还有一种隐蔽情况是浏览器、其他推理进程占着显存nvidia-smi那一列看到的是总量不看进程列表发现不了。解决固定--n_samples 1 --n_iter 1 --H 512 --W 512 --precision autocast先跑通确认不是自己的参数问题然后看进程列表把占卡的进程清掉仍然不够就把--H--W降到 448 再试一次能出图就说明是显存余量问题不是环境问题。提示OOM 之后不要立刻重跑先等几秒让显存释放。某些情况下进程退出后显存回收有延迟紧接着重跑会继续报同样的错很容易误判成参数没生效。5.4 找不到模块或者找不到权重文件现象ModuleNotFoundError: No module named ldm或者FileNotFoundError指向model.ckpt。原因前者的原因是工作目录不对脚本里的ldm是仓库内的相对导入必须在仓库根目录执行后者是权重路径或文件名和默认约定不一致或者 yaml 没有跟权重放在一起。解决pwd确认自己在stable-diffusion根目录下再执行权重问题用绝对路径显式指定--ckpt和--config成对传绕开默认路径。放权重的目录权限也要看一眼读不到的文件和不存在报的错是一样的。5.5 出图是一整片灰噪点或者纯色现象命令跑完没报错输出目录里也有图但内容完全是噪声、纯灰或者糊成一团看不出提示词里的东西。原因通常是权重文件不完整下载中断导致文件截断也可能是用了半精度但权重和配置不配套还有一种是把步数压得太低--ddim_steps给到 5 以下采样还没收敛就结束了。解决先校验权重文件大小是否和发布说明一致不一致就重新获取再把--precision autocast去掉用全精度跑一次同样的种子能出正常图就说明是精度路径的问题最后把--ddim_steps提到 20 以上。三步按顺序做基本能定位到具体哪一环。6. 装完怎么验证跑通三步确认和一份基线记录环境装完真正的收尾不是看到一张图而是确认这张图可以被复现、可以量化、出问题时能对照。我一般走三步全程十分钟以内。第一步确认运行时链路。仓库外跑一次 3.3 的验证脚本重点看两个值版本号带cu后缀矩阵乘法的结果落在cuda:0上。这两条不过后面所有出图都别谈。第二步最小成本出图。用第 4.3 那条命令尺寸 512、单张、步数 20、固定种子。判断标准不是“好不好看”而是终端有没有正常打印耗时、输出目录有没有生成文件、图里能不能看出提示词描述的主体。三者都满足链路就算通了。第三步做一次可复现性检查。同一个种子连跑两次比对输出的哈希# 同种子跑两次文件名里的种子号相同比对内容是否一致 python scripts/txt2img.py --prompt a fantasy landscape --plms \ --ddim_steps 20 --n_samples 1 --H 512 --W 512 --seed 42 \ --precision autocast --outdir outputs/repro-a python scripts/txt2img.py --prompt a fantasy landscape --plms \ --ddim_steps 20 --n_samples 1 --H 512 --W 512 --seed 42 \ --precision autocast --outdir outputs/repro-b # 比对两张图的哈希一致说明环境稳定可复现 sha256sum outputs/repro-a/*.png outputs/repro-b/*.png两条哈希一致说明这套环境在确定性上是可靠的之后调提示词、调采样器才有对照意义。不一致也别慌先确认两次的--ddim_steps、尺寸、精度开关完全一致只要有一个不同结果必然不同参数完全一致却不一致才需要怀疑驱动或运行时的非确定性行为。最后留一份基线记录我习惯写在仓库外的env-baseline.md里内容是下面这张表的实际取值记录项取值来源用途显卡型号与显存nvidia-smi换机时判断档位驱动版本nvidia-smi升级前后对比Python 版本python -V换环境时复现torch 版本与后缀pip show torch判断是否被降级512×512/20 步耗时首次运行终端输出性能基线权重文件大小文件系统判断是否截断这份表最值钱的是耗时那一行。某天出图突然从十几秒变成两分钟不用猜先比耗时再比 torch 版本后缀八成能定位到是环境被别的安装动了。从那以后我每次装完这套环境都会强制走一遍固定种子复现加基线记录踩过的坑不再踩第二遍。希望帮到你。本文还有配套的精品资源点击获取
简介面向希望上手人工智能绘画的开发者与创作者这份 Stable Diffusion 安装与使用详解以单份 PDF 形式呈现压缩包约 814KB共 1 个文件适合作为入门到初步实践的桌面参考。内容围绕环境准备、Python 与 PyTorch 依赖配置、代码库与预训练模型获取、文本生成图像命令及参数调节展开并补充 GPU 资源需求、采样步骤与图像优化思路能帮助读者理解从搭建运行环境到完成首轮出图的完整链路。已有 945 人学习说明其在同类入门资料中具备一定参考价值。读者可据此梳理安装前的软硬件检查项、虚拟环境与依赖安装顺序、常见命令参数的含义以及生成质量与耗时之间的取舍减少在环境配置和首次运行阶段反复试错。PDF 体量轻便便于按章节查阅和对照操作适合需要快速建立 Stable Diffusion 使用框架、并希望后续自行扩展实践的学习者。1. 显卡明明在torch 却说没有Stable Diffusion 安装最先栽的一步nvidia-smi能正常打出显卡型号torch.cuda.is_available()却回一个False这是我见过最多人卡住的地方。Stable Diffusion 安装这件事真正麻烦的不是代码克隆也不是模型放错目录而是 Python、PyTorch、CUDA 三层版本在暗处对不上装成 CPU 版的 torch 一样能跑只是把一张 512×512 的图从十几秒拖到半小时还不报错。这套环境现在几乎是人工智能绘画的入门标配做美术参考、做素材草图、做模型微调前的前置验证都要先把它跑起来。下文按一台带独显的机器从零走一遍装什么版本、参数怎么选、炸了怎么救都写清楚适合第一次搭这类绘画软件环境、又不想反复重装系统的人。2. 环境先列清Python、PyTorch、CUDA 三者的版本对照动手前先把机器盘一遍比装完再返工省事。Stable Diffusion 的推理链路对版本并不算苛刻但对“三者互相匹配”很敏感Python 版本决定能装到哪些轮子PyTorch 版本决定它自带哪一档 CUDA 运行时显卡驱动版本决定这一档运行时能不能被拉起。任何一层越级表现往往不是报错而是回落到 CPU 或者直接抛出设备不匹配。2.1 先量硬件显存决定你装哪一档不是越新越好打开终端先跑一条命令看驱动和显存# 右上角那列 CUDA Version 是驱动支持的上限不是你已经安装的 CUDA 版本 nvidia-smi # 只想要的显存数字可以走这条 nvidia-smi --query-gpuname,memory.total,driver_version --formatcsv这里有个特别容易误解的点nvidia-smi显示的 CUDA Version 是驱动能兼容的最高运行时版本它不代表本机装了 CUDA。装 PyTorch 的时候只要选对应通道的 wheel运行时是打包在轮子里的本地不需要再单独装一套完整的 CUDA Toolkit。很多人照着老教程把 Toolkit 装了一遍结果和驱动版本打架反而多花两小时排查。显存和能跑什么大致是这么个对应关系我一般按这张表先给机器定档显存可跑的尺寸与批量实际体感建议4GB 及以下512×512--n_samples 1半精度单张几十秒到数分钟容易爆显存先跑通链路别追求出图速度6GB512×512单张半精度可用批量必须为 1关掉其他占显存的进程再跑8GB512×512 单张宽松可尝试 640日常够用推荐的最低舒服档位12GB 及以上512×512 批量 24768 尺寸出图顺手可以把--n_samples提上去没有独显、只有集显的机器也能装torch.cuda.is_available()会是False走 CPU 推理能出图但慢得离谱。如果只是想验证流程通不通CPU 版完全可以先跑一遍最小尺寸确认代码、模型、参数都没问题再换到有卡的机器上。2.2 版本对照Python 3.10 PyTorch 2.x CUDA 11.8 是我常用的组合原始说明里写的是 Python 3.7 或更高这句话没错但“更高”是有边界的。Python 3.11、3.12 上部分依赖的预编译轮子跟不上pip install -r requirements.txt会退回到源码编译编译又需要额外的编译器和头文件新手在这里翻车的概率极高。常见做法是把解释器压在 3.83.10 之间我自己固定用 3.10兼容面最宽。组件建议版本为什么是它越级会怎样Python3.10.x依赖轮子齐全虚拟环境工具链成熟3.11 部分包无轮子转源码编译PyTorch2.02.3带 cu 后缀与 11.8 运行时配套API 稳定混装 CPU 版静默降速CUDA 运行时11.8 或 12.1由 torch 的 index 通道决定本地另装 Toolkit 易与驱动冲突显卡驱动支持上述运行时的较新版本驱动向下兼容升级成本低驱动过旧运行时报初始化失败git任意较新版本只用来拉仓库版本过旧对 HTTPS 拉取不友好表格里最需要盯的是第二行和第三行的绑定关系cu118的 torch 只能在支持 CUDA 11.8 运行时的驱动上工作cu121同理。判断办法很简单nvidia-smi右上角的版本号大于等于你要装的那一档就可以走。2.3 驱动与运行时的边界装到哪一步就该停手我一般的顺序是升级显卡驱动 → 不装本地 CUDA Toolkit → 直接装带 cu 后缀的 torch。这样整条链路上只有两样东西可能出问题驱动太旧或者 torch 装错通道。排查面窄出问题好定位。如果你已经装过本地 Toolkit也不用卸只要保证PATH里那套和 torch 自带的运行时不打架就行。判断有没有打架看一条命令的输出# 列出当前环境里 torch 自带的运行时版本和 nvidia-smi 的上限做对比 python -c import torch; print(torch.version.cuda)输出是11.8这类数字说明 torch 自带运行时已经就位输出None说明装的是 CPU 版后面所有出图都会慢到怀疑人生。这一步建议在装完 torch 之后立刻做不要等到跑模型时才发现。提示驱动升级属于系统级操作动之前先确认这台机器上没有别的深度学习项目依赖旧驱动多项目共存的机器更推荐用虚拟环境隔离 Python 侧驱动侧尽量保持一份。3. 虚拟环境与 PyTorch 安装几条命令里的参数取舍环境隔离这一步被人跳过的概率很高理由通常是“我就装一个东西”。但 Stable Diffusion 的依赖里对numpy、transformers、torch的版本都有隐性要求装到全局环境里很容易把机器上其他项目的依赖顶掉事后想回滚都找不到原始版本。虚拟环境是这儿的后悔药成本一分钟。3.1 创建并激活 venvWindows 和 Linux 的激活命令别抄错# 创建虚拟环境目录名固定成 stable-diffusion-env后面所有操作都在这个环境里 python -m venv stable-diffusion-env # Linux / macOS 激活路径用正斜杠 source stable-diffusion-env/bin/activate # Windows PowerShell 激活路径用反斜杠别和上面混 stable-diffusion-env\Scripts\activate激活成功的标志是命令行提示符前面多出(stable-diffusion-env)。这个括号很重要它是你判断“当前 pip 装到哪去了”的唯一依据。我见过有人pip install装了一堆结果括号没出现全部装进全局虚拟环境里空空如也跑脚本时一直报缺模块。Windows 上还有一个坑PowerShell 默认执行策略会拦住激活脚本报“无法加载文件因为在此系统上禁止运行脚本”。解决办法是给当前用户放开策略不需要管理员权限# 只对当前用户放开脚本执行比改全局策略安全 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned放开之后再执行激活命令就正常了。Linux 侧对应的问题是python命令指向 Python 2这时候把上面的python换成python3并且确认python3 -V输出的是 3.10 那一档。3.2 装 torchindex-url 决定你拿到的是 GPU 版还是 CPU 版这是整篇里最关键的一条命令。默认源上的pip install torch在部分平台会给你 CPU 版轮子装完不报错is_available()却是False。指定官方 wheel 通道可以避免这个玄学# 先确认 pip 是最新的旧版 pip 解析 wheel 标签会出错 python -m pip install --upgrade pip # 带 CUDA 11.8 运行时的三件套cu118 后缀是判断 GPU 版的关键 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118参数逐个说清楚torch是主框架torchvision提供图像相关的算子与变换torchaudio在纯出图场景用不上但它和另外两个的版本是绑定的一起装能避免后续被依赖项顶成不匹配的组合。--index-url把包源整体指向官方 wheel 通道注意它会覆盖默认源所以这条命令要单独执行不要和requirements.txt混在一条里。如果你的驱动只支持到 CUDA 12.1把cu118换成cu121其余不变。没有独显、只想先跑通流程就用 CPU 通道# CPU 版体积小、装得快出图慢只适合验证链路 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu装完别急着往下走看一眼版本号后缀# 期望输出类似 2.1.2cu118带 cu 说明是 GPU 版 pip show torch | grep -i versioncu118这个后缀是黑匣子里的关键线索。没有后缀、或者后缀是cpu说明通道选错了卸载重装比在现有环境上打补丁快得多。3.3 验证 torch 是否真的认到卡别只看 is_availableimport torch # 版本号带 cu 才算装对通道 print(torch.__version__) # 必须是 TrueFalse 说明拿到的是 CPU 版轮子或者驱动不匹配 print(torch.cuda.is_available()) # 多卡机器会大于 1单卡是 1 print(torch.cuda.device_count()) # 确认拿到的是哪张卡多卡机器要留意编号 print(torch.cuda.get_device_name(0)) # 真跑一次矩阵乘法比只看 is_available 更能说明运行时是否可用 a torch.randn(1024, 1024, devicecuda) b torch.randn(1024, 1024, devicecuda) c a b print(c.device, c.dtype, c.shape)这段脚本我一般存成check_env.py放在仓库外面每次重装环境都跑一遍。is_available()返回True只说明驱动和运行时握手成功真正做一次张量运算才能确认显存分配、内核加载都没问题。如果is_available()是True但矩阵乘法报CUDA error: no kernel image is available for execution on the device那就是显卡算力和这档运行时对不上通常是卡太老、或者装到了不匹配的架构版本换cu118/cu121通道重装一般能解决。4. 代码、依赖与模型落地CompVis 仓库的目录约定到这一步环境已经干净了接下来是把代码拉下来、把依赖补齐、把模型放到脚本认死的位置。这三件事的顺序不能乱乱了之后最典型的症状是“明明装了 torch装依赖时又被降级成 CPU 版”。4.1 clone 与 requirements先 torch 后依赖顺序反了要重装# 拉代码目录名保持默认后面脚本里的相对路径都按它算 git clone https://github.com/CompVis/stable-diffusion.git cd stable-diffusion # 依赖清单注意这一步会读取仓库里钉死的版本约束 pip install -r requirements.txt这里的顺序是有讲究的。仓库里的requirements.txt往往会钉住某个 torch 版本范围如果你先装依赖它可能把刚装好的cu118版本顶成另一个不带后缀的版本正确做法是先在 3.2 里把 torch 三件套装好再来装其余依赖装完再回头确认一次版本后缀。装依赖的过程中最常见的两类输出要会读一类是Requirement already satisfied说明这条已经满足不用管另一类是Building wheel for xxx说明这个包没有现成轮子正在本地编译这种通常会卡很久甚至因为缺编译器失败。遇到编译失败先升级 pip再确认 Python 版本没有越到 3.11 以上两条都排掉还失败才去考虑单独装那个包的老版本。装完之后再跑一遍 3.3 的验证脚本。这一步别省依赖装完 torch 被降级的情况我遇到不止一次。4.2 模型权重放哪目录名和文件名都是写死的代码仓库本身不含权重权重需要按仓库说明单独获取。放的位置有严格约定脚本默认按这个相对路径去找stable-diffusion/ ├── models/ │ └── ldm/ │ └── stable-diffusion-v1/ │ ├── model.ckpt # 权重文件体积很大放之前先确认磁盘空间 │ └── config.yaml # 与权重配套的配置文件缺了会直接报错 ├── scripts/ │ └── txt2img.py └── requirements.txt目录名stable-diffusion-v1和文件名model.ckpt都不是随便起的脚本里默认值就是它。有人把权重改名成sd-v1-4.ckpt丢进去然后一直报找不到文件翻半天文档才发现是名字的问题。想用别的名字也可以运行时用--ckpt显式指过去就行但配置文件得一起用--config指过去两个参数要成对出现。权重文件通常有几个 GB下载完建议校验一次大小和发布说明里给的对得上再放进目录。半截断掉的权重不会在加载时报错而是在生成阶段输出一片噪声图这种问题最难查。注意权重和配置文件必须来自同一份发布。只换权重不换 yaml会出现加载成功但结构对不上的情况表现为运行到一半抛张量维度错误。4.3 第一次跑 txt2img最小命令与参数逐个拆# 在仓库根目录执行不要在 scripts 目录里跑相对路径会全错 python scripts/txt2img.py \ --prompt a fantasy landscape, wide shot \ --plms \ --ddim_steps 20 \ --n_samples 1 \ --n_iter 1 \ --H 512 --W 512 \ --seed 42 \ --precision autocast \ --outdir outputs/first-run这段是首次验证用的最小命令下面把每个参数交代清楚--prompt文本提示决定画面内容。第一次跑用英文短语更稳分词器对英文的处理路径最短。--plms采样器开关是个不带值的旗标。原始说明里把它和--ddim并列两者二选一都不写就走默认的 DDIM。--ddim_steps采样步数。这里要特别注意原始示例里写的是--steps但 CompVis 这套脚本的参数名是--ddim_steps直接抄--steps会报unrecognized arguments。--steps是另一些封装工具的叫法别混。--n_samples一次生成几张显存不够就固定 1。--n_iter跑几轮调试阶段固定 1避免一次跑太久。--H/--W出图高宽必须能被 64 整除起步就 512×512。--seed随机种子固定住才能复现同一张图排查问题时必用。--precision autocast半精度自动混合省显存的主要开关6GB 卡必须带上。--outdir输出目录脚本会自动创建。跑通之后输出目录里会出现grid-*.png和单张图终端会打印每轮的耗时。第一次的耗时数字记下来后面调参、换卡、换驱动都拿它当基线。低于 512 的尺寸不建议试模型训练分辨率就在 512 附近压太小出图会糊成一团反而不利于判断环境是否正常。5. 避坑与排查五条血泪记录对着症状找原因这一节按“现象 → 原因 → 解决”写都是我实际踩过或者帮人定位过的。排在前面的是出现频率最高的。5.1 依赖装完torch 掉回 CPU 版现象第 3 章验证时is_available()还是True装完requirements.txt再跑一次变成False或者版本号后缀的cu118消失了。原因requirements.txt里钉了 torch 的版本范围pip 在解析时把已经装好的 GPU 轮子替换成了默认源上的通用版本。pip 的依赖解析器只看版本号是否满足约束不看轮子来自哪个通道。解决先pip show torch确认当前版本然后重装 GPU 通道那一条命令装完立刻再跑一次验证脚本。如果反复被顶掉可以给依赖安装加--no-deps跳过传递依赖再手动补装缺的包代价是要自己盯报错。更省事的办法是把 torch 那条命令放到最后执行让它在依赖解析之后覆盖掉。5.2 运行时报 numpy 相关的属性错误现象脚本刚启动就抛AttributeError: module numpy has no attribute float或类似的别名缺失错误堆栈指向某个第三方库。原因环境里装到了 numpy 2.x而这套仓库以及部分依赖仍在用 numpy 1.x 的旧别名。两者接口不兼容属于版本越级。解决把 numpy 压回 1.x 系列命令是pip install numpy2装完重新跑脚本。这类问题的通用判断方法是看报错里的包名如果是numpy、pillow这类基础库的别名或常量找不到九成是版本越级降版本比改源码靠谱。5.3 显存明明够却抛 CUDA out of memory现象8GB 的卡跑 512×512 单张仍然 OOMnvidia-smi里却显示显存占用不高。原因最常见的是--n_samples或--n_iter没改成 1一次申请了多份显存其次是没带--precision autocast全程全精度推理还有一种隐蔽情况是浏览器、其他推理进程占着显存nvidia-smi那一列看到的是总量不看进程列表发现不了。解决固定--n_samples 1 --n_iter 1 --H 512 --W 512 --precision autocast先跑通确认不是自己的参数问题然后看进程列表把占卡的进程清掉仍然不够就把--H--W降到 448 再试一次能出图就说明是显存余量问题不是环境问题。提示OOM 之后不要立刻重跑先等几秒让显存释放。某些情况下进程退出后显存回收有延迟紧接着重跑会继续报同样的错很容易误判成参数没生效。5.4 找不到模块或者找不到权重文件现象ModuleNotFoundError: No module named ldm或者FileNotFoundError指向model.ckpt。原因前者的原因是工作目录不对脚本里的ldm是仓库内的相对导入必须在仓库根目录执行后者是权重路径或文件名和默认约定不一致或者 yaml 没有跟权重放在一起。解决pwd确认自己在stable-diffusion根目录下再执行权重问题用绝对路径显式指定--ckpt和--config成对传绕开默认路径。放权重的目录权限也要看一眼读不到的文件和不存在报的错是一样的。5.5 出图是一整片灰噪点或者纯色现象命令跑完没报错输出目录里也有图但内容完全是噪声、纯灰或者糊成一团看不出提示词里的东西。原因通常是权重文件不完整下载中断导致文件截断也可能是用了半精度但权重和配置不配套还有一种是把步数压得太低--ddim_steps给到 5 以下采样还没收敛就结束了。解决先校验权重文件大小是否和发布说明一致不一致就重新获取再把--precision autocast去掉用全精度跑一次同样的种子能出正常图就说明是精度路径的问题最后把--ddim_steps提到 20 以上。三步按顺序做基本能定位到具体哪一环。6. 装完怎么验证跑通三步确认和一份基线记录环境装完真正的收尾不是看到一张图而是确认这张图可以被复现、可以量化、出问题时能对照。我一般走三步全程十分钟以内。第一步确认运行时链路。仓库外跑一次 3.3 的验证脚本重点看两个值版本号带cu后缀矩阵乘法的结果落在cuda:0上。这两条不过后面所有出图都别谈。第二步最小成本出图。用第 4.3 那条命令尺寸 512、单张、步数 20、固定种子。判断标准不是“好不好看”而是终端有没有正常打印耗时、输出目录有没有生成文件、图里能不能看出提示词描述的主体。三者都满足链路就算通了。第三步做一次可复现性检查。同一个种子连跑两次比对输出的哈希# 同种子跑两次文件名里的种子号相同比对内容是否一致 python scripts/txt2img.py --prompt a fantasy landscape --plms \ --ddim_steps 20 --n_samples 1 --H 512 --W 512 --seed 42 \ --precision autocast --outdir outputs/repro-a python scripts/txt2img.py --prompt a fantasy landscape --plms \ --ddim_steps 20 --n_samples 1 --H 512 --W 512 --seed 42 \ --precision autocast --outdir outputs/repro-b # 比对两张图的哈希一致说明环境稳定可复现 sha256sum outputs/repro-a/*.png outputs/repro-b/*.png两条哈希一致说明这套环境在确定性上是可靠的之后调提示词、调采样器才有对照意义。不一致也别慌先确认两次的--ddim_steps、尺寸、精度开关完全一致只要有一个不同结果必然不同参数完全一致却不一致才需要怀疑驱动或运行时的非确定性行为。最后留一份基线记录我习惯写在仓库外的env-baseline.md里内容是下面这张表的实际取值记录项取值来源用途显卡型号与显存nvidia-smi换机时判断档位驱动版本nvidia-smi升级前后对比Python 版本python -V换环境时复现torch 版本与后缀pip show torch判断是否被降级512×512/20 步耗时首次运行终端输出性能基线权重文件大小文件系统判断是否截断这份表最值钱的是耗时那一行。某天出图突然从十几秒变成两分钟不用猜先比耗时再比 torch 版本后缀八成能定位到是环境被别的安装动了。从那以后我每次装完这套环境都会强制走一遍固定种子复现加基线记录踩过的坑不再踩第二遍。希望帮到你。本文还有配套的精品资源点击获取
