深入 ltx-2.5-mlx-q8 量化配方:int8 group 64 完整拆解,embed_tokens 为何必须保持 bf16

原创2026-10-17 13:45:551,446 阅读
文章标签:人工智能大模型基础模型模型量化本地部署媒体生成音频视频

深入 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。

ltx-2.5-mlx-q8 量化后内存对比:bf16 文本编码器 ~24.8 GB 峰值 vs int8 编码器 14.6 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 的配方值得新手记住三点:

  1. 量化要选准对象——328 个线性投影全部 int8 group 64,省出 6.5 GB;
  2. 量化要会「留一手」——embed_tokens 作为第 0 环状态和全部 48 层的输入,保持 bf16 是整条链路的地基,state 00 == 1.000000 就是它的保真指纹;
  3. 验证要看对位置——只在 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 文生视频的关键。

登录后查看全文
ltx-2.5-mlx-q8