企业官网建设流程全解析

• 人工智能
• 大模型
• 基础模型
• 模型量化
• 本地部署
• 媒体生成
• 音频
• 视频

ltx-2.5-mlx-q8是面向 Apple Silicon 的 LTX-2.5 音视频生成模型组件树，它与 bf16 版本唯一的区别：把 Gemma-4 12B 文本编码器 量化为int8，整棵组件树从 23.8 GB 瘦身到 13.6 GB。这篇文章带你深潜这个文本编码器：48 层混合注意力如何排布、connector 如何把 3840 维文本特征"翻译"成 4096 维的 DiT 条件、128 个可学习寄存器又扮演什么角色。

一、为什么要把文本编码器量化成 int8？

在 LTX-2.5 推理中，峰值显存并不由视频分辨率决定，而是被 bf16 文本编码器"兜底"——无论生成 256×256×9 的短片还是 512×288×121 的片段，峰值都在24.8 GB附近（详见 README.md）。这个数字直接压垮了 24 GB / 32 GB 内存的机器。

换上 int8 文本编码器后，全程峰值降到14.6 GB / 15.4 GB——24 GB 机型第一次能够完整跑通 LTX-2.5。这也是"q8"这个名字的由来。

💡 注意：本仓库不含量化版 DiT（transformer 主干）。编码器量化与 DiT 量化是两条独立的轴，可以任意组合：int8 编码器 + bf16 DiT、int8 编码器 + int8 DiT 都可以。

二、编码器本体：gemma4-12b-ltx-v1 是什么？

gemma4-12b-ltx-v1/ 目录存放的就是被量化的文本编码器，核心参数如下：

权重分布在三个 safetensors 分片（约 5.32 + 5.32 + 2.96 GB）：

• model-00001-of-00003.safetensors
• model-00002-of-00003.safetensors
• model-00003-of-00003.safetensors

它是一个gemma4_unified统一架构（Gemma4UnifiedForConditionalGeneration），文本、视觉、音频三种模态的配置都写在同一份 config.json 里——但在 LTX-2.5 的生成管线中，真正干活的只是它的文本分支：读入提示词，输出各层隐状态，交给 connector 加工后喂给 DiT。

三、48 层注意力排布：40 层滑窗 + 8 层全局

打开 gemma4-12b-ltx-v1/config.json 的layer_types字段，可以看到 48 个层的类型列表。统计一下规律非常清晰：

full_attention 出现在 0-based 第 5、11、17、23、29、35、41、47 层 其余 40 层全部是 sliding_attention

也就是说：每 6 层里，前 5 层用滑动窗口注意力（只看最近 1024 个 token），第 6 层用全局注意力（看到全部上下文），最后以全局层收尾。

这种"滑窗为主、全局点缀"的混合结构是长上下文大模型的典型省算设计：

• 🪟滑窗层：注意力复杂度近似线性，提示词越长越划算，短促的词汇/句法信息在局部就消化掉了；
• 🌐全局层：负责跨长距离的信息汇总，让"开头的一句话"能影响"结尾的画面"；
• 两层还用了不同的 RoPE 配置（见 config.json）：全局层rope_theta = 1,000,000且只旋转 25% 的维度（partial_rotary_factor: 0.25），滑窗层rope_theta = 10,000——窗口内根本不需要那么高的位置分辨率。

对普通用户来说结论很简单：同样的提示词，编码成本远低于"48 层全注意力"的朴素方案，而全局语义基本不打折。

四、int8 量化配方：group 64，但 embed_tokens 被刻意豁免

量化配置写在 config.json：

"quantization": { "group_size": 64, "bits": 8, "mode": "affine" }

即 8-bit 仿射（带 scale/bias 的仿射）分组量化，每 64 个权重一组共享一个 scale。从权重索引（model.safetensors.index.json）能看到，每个线性层都被拆成.weight+.scales+.biases三个张量，正是 group-64 affine 量化的指纹。

而整个配方里最关键的一个"反直觉"决策是：词嵌入表embed_tokens被刻意排除在量化之外，保留 bf16（README.md）。原因：

• 编码器的第 0 号隐状态就是embedTokens(ids) · embedScale——它既是 connector 直接消费的 49 个状态之一，也是全部 48 层的输入起点；
• 量化词嵌入会单独污染这一号状态，误差从源头放大到全链路；
• 验证方法也很讲究：bf16 版第 0 号状态与词嵌入的余弦恰好是1.000000，int8 版若出现这个精确值，就证明词嵌入没被动过。

五、connector：3840 维到 4096 维的"翻译官"

编码器输出的文本特征宽度是 3840（hidden_size），但 LTX-2.5 的音视频 DiT 交叉注意力要求条件向量是4096 维（主 config.json 的cross_attention_dim: 4096）。两者之间的桥梁就是 connector.safetensors（约 6.34 GB，bf16，不量化）。

它的结构参数来自 embedded_config.json：

数据流可以概括为：提示词 → Gemma-4 编码器 → 49 个隐状态（0 号词嵌入态 + 48 层输出）→ PER_TOKEN_RMS 归一化 → 线性投影 3840→4096 → 8 层 connector（含 128 个寄存器）→ 输出给 48 层 DiT 的交叉注意力。

connector 同时启用 gated attention（embedded_config.json 的connector_apply_gated_attention），与 DiT 主干的apply_gated_attention保持一致。

六、128 个可学习寄存器：占满序列的"沉默 token"

connector_num_learnable_registers: 128是最容易被忽略、却影响解读的字段。

寄存器（registers）是 128 个不参与提示词、随权重一起学习的额外 token，与提示词 token 一起进入 connector 的 8 层注意力。它们的作用类似视觉模型里的 register token：为注意力提供"泄洪区"，吸收那些不属于任何具体词的高频统计量，让真正的文本 token 携带更干净、更判别性的表示。

理解这一点后，再来看 README.md 里的保真度指标就不会困惑：

• 在短提示词场景下，connector 输出的 1024 个位置中大部分是寄存器位置；
• 寄存器在所有编码器版本（bf16 或 int8）中完全相同——它们不携带文本信息；
• 所以用"整条数组的余弦相似度"来评估量化质量会被寄存器稀释 3~30 倍：一个故意污染的编码器臂整数组得分 0.994316，真实 token 位置却只有 0.829329。

因此官方给出的指标是只看有效 token 位置的余弦：int8 编码器0.999820，对比 bf16 自身基线0.999879——几乎贴近理论下限，说明量化几乎无损。

另外两点值得新手记住（README.md）：

• ⚠️ int8 输出不是bf16 的逐位复刻：条件信号变了，采样轨迹就不同，最终视频是"另一条同样有效的路径"；
• ⚠️ 用 SSIM/PSNR 去逐像素对比两个分支的输出是"类别错误"，官方结论来自盲评 A/B 感知测试。

七、目录速览：每个文件是干什么的

八、新手上手要点

1. 先算内存再跑模型：int8 编码器的价值在 24 GB 级别内存上最明显（峰值 14.6 GB）；搭配 DiT 流式加载才能真正发挥，两者缺一不可；
2. 组件可混搭：本仓库只提供量化编码器，DiT 可以选 bf16 或 int8（后者是独立的ltx-2.5-mlx-ditq8仓库），互不绑定；
3. 别碰 embed_tokens 的量化：如果你自己实验量化，记住词嵌入表被保留 bf16 是刻意为之，第 0 号隐状态是全链路的起点；
4. 看指标要看对地方：评估文本编码器量化，只看有效 token 位置的余弦，整数组余弦会被 128 个寄存器稀释到失去意义；
5. 注意许可：模型基于 LTX-2 社区许可（LICENSE.md），年收入超过 1000 万美元的商用实体需要单独获得商业授权，并附快照版可接受使用政策 ltx-acceptable-use-policy-snapshot-2026-08-12.pdf。

总结

ltx-2.5-mlx-q8 用最克制的方式解决了最要命的问题：一棵与 bf16 版逐字节相同的组件树，只换一个 int8 的 Gemma-4 文本编码器，就让 24 GB 的 Mac 也能完整跑 LTX-2.5。而编码器内部的设计同样值得品味——48 层里 40 层滑窗 + 8 层全局注意力的混合排布、group-64 量化中刻意豁免的词嵌入表、8 层 connector 里 128 个默默工作的可学习寄存器，每一处细节都能在 gemma4-12b-ltx-v1/config.json 和 embedded_config.json 里找到实证。读懂这三个部件，你就读懂了"文本提示词如何变成 4096 维条件向量"的完整旅程。

• 人工智能
• 大模型
• 基础模型
• 模型量化
• 本地部署
• 媒体生成
• 音频
• 视频