Add README

README.md

@@ -0,0 +1,108 @@
+---
+license: gpl-3.0
+language:
+- zh
+- en
+pipeline_tag: image-to-image
+base_model: OpenMOSS/MOSS-Image-Base
+base_model_relation: adapter
+tags:
+- moss-image
+- rgba
+- transparent-background
+- vae
+- lora
+- mage
+library_name: peft
+inference: false
+---
+
+# CKMoss-Image-RGBA VAE — step 14000 continuation
+
+本仓库发布 **Mage RGBA VAE 的续训权重（step 14000）**，以及用 MOSS-Image-Base 实际生成的三张示例图。
+结构参考 [ChenkinLab/CKMoss-Image-RGBA](https://huggingface.co/ChenkinLab/CKMoss-Image-RGBA)。
+
+## 文件
+
+| 路径 | 说明 |
+| --- | --- |
+| `vae/moss_rgba_vae.safetensors` | 已合并 LoRA 的 RGBA VAE 权重（404.6 MB），可直接加载 |
+| `vae/mage_config.json` | 模型结构配置 |
+| `vae/weights.json` | 合并前后数值一致性报告 |
+| `checkpoint-00014000/lora/adapter_model.safetensors` | 未合并的 LoRA 适配器（43.7 MB，rank 32） |
+| `checkpoint-00014000/lora/adapter_config.json` | PEFT/LoRA 配置 |
+| `checkpoint-00014000/progress.json` | 训练进度（step 14000，next_batch 44000） |
+| `samples/generation/` | 三张 MOSS-Image-Base 生成图（透明版） |
+| `samples/generation/opaque/` | 同一批生成图的模型原生输出（不透明） |
+| `samples/reconstruction/` | 三张输入图的 VAE 重建结果 |
+| `samples/source/` | 原始输入图（保留原始 PNG 元数据） |
+| `samples/previews/` | 棋盘格预览 |
+
+## 训练指标
+
+从 step 3000 的官方 checkpoint 继续训练，累计到 **14310** 步；**最后一个完整保存的 checkpoint 是 step 14000**。
+
+| 指标（1131 条日志，3010→14310） | 前 100 条均值 | 后 100 条均值 | 变化 |
+| --- | ---: | ---: | ---: |
+| Total loss | 0.010546 | 0.008037 | −23.8% |
+| Alpha MAE | 0.011672 | 0.008140 | −30.3% |
+| AB-MSE | 0.001462 | 0.001092 | −25.3% |
+| LPIPS | 0.009080 | 0.006940 | −23.6% |
+| Latent RMS | 1.0184 | 1.0378 | +1.9% |
+
+固定 8 张验证图：
+
+| 指标 | step 3500 | step 14000 | 最佳 |
+| --- | ---: | ---: | --- |
+| Alpha MAE ↓ | 0.01498 | 0.01131 | 0.01107 @ 11500 |
+| PSNR ↑ | 29.99 dB | 31.12 dB | 31.12 dB @ 13500 |
+| 黑底 PSNR ↑ | 31.98 dB | 32.70 dB | — |
+| 白底 PSNR ↑ | 28.01 dB | 29.54 dB | — |
+
+训练配置：512px、bf16、micro-batch 8 × accumulation 4（global batch 32）、LoRA rank/alpha 32、单卡 DCU，平均约 **4.79 秒/步**。
+优化器与随机状态文件只用于精确续训，推理不需要。
+
+## 生成示例
+
+三张示例由 **OpenMOSS/MOSS-Image-Base**（base 版本，不使用 SFT、不加载 DiT LoRA）+ 本仓库 `vae/moss_rgba_vae.safetensors` 生成：
+30 steps、CFG 4.0、512×768、seed 47 / 312 / 721。完整 prompt 见 `samples/generation/manifest.json`。
+
+### 重要说明：原生 alpha 与后处理
+
+本次只训练了 **VAE**，没有训练第二阶段 **DiT LoRA**。因此：
+
+- VAE 对**真实 RGBA 输入**的重建可以正确恢复 Alpha（见 `samples/reconstruction/` 与验证指标）；
+- 但 MOSS-Image-Base 的 DiT 只生成 RGB 潜变量，不携带透明度信息，所以**生成图的模型原生 alpha 接近 1（不透明）**，见 `samples/generation/opaque/`；
+- `samples/generation/` 中的透明 PNG 是对模型输出做**白底连通域抠图 + 边缘羽化**得到的展示版本，不是模型原生 alpha。README 与 manifest 中已明确标注。
+
+如果需要对生成图原生输出透明通道，需要补训 DiT LoRA 阶段。
+
+## 重建示例
+
+`samples/reconstruction/` 用同一 step 14000 VAE 对三张输入图做编码-解码（512 长边、16 倍数尺寸）：
+
+| 输入 | 尺寸 | 前景 RGB MAE | Alpha 均值 |
+| --- | --- | ---: | ---: |
+| moss_00029.png | 352×512 | 0.0152 | 0.998 |
+| sample_639469.png | 288×512 | 0.0303 | 0.995 |
+| tavern_ruyueming.png | 336×512 | 0.0049 | 1.003 |
+
+## 使用
+
+```python
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+
+repo = "leafmoone/CKMoss-Image-RGBA-vae"
+weights = hf_hub_download(repo, "vae/moss_rgba_vae.safetensors")
+state = load_file(weights)
+```
+
+VAE 输入/输出均为 4 通道、归一化到 `[-1, 1]`，Alpha 在通道 3，`+1` 表示不透明。
+
+## 许可与致谢
+
+基于 [MOSS-Image](https://github.com/OpenMOSS/MOSS-Image)（Apache-2.0）、
+[Mage](https://github.com/microsoft/Mage)（MIT）与
+[CKMoss-Image-RGBA](https://github.com/Chenkin-x/CKMoss-Image-RGBA)（GPLv3）。
+本项目采用 GPLv3，见 `LICENSE` 与 `NOTICE`。