Stable Diffusion模型服务化：基于BentoDiffusion的生产级部署实践

在 AI 图像生成落地时，Stable Diffusion 这类模型真正的瓶颈往往不在模型效果，而在交付链路。模型跑在 notebook 里能出图，但要变成一个可以被业务系统调用、支持并发、能上 GPU 集群的 HTTP 服务，还需要解决模型加载、依赖隔离、请求协议、超时控制和资源调度等一系列工程问题。BentoDiffusion 正是围绕这一场景出现的参考项目，它背靠 BentoML 框架，把 Stable Diffusion 的模型服务化过程拆成可执行的模板。这篇文章会沿 BentoDiffusion 的生产思路，从一个最小文本生图服务入手，讲清楚如何准备环境、定义服务、构建 Bento、本地验证，最后再谈容器部署和常见排错。

1. 先理解 BentoDiffusion 到底解决了什么问题

1.1 从“Notebook 能出图”到“服务能被调用”之间缺了什么

大多数 Stable Diffusion 初学者都会经历一个流程：在 Jupyter Notebook 里加载diffusers，调用StableDiffusionPipeline，输入 prompt，得到一张图。这个过程非常顺利，因为所有依赖都装在同一套 Python 环境里，显卡驱动、CUDA 版本、模型文件路径都是当前机器上已经验证过的。

但一旦要把这个能力开放给其他人，问题立刻出现：

• 业务方不知道你的 Python 环境装了哪些包，版本是什么。
• 模型文件可能被放在本地某个目录，换一台机器就没有了。
• API 应该接收什么字段、返回什么格式，完全没有约定。
• 多人同时调用时，GPU 显存怎么分配、超时怎么处理，没有策略。
• 服务崩溃后如何自动恢复，如何查看日志，如何扩容，都是空白。

BentoDiffusion 的价值不是让模型出图更快，而是把“模型代码、依赖描述、推理入口、运行配置”打包成一个可复用的产物。这个产物可以本地运行，可以构建成镜像，也可以直接部署到 Kubernetes。它把原本散乱在 notebook 里的一次性代码，整理成了一套可交付的工程结构。

1.2 BentoML 和 BentoDiffusion 的分工

BentoML 是一个面向 AI 模型的服务化框架，负责处理服务生命周期、依赖打包、API 定义和部署对接。它提供了bentoml.service、bentoml.api这样的 Python 装饰器，也提供了bentoml build、bentoml serve、bentoml containerize等命令行工具。

BentoDiffusion 则是 BentoML 生态里针对扩散模型场景的参考实现。它不是一个独立的重型框架，而是把 Stable Diffusion 与 BentoML 结合时最常用的一套工程约定。从仓库结构来看，核心通常是service.py和bentofile.yaml：前者定义模型加载和推理接口，后者声明服务运行所需的依赖和文件。

在真实项目里，你需要同时理解这两层：

• BentoML 负责“服务怎么跑起来、怎么被打包、怎么被调度”。
• BentoDiffusion 负责“Stable Diffusion 这个具体模型怎么加载、怎么出图、怎么控制显存”。

如果你只是需要一个能出图的 API，直接照抄示例也能跑通；但如果想在生产环境稳定运行，必须理解每一层设计背后的原因。

1.3 什么场景适合用 BentoDiffusion 这种打包方式

适合的场景很明确：

不太适合的场景是：对首次推理延迟要求极低、需要毫秒级响应、且完全没有 GPU 资源的环境。Stable Diffusion 本身计算量大，BentoDiffusion 解决的是服务化问题，不是算法加速问题。如果目标是每秒处理几百张图，还需要在推理优化和硬件规模上单独投入。

2. 环境准备：硬件驱动、Python 依赖和模型下载链路

2.1 本地开发环境需要先确认三件事

在写服务代码之前，先把环境跑通。常见顺序是：

1. 确认 GPU 驱动和 CUDA 可用。
2. 创建独立 Python 虚拟环境。
3. 确认能下载 Hugging Face 模型文件。

第一步用nvidia-smi检查驱动，同时确认显卡驱动支持的 CUDA 版本足够新。注意，nvidia-smi显示的 CUDA 版本是驱动支持的版本，不一定是 PyTorch 运行时的版本。PyTorch 通常自带 CUDA 运行时，只要驱动版本不低于 PyTorch 要求即可。

nvidia-smi

预期输出里会有一行CUDA Version: 12.2之类的信息。如果你没有 GPU，也可以用 CPU 跑通服务，但生成速度会非常慢，后面的显存相关排错部分可以跳过。

第二步是创建虚拟环境，避免把依赖装进系统 Python。推荐使用 Python 3.10 或 3.11，这两个版本对 PyTorch 和 diffusers 的兼容性比较稳定。

python -m venv .venv source .venv/bin/activate

2.2 安装 bentoml 和 Stable Diffusion 依赖

BentoDiffusion 的核心依赖包括bentoml、diffusers、transformers、torch、accelerate、safetensors。其中accelerate用于设备管理和混合精度，safetensors用于安全加载权重。

pip install --upgrade pip pip install bentoml pip install diffusers transformers accelerate safetensors pip install torch --index-url https://download.pytorch.org/whl/cu121

这里有两个值得注意的点：

• torch版本要和本地 GPU 驱动匹配，不要盲目安装最新版本。
• diffusers版本更新很快，示例代码在不同版本之间可能有细微差异。落地时建议固定版本号，而不是直接使用latest。

安装完成后，用一段 Python 代码验证关键链路：

import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else "CPU only")

如果torch.cuda.is_available()返回False，后面服务启动时就算配置了 GPU 资源，模型也会被加载到 CPU，生成速度会明显变慢。

2.3 模型下载链路要提前通

BentoDiffusion 的服务在启动时通常会把模型加载到内存。这个动作依赖 Hugging Face 的模型下载链路。如果你没有先验证过模型下载，服务启动时可能会出现网络超时或者认证失败。

这里要区分两种模型访问方式：

• 公开模型：例如stabilityai/stable-diffusion-2-1-base，直接下载即可。
• 受限模型：某些模型需要登录 Hugging Face 并同意协议。

如果使用受限模型，需要先登录：

huggingface-cli login

登录成功后，模型会被缓存到本地目录。缓存存在的好处是，服务启动时如果模型已经存在，就不需要重新下载；坏处是如果你修改了模型版本，旧缓存可能导致“看起来没生效”的问题，后面排查部分会专门提到。

学习环境可以接受“启动时临时下载”，但生产环境不建议这样做。生产环境应该在构建镜像或构建 Bento 时把模型文件放进去，或者在部署前预热到持久化缓存，避免每次扩容都触发一次完整下载。

3. 编写 BentoDiffusion 风格的服务入口

3.1 项目目录设计

一个最小项目通常只需要两个核心文件：

sd-service/ ├── service.py └── bentofile.yaml

service.py是服务逻辑，bentofile.yaml是构建 Bento 的描述文件。模型文件不放在代码目录，运行时由diffusers从本地缓存加载。

如果你参考 BentoDiffusion 仓库，会发现它还有一些额外的部署描述文件。不过从学习顺序来说，先跑通这两个文件就足够。

3.2 定义 API 和数据返回格式

下面是一个最小可运行的service.py。它接收用户输入 prompt，调用 Stable Diffusion Pipeline 生成图片，然后把图片以 base64 字符串返回。

from __future__ import annotations import base64 import io import bentoml from bentoml.io import JSON MODEL_ID = "stabilityai/stable-diffusion-2-1-base" @bentoml.service( resources={"gpu": 1}, traffic={"timeout": 120}, ) class StableDiffusionService: def __init__(self) -> None: self.pipe = None @bentoml.on_event("startup") async def load_model(self) -> None: import torch from diffusers import StableDiffusionPipeline self.pipe = StableDiffusionPipeline.from_pretrained( MODEL_ID, torch_dtype=torch.float16, ) self.pipe.to("cuda") @bentoml.api def generate(self, prompt: str = "a cat on the moon") -> JSON: image = self.pipe( prompt=prompt, num_inference_steps=30, guidance_scale=7.5, ).images[0] buffer = io.BytesIO() image.save(buffer, format="PNG") encoded = base64.b64encode(buffer.getvalue()).decode("utf-8") return JSON( { "image_base64": encoded, "format": "png", "model_id": MODEL_ID, } )

这段代码有几个关键点。

@bentoml.service里的resources={"gpu": 1}告诉部署平台，这个服务需要一张 GPU 卡。这个配置在本地直接用bentoml serve时不会强制校验，但在 Kubernetes 或云平台调度时会被读取。

traffic={"timeout": 120}把单次请求的超时时间设置为 120 秒。Stable Diffusion 在 CPU 容器里跑的时候，30 步推理很容易超过 60 秒。如果不设置较大的超时，请求很容易在代理层被中断。

@bentoml.on_event("startup")是模型预热入口。模型加载很慢，不能每次请求都重新加载。放在启动事件里，可以保证服务对外提供请求之前，模型已经就绪。

返回 base64 而不是直接返回图片，是为了让示例更通用。前端拿到 base64 后可以直接展示，也可以转存到对象存储。如果业务方更希望接口直接返回图片二进制流，可以把返回类型改成bentoml.io.Image，但那样连调用测试和后续维护都要一起调整。

3.3 用 bentofile.yaml 描述依赖和文件

bentofile.yaml是 BentoML 打包时的元数据。它告诉 BentoML：服务入口在哪、需要包含哪些文件、需要安装哪些 Python 包。

service: "service.py:svc" include: - "service.py" python: packages: - bentoml>=1.2.0 - diffusers>=0.26.0 - transformers>=4.36.0 - accelerate>=0.25.0 - safetensors>=0.4.0

注意service字段写的是"service.py:svc"，意思是查找service.py里名称叫svc的变量。我们在代码里没有显式定义svc，怎么办？BentoML 会把你用@bentoml.service装饰的类自动挂载为默认服务对象。实际项目中也可以显式写svc = StableDiffusionService，这样更清晰。

include列表很重要。如果在本地代码里还使用了prompts.txt、模型配置文件、工具模块，都要把它们列进来。漏掉某个文件，本地运行没问题，构建新环境后会直接报FileNotFoundError。

python.packages是创建运行环境时执行的pip install列表。这里写的是版本下限，实际项目建议使用==锁定版本，避免未来依赖升级导致行为变化。需要特别提醒：torch没有写在这里。原因是为了避免 Bento 构建时统一从默认源安装 torch 而覆盖你本地的 CUDA 版本。在生产构建时，可以把 torch 的安装源和版本显式加入，但本地开发阶段先保持简单。

3.4 关键配置参数速查

BentoDiffusion 风格的服务配置并不复杂，但每个参数都有明确的含义。以下是最常用的一组：

这些参数在第一次本地运行时不一定全部显式配置，但进入生产环境前必须逐项确认。

4. 本地构建 Bento 并验证服务

4.1 构建 Bento 产物

在项目目录下执行：

bentoml build

执行成功后，bentoml list可以看到生成结果。

构建的本质是生成一个自包含的交付单元，里面包括代码、依赖描述、服务配置和构建信息。它不是把模型权重也复制进去。默认情况下，模型仍然从 Hugging Face 缓存读取。如果希望把模型权重也塞进 Bento，需要额外处理，但这会显著增大 Bento 体积，实际项目里通常会改用待部署机器的本地缓存。

如果bentoml build失败，最常见的原因是bentofile.yaml里的依赖名称写错，或者service.py在导入阶段就报错。注意，检查失败时不会真正去安装所有依赖，主要还是做静态检查。

4.2 本地启动服务

本地调试可以使用：

bentoml serve service.py:svc --reload

--reload是开发模式，修改代码后会自动重启。使用--reload时不需要先执行bentoml build，直接读取本地文件。

如果一切正常，日志里会出现类似下面的信息：

Starting production HTTP server on 0.0.0.0:3000

默认端口是 3000。访问http://127.0.0.1:3000可以看到服务描述页面，这有助于快速确认接口路径和参数格式。

4.3 用 curl 验证文本生图接口

服务启动后，用 curl 发起一个请求：

curl -X POST http://127.0.0.1:3000/generate \ -H "Content-Type: application/json" \ -d '{"prompt": "a red fox in the snow"}'

返回内容是一个 JSON，包含字段image_base64。为了方便验证图片是否正确，可以把 base64 保存成文件：

curl -s -X POST http://127.0.0.1:3000/generate \ -H "Content-Type: application/json" \ -d '{"prompt": "a red fox in the snow"}' \ | python -c "import sys, json, base64; data=json.load(sys.stdin); open('out.png', 'wb').write(base64.b64decode(data['image_base64']))"

这条命令只是把请求返回的 base64 字段还原成图片文件。打开out.png如果能看到内容，说明推理链路是通的。

4.4 验证日志和基础性能指标

服务启动后，观察日志可以发现几个重要信号：

• 模型加载耗时。
• 是否使用了 GPU。
• 单次推理耗时。
• 是否存在 CUDA 内存不足警告。

在本地开发阶段，不需要复杂监控。只要确认下面几点：

如果你的机器没有 GPU，日志里会显示模型加载到了 CPU，生成时间可能是几十秒甚至几分钟。这不代表代码有错，只说明资源不满足生产条件。

5. 部署到生产：容器镜像与 GPU 调度

5.1 从 Bento 构建容器镜像

本地服务验证通过后，下一步是构建可部署镜像。BentoML 提供了containerize命令：

bentoml containerize <bento_tag>

这里需要先通过bentoml list查看构建出来的 Bento tag，例如stable-diffusion-service:latest。

镜像构建完成后，可以用 Docker 启动：

docker run -p 3000:3000 --gpus all stable-diffusion-service:latest

--gpus all是把宿主机 GPU 设备传给容器。这里的镜像基础结构会由 BentoML 自动生成，不需要手动写 Dockerfile。但要注意镜像体积会比较大，因为里面包含 Python 运行环境和所有依赖。

5.2 Kubernetes 部署时的 GPU 资源申请

如果部署到 Kubernetes，核心是正确处理 GPU 资源声明。以下是一个最小 Deployment 片段：

apiVersion: apps/v1 kind: Deployment metadata: name: bento-diffusion spec: replicas: 1 selector: matchLabels: app: bento-diffusion template: metadata: labels: app: bento-diffusion spec: containers: - name: bento-diffusion image: your-registry/stable-diffusion-service:latest ports: - containerPort: 3000 resources: limits: nvidia.com/gpu: "1" env: - name: BENTOML_GRPC_PORT value: "3000"

关键点是limits.nvidia.com/gpu: "1"。这要求集群里有 GPU 调度能力，通常需要安装 NVIDIA Device Plugin。如果不加这个字段，Pod 可能被调度到没有 GPU 的节点上。

另一个需要注意的问题是模型权重。如果镜像里没有模型权重，Pod 启动时会在运行时从 Hugging Face 下载。这造成两个问题：第一是扩容时多个 Pod 同时下载，占用带宽；第二是如果构建环境无法访问外网，Pod 会反复失败。生产环境通常把模型权重放在共享存储，或者把权重在镜像构建阶段固化进去。

5.3 暴露服务和外部流量控制

Kubernetes 中通过 Service 暴露端口：

apiVersion: v1 kind: Service metadata: name: bento-diffusion-svc spec: selector: app: bento-diffusion ports: - port: 3000 targetPort: 3000

如果集群里使用 Ingress 或 API 网关，还需要在网关层处理超时时间。这里要特别注意，BentoML 服务内部超时是 120 秒，但如果网关层超时设置成 30 秒，请求仍会被提前断开。生产环境应该把网关超时、Service 超时、BentoMLtraffic.timeout三者对齐。

6. 常见坑和排查链路

6.1 现象一：CUDA out of memory

这个错误在图像生成服务里非常高频。日志中通常会出现：

torch.cuda.OutOfMemoryError: CUDA out of memory.

可能原因有：

• 显存被其他进程占用。
• 推理时同时发起了多个请求，每个请求都分配了显存。
• 模型加载到 GPU 后，又叠加了太多中间张量。

检查顺序：

nvidia-smi

先看当前 GPU 显存使用率。如果显存已经被占满，先释放其他进程。

再用docker stats或kubectl describe pod看容器内的显存配额。如果问题只在并发时出现，需要限制服务并发数，或者在@bentoml.service的traffic中设置较小的concurrency。

代码层面也可以优化，例如把 pipeline 固定使用float16，减少精度带来的显存开销。必要时，可以在一张卡上同时跑多个模型，但必须显式控制显存，否则某个请求可能触发 OOM。

6.2 现象二：服务启动时反复下载模型

日志里如果出现大量Downloading输出，说明模型缓存没有生效。可能原因：

• 每次运行使用的容器不同，缓存路径没有持久化。
• 修改了MODEL_ID，导致模型目录变化。
• 缓存目录权限不足，无法写入。

本地开发时，检查 Hugging Face 缓存目录：

echo $HF_HOME echo $HUGGINGFACE_HUB_CACHE

如果没有设置，可以统一设置到持久化目录：

export HF_HOME=/data/huggingface

生产环境建议把模型权重作为一个独立镜像层，或者在共享存储中预热。

6.3 现象三：接口返回 500 或者请求超时

接口返回 500 时，先看 BentoML 日志。常见原因：

• MODEL_ID写错，模型加载失败。
• prompt 参数为空或者类型不对。
• 代码中base64.b64encode接收了非 bytes 类型。
• 显存不足，生成过程中崩溃。

请求超时则优先检查：

1. 是否有 GPU，模型是否真的加载到 GPU。
2. 服务是否在冷启动阶段，模型是否还未加载完成。
3. 上层网关的超时配置是否比 BentoML 的超时短。

冷启动问题尤其容易误判。模型加载可能需要几十秒，如果在这个阶段发请求，服务可能还在初始化。生产环境可以通过 BentoML 的 readiness 探针来控制流量进入时间，避免把未就绪实例暴露给业务方。

6.4 快速排查顺序表

排错时不要一上来就怀疑 BentoDiffusion 本身。绝大多数问题出在依赖版本、资源声明和文件路径上。

7. 生产最佳实践与可复用清单

7.1 配置外置化，不要硬编码模型和路径

现在service.py里直接写了MODEL_ID。这个问题在示例里可以接受，生产环境则应该通过环境变量注入。

import os MODEL_ID = os.getenv("MODEL_ID", "stabilityai/stable-diffusion-2-1-base")

这样不同环境可以切换不同模型，不用改代码。类似地，num_inference_steps、guidance_scale、缓存目录、并发数、超时时间都可以用环境变量控制。配置外置化的意义在于，让开发和运维在不用重新构建镜像的前提下调整服务行为。

7.2 增加鉴权、限流和监控

Stable Diffusion 服务通常不会直接暴露在公网。就算在公网，也应该在网关层加认证。最简单的做法是在 Ingress 或者 API 网关注入 Token 校验。

服务内部同样可以记录关键指标：

• 请求总数。
• 推理耗时。
• 显存水位。
• 模型加载耗时。

BentoML 本身提供了一些指标能力，但生产环境通常还需要把指标接入 Prometheus 或云监控。第一步不一定做得很全，但至少要能在出问题时说清楚“是模型推理慢，还是容器调度慢”。

7.3 性能优化和成本控制

Stable Diffusion 服务是典型的 GPU 消耗型服务。在没有 GPU 的时候，CPU 推理速度非常慢，不适合生产。在 GPU 环境里，也要关注单卡吞吐和任务排队。

常见优化方向：

在成本控制上，最重要的是不要对长尾请求使用过大 GPU。有很多请求可能只需要 20 步就能达到业务要求，不一定非要默认 50 步。把参数做成可配置，让调用方根据业务场景选择。

7.4 发布前检查清单

以下清单可以直接复制到团队文档中：

• [ ] Python 版本和依赖版本是否固定。
• [ ]nvidia-smi查看 GPU 驱动是否正常。
• [ ]torch.cuda.is_available()是否返回True。
• [ ] 模型是否可以从当前环境访问。
• [ ] 模型权重是否已经持久化，而不是运行时临时下载。
• [ ]bentoml build是否能成功。
• [ ] 本地bentoml serve是否能用 curl 生成图片。
• [ ] 镜像构建是否有足够磁盘空间。
• [ ] Kubernetes 是否配置了 GPU 资源limits.nvidia.com/gpu。
• [ ] 网关、Service、BentoML 三层的超时时间是否一致。
• [ ] 是否配置了 readiness 或健康检查，避免流量进入未就绪实例。
• [ ] 是否设置了鉴权、限流和日志采集。

这些项目不需要一次全部做完，但每进入一个新环境，都应该按这个顺序检查一遍。BentoDiffusion 的逻辑并不复杂，稳定部署的关键在于环境可复现和异常可观测。第一次跑通后，建议把生成的bentofile.yaml和service.py变成团队内部模板。后续接入其他扩散模型时，改动模型 ID、参数和依赖版本即可，比每次从 notebook 重新整理代码要高效得多。