## 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`