Docker 中的 Stable Diffusion

在 GPU 加速的 Docker 容器中运行 Hugging Face 上官方 Stable Diffusion 发布版本。

./build.sh run '沙漠中一只鹦鹉吃意大利面的印象派画作'

./build.sh run --image parakeet_eating_spaghetti.png --strength 0.6 '玫瑰花束'

开始之前

最低要求

默认情况下，该流程使用完整模型和权重，需要具备 8GB 以上显存的 CUDA 兼容 GPU。生成一张图像大约需要几秒钟。在性能较弱的 GPU 上，您可能需要调整一些选项；有关详细信息，请参阅 示例 部分。如果您没有合适的 GPU，可以改用 --device cpu 和 --onnx 选项。

Hugging Face 令牌

由于使用的是官方模型，您需要在您的 Hugging Face 账户 中创建一个 用户访问令牌。将用户访问令牌保存到名为 token.txt 的文件中，并确保在构建容器时该文件可用。令牌内容应以 hf_... 开头。

快速入门

该流程通过单个 build.sh 脚本进行管理。

使用 ./build.sh pull 拉取最新版本的 stable-diffusion-docker。在使用 ./build run 时，您需要使用 --token 选项指定有效的 用户访问令牌。

或者，您也可以先在本地构建镜像，然后再运行。

构建

请确保您的 用户访问令牌 已保存到名为 token.txt 的文件中。

构建命令如下：

./build.sh build  # 或者直接 ./build.sh

运行

文本转图像 (txt2img)

根据文本提示生成图像。

运行命令如下：

./build.sh run '瓶中的仙女座星系'

图像转图像 (img2img)

根据现有图像和文本提示生成新图像。

首先，将图像复制到 input 文件夹。然后，运行以下命令：

./build.sh run --image image.png '瓶中的仙女座星系'

深度引导扩散 (depth2img)

结合深度图和文本提示修改现有图像。

首先，将图像复制到 input 文件夹。然后，运行以下命令：

./build.sh run --model 'stabilityai/stable-diffusion-2-depth' \
  --image image.png '对要更改物体的详细描述'

指令式 Pix2Pix (pix2pix)

结合文本提示修改现有图像。

首先，将图像复制到 input 文件夹。然后，运行以下命令：

./build.sh run --model 'timbrooks/instruct-pix2pix' \
  --image image.png '对要更改物体的详细描述'

Stable UnCLIP 变体 (unclip)

根据文本提示生成同一图像的不同版本。

首先，将图像复制到 input 文件夹。然后，运行以下命令：

./build.sh run --model 'stabilityai/stable-diffusion-2-1-unclip-small' \
  --image image.png '对图像的详细描述'

图像超分辨率 (upscale4x)

根据现有图像和文本提示生成高分辨率图像。

首先，将图像复制到 input 文件夹。然后，运行以下命令：

./build.sh run --model 'stabilityai/stable-diffusion-x4-upscaler' \
  --image image.png '瓶中的仙女座星系'

扩散修复 (inpaint)

结合图像掩码和文本提示修改现有图像的特定区域。

首先，将图像和图像掩码复制到 input 文件夹。掩码中的白色区域将被扩散处理，而黑色区域则保持不变。然后，运行以下命令：

./build.sh run --model 'runwayml/stable-diffusion-inpainting' \
  --image image.png --mask mask.png '瓶中的仙女座星系'

选项

以下是最常见的选项：

• --prompt [PROMPT]：用于生成图像的提示词
• --model [MODEL]：用于生成图像的模型（默认为 CompVis/stable-diffusion-v1-4）
• --height [HEIGHT]：图像高度，单位为像素（默认 512，必须能被 64 整除）
• --width [WIDTH]：图像宽度，单位为像素（默认 512，必须能被 64 整除）
• --iters [ITERS]：运行管道的次数（默认 1）
• --samples [SAMPLES]：每次运行生成的图像数量（默认 1）
• --scale [SCALE]：图像与提示词的匹配程度（默认 7.5）
• --scheduler [SCHEDULER]：覆盖用于去噪图像的调度器（默认为 None）
• --seed [SEED]：随机数生成器种子，用于实现结果的可重复性（默认为随机种子）
• --steps [STEPS]：采样步骤数（默认 50）

其他选项：

• --attention-slicing：减少内存使用，但会降低推理速度（默认不启用注意力切片）
• --device [DEVICE]：用于渲染图像的 CPU 或 CUDA 设备（默认为 cuda）
• --half：使用 float16 张量代替 float32（默认为 float32）
• --image [IMAGE]：用于图像到图像扩散的输入图像（默认为 None）
• --image-scale [IMAGE_SCALE]：图像与原始图像的匹配程度（默认为 None）
• --mask [MASK]：用于扩散修复的输入掩码（默认为 None）
• --negative-prompt [NEGATIVE_PROMPT]：不应生成的提示词（默认为 None）
• --onnx：使用 ONNX 运行时进行推理（默认关闭）
• --skip：跳过安全检查器（默认开启安全检查）
• --strength [STRENGTH]：应用于输入图像的扩散强度（默认 0.75）
• --token [TOKEN]：在命令行中指定 Hugging Face 用户访问令牌，而不是从文件中读取（默认从文件中读取）
• --vae-slicing：在创建大批量图像时减少内存使用（默认不启用 VAE 切片）
• --vae-tiling：在创建超高分辨率图像时减少内存使用，但会大幅降低推理速度（默认不启用 VAE 瓦片化）
• --xformers-memory-efficient-attention：减少内存使用，但需要 xformers 库支持（默认不需要 xformers）

为了便于使用并与其他管道兼容，部分原始 txt2img.py 选项已被重命名：

txt2img	stable-diffusion-docker
--H	--height
--W	--width
--n_iter	--iters
--n_samples	--samples
--ddim_steps	--steps

示例

以下两条命令是等价的：

./build.sh run 'abstract art'
./build.sh run --prompt 'abstract art'

设置种子为 42：

./build.sh run --seed 42 'abstract art'

选项可以组合使用：

./build.sh run --scale 7.0 --seed 42 'abstract art'

许多流行模型开箱即用：

模型名称	使用 --model 的选项
Stable Diffusion 1.4	'CompVis/stable-diffusion-v1-4'
Stable Diffusion 1.5	'runwayml/stable-diffusion-v1-5'
Stable Diffusion 2.0	'stabilityai/stable-diffusion-2'
Stable Diffusion 2.1	'stabilityai/stable-diffusion-2-1'
Stable Diffusion XL	'stabilityai/stable-diffusion-xl-base-1.0'
OpenJourney 1.0	'prompthero/openjourney'
Dreamlike Diffusion 1.0	'dreamlike-art/dreamlike-diffusion-1.0'
等等！	...

./build.sh run --model 'prompthero/openjourney' --prompt 'abstract art'

在 GPU 显存不足的系统上，可以尝试组合使用不同的选项：

• 如果容器被终止，可在 Docker Desktop 的“设置 -> 资源”中增加 CPU、内存和交换空间，以提供更多资源。
• 使用 --height 和 --width 将图像尺寸缩小到 512×512 以下，以减少内存占用并加快图像生成速度。
• 使用 --half 可减少内存使用，但会略微降低图像质量。
• 使用 --attention-slicing 可减少内存使用，但也会降低图像生成速度。
• 如果管道和硬件支持，可使用 --xformers-memory-efficient-attention 来减少内存使用。
• 通过调整 --samples 和 --iters，减少样本数量并增加迭代次数，从而降低整体内存使用。
• 使用 --skip 跳过安全检查，以减少代码执行量。

./build.sh run --height 256 --width 256 --half \
  --attention-slicing --xformers-memory-efficient-attention \
  --samples 1 --iters 1 --skip --prompt 'abstract art'

在 Windows 上，如果未使用 WSL2 而是 MSYS、MinGW 或 Git Bash，请在命令前加上 MSYS_NO_PATHCONV=1（或提前导出该变量）：

MSYS_NO_PATHCONV=1 ./build.sh run --half --prompt 'abstract art'

输出

模型

模型及其他文件会被缓存在名为 huggingface 的卷中。模型存储路径为 <volume>/diffusers/<model>/snapshots/<githash>/unet/<weights>。检查点文件（.ckpt）是官方模型的非官方版本，因此不属于官方发布内容。

图像

图像会以 PNG 格式保存在 output 文件夹中，文件名基于提示词文本。build.sh 脚本会在容器中创建并挂载该文件夹作为卷。

贡献

更多详情请参阅 CONTRIBUTING.md 文件。简而言之，遵循代码风格指南，同意开发者证书，并提交拉取请求。

Stable Diffusion Docker 快速上手指南

本指南帮助你在 GPU 加速的 Docker 容器中快速运行官方 Stable Diffusion 模型。

环境准备

系统要求

• GPU: 推荐使用支持 CUDA 的显卡，显存需 8GB 或以上（默认使用全量模型）。
  • 低配方案: 若显存不足，可通过添加 --device cpu 和 --onnx 参数使用 CPU 运行（速度较慢），或参考下文“选项”部分进行内存优化。
• Docker: 已安装 Docker 及 Docker Compose。
• 操作系统: Linux, macOS, 或 Windows (推荐 WSL2)。
  • Windows 注意: 若使用 MSYS/MinGW/Git Bash 而非 WSL2，需在命令前添加 MSYS_NO_PATHCONV=1。

前置依赖：Hugging Face Token

由于使用官方模型，必须配置 Hugging Face 访问令牌：

1. 登录 Hugging Face 账户。
2. 创建一个新的 User Access Token (权限选择 read)。
3. 将生成的令牌（以 hf_... 开头）保存为当前目录下的 token.txt 文件。

安装步骤

1. 克隆项目 (如果尚未下载):

   git clone https://github.com/fboulnois/stable-diffusion-docker.git
   cd stable-diffusion-docker
   

2. 构建镜像: 确保 token.txt 已在当前目录，然后执行：

   ./build.sh build
   # 或者简写为
   ./build.sh
   

   注：首次构建会自动拉取基础镜像和模型权重，耗时取决于网络状况。

   (可选) 直接拉取预构建镜像:

   ./build.sh pull
   

基本使用

所有操作均通过 ./build.sh run 命令完成。生成的图片将保存在 output 文件夹中。

1. 文生图 (Text-to-Image)

最基础的用法，根据提示词生成图片：

./build.sh run 'An impressionist painting of a parakeet eating spaghetti in the desert'

2. 图生图 (Image-to-Image)

基于现有图片和提示词生成新图片：

1. 将源图片复制到 input 文件夹（例如 parakeet_eating_spaghetti.png）。
2. 运行命令：

   ./build.sh run --image parakeet_eating_spaghetti.png --strength 0.6 'Bouquet of roses'
   

   • --strength: 控制重绘强度 (0.0-1.0)，数值越高改变越大。

3. 指定模型运行

支持直接调用 Hugging Face 上的热门模型（如 SDXL, OpenJourney 等）：

./build.sh run --model 'prompthero/openjourney' --prompt 'abstract art'

常用参数速查

• --prompt [TEXT]: 生成图片的提示词。
• --model [NAME]: 指定模型 ID (默认 CompVis/stable-diffusion-v1-4)。
• --height / --width: 图片分辨率 (默认 512，必须是 64 的倍数)。
• --seed [NUM]: 随机种子，用于复现结果。
• --steps [NUM]: 采样步数 (默认 50，步数越多质量越高但越慢)。
• --negative-prompt [TEXT]: 负向提示词（不希望出现的内容）。

低显存优化示例

若遇到显存不足导致容器崩溃，可组合以下参数降低资源消耗：

./build.sh run --height 256 --width 256 --half \
  --attention-slicing --xformers-memory-efficient-attention \
  --samples 1 --iters 1 --skip --prompt 'abstract art'