深入 ltx-2.5-mlx-q8 量化配方:int8 group 64 完整拆解,embed_tokens 为何必须保持 bf16
深入 ltx-2.5-mlx-q8 量化配方:int8 group 64 完整拆解,embed_tokens 为何必须保持 bf16
如果你想在 24 GB 甚至 16 GB 内存的 Apple Silicon 上跑 LTX-2.5 文生视频,ltx-2.5-mlx-q8 是目前最实用的一站。它的量化配方只有两句话:int8、group 64,并且刻意把 embed_tokens 排除在量化之外、保持 bf16。这一组合把 Gemma-4 文本编码器从 23.8 GB 压到 13.6 GB,直接把整机峰值内存从「24/32 GB 都超预算」拉回 14.6 GB 左右。本文用仓库里的真实文件,把这个配方逐项拆开。
| 项目 | 说明 |
|---|---|
| 基座 | Lightricks/LTX-2.5(与 bf16 原版唯一差异是文本编码器) |
| 量化对象 | gemma4-12b-ltx-v1 文本编码器(119 亿参数) |
| 量化方案 | int8、group_size 64、affine 模式 |
| 关键例外 | embed_tokens 保持 bf16 |
| 体积 | 13.6 GB(bf16 版 23.8 GB) |
| 许可证 | LTX-2 Community License,见 LICENSE.md |
一、为什么量化对「小内存机器」是刚需,而不是锦上添花
先看一个反直觉的测量结论:在 DiT 使用流式(streaming)加载的情况下,LTX-2.5 的峰值内存由一个与视频几何尺寸基本无关的 ~24.8 GB 下限决定——实测 256×256×9 和 512×288×121 两段视频,峰值内存相差不到 0.01 GB。
上图示意:bf16 编码器构成一条与分辨率无关的内存「地板线」,int8 编码器把地板从 24.8 GB 降到约 14.6 GB。
这条地板线就是 bf16 文本编码器本身:如果是「解码瓶颈」,峰值会随几何尺寸增长,而它不增长。于是:
- 24 GB 机器:超预算 ❌
- 32 GB 机器:也超预算 ❌
- 换上 int8 编码器后:峰值 14.6 GB / 15.4 GB ✅
更关键的是 README.md 里的一句话:两个杠杆缺一不可。常驻内存受 DiT 约束,编码器量化在不开流式加载时完全「看不见」;而只开流式、不换编码器,地板线依然超预算。
二、配方拆解:int8 + group 64 到底做了什么
2.1 量化参数写在哪个文件里
打开 gemma4-12b-ltx-v1/config.json,配方一目了然:
"quantization_config": {
"group_size": 64,
"bits": 8,
"mode": "affine"
}
三个参数分别意味着:
| 参数 | 值 | 含义 |
|---|---|---|
bits |
8 | 权重值用 int8(1 字节)存储 |
group_size |
64 | 每 64 个权重为一组,共享一组缩放参数 |
mode |
affine | 每组同时带**缩放(scale)和偏置(bias)**两个参数 |
2.2 量化张量长什么样
在 MLX 的 affine 量化里,一个线性层的权重会被存成三元组。以 48 层中的第 0 层的 q_proj 为例,gemma4-12b-ltx-v1/model.safetensors.index.json 里能找到这三个键:
language_model.model.layers.0.self_attn.q_proj.weight # int8 权重
language_model.model.layers.0.self_attn.q_proj.scales # 每 64 个元素一个 scale
language_model.model.layers.0.self_attn.q_proj.biases # 每 64 个元素一个 bias
反量化时执行 w = q * scale + bias(逐组)。group 64 的意义:权重分布在整张矩阵上差异很大,组越小、每组能拟合的局部范围越准,精度损失越低;代价是 scale/bias 的元数据变多。64 是 MLX 生态里 int8 的常用折中值。
2.3 哪些层被量化、哪些没有
逐条核对权重索引,全模型共 1655 个张量,规律非常干净:
| 类别 | 数量 | 存储格式 |
|---|---|---|
| 量化线性投影(每层 q/k/v/o + gate/up/down 共 7 个 × 48 层) | 48 × 7 = 328 个 .weight,各配一套 .scales + .biases |
int8 值 + bf16 缩放元数据 |
各层 RMSNorm 权重 + 全局 model.norm |
48 × 13 + 1 | bf16 原样 |
layer_scalar(逐层标量) |
48 | bf16 原样 |
language_model.model.embed_tokens.weight |
1 | bf16 原样 ⭐ |
其中 embed_tokens 是词表 262144 × 隐层 3840 的查表矩阵,bf16 下独占 2.01 GB——它是全模型里最大的单个非量化块,也是本文的戏眼。
2.4 13.6 GB 是怎么来的(算给你看)
索引文件 model.safetensors.index.json 的 metadata 写着 total_size: 13595999840(≈13.6 GB)、total_parameters: 11907350272。拆开验证:
| 组成 | 字节数 |
|---|---|
| int8 权重值(11,554,789,504 个值) | ≈ 11.55 GB |
词嵌入 embed_tokens(bf16,262144 × 3840) |
≈ 2.01 GB |
| scales + biases 元数据(各 90,048 个组 × bf16 × 2 字段 × 48 层) | ≈ 43.6 MB |
全部 Norm 权重 + 48 个 layer_scalar(bf16) |
≈ 1.2 MB |
| 合计 | ≈ 13.6 GB ✅ |
对照 bf16 原版 23.8 GB:328 个线性从 bf16(≈10.76 GB)换成 int8+元数据(≈4.30 GB),省下约 6.46 GB;再加上词嵌入等其余部分,整体从 23.8 GB → 13.6 GB,数字完全吻合。
三、为什么 embed_tokens 必须保持 bf16
这是整个配方里最值得细看的一个决策。README 给出的依据(README.md)可以翻译成三层理由:
1)它是整条链路的「第 0 环」。
在 LTX-2.5 里,文本编码器输出的隐藏状态一共 49 个(每层一个)。其中 state 00 的定义就是 embedTokens(ids) · embedScale——它有两个双重身份:
- 是 connector 直接消费的 49 个状态之一(connector 结构见 embedded_config.json:
connector_num_layers: 8、connector_num_learnable_registers: 128,它把编码器输出接成 DiT 的 cross-attention 条件); - 是全部 48 层 transformer 的输入——后面每一层的残差都叠在它上面。
量化它,意味着这个「地基」状态会单独发生偏移,且误差会一路传播进所有 48 层和 connector,没有机会被后续层「修正」。
2)它是一张纯查表,量化收益极低、风险极高。
embed_tokens 是一次索引取行操作:每个 token 只取自己对应的那一行向量。int8 group 64 的误差对「连续计算的矩阵乘」影响有限,但对「直接当作后续计算起点」的向量却是实打实的位移。花 2.01 GB 的 bf16 保住它,换来的是一条干净的地基。
3)state 00 == 1.000000 是它的指纹。
README 提到一个漂亮的验证方法:如果 embed_tokens 保持 bf16,那么量化版与 bf16 版对比时,state 00 的相似度应当精确等于 1.000000(因为该状态的计算路径上没有任何量化操作)。一旦它不是 1,说明配方被污染了。这是量化验证里「一处指纹、全局安心」的典型设计。
💡 顺带一提:配置里
tie_word_embeddings: true(config.json),且索引中没有独立的lm_head——权重索引中唯一的大块非量化张量就是embed_tokens,与配方描述一一对应。
四、保真度怎么验证:别看整数组余弦
量化文本编码器的验收,仓库给了三个层层递进的证据:
① 连接器输出相似度(决定性指标)。 在 valid token 位置上,int8 版读数为 0.999820,bf16 版的理论下限(floor)是 0.999879——几乎贴着地板。
② 为什么不能看「整数组余弦」。 短提示词下,1024 个位置里大部分是 learned registers(可学习寄存器),它们在所有编码器版本间都完全相同,会把整数组相似度「稀释」3~30 倍。README 里的实证:一个被刻意污染(deliberately-poisoned)的对照组,整数组余弦能拿 0.994316,但真实 token 位置上只有 0.829329。整数组好看 ≠ 真的没坏。
③ 盲测 A/B 感知评估。 必须接受一个事实:样本画面会移动。输出与 bf16 版不逐位相同(均值 −0.1421/σ 0.4253 vs −0.1274/0.4222)——因为换了编码器,条件变了,扩散轨迹必然不同,它是一条「不同但同样有效」的视频。因此团队在 704×512 与 512×288 两种几何下做了 4 对盲测 A/B(含面部特写提示词),结论是可接受;而拿 SSIM/PSNR 去对比两版画面属于「范畴错误」(category error)。
五、组合玩法与使用提示
- 编码器与 DiT 是两条独立的量化轴。 本仓库不含量化 DiT(见 README.md):DiT 的 int8 版本在
mlx-community/ltx-2.5-mlx-ditq8。int8 编码器可以随意搭配 bf16 或 int8 DiT。 - PrunaVAED 可选瘦身解码器。 仓库附带 vae_decoder_pruna.safetensors,解码速度约 2 倍、解码激活峰值显著更小;在 704×512×121 的解码瓶颈场景下,峰值从 21.1 GB 降到 14.5 GB。
- 配套配置文件:DiT 结构见 config.json(48 层、cross_attention_dim 4096),完整管线嵌入配置见 embedded_config.json。
- 许可证提醒:基于 Lightricks LTX-2.5 的衍生模型,沿用其条款(含 Attachment A 收入门槛与竞业限制),再分发须按 §3 传播条款。详见 LICENSE.md。
六、写在最后
ltx-2.5-mlx-q8 的配方值得新手记住三点:
- 量化要选准对象——328 个线性投影全部 int8 group 64,省出 6.5 GB;
- 量化要会「留一手」——
embed_tokens作为第 0 环状态和全部 48 层的输入,保持 bf16 是整条链路的地基,state 00 == 1.000000就是它的保真指纹; - 验证要看对位置——只在 valid token 上量相似度,整数组余弦会被 learned registers 稀释出假象。
23.8 GB → 13.6 GB,峰值内存 24.8 GB → 14.6 GB:这套「int8 group 64 + embed_tokens 保 bf16」的组合拳,正是小内存 Apple Silicon 跑起 LTX-2.5 文生视频的关键。