Stable Diffusion 3.5 官方权重本地部署教程:Large / Large Turbo / Medium 三档模型,从下载到出图完整流程

Stable Diffusion 3.5(SD3.5)是 Stability AI 在 2024 年 10 月发布的开源图像生成模型家族。与网上各种「一键整合包」「桌面发布版」不同,本文按 Stability AI 官方仓库 Stability-AI/sd3.5 走一遍从零部署:装环境、拿权重、跑出图、加 ControlNet。全程命令来自官方 README,不掺第三方封装。

先说明一件事:这个仓库是推理参考实现,不是给你日常画图用的成品软件。官方 README 写得很直白——「For alternate inference, use ComfyUI」。所以本文的定位是:想搞清 SD3.5 到底怎么跑、想接进自己代码、想验证官方实现的人,看这篇;只想点按钮出图的,直接去用 ComfyUI 或 WebUI 更省事。

一、这个仓库到底是什么

Stability-AI/sd3.5 官方描述是「Inference-only tiny reference implementation of SD3.5 and SD3」,翻成大白话:只做推理的精简参考实现,仓库里没有权重文件,只有代码。

仓库包含三块核心代码:

• 文本编码器:OpenAI CLIP-L/14、OpenCLIP bigG、Google T5-XXL(这三个模型本身是公开的);
• VAE 解码器:与早期 SD 模型类似,但改成 16 通道,并且没有 postquantconv 这一步;
• 核心 MM-DiT:SD3.5 全新设计的骨干网络。

代码文件分工也很清楚:

二、版本时间线(官方 README 原文)

三、三档模型怎么选

SD3.5 家族有三个成员,官方仓库都能跑:

• SD3.5 Large:画质最好的一档,适合出成品图、做商业素材。代价是显存和速度要求最高。
• SD3.5 Large Turbo:Large 的加速版,用更少采样步数出图,适合批量试稿、快速迭代。
• SD3.5 Medium:体积和显存最友好的一档,官方明确支持 2K 分辨率出图(README 里有 --width 1920 --height 1080 的示例)。

官方公告给出的显存口径是:SD3.5 Medium 仅需 9.9 GB 显存(不含文本编码器)即可发挥完整性能;而 NVIDIA 官方 NIM 支持矩阵给 SD3.5 Large 的运行要求是最低 24 GB 显存、48 GB 内存(Linux/WSL2)。换句话说,Medium 是消费级显卡的现实选择,Large 更适合 24 GB 以上的卡。

四、前置条件

1. Python 环境。官方 requirements.txt 未固定 Python 版本,建议使用 3.10 以上版本,并且一定在虚拟环境里装,避免污染系统环境。
2. PyTorch 与 CUDA。官方 requirements.txt 第一行就是 --extra-index-url https://download.pytorch.org/whl/cu118,即默认按 CUDA 11.8 的 PyTorch 轮子安装。如果你的驱动对应的不是 cu118,请自行把这一行换成本机匹配的 CUDA 版本索引,否则会出现装上了但 torch.cuda.is_available() 为 False 的情况。
3. 磁盘空间。模型权重、三个文本编码器加 VAE 体积都不小,建议预留几十 GB 空闲空间。
4. Hugging Face 账号。SD3.5 的权重是受限(gated)模型,必须先登录账号、在模型页接受 Stability AI 社区许可,才能下载。直接匿名 wget 会拿到 401。

requirements.txt 的完整依赖:transformers、torch、torchvision、numpy、fire、pillow、einops、sentencepiece、protobuf、webdataset。

五、安装步骤(照官方 README 执行)

git clone https://github.com/Stability-AI/sd3.5
cd sd3.5

# 创建虚拟环境(Linux / macOS)
python3 -s -m venv .sd3.5
source .sd3.5/bin/activate

# Windows 下激活方式不同,且把 python3 换成 python
# .sd3.5\Scripts\activate

python3 -s -m pip install -r requirements.txt

Windows 用户注意两点,这是官方 README 明确写出来的:

• 命令里用 python,不是 python3;
• 激活脚本路径是 venv/scripts/activate(按官方原文),实际取决于你的虚拟环境目录名。

装完后建议先验一下环境:

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

输出 True 才说明 GPU 可用。

六、下载模型权重

官方要求把下面这些文件下载到仓库的 models 目录:

1. 主模型(三选一)
   • sd3.5_large.safetensors
   • sd3.5_large_turbo.safetensors
   • sd3.5_medium.safetensors
2. CLIP-L:text_encoders/clip_l.safetensors
3. OpenCLIP bigG:text_encoders/clip_g.safetensors
4. T5-XXL:text_encoders/t5xxl_fp16.safetensors

最终 models/ 目录里应该是这几个文件:

models/
├── clip_l.safetensors
├── clip_g.safetensors
├── t5xxl.safetensors
└── sd3.5_large.safetensors   # 或 large_turbo / medium

推荐用官方提到的 huggingface_hub 方式下载,先登录再拉:

pip install huggingface_hub
huggingface-cli login

from huggingface_hub import hf_hub_download

hf_hub_download("stabilityai/stable-diffusion-3.5-large", "sd3.5_large.safetensors", local_dir="models")
hf_hub_download("stabilityai/stable-diffusion-3.5-large", "text_encoders/clip_l.safetensors", local_dir="models")
hf_hub_download("stabilityai/stable-diffusion-3.5-large", "text_encoders/clip_g.safetensors", local_dir="models")
hf_hub_download("stabilityai/stable-diffusion-3.5-large", "text_encoders/t5xxl_fp16.safetensors", local_dir="models")

huggingface-cli login 之后如果仍报 403/401,说明你还没在该模型页点「Agree and access repository」,去页面接受一次许可即可。

七、跑第一张图

官方 README 里最基础的命令:

python3 sd3_infer.py --prompt "cute wallpaper art of a cat"

默认会用 models/sd3.5_large.safetensors 和它自带的默认参数。生成结果输出到:

outputs/<MODEL>/<PROMPT>_<DATETIME>_<POSTFIX>

几个常用变体,全部来自官方 README:

# 用提示词文件批量出图,指定 Large
python3 sd3_infer.py --prompt path/to/my_prompts.txt --model models/sd3.5_large.safetensors

# 用 Large Turbo 出图
python3 sd3_infer.py --prompt path/to/my_prompts.txt --model models/sd3.5_large_turbo.safetensors

# 用 Medium 出 2K 分辨率
python3 sd3_infer.py --prompt path/to/my_prompts.txt --model models/sd3.5_medium.safetensors --width 1920 --height 1080

# 兼容 SD3 Medium
python3 sd3_infer.py --prompt path/to/my_prompts.txt --model models/sd3_medium.safetensors

参数说明(均为官方文档列出的):

• --model:指定权重文件路径;
• --steps:采样步数,示例 --steps 100;
• --width / --height:输出分辨率;
• --postfix:给输出目录加后缀,方便区分批次,例如 --postfix "steps100";
• --skip_layer_cfg True:开启 Skip Layer Guidance,官方说明它对 SD3.5 Medium 的结构与人体解剖连贯性可能更好。

一个完整例子:

python3 sd3_infer.py --prompt path/to/my_prompts.txt \
  --model models/sd3.5_medium.safetensors \
  --width 1920 --height 1080 \
  --postfix "demo" --steps 40 --skip_layer_cfg True

八、ControlNet(仅 Large)

2024-11-26 官方放出了 SD3.5 Large 的三套 ControlNet,分别是 Blur、Canny、Depth。下载方式(官方 README 给的):

from huggingface_hub import hf_hub_download
hf_hub_download("stabilityai/stable-diffusion-3.5-controlnets", "sd3.5_large_controlnet_blur.safetensors", local_dir="models")
hf_hub_download("stabilityai/stable-diffusion-3.5-controlnets", "sd3.5_large_controlnet_canny.safetensors", local_dir="models")
hf_hub_download("stabilityai/stable-diffusion-3.5-controlnets", "sd3.5_large_controlnet_depth.safetensors", local_dir="models")

调用示例:

# Blur 控制
python sd3_infer.py --model models/sd3.5_large.safetensors \
  --controlnet_ckpt models/sd3.5_large_controlnet_blur.safetensors \
  --controlnet_cond_image inputs/blur.png \
  --prompt "generated ai art, a tiny, lost rubber ducky in an action shot close-up, surfing the humongous waves, inside the tube, in the style of Kelly Slater"

# Canny 控制
python sd3_infer.py --model models/sd3.5_large.safetensors \
  --controlnet_ckpt models/sd3.5_large_controlnet_canny.safetensors \
  --controlnet_cond_image inputs/canny.png \
  --prompt "A Night time photo taken by Leica M11, portrait of a Japanese woman in a kimono, looking at the camera, Cherry blossoms"

# Depth 控制
python sd3_infer.py --model models/sd3.5_large.safetensors \
  --controlnet_ckpt models/sd3.5_large_controlnet_depth.safetensors \
  --controlnet_cond_image inputs/depth.png \
  --prompt "photo of woman, presumably in her mid-thirties, striking a balanced yoga pose on a rocky outcrop during dusk or dawn..."

三种控制图的前处理方式各不相同,官方要求看 ControlNet 的模型卡,不要混用。

九、常见问题排查

1. torch.cuda.is_available() 为 False requirements.txt 默认走 cu118。驱动版本不匹配时,手动装对应 CUDA 版本的 torch:先 pip uninstall torch torchvision,再按 pytorch.org 官方索引重装。

2. 下载权重报 401 / 403 SD3.5 是 gated 模型。必须 huggingface-cli login 并在模型页接受社区许可。匿名链接直下必然失败。

3. 报找不到 T5 或 CLIP models/ 下必须同时有 clip_l.safetensors、clip_g.safetensors、t5xxl.safetensors。只放主模型是不够的。

4. 显存不足(OOM) Medium 官方口径 9.9 GB 起(不含文本编码器);Large 按 NVIDIA NIM 矩阵最低 24 GB。显存不够就先降到 Medium,或降低 --width/--height,或减少批量提示词数量。

5. Windows 上虚拟环境激活失败 官方 README 明确:Windows 用 python 而不是 python3,激活脚本在 venv/scripts/activate。PowerShell 下若提示禁止运行脚本,需要调整执行策略。

6. sd3_infer.py 没有 --help 输出 入口用 fire 库解析参数,直接跑 python3 sd3_infer.py --help 可以看到全部可传参数。

十、它和你熟悉的 WebUI / ComfyUI 是什么关系

三者的定位完全不同,别搞混:

• Stability-AI/sd3.5:官方参考实现,命令行出图,没有界面,适合二次开发和验证;
• ComfyUI:官方 README 明确推荐的替代推理方案,节点式工作流,插件生态最全;
• Stable Diffusion WebUI / SD.Next / Forge:社区维护的图形界面,适合日常画图。

只想用,不想碰命令行,就走 ComfyUI 或 WebUI;要把 SD3.5 接进自己的程序、批量出图、做服务化,才用这个官方仓库。

十一、许可与合规

• 代码:2024-10-24 起改为 MIT License,以仓库 LICENSE-CODE 为准。
• 模型权重:走 Stability AI Community License,属于受限许可,商用前请到 Hugging Face 模型页阅读原文条款,确认自己的主体规模和用途是否在许可范围内。注意代码开源不等于权重可以随便商用,这两件事必须分开看。
• 仓库里 other_impls 的部分代码来自 HuggingFace,遵循 Apache 2.0。

十二、责任使用提醒

生成式图像模型的能力边界和风险都很明确,使用时请守住几条:

1. 不使用他人肖像、商标、版权作品作为生成素材或模仿目标,除非你已获得授权;
2. 不生成用于欺诈、冒充、造谣的内容;
3. 商用前确认模型许可条款与所在地区的合规要求;
4. 对生成结果做人工审核,不要把模型输出直接当作事实。

官方资源

• 代码仓库:https://github.com/Stability-AI/sd3.5
• 模型权重:https://huggingface.co/stabilityai/stable-diffusion-3.5-large(Large / Large Turbo / Medium 各自独立页面)
• ControlNet:https://huggingface.co/stabilityai/stable-diffusion-3.5-controlnets
• 发布公告:https://stability.ai/news/introducing-stable-diffusion-3-5

本文所有安装命令、参数、输出路径均取自 Stability-AI/sd3.5 官方 README;硬件数据取自 Stability AI 发布公告与 NVIDIA NIM 支持矩阵。未使用任何第三方整合包的说法。