Spaces:
Sleeping
Sleeping
|
Download MODEL_SCOPE_DEPLOY.md from wkea/blockdiffusion-api: direct link, hf CLI and curl.
- Browser
- Download file 9.7 kB
-
https://huggingface.co/spaces/wkea/blockdiffusion-api/resolve/main/MODEL_SCOPE_DEPLOY.md
- Command line
-
hf download hf://spaces/wkea/blockdiffusion-api/MODEL_SCOPE_DEPLOY.md
-
curl -L -o MODEL_SCOPE_DEPLOY.md https://huggingface.co/spaces/wkea/blockdiffusion-api/resolve/main/MODEL_SCOPE_DEPLOY.md
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` | |