wkea's picture
Deploy Space
c388140 verified
|
Raw History Blame Contribute Delete
6.77 kB
## 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 无条件配置;但这会丢失“通道数/条件/调度”等信息,不建议用于长期维护。