blockdiffusion-api / MODEL_SCOPE_DEPLOY.md
wkea's picture
Deploy Space
c388140 verified
|
Raw History Blame Contribute Delete
9.7 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

ModelScope 快速部署指南(SwingDeploy / ModelScope Pipeline / 函数计算 FC)

本文面向“接手者/AI 代理”,目标是让你在不了解本仓库历史的前提下,也能把 BlockDiffusion 作为 ModelScope Pipeline 形态快速部署到 SwingDeploy → FC。


0. 目标与前置假设

0.1 目标

  • 让 ModelScope 能在云端自动:
    • 安装依赖(requirements.txt)
    • 拉取模型仓库文件(含权重)
    • 通过 ModelScope Pipeline 标准接口加载并提供 HTTP 服务
  • 最终实现:
    • SwingDeploy 一键部署(选择 ModelScope Pipeline 框架)
    • 部署目标可选:函数计算 FC / PAI-EAS / ENS

0.2 前置假设

  • 你已经有一个可用的 .pt checkpoint(训练脚本产物)。
  • 该 checkpoint 遵循本仓库保存格式(推荐),即包含 meta(见下文),这样推理侧可以自动还原:
    • 是否 text_cond
    • UNet 配置、扩散调度、通道数等

1. 关键思路:allow_remote 外部组件

本仓库的模型并不属于 ModelScope 主库内置模型类型,因此要走 外部组件注册方案:

  • 在 configuration.json 中启用:
    • "allow_remote": true
  • 在仓库根目录提供 ms_wrapper.py:
    • 用 MODELS.register_module(...) 注册自定义 Model
    • 用 PIPELINES.register_module(...) 注册自定义 Pipeline

ModelScope 在加载该模型时会根据 configuration.json 的 task / model.type / pipeline.type 找到并加载 ms_wrapper.py 里同名注册的组件,从而让 SwingDeploy 能“识别这是可部署的 Pipeline 模型”。


2. 仓库根目录最小文件结构(必需)

以下文件需位于 模型仓库根目录(不是子目录):

  • configuration.json
    • 声明 framework / task / model.type / pipeline.type / allow_remote
  • ms_wrapper.py
    • 实现并注册自定义 Model + Pipeline
  • requirements.txt
    • 推理运行依赖(必须包含 modelscope)
  • pytorch_model.bin(强烈建议)
    • 模型权重文件,建议统一命名,减少部署时的歧义
  • README.md
    • 模型卡片(建议包含 tasks 标签;可选配置在线 Demo widget)

本仓库已提供 configuration.json 与 ms_wrapper.py 的基础实现;你只需要按约定上传权重,并把这些文件推送到 ModelScope 仓库。


3. configuration.json 规范(与 ms_wrapper.py 强绑定)

本仓库当前配置采用:

  • task: "text-to-image-synthesis"
  • model.type: "blockdiffusion-text2img-model"
  • pipeline.type: "blockdiffusion-text2img-pipeline"
  • allow_remote: true

关键约束:

  • model.type 必须与 ms_wrapper.py 里 @MODELS.register_module(task, module_name=...) 的 module_name 一致。
  • pipeline.type 必须与 ms_wrapper.py 里 @PIPELINES.register_module(task, module_name=...) 的 module_name 一致。
  • task 必须在两处一致(否则 Registry 维度不匹配)。

如果你想换 task 名称:

  • 必须同时修改:
    • configuration.json 的 task
    • ms_wrapper.py 两个注册装饰器里的 task(当前写死为 "text-to-image-synthesis")

4. 权重文件命名与 checkpoint 格式(强烈建议)

4.1 权重命名

部署时建议把目标 checkpoint 重命名为:

  • pytorch_model.bin

并放在模型仓库根目录。

原因:

  • 这是 ModelScope/transformers 生态里常见约定;
  • 能避免仓库内存在多个 .pt 时选错权重;
  • 本仓库的 ms_wrapper.py 会优先寻找该文件。

4.2 checkpoint 字段(本仓库推荐格式)

推荐的 checkpoint 是一个 dict,至少包含:

  • model: state_dict
  • meta: dict(用于推理时重建配置)
  • 可选:ema(采样质量更稳,推理侧会优先使用)

meta 常见字段(训练脚本已按此保存):

  • model_type: "text_cond" 或(其他/缺省)无条件
  • unet_cfg: UNet16Config 的字典
  • text_cfg: TextCondConfig 的字典(仅 text_cond)
  • tokenizer: SimpleVocab.to_dict()(仅 text_cond)
  • diffusion: {"timesteps": ..., "beta_schedule": ...}
  • data: {"image_size": 16, "channels": 3/4}

如果 checkpoint 缺少 meta/unet_cfg:

  • 推理侧会回退到默认 16×16 RGB 的无条件配置
  • 这会导致“通道数/条件/调度”等信息丢失,部署能跑但结果可能不符合预期

5. ms_wrapper.py 的职责边界(为什么必须有它)

ms_wrapper.py 是“让 ModelScope 识别如何推理”的关键文件,它做了四件事:

  1. 加载 checkpoint
    • 在 model_dir 里寻找 pytorch_model.bin 等候选
  2. 重建网络
    • model_type == text_cond → TextCondUNet16
    • 否则 → UNet16
  3. 构建 diffusion
    • 根据 meta.diffusion 还原 timesteps/beta_schedule
  4. 提供 Pipeline 标准输出
    • 输出字典里包含:
      • OutputKeys.OUTPUT_IMG:单张图(HWC uint8 ndarray)
      • OutputKeys.OUTPUT_IMGS:多张图(List[HWC uint8 ndarray])

这样 SwingDeploy 才能把服务做成统一的 HTTP 形式并返回可序列化结果。


6. Pipeline 的输入输出协议(服务调用层面)

6.1 输入(prompt)

Pipeline 支持以下输入:

  • 直接传字符串(等价 prompt)
  • 传 dict,支持键:
    • {"text": "xxx"}
    • {"prompt": "xxx"}

6.2 参数(parameters)

当前支持的常用参数(都走 Pipeline 的 parameters):

  • n: 生成张数(默认 1)
  • batch: 单次采样 batch(默认 1)
  • use_ddim: 是否用 DDIM(默认 True)
  • ddim_steps: DDIM 步数(默认 50)
  • ddim_eta: DDIM eta(默认 0)
  • cfg_scale: CFG 强度(默认 3,仅 text_cond + prompt 时生效)
  • seed: 随机种子(可选)

建议:

  • FC 场景默认以“低延迟”为目标:
    • n=1
    • batch=1
    • ddim_steps 适当调小(例如 20~50)

6.3 输出

输出是标准 dict:

  • OutputKeys.OUTPUT_IMG:一张图片(HWC,uint8,RGB 或 RGBA)
  • OutputKeys.OUTPUT_IMGS:多张图片(List[HWC uint8])

注意:

  • RGBA 会输出 4 通道;
  • 下游服务需要支持带 alpha 的 image array 序列化(ModelScope 服务链路通常可处理)。

7. 将本地仓库正确推到 ModelScope(操作要点)

7.1 你必须确认的内容

  • 仓库根目录存在:
    • configuration.json
    • ms_wrapper.py
    • requirements.txt
    • pytorch_model.bin
    • README.md
  • requirements.txt 里包含 modelscope,并补齐 numpy 等必需依赖
  • configuration.json 的 task/model.type/pipeline.type 与 ms_wrapper.py 注册一致

7.2 README.md(模型卡片)建议

建议在 README 的 YAML header 中声明 tasks(用于平台识别任务类型),例如:

  • task 选择与 configuration.json.task 一致(本仓库是 text-to-image-synthesis)

并可选配置 widget,让网页侧出现“在线体验”。


8. SwingDeploy → FC 一键部署(平台侧操作要点)

8.1 选择部署方式

在模型页面点击“部署”:

  • 选择 快速部署(SwingDeploy)
  • 框架选择 ModelScope Pipeline
  • 目标资源选择 函数计算(FC)

8.2 资源与性能建议

  • 强烈建议 GPU:扩散采样是循环推理,CPU 延迟通常不可接受
  • 冷启动:
    • PyTorch 依赖体积大、初始化重
    • 建议使用平台提供的“预留/常驻”能力减少冷启动
  • 超时:
    • 降低 ddim_steps
    • 限制 n/batch

9. 常见故障与定位(按症状)

9.1 部署时导入失败(ImportError / ModuleNotFoundError)

优先检查:

  • requirements.txt 是否包含:
    • modelscope
    • numpy
    • torch/torchvision/pillow/tqdm
  • 是否存在额外依赖(例如某些 CUDA/系统库)在 FC 环境不可用

9.2 找不到权重文件

症状:

  • 报错提示未找到 pytorch_model.bin 等

处理:

  • 确保权重放在仓库根目录
  • 建议统一命名为 pytorch_model.bin

9.3 state_dict 不匹配(size mismatch / missing keys)

常见原因:

  • 使用了与权重不匹配的 UNet16Config(例如通道数 3/4 不一致)
  • 续训/导出时 tokenizer/vocab 改了导致 TextEncoder embedding 尺寸变化

处理:

  • 确保 checkpoint 内 meta 完整,推理侧会复用 meta.unet_cfg/tokenizer/text_cfg
  • 不要在续训时重建新词表(会破坏 embedding 尺寸)

9.4 prompt 无效 / CFG 无效

常见原因:

  • 部署的是无条件 checkpoint(meta.model_type != text_cond)

处理:

  • 用带 captions 训练出来的 text_cond checkpoint

9.5 FC 超时 / 资源不足

处理方向:

  • 降低 ddim_steps(优先)
  • 强制 n=1 batch=1
  • 选择更高规格 GPU 或改为 PAI-EAS

10. 对接下一个 AI 的“最短执行清单”

  1. 把最终 checkpoint 重命名为 pytorch_model.bin,放仓库根目录
  2. 确认根目录存在 configuration.json / ms_wrapper.py / requirements.txt
  3. 确认 configuration.json 的 task/model.type/pipeline.type 与 ms_wrapper.py 注册一致
  4. 推送到 ModelScope 模型仓库
  5. 在模型页面:SwingDeploy → ModelScope Pipeline → FC 一键部署
  6. 调用时传:
    • input.text(prompt)
    • parameters.ddim_steps / cfg_scale / n / batch / seed