PaddleHub 文图生成实战：disco_diffusion_clip_rn50 模型安装、API 调用与 Serving 部署全解析-平芜编程栈

人工智能
大模型
微调
模型推理服务

【免费下载链接】PaddleFormers

PaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.

项目地址：https://gitcode.com/gh_mirrors/pa/PaddleFormers

本文以 PaddleFormers 仓库中的disco_diffusion_clip_rn50文图生成模块为主体，系统讲解基于 PaddlePaddle 的 Disco Diffusion（DD + CLIP ResNet50）文图生成模型的原理、安装步骤、命令行与 Python API 调用方式、全部生成参数的含义与调优建议，以及基于 PaddleHub Serving 的在线服务部署方法。读完本文，你将掌握如何用一句话 prompt 生成高质量艺术图像，并能独立完成该模型的本地推理与在线服务化。

一、模型基本信息与核心原理

1.1 模型概览

disco_diffusion_clip_rn50是 PaddleHub 提供的一个文图生成（Text-to-Image）模块，其基本信息如下：

项目	内容
模型名称	disco_diffusion_clip_rn50
类别	图像-文图生成
网络	DD + CLIP ResNet50
数据集	-
是否支持 Fine-tuning	否
模型大小	2.8GB
最新更新日期	2022-08-02
数据指标	-

该模块由两部分核心组件构成：

扩散模型（Diffusion Model）：一种生成模型，能够从纯噪声输入中逐步重建出原始图像，负责"作画"；
多模态预训练模型 CLIP：将文本与图像表示到同一个特征空间，语义相近的文本与图像在该空间中的距离更近，负责"把关"。

生成过程中，扩散模型从初始噪声（或用户指定的初始图像）出发生成候选图像，CLIP 持续计算候选图像与输入文本之间的语义距离并给出引导梯度，扩散模型在 CLIP 引导下迭代优化，最终生成与文本描述语义一致的图像。本模块使用的 CLIP 模型结构为 ResNet50（RN50）。

该方案对应的基础研究工作分别为扩散模型方向（Diffusion Models Beat GANs on Image Synthesis）与多模态表征方向（Learning Transferable Visual Models From Natural Language Supervision），在模块目录的 README.md 中有对应论文说明。

1.2 仓库中的源码组织

从仓库源码结构看，本模块的工程实现分为四部分（见模块目录）：

module.py：PaddleHub 模块入口，定义DiscoDiffusionClip类，封装generate_imageAPI 以及命令行（@runnable）与 Serving（@serving）两种执行方式；
reverse_diffusion/：扩散模型核心实现，包括runner.py（生成主循环）、config.py（参数加载与校验）、helper.py（模型加载与 prompt 解析）、resources/default.yml（默认参数）以及model/下的 UNet、高斯扩散、cutouts、噪声等实现；
clip/：OpenAI CLIP 的 Paddle 实现（源自 clip.paddle 项目），用于引导扩散过程；
resize_right/：高质量图像缩放工具库。

二、环境依赖与安装

2.1 环境依赖

使用该模块前需要满足以下环境条件：

paddlepaddle >= 2.0.0
paddlehub >= 2.2.0，PaddleHub 的安装方式可参考 PaddleHub 安装文档

此外，模块自身还依赖以下 Python 包（见 requirements.txt）：

numpy paddle_lpips==0.1.2 ftfy docarray>=0.13.29 pyyaml regex tqdm ipywidgets

其中paddle_lpips用于计算初始图像与生成图像之间的感知相似度损失，docarray用于承载和操作生成结果。

2.2 安装模块

在满足上述依赖后，通过 PaddleHub 一条命令即可安装：

$ hub install disco_diffusion_clip_rn50

如需安装指定版本，可执行：

$ hub install disco_diffusion_clip_rn50 == 1.0.0

如安装过程中遇到问题，可以参考仓库提供的零基础环境搭建文档：零基础 Windows 安装、零基础 Linux 安装、零基础 MacOS 安装。

三、模型 API 预测

3.1 命令行预测

安装完成后，可直接通过hub run命令进行文图生成。以下命令输入一句描述性文本，将图像输出到指定目录：

$ hub run disco_diffusion_clip_rn50 --text_prompts "A beautiful painting of a singular lighthouse, shining its light across a tumultuous sea of blood by greg rutkowski and thomas kinkade, Trending on artstation." --output_dir disco_diffusion_clip_rn50_out

hub run底层会调用module.py中run_cmd方法（见 module.py），该方法通过 argparse 解析所有命令行参数并逐项传入generate_image，因此命令行模式下可以覆盖该 API 的全部参数，例如指定随机种子、调整图像尺寸等：

$ hub run disco_diffusion_clip_rn50 \ --text_prompts "a beautiful painting of Chinese architecture, by krenz, sunny, super wide angle, artstation." \ --seed 42 \ --width_height "[512, 512]" \ --steps 250 \ --clip_guidance_scale 5000 \ --output_dir my_out

3.2 预测代码示例

在 Python 中，通过 PaddleHub 加载模块并调用generate_image即可生成图像：

import paddlehub as hub module = hub.Module(name="disco_diffusion_clip_rn50") text_prompts = ["A beautiful painting of a singular lighthouse, shining its light across a tumultuous sea of blood by greg rutkowski and thomas kinkade, Trending on artstation."] # 生成图像，默认会在 disco_diffusion_clip_rn50_out 目录保存图像 # 返回的 da 是一个 DocumentArray 对象，保存了所有结果，包括最终结果和迭代过程的中间结果 # 可以通过操作 DocumentArray 对象对生成的图像做后处理，保存或者分析 da = module.generate_image(text_prompts=text_prompts, output_dir='./disco_diffusion_clip_rn50_out/') # 手动将最终生成的图像保存到指定路径 da[0].save_uri_to_file('disco_diffusion_clip_rn50_out-result.png') # 展示所有的中间结果 da[0].chunks.plot_image_sprites(skip_empty=True, show_index=True, keep_aspect_ratio=True) # 将整个生成过程保存为一个动态图 gif da[0].chunks.save_gif('disco_diffusion_clip_rn50_out-result.gif')

从源码看，生成过程中的每个中间结果都会被记录为Document的chunks（见 runner.py），因此你可以通过da[0].chunks访问完整迭代过程，既能把最终结果保存为 PNG，也能把全部中间帧导出为 GIF 动画，直观观察"噪声 → 艺术图像"的演化轨迹。

3.3 生成流程的源码级解析

了解底层执行链路有助于更好地使用该模型。generate_image最终调用reverse_diffusion包中的create函数（见 reverse_diffusion/init.py），整体流程为：

参数装配：create将用户传入的 kwargs 与resources/default.yml中的默认参数合并，类型校验后封装为配置对象（见 config.py）；
模型加载：加载扩散 UNet 模型（512x512_diffusion_uncond_finetune_008100）与辅助模型 Secondary Diffusion Model，并加载启用的 CLIP 模型，所有参数stop_gradient = True冻结（见 helper.py）；
初始状态构造：默认以随机高斯噪声为起点；若指定init_image则将图像归一化到 [-1, 1]；若启用perlin_init则生成 Perlin 噪声作为起点；
引导采样：在runner.do_run中，每一步迭代都通过cond_fn完成——将当前图像切分为若干 "cuts"（overview cuts 与 inner cuts），送入 CLIP 编码得到图像嵌入，与文本 prompt 的目标嵌入计算球面距离损失（spherical_dist_loss），再叠加 TV 损失、range 损失、饱和度损失以及（可选）LPIPS 初始图像一致性损失，最终得到引导梯度并反传给扩散采样器（runner.py）；
采样与输出：按diffusion_sampling_mode选择 DDIM 或 PLMS 采样器逐步去噪，按display_rate周期性保存中间帧到输出目录，最终返回包含全部结果的DocumentArray。

3.4 generate_image API 详解

generate_image的完整函数签名如下（见 module.py）：

def generate_image( text_prompts, style: Optional[str] = None, artist: Optional[str] = None, init_image: Optional[str] = None, width_height: Optional[List[int]] = [1280, 768], skip_steps: Optional[int] = 0, steps: Optional[int] = 250, cut_ic_pow: Optional[int] = 1, init_scale: Optional[int] = 1000, clip_guidance_scale: Optional[int] = 5000, tv_scale: Optional[int] = 0, range_scale: Optional[int] = 0, sat_scale: Optional[int] = 0, cutn_batches: Optional[int] = 4, diffusion_sampling_mode: Optional[str] = 'ddim', perlin_init: Optional[bool] = False, perlin_mode: Optional[str] = 'mixed', seed: Optional[int] = None, eta: Optional[float] = 0.8, clamp_grad: Optional[bool] = True, clamp_max: Optional[float] = 0.05, randomize_class: Optional[bool] = True, clip_denoised: Optional[bool] = False, fuzzy_prompt: Optional[bool] = False, rand_mag: Optional[float] = 0.05, cut_overview: Optional[str] = '[12]*400+[4]*600', cut_innercut: Optional[str] = '[4]*400+[12]*600', cut_icgray_p: Optional[str] = '[0.2]*400+[0]*600', display_rate: Optional[int] = 10, n_batches: Optional[int] = 1, batch_size: Optional[int] = 1, batch_name: Optional[str] = '', use_gpu: Optional[bool] = True, output_dir: Optional[str] = 'disco_diffusion_clip_rn50_out'):

3.4.1 输入提示词与风格参数

text_prompts(str)：输入的语句，描述想要生成的图像内容。比较有效的构造方式是"一段描述性的文字内容 + 指定艺术家的名字"，例如"a beautiful painting of Chinese architecture, by krenz, sunny, super wide angle, artstation."。从 helper.py 的parse_prompt实现可以看到，prompt 支持以冒号分隔的权重写法（如"a cat:0.8"），权重会参与引导损失加权归一化（权重之和需非零，否则抛出RuntimeError）；
style(Optional[str])：指定绘画风格，如'watercolor'、'Chinese painting'等。不指定时风格完全由 prompt 决定。从 module.py 可以看到，指定 style 后会被自动拼接到 prompt 末尾（",{style}"）；
artist(Optional[str])：指定特定艺术家（如Greg Rutkowski、krenz），生成该艺术家的绘画风格。指定后同样会自动拼接，并追加",trending on artstation"后缀；
init_image(Optional[str])：初始图像路径。提供后将用该图像替换随机噪声作为扩散起点（图像会被缩放并对齐到 64 的倍数后归一化到 [-1, 1]）。使用 init_image 时通常需要把skip_steps提高到总步数的 50% 左右才能保留原图的主体特征；低skip_steps得到"受原图启发"的结果（保留颜色与大致构图），高skip_steps则更接近对原图的纹理微调。

3.4.2 画布尺寸与随机性参数

width_height(Optional[List[int]])：输出图像的宽高，默认[1280, 768]。宽高均需为 64 的倍数（runner 中通过(size // 64) * 64自动向下取整对齐），图像越大计算时间越长；
seed(Optional[int])：随机种子。输入默认是随机高斯噪声，不同种子得到不同初始输入与不同结果。指定相同种子可复现相近的输出（严格来说结果相似但不完全相同）。若不指定，config 会随机生成一个种子，并在参数报告中打印实际使用的种子值；
n_batches(int)：生成的图像数量（默认 1），每个 batch 对应返回结果中的一个 Document；
batch_size(int)：每个 batch 内部并行生成的图像数，默认为 1。

3.4.3 扩散过程核心参数（质量关键）

steps(int)：去噪总步数，默认 250。步数越多细节越精细，但渲染时间线性增长；250–500 步之后收益递减，复杂画面可适当提升到 1000 甚至更多；
skip_steps(int)：跳过的初始去噪步数，默认 0。前几步噪声极高、画面变化剧烈，跳过约 10%–15% 的步数通常不影响最终效果，还能显著缩短渲染时间；跳过头则剩余噪声不足以生成新内容；
diffusion_sampling_mode(str)：采样算法，可选ddim（默认，更成熟稳定）或plms（更少的步数即可取得不错效果，但测试较少、可能有副作用）；
eta(float)：扩散模型变量，控制每个时间步混入的随机缩放噪声量（0 为无噪声，1.0 为更多噪声，默认 0.8）。eta 设为 0 时 50–75 步即可得到不错结果，设为 1.0 则建议配合 250 步以上使用；
clip_denoised(bool)：是否对去噪结果做 CLIP 裁剪，默认 False；
randomize_class(bool)：是否随机化类别，默认 True。

3.4.4 CLIP 引导强度参数

clip_guidance_scale(int)：CLIP 引导强度（CGS），默认 5000。它决定每个时间步 CLIP 把图像向 prompt 方向推动的力度，是影响图像质量最重要的参数之一。CGS 一般随图像尺寸等比缩放：例如从 512×512 提高到 512×768（总像素增加 50%），可相应把 CGS 从 5000 提高到 7500。CGS 过小则图像与文本关联弱，过大则过冲导致画面失真；
init_scale(int)：CLIP 匹配初始图像的强度，默认 1000。与 CGS 互相制衡：init_scale 过大则图像在扩散中几乎不变，CGS 过大则初始图像信息丢失；
cutn_batches(int)：每个时间步的切块评估批次，默认 4。默认调度下每步执行 16 个 cuts，cutn_batches=4时每步共 64 个 cuts、分 4 批串行计算，从而在不增加峰值显存的前提下提升细节质量，代价是渲染时间约为原来的 4 倍。关系为：(调度 cuts) × cutn_batches = 每时间步总 cuts；
cut_ic_pow(int)：inner cuts 边框尺寸指数，默认 1。值越大边框越大、切块越小、细节越精细，但过小/过多的 inner cuts 会导致整体连贯性下降甚至出现马赛克效应；
cut_overview / cut_innercut / cut_icgray_p(str)：overview cuts、inner cuts 与 inner cut 灰度概率的调度字符串（默认分别为[12]*400+[4]*600、[4]*400+[12]*600、[0.2]*400+[0]*600）。runner 中会通过eval解析为列表，并按当前时间步索引取值（见 runner.py），实现"前 400 步粗切、后 600 步细切"的自适应切块调度。

3.4.5 正则化与图像质量参数

tv_scale(int)：全变差去噪强度，默认 0（关闭）。控制输出平滑度，图像过于"噪点颗粒感"时可调大；TV 去噪在平滑平坦区域噪声的同时能较好保留边缘；
range_scale(int)：色彩对比度调节，默认 0（关闭）。值越小对比度越高、色板更精简，产生更鲜艳或海报化的效果；值越大画面越柔和；
sat_scale(int)：饱和度调节，默认 0（关闭）。图像过饱和时可调大以降低饱和度；
clamp_grad(bool) / clamp_max(float)：内部梯度限幅开关与限幅值。clamp_grad 阻止极端结果；clamp_max 默认 0.05 提供更平滑柔和的色彩，调高到 0.15–0.3 可带来更鲜明的对比与活力。若关闭 clamp_grad 后图像剧烈变化，通常说明 clip_guidance_scale 偏高；
fuzzy_prompt(bool) / rand_mag(float)：是否在 prompt 损失中加入多个带噪声的 prompt 以增加输出多样性（默认关闭），rand_mag 控制所加随机噪声的幅度。

3.4.6 起始噪声与过程监控参数

perlin_init(bool) / perlin_mode(str)：是否使用 Perlin 噪声作为扩散起点（默认 False）。Perlin 噪声特性与随机噪声明显不同，值得实验；注意启用 perlin_init 会覆盖 init_image。perlin_mode 支持colored、gray、mixed（默认混合模式），见 runner.py；
display_rate(int)：每隔多少步保存并展示一次中间结果，默认 10。设低（如 5 或 10）可尽早预览生成方向，设高可减少展示开销；
batch_name(str)：批次命名，生成的 DocumentArray 会以disco_diffusion_clip_rn50-[batch_name]-[seed]命名，建议使用唯一名称避免结果被覆盖。

3.4.7 计算设备与输出目录

use_gpu(bool)：是否使用 GPU，默认 True。使用 GPU 时需要正确设置CUDA_VISIBLE_DEVICES环境变量；module.py中会据此调用paddle.device.set_device完成设备切换；
output_dir(str)：输出目录，默认disco_diffusion_clip_rn50_out，中间过程帧（progress-*.png）与最终结果都会写入该目录。

3.5 返回值说明

generate_image返回一个DocumentArray对象（ra），其中包含n_batches个 Document，每个 Document 的chunks中保存了迭代过程的所有中间结果（每条 chunk 还带有cur_t时间步标签，见 runner.py）。你可以通过da[0].save_uri_to_file(...)保存最终图像，通过da[0].chunks.save_gif(...)导出动态过程，或通过da[0].chunks.plot_image_sprites(...)拼接展示所有中间帧，对结果做灵活的保存与分析。

四、PaddleHub Serving 服务部署

PaddleHub Serving 可以将该模块部署为一个在线文图生成服务，供其他程序通过 HTTP 调用。

4.1 第一步：启动 PaddleHub Serving

运行如下启动命令：

$ hub serving start -m disco_diffusion_clip_rn50

启动完成后即完成了一个文图生成在线服务 API 的部署，默认端口号为8866。

NOTE：如使用 GPU 预测，需要在启动服务之前设置CUDA_VISIBLE_DEVICES环境变量，否则无需设置。

4.2 第二步：发送预测请求

服务端配置好后，以下代码即可发送预测请求并获取结果。返回的预测结果在反序列化后即是上述接口声明中的 DocumentArray 类型，返回后对结果的操作方式与使用generate_image接口完全相同：

import requests import json import cv2 import base64 from docarray import DocumentArray # 发送HTTP请求 data = {'text_prompts': 'in the morning light,Overlooking TOKYO city by greg rutkowski and thomas kinkade,Trending on artstation.'} headers = {"Content-type": "application/json"} url = "http://127.0.0.1:8866/predict/disco_diffusion_clip_rn50" r = requests.post(url=url, headers=headers, data=json.dumps(data)) # 获取返回结果 da = DocumentArray.from_base64(r.json()["results"]) # 手动将最终生成的图像保存到指定路径 da[0].save_uri_to_file('disco_diffusion_clip_rn50_out-result.png') # 将生成过程保存为一个动态图gif da[0].chunks.save_gif('disco_diffusion_clip_rn50_out-result.gif')

从实现角度看，Serving 请求会进入module.py中标注@serving的serving_method（见 module.py）：它将请求参数透传给generate_image，并把返回的 DocumentArray 通过to_base64()序列化后随 HTTP 响应返回，客户端再用DocumentArray.from_base64(...)反序列化还原，因此两端对结果的处理方式完全一致。

五、版本与更新历史

1.0.0：初始发布，可通过以下命令安装指定版本：
```
$ hub install disco_diffusion_clip_rn50 == 1.0.0
```

六、使用建议与注意事项

prompt 构造：推荐遵循[主体] + [细节] + [场景/氛围] + [艺术家/风格修饰]的结构，并善用style、artist参数自动拼接；prompt 支持:权重语法来调整不同元素的相对重要程度；
显存与速度权衡：图像尺寸、steps、cutn_batches 是渲染时间的主要来源。默认 1280×768 输出在消费级 GPU 上耗时较长，可先用 512×512 快速试验 prompt 效果，再放大尺寸精修；
可复现性：固定seed可复现相近结果；每次运行后配置会以参数表形式打印实际使用的种子，便于回放；
初始图像创作：传入init_image并配合较高skip_steps（约为总步数的一半）可对已有图像进行风格重绘，是扩展创作手段的有效方式；
模型不可微调：该模块不支持 Fine-tuning（表中"是否支持 Fine-tuning"为"否"），使用时以推理为主。