## 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`:极简词表(含 `/`),可序列化到 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`:`` - `id=1`:`` - **重要限制(续训/推理一致性)** - 续训或推理时必须复用 checkpoint 内保存的词表;否则 `Embedding` 尺寸会不匹配。 - 新出现但不在旧词表中的词会被编码成 ``:可继续运行,但无法学习/表达新词语义。 ### 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 无条件配置;但这会丢失“通道数/条件/调度”等信息,不建议用于长期维护。