Blame for README.md

---
license: other
library_name: flip
tags:
  - 3d
  - gaussian-splatting
  - triposplat
  - distillation
  - int4
  - webgpu
base_model:
  - VAST-AI/TripoSplat
---

# flip student · 2 steps · int4

TripoSplat 的扩散模型（DiT）的一个 2 步学生，量化到 int4。

上游用 20 步 Euler + CFG 3 生成 3D 高斯；这个学生用 **2 步、无 CFG** 做同一件事，
T4 上出图从 91–95 秒降到 4.6–5.0 秒（19×），权重从 1.48 GB 压到 209 MB。

**这不是一条完整管线。** 图像编码（DINOv3 + Flux2 VAE）、抠图（BiRefNet）、
解码（octree + Gaussian decoder）都是上游的，不在这里。这个仓库只替换
`ckpts/diffusion_models/triposplat_fp16.safetensors` 这一个文件。

## 文件

| 文件 | 内容 |
|---|---|
| `model.safetensors` | 763 个张量：204 个 int4（U8 成对）+ 204 个 fp16 scale + 355 个 fp16（norm/bias/embedding） |
| `dit.int4.onnx` | 同一个模型，整图 ONNX：203 个 `com.microsoft::MatMulNBits` + 剩下的 fp32 |
| `quantize.json` | 量化语义：4 bit、每 32 权重一个 fp16 scale、对称、zero point 8、沿 K 打包 |
| `config.json` | 结构参数与采样参数 |

## `dit.int4.onnx`

静态形状，输入是编码器的原始输出：

```
latent   [1, 8192, 16]     噪声 / 当前状态
camera   [1, 1, 5]
feature1 [1, 4101, 1280]   DINOv3
feature2 [1, 4096, 128]    Flux2 VAE（图内部补 5 个零 token，对齐 4101）
t        [1]
-> out_latent [1, 8192, 16], out_camera [1, 1, 5]
```

6265 个节点，294 MB。259 个 MatMul 里 203 个变成了 int4；**剩下的 56 个就是 28 层注意力的
QKᵀ 和 PV**——它们没有权重，量化不到，也不该量化。

**这张图不是最快的路径，是最互通的路径。** 在 ORT-web 1.31.1 / apple metal-3 上实测
（`webgpu/onnx-probe.html`）：

| 图 | ORT WebGPU | 我们的 WGSL |
|---|---|---|
| int4 MatMulNBits 1024→3072 @12294 | 789 GFLOP/s | 1591–1796 |
| 注意力，1 头 L=12294（物化） | 406 | 1789 |
| `com.microsoft::Attention` 16 头 | 1023 | 1789 |
| 卷积 3×3 128→128 @128² | 711 | 443 |

也就是说：矩阵乘交给 ORT 是 2.3 倍代价，注意力是 4.4 倍。**想跑进 60 秒，注意力得用
我们自己的核**，靠 `preferredOutputLocation: 'gpu-buffer'` 和 ORT 交接；其余走 ONNX。
卷积反而是 ORT 更快，所以 VAE 就该用 ONNX。

这张图在 CPU 上没有端到端跑过（一次前向 5 分钟，内核撑不住）。int4 的正确性证据是
矩阵乘级别的：fp32 对比 int4，cosine 0.997、rel_l2 0.073。

## 怎么接进上游

```python
from safetensors.torch import load_file
from triposplat import TripoSplatPipeline         # VAST-AI/TripoSplat

# 1. 反量化：U8 成对 + fp16 scale -> 权重
#    even k 在低四位，odd k 在高四位
w = (packed_to_int8(u8) - 8).float() * scale.repeat_interleave(32, dim=1)

# 2. 装进上游模块，存成 fp16 safetensors
# 3. 采样时：steps=2, shift=1.0, guidance=1.0（无 CFG）
```

`steps=50, shift=3, guidance=7` 是教师的参数，套在学生上会得到一个糊掉的模型。

## 数值（都是实测的）

量化质量，在真实采样状态上比 fp32 与「读回 int4 再反量化」的前向：

| 项 | 值 |
|---|---|
| latent cosine | 0.992 |
| latent rel-l2 | 0.123 |
| camera cosine | 0.999 |
| 密度 | 4.50 bits/weight |
| 体积 | 209,328,746 字节 |

蒸馏效果，同一 seed 与教师 20 步比（3 张 fuliji 图）：

| 项 | 学生 2 步 | 教师 20 步 |
|---|---|---|
| 出图耗时（T4） | 4.6–5.0 s | 91–95 s |
| opacity 均值 | 0.48–0.50 | 0.88–0.94 |
| latent cosine vs 教师 | 0.49 / 0.67 / 0.68 | — |
| camera cosine vs 教师 | 0.98 | — |

**诚实的短处**：opacity 掉到教师的一半，scale 偏大（0.0057 对 0.0030）。
肉眼上花纹和形体保住了，边缘略虚。latent 余弦只有 0.49–0.68，但它不是质量指标——
教师自己在 4 步时的 latent 距离更远（0.46–0.61），出图反而更糊。

## 怎么训的

- 教师：TripoSplat 官方权重，20 步 Euler，guidance 3
- 数据：`DownFlow/fuliji` 的 32 张图 + 上游示例图
- 目标：段平均速度 `v* = (x_{k+n} − x_k) / Σdt`。学生 2 步的网格是 `[0, 15, 20]`
  （按 σ 等分，每段 Δσ = 0.5），不是按步数均分的 `[0, 10, 20]`
- 训练：16 epoch，Adam，最终 loss 0.0787（camera 0.0213 / latent 0.0776）

2 步学生的上限由教师 20 步的终点决定，与教师 2 步无关——后者带 CFG，不是一个可比的对象。

## 许可

权重由 TripoSplat 蒸馏而来，上游条款见 [VAST-AI/TripoSplat](https://huggingface.co/VAST-AI/TripoSplat)。
此权重仅供研究，不商用。代码在 GPL-3.0 下发布。

## 引用

```bibtex
@software{flip_student_2step,
  title  = {flip: a distilled, int4 TripoSplat for WebGPU},
  year   = {2026},
  note   = {2-step student of the TripoSplat diffusion model}
}
```