Spaces:
Sleeping
Sleeping
File size: 6,771 Bytes
c388140 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | ## 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 无条件配置;但这会丢失“通道数/条件/调度”等信息,不建议用于长期维护。
|