MLX-VLM 的 LongCat-Flash-Lite-Sparse 支持:LSA 稀疏注意力、n-gram 融合与预填充优化解析

原创2026-09-17 23:29:271,866 阅读
文章标签:人工智能大模型本地部署多模态模型推理服务模型量化微调计算机视觉模型评测

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))

需要注意两点前提:

  1. 若 Hugging Face 上的 config 缺少 model_type,需手动补为 "longcat_flash_sparse" 才能正确分发(见上文调度方式);
  2. 社区已提供 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)"与"正确融合"声明在代码层的落点。

登录后查看全文
mlx-vlm