Spaces:
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
A newer version of the Gradio SDK is available: 6.32.0
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 前置假设
- 你已经有一个可用的
.ptcheckpoint(训练脚本产物)。 - 该 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的taskms_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_dictmeta: 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 识别如何推理”的关键文件,它做了四件事:
- 加载 checkpoint
- 在
model_dir里寻找pytorch_model.bin等候选
- 在
- 重建网络
model_type == text_cond→TextCondUNet16- 否则 →
UNet16
- 构建 diffusion
- 根据
meta.diffusion还原timesteps/beta_schedule
- 根据
- 提供 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=1batch=1ddim_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.jsonms_wrapper.pyrequirements.txtpytorch_model.binREADME.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是否包含:modelscopenumpytorch/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 的“最短执行清单”
- 把最终 checkpoint 重命名为
pytorch_model.bin,放仓库根目录 - 确认根目录存在
configuration.json / ms_wrapper.py / requirements.txt - 确认
configuration.json的task/model.type/pipeline.type与ms_wrapper.py注册一致 - 推送到 ModelScope 模型仓库
- 在模型页面:SwingDeploy → ModelScope Pipeline → FC 一键部署
- 调用时传:
input.text(prompt)parameters.ddim_steps / cfg_scale / n / batch / seed