wkea's picture
Deploy Space
c388140 verified
|
Raw History Blame Contribute Delete
6.77 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

BlockDiffusion 模型说明(Model README)

本文件只描述模型本身(网络结构、输入输出、条件机制、checkpoint 格式),不描述训练脚本的使用方式。

1. 模型定位

  • 任务:生成/还原 16×16 的《我的世界》纹理(支持 RGB 或 RGBA)。
  • 扩散建模:epsilon-predictor(预测噪声 (\epsilon)),网络输出通道数与输入一致。
  • 条件方式:可选的文本提示词条件(Text Conditioning),并支持 CFG(Classifier-Free Guidance)的“条件丢弃训练 + 采样引导”范式。

2. 模型组件与代码位置

  • UNet 主体:blockdiffusion/models/unet16.py
    • UNet16Config:UNet 配置(通道、层数、注意力分辨率等)
    • UNet16:16×16 专用 UNet(epsilon predictor)
  • 文本条件封装:blockdiffusion/models/text_unet16.py
    • TextCondConfig:文本侧配置(长度、embedding 维度等)
    • TextCondUNet16:TextEncoder + UNet16 的组合模型
  • 文本编码器:blockdiffusion/text/text_encoder.py
    • TextEncoder:masked mean pooling + MLP 投影到条件向量
  • Tokenizer / 词表:blockdiffusion/text/simple_tokenizer.py
    • tokenize():轻量分词(支持 CJK 单字切分)
    • SimpleVocab:极简词表(含 <pad>/<unk>),可序列化到 checkpoint
  • CFG 采样包装器:blockdiffusion/train/guidance.py
    • CFGuidanceModel:把任意支持 forward(x, t, **kwargs) 的模型包装成 CFG 采样模型

3. 前向接口(输入/输出约定)

3.1 UNet16

  • 函数签名(语义):eps = UNet16(x, t, cond=None)
  • 输入
    • x:形状 (B, C, 16, 16),取值范围约定为 [-1, 1]
    • t:形状 (B,),dtype 通常为 int64,表示扩散 timestep
    • cond(可选):形状 (B, cond_dim) 的条件向量;None 表示无条件
  • 输出
    • eps:形状 (B, C, 16, 16),预测噪声 (\epsilon)

3.2 TextCondUNet16

  • 函数签名(语义):eps = TextCondUNet16(x, t, tokens=None, mask=None)
  • 输入
    • x / t:同 UNet16
    • tokens(可选):形状 (B, L),dtype 通常为 int64
    • mask(可选):形状 (B, L),bool 或 0/1
      • mask=None 时会自动由 tokens != pad_id 推导
      • 当 tokens=None 或 mask 全 0 时,模型等价于无条件
  • 输出
    • eps:同 UNet16

4. 条件注入机制(Text Conditioning)

  • TextEncoder 把 tokens/mask 编码为 cond(形状 (B, time_emb_dim))。
  • cond 通过“加和”注入到 UNet 的 time embedding:
    • t_emb = time_embed(t)
    • t_emb = t_emb + cond_proj(cond)(无 cond 时不加)
  • 这是一种轻量、易训练、可随 checkpoint 保存的条件方案,不依赖外部大型文本模型。

5. CFG(Classifier-Free Guidance)说明

  • 训练侧:通过一定概率把条件 mask 置空(等价无条件),让模型同时学到 cond/uncond。
  • 采样侧:CFGuidanceModel 组合两次前向,按以下公式合成:

[ \epsilon = \epsilon_{\text{uncond}} + s \cdot (\epsilon_{\text{cond}} - \epsilon_{\text{uncond}}) ]

其中 (s) 为 cfg_scale。

6. 关键配置项(建议对照 checkpoint 的 meta)

6.1 UNet16Config

字段 含义 备注
in_channels 输入通道数 3=RGB,4=RGBA
out_channels 输出通道数 epsilon 预测,通常与输入一致
base_channels 基础通道宽度 模型容量主开关
channel_mults 各层通道倍率 默认 (1,2,2) 对应 16→8→4
num_res_blocks 每层 ResBlock 数 16×16 不建议太大
attn_resolutions 启用自注意力的分辨率 默认在 8/4 上更划算
dropout ResBlock dropout 0 表示关闭
time_emb_dim time embedding 维度 也作为条件注入维度基准
cond_dim 条件向量维度 通过 cond_proj 对齐到 time_emb_dim

6.2 TextCondConfig

字段 含义 备注
max_text_len 最大 token 长度 (L) 影响 tokens 形状与 TextEncoder pooling
emb_dim token embedding 维度 TextEncoder 内部使用
dropout TextEncoder dropout 0 表示关闭

TextEncoderConfig.out_dim 会被设置为 UNet16Config.time_emb_dim,从而保证条件向量可直接注入 UNet。

7. Tokenizer 与词表(SimpleVocab)

  • Tokenizer 特性
    • 统一转小写
    • 英文/数字按“词”切分(把 _/- 视作词内字符)
    • CJK(中日韩)字符按“单字”切分,适配无空格中文提示词
  • 词表约定
    • id=0:<pad>
    • id=1:<unk>
  • 重要限制(续训/推理一致性)
    • 续训或推理时必须复用 checkpoint 内保存的词表;否则 Embedding 尺寸会不匹配。
    • 新出现但不在旧词表中的词会被编码成 <unk>:可继续运行,但无法学习/表达新词语义。

8. Checkpoint(.pt)格式与推荐加载流程

8.1 文件内容(关键键)

训练保存的 checkpoint 是一个 dict,关键字段如下:

  • model:模型 state_dict
  • ema:EMA state_dict(若存在,采样建议使用)
  • step:保存时的全局 step
  • meta:重建模型所需的结构化信息(强烈依赖)
  • trainer_cfg / optimizer / scaler:与训练相关(推理通常不需要)

8.2 meta 约定(常用字段)

  • model_type:"text_cond" 或(缺省/其他)无条件
  • unet_cfg:UNet16Config 的字典形式(dataclasses.asdict)
  • text_cfg:TextCondConfig 的字典形式(仅 text_cond)
  • tokenizer:SimpleVocab.to_dict() 的结果(仅 text_cond)
  • diffusion:{"timesteps": ..., "beta_schedule": ...}(采样需一致)
  • data:{"image_size": 16, "channels": 3/4}(采样 shape 需一致)

8.3 推荐加载流程(文字版)

  • 步骤
    • 读取 .pt 到内存(torch.load)
    • 从 meta 判断 model_type
    • 由 meta["unet_cfg"] 重建 UNet16Config
    • 若为 text_cond:从 meta["tokenizer"] 重建 SimpleVocab,从 meta["text_cfg"] 重建 TextCondConfig
    • 实例化 UNet16 或 TextCondUNet16
    • load_state_dict(ckpt["model"], strict=True)
    • 如需更稳的采样:把 ckpt["ema"] 应用到模型参数

兼容性提示:若旧 checkpoint 不含 meta/unet_cfg,项目内的采样入口会回落到默认的 16×16 RGB 无条件配置;但这会丢失“通道数/条件/调度”等信息,不建议用于长期维护。