Spaces:
Sleeping
Sleeping
File size: 9,699 Bytes
c388140 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 | ## 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`
|