MLX-VLM 的 LongCat-Flash-Lite-Sparse 支持:LSA 稀疏注意力、n-gram 融合与预填充优化解析
MLX-VLM 的 LongCat-Flash-Lite-Sparse 支持:LSA 稀疏注意力、n-gram 融合与预填充优化解析
本篇技术指南以 mlx-vlm 仓库中 LongCat-Flash-Lite-Sparse 模型文档 为核心,完整讲解该模型在 Apple Silicon(MLX)上的落地实现:包括 LSA(LongCat Sparse Attention)稀疏注意力、零计算 MoE、n-gram 输入嵌入的融合修正,以及两项精确的预填充(prefill)优化。读者读完本文后,可以掌握该模型的调度配置方式、架构细节、调用方法,以及源码层面的实现原理与验证方法。
模型定位与调度方式
LongCat-Flash-Lite-Sparse(代码中的 LongcatCausalLM)是 LongCat-Flash 家族中采用 LSA 稀疏注意力 + n-gram 嵌入 的变体。MLX-VLM 通过 mlx_vlm.models.longcat_flash_sparse 模块为其提供原生支持,模块入口导出 Model 与 ModelConfig(见 模块 __init__.py)。
一个关键的调度细节是:该模型在 Hugging Face 上的 config 中省略了 model_type 字段,因此加载时必须显式补上:
{
"model_type": "longcat_flash_sparse"
}
MLX-VLM 的模型解析入口 get_model_and_args 会读取 model_type 并将其小写化,然后依次尝试从 mlx_vlm.models 与 mlx_vlm.speculative.drafters 两个包中按同名模块导入。设置 model_type: "longcat_flash_sparse" 后即会正确分发到本模块。
架构总览
根据 README 与 config.py 中的默认配置,模型整体由以下组件构成:
| 组件 | 说明 | 关键默认配置 |
|---|---|---|
| ScMoE 解码器 | 14 层,每层运行两个注意力子块(dual-block)加一个 MoE 捷径分支(shortcut branch) | num_layers=14 |
| MLA | 多头潜在注意力(Multi-head Latent Attention),q/kv-LoRA 压缩,吸收式 embed_q / unembed_out 投影 |
kv_lora_rank=512,q_lora_rank=1536 |
| LSA | DeepSeek 风格 lightning indexer 在 MLA 之上挑选 top-index_topk(2048)个 key |
attention_method="LSA" |
| 零计算 MoE | 256 个路由专家 + 128 个 identity 专家,top-12 路由 | n_routed_experts=256,moe_topk=12 |
N-gram(oe)输入嵌入 |
token 嵌入 = word + Σ projections,约占参数量的 46% |
oe_vocab_size_ratio、oe_neighbor_num=4、oe_split_num=4 |
此外默认配置还包括:hidden_size=3072、ffn_hidden_size=6144、expert_ffn_hidden_size=1024、vocab_size=131072、max_position_embeddings=983040、num_attention_heads=32、qk_rope_head_dim=64、qk_nope_head_dim=128、v_head_dim=128、routed_scaling_factor=6.0、rope_theta=1000000.0。
模型结构上,longcat_flash_sparse.py 中的 Model 仅封装一个 LanguageModel(language.py 中的 LanguageModel),内部由 LongcatFlashModel(嵌入层 + 14 层 LongcatFlashDecoderLayer + 末层 RMSNorm)与 lm_head 组成。
LSA:LongCat 稀疏注意力
LSA 是本模型最核心的机制。从 Indexer 实现 可以看到:
- 索引器结构:
wq_b将 q-LoRA 表示(q_lora_rank维)投影到index_n_heads × index_head_dim;wk对隐藏状态投影得到索引 key,并做 RMSNorm(index_k_norm_type="rms");weights_proj为每个索引头生成加权标量;索引查询/键共享 MLA 的 RoPE 配置(qk_rope_head_dim、rope_theta、rope_scaling)。 - 稀疏选择:计算
q @ k后经 ReLU 与头加权求和(或调用融合 Metal kernel,见下文优化章节),得到每查询位置对全部 key 的稀疏分数,最终用mx.argpartition(..., kth=-index_topk)取出分数最高的index_topk(2048)个 key 索引。 - 流式感知索引(streaming-aware indexing):
index_init_tokens(固定 sink token)与index_local_tokens(本地滑动窗口)对应的列会被强制设为+inf,保证这些位置永远入选 top-k——这与 DeepSeek 类长上下文稀疏注意力的思路一致。 - 密集回退:当缓存序列长度
seqlen <= index_topk时,索引器直接返回None,注意力完整回退到密集 MLA 计算,避免在短序列上做无谓的稀疏化。 - 跨层索引复用:每层包含两个注意力子块,但只有一个子块(
is_index_owner为真的第一个子块)持有Indexer实例;第二个子块复用第一个子块的topk_indices,对应配置项cli_factor(注意:当前LongcatFlashDecoderLayer固定两个子块共享一次索引器前向,即每层只跑一次索引器)。解码阶段(L == 1)通过take_along_axis直接按 top-k 索引 gather KV;预填充阶段则构造稀疏 bool mask 参与注意力。
从源码结构看,LSA 与 MLA 通过 attention_method 配置切换:设为 "LSA" 启用稀疏索引器,设为 "MLA" 则为纯密集双块注意力。测试 test_longcat_flash_sparse_language_model 同时验证了两种模式:LSA 模式下每层缓存含 3 个槽位(latent(0)、indexer(0)、latent(1)),而密集模式每层只有 2 个槽位,且两者都能保证缓存增量推理(cached forward)与整段前向输出一致。
零计算 MoE
LongcatFlashMoE 与路由器的实现在 language.py:
- 路由器(
LongcatFlashTopkRouter)先对hidden_size做线性分类,softmax 得到分数,经argpartition取 top-12,权重乘routed_scaling_factor;norm_topk_prob控制是否归一化。 - identity 专家:配置
zero_expert_type="identity"且zero_expert_num>0时,MoE 输出中会额外加上hidden_states * identity_weights_sum——即被路由到 identity 专家的 token,其门控权重直接作用于输入本身,不触发任何专家 GEMM 计算,因此称为"零计算"。 - 常规 256 个路由专家通过
SwitchGLU批量计算(switch_mlp在sanitize阶段把mlp.experts.*的权重堆叠成(num_experts, in, out)的单一张量,见sanitize中对gate_proj/up_proj/down_proj的mx.stack合并)。
每层的 LongcatFlashDecoderLayer 还实现了 README 中提到的 MoE 捷径分支:两个注意力子块各接一个普通 LongcatFlashMLP,而 MoE 只在第一个子块后计算一次,其输出在第二个子块的 MLP 之后叠加回残差流(hidden_states + shortcut_mlp_output)。
N-gram(oe)输入嵌入与融合修正
NgramEmbedding(language.py)是 Lite / Lite-Sparse 系列的关键:
-
哈希投影表:设
m = oe_vocab_size_ratio * vocab_size、k = oe_split_num、n = oe_neighbor_num,则共有num_embedders = k * (n-1)个子嵌入表,每张表的词表大小为m + i*2 + 1,维数为hidden_size // num_embedders。n-gram id 通过对历史 token 的幂次取模哈希(_vocab_mods)生成,代码中维护了长度为n-1的上下文窗口(ArraysCache)。 -
融合(fusion):
NgramEmbedding.__call__的最后一行为proj = self.post_proj(mx.concatenate(lookups, axis=-1)) return x + proj / (1 + self.num_embedders)这正是 README 强调的唯一差异点:Lite-Sparse 构建把 word embedding 保持在满尺度(
word + Σ projections / (1 + num_embedders)),而密集版longcat_flash_ngram采用(word + Σ projections) / (1 + num_embedders),即连 word 项一起除。README 明确指出,将 word 项除以1 + num_embedders会破坏生成质量("garbles generation"),因此本实现采用了正确(满尺度 word)的融合方式。 -
post_proj把拼接后的 n-gram 查找结果一次投影回hidden_size,这也与预填充优化中的"n-gram 投影融合"直接对应(见下)。
当 oe_vocab_size_ratio > 0 时启用 n-gram 嵌入,否则退化为普通 embed_tokens(LongcatFlashModel 中的 use_ngram 判断)。权重 sanitize 会把 model.embed_tokens.weight、model.oe_embed_tokens.*、model.oe_embed_proj.* 分别重映射为 ngram_embeddings.word_embeddings、embedders.* 与融合后的 post_proj.weight,并剔除 model.mtp.* 权重。
使用方式
按照 README 的 Usage 章节,推理入口与 MLX-VLM 其他模型一致:
from mlx_vlm import generate, load
model, processor = load(
"mlx-community/LongCat-Flash-Lite-Sparse-4bit", trust_remote_code=True
)
print(generate(model, processor, "Explain multi-head latent attention.", max_tokens=256))
需要注意两点前提:
- 若 Hugging Face 上的 config 缺少
model_type,需手动补为"longcat_flash_sparse"才能正确分发(见上文调度方式); - 社区已提供 4-bit、6-bit、8-bit 三档 MLX 量化 checkpoint(
mlx-community/LongCat-Flash-Lite-Sparse-4bit/-6bit/-8bit),示例使用 4-bit 版本。
在量化与缓存方面,源码还提供了以下细节:
LanguageModel.quant_predicate对 MoE 路由器classifier指定{"group_size": 64, "bits": 8},其余模块按默认量化策略处理;cast_predicate则排除e_score_correction_bias(测试 test_longcat_flash_sparse_language_model 中对此有断言)。make_cache按注意力模式返回不同缓存结构:LSA 下每层为CacheList(KVCache(), KVCache(), KVCache())(潜在 KV、索引器 KV、第二子块潜在 KV),n-gram 模式在最前面追加一个ArraysCache用于保存 n-gram 上下文;密集 MLA 模式每层仅两个KVCache。- 解码时
mx.depends将潜在缓存与索引器缓存建立依赖,保证take_along_axis的 gather 操作与索引器更新顺序正确。
预填充优化
README 的 Prefill optimizations 章节列出两项位于计算路径上、不改变权重、且相对参考实现精确到 ≤1e-6 的优化:
| 优化 | 效果 |
|---|---|
| n-gram 投影融合 | 12 个 per-embedder 投影合并为对拼接后查找结果的一次 GEMM(12 次 kernel launch → 1 次),投影部分约 1.5× 加速 |
| indexer epilogue kernel | 用 deepseek_v4 的融合 Metal kernel 替代 ReLU + 加权头求和 epilogue(原实现会物化 [B, 16, s, S] 张量),epilogue 部分约 1.6× 加速 |
两者的源码佐证:
- n-gram 投影融合:
NgramEmbedding中不再为每个 embedder 单独准备投影层,而是将所有 lookup 沿最后一维mx.concatenate后经单一post_proj = nn.Linear(num_embedders * emb_dim, hidden_size, bias=False)完成投影;对应地,sanitize在加载权重时用mx.concatenate(..., axis=1)把各oe_embed_proj权重融合为一张 GEMM 权重。 - indexer epilogue kernel:indexer_kernel.py 定义了基于
mx.fast.metal_kernel的indexer_epilogue_h{n_heads}kernel(模板参数NHEADS、threadgroup 256),在 GPU 上直接完成acc += max(g, 0.0) * wc[h]的 ReLU-加权求和,避免物化[B, 16, s, S]中间张量。入口函数indexer_dense_scores仅在mx.default_device() == mx.gpu且 Metal 可用时启用(indexer_dense_scores_available),否则Indexer.__call__回退到纯 MLX 的mx.maximum(q @ k^T, 0)+ 加权求和路径,保证非 GPU 环境同样正确。
测试与验证
仓库为 longcat_flash_sparse 提供了直接测试证据:
- test_models.py 中的 TestLongcatFlashModel(针对同家族的
longcat_flash)验证了原生加载、双缓存(dual cache)、权重sanitize(专家堆叠、kv_b_proj拆分为embed_q/unembed_out、剔除 MTP)以及量化/类型谓词; - test_longcat_flash_sparse_language_model 直接构造 LSA 配置(
index_topk=8、index_init_tokens=2、index_local_tokens=4、cli_factor=2),验证了:LSA 层每层 3 个缓存槽、密集模式 2 个缓存槽、全量前向与缓存增量前向的 logits 形状与有限性,以及sanitize对专家权重与kv_b_proj的合并拆分行为; - test_absorbed_mla.py 将
longcat_flash_sparse纳入 MLA 吸收式注意力(absorbed attention)的覆盖范围,验证q_lora_rank路径下embed_q/unembed_out吸收式实现与参考实现的等价性。
这些测试共同保证了模型加载、稀疏索引、缓存结构与数值正确性,是 README 中"精确(≤1e-6)"与"正确融合"声明在代码层的落点。