blockdiffusion-api / MODEL_SCOPE_DEPLOY.md
wkea's picture
Deploy Space
c388140 verified
|
Raw History Blame Contribute Delete
9.7 kB
## 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`