Spaces:
Sleeping
Sleeping
|
Download blockdiffusion/models/README.md from wkea/blockdiffusion-api: direct link, hf CLI and curl.
- Browser
- Download file 6.77 kB
-
https://huggingface.co/spaces/wkea/blockdiffusion-api/resolve/main/blockdiffusion/models/README.md
- Command line
-
hf download hf://spaces/wkea/blockdiffusion-api/blockdiffusion/models/README.md
-
curl -L -o README.md https://huggingface.co/spaces/wkea/blockdiffusion-api/resolve/main/blockdiffusion/models/README.md
6.77 kB
A newer version of the Gradio SDK is available: 6.32.0
BlockDiffusion 模型说明(Model README)
本文件只描述模型本身(网络结构、输入输出、条件机制、checkpoint 格式),不描述训练脚本的使用方式。
1. 模型定位
- 任务:生成/还原 16×16 的《我的世界》纹理(支持 RGB 或 RGBA)。
- 扩散建模:epsilon-predictor(预测噪声 (\epsilon)),网络输出通道数与输入一致。
- 条件方式:可选的文本提示词条件(Text Conditioning),并支持 CFG(Classifier-Free Guidance)的“条件丢弃训练 + 采样引导”范式。
2. 模型组件与代码位置
- UNet 主体:
blockdiffusion/models/unet16.pyUNet16Config:UNet 配置(通道、层数、注意力分辨率等)UNet16:16×16 专用 UNet(epsilon predictor)
- 文本条件封装:
blockdiffusion/models/text_unet16.pyTextCondConfig:文本侧配置(长度、embedding 维度等)TextCondUNet16:TextEncoder + UNet16 的组合模型
- 文本编码器:
blockdiffusion/text/text_encoder.pyTextEncoder:masked mean pooling + MLP 投影到条件向量
- Tokenizer / 词表:
blockdiffusion/text/simple_tokenizer.pytokenize():轻量分词(支持 CJK 单字切分)SimpleVocab:极简词表(含<pad>/<unk>),可序列化到 checkpoint
- CFG 采样包装器:
blockdiffusion/train/guidance.pyCFGuidanceModel:把任意支持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,表示扩散 timestepcond(可选):形状(B, cond_dim)的条件向量;None表示无条件
- 输出
eps:形状(B, C, 16, 16),预测噪声 (\epsilon)
3.2 TextCondUNet16
- 函数签名(语义):
eps = TextCondUNet16(x, t, tokens=None, mask=None) - 输入
x/t:同UNet16tokens(可选):形状(B, L),dtype 通常为int64mask(可选):形状(B, L),bool 或 0/1mask=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>:可继续运行,但无法学习/表达新词语义。
- 续训或推理时必须复用 checkpoint 内保存的词表;否则
8. Checkpoint(.pt)格式与推荐加载流程
8.1 文件内容(关键键)
训练保存的 checkpoint 是一个 dict,关键字段如下:
model:模型state_dictema:EMAstate_dict(若存在,采样建议使用)step:保存时的全局 stepmeta:重建模型所需的结构化信息(强烈依赖)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 无条件配置;但这会丢失“通道数/条件/调度”等信息,不建议用于长期维护。