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 无条件配置;但这会丢失“通道数/条件/调度”等信息,不建议用于长期维护。