MLX-VLM 的 LongCat-Flash-Lite-Sparse 支持LSA 稀疏注意力、n-gram 融合与预填充优化解析【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm本篇技术指南以 mlx-vlm 仓库中 LongCat-Flash-Lite-Sparse 模型文档 为核心完整讲解该模型在 Apple SiliconMLX上的落地实现包括 LSALongCat 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 branchnum_layers14MLA多头潜在注意力Multi-head Latent Attentionq/kv-LoRA 压缩吸收式embed_q/unembed_out投影kv_lora_rank512q_lora_rank1536LSADeepSeek 风格 lightning indexer 在 MLA 之上挑选 top-index_topk2048个 keyattention_methodLSA零计算 MoE256 个路由专家 128 个 identity 专家top-12 路由n_routed_experts256moe_topk12N-gramoe输入嵌入token 嵌入 word Σ projections约占参数量的 46%oe_vocab_size_ratio、oe_neighbor_num4、oe_split_num4此外默认配置还包括hidden_size3072、ffn_hidden_size6144、expert_ffn_hidden_size1024、vocab_size131072、max_position_embeddings983040、num_attention_heads32、qk_rope_head_dim64、qk_nope_head_dim128、v_head_dim128、routed_scaling_factor6.0、rope_theta1000000.0。模型结构上longcat_flash_sparse.py 中的Model仅封装一个LanguageModellanguage.py 中的LanguageModel内部由LongcatFlashModel嵌入层 14 层LongcatFlashDecoderLayer 末层 RMSNorm与lm_head组成。LSALongCat 稀疏注意力LSA 是本模型最核心的机制。从 Indexer 实现 可以看到索引器结构wq_b将 q-LoRA 表示q_lora_rank维投影到index_n_heads × index_head_dimwk对隐藏状态投影得到索引 key并做 RMSNormindex_k_norm_typermsweights_proj为每个索引头生成加权标量索引查询/键共享 MLA 的 RoPE 配置qk_rope_head_dim、rope_theta、rope_scaling。稀疏选择计算q k后经 ReLU 与头加权求和或调用融合 Metal kernel见下文优化章节得到每查询位置对全部 key 的稀疏分数最终用mx.argpartition(..., kth-index_topk)取出分数最高的index_topk2048个 key 索引。流式感知索引streaming-aware indexingindex_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与整段前向输出一致。零计算 MoELongcatFlashMoE与路由器的实现在 language.py路由器LongcatFlashTopkRouter先对hidden_size做线性分类softmax 得到分数经argpartition取 top-12权重乘routed_scaling_factornorm_topk_prob控制是否归一化。identity 专家配置zero_expert_typeidentity且zero_expert_num0时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-gramoe输入嵌入与融合修正NgramEmbeddinglanguage.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。融合fusionNgramEmbedding.__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_tokensLongcatFlashModel中的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_codeTrue ) print(generate(model, processor, Explain multi-head latent attention., max_tokens256))需要注意两点前提若 Hugging Face 上的 config 缺少model_type需手动补为longcat_flash_sparse才能正确分发见上文调度方式社区已提供 4-bit、6-bit、8-bit 三档 MLX 量化 checkpointmlx-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、第二子块潜在 KVn-gram 模式在最前面追加一个ArraysCache用于保存 n-gram 上下文密集 MLA 模式每层仅两个KVCache。解码时mx.depends将潜在缓存与索引器缓存建立依赖保证take_along_axis的 gather 操作与索引器更新顺序正确。预填充优化README 的 Prefill optimizations 章节列出两项位于计算路径上、不改变权重、且相对参考实现精确到 ≤1e-6的优化优化效果n-gram 投影融合12 个 per-embedder 投影合并为对拼接后查找结果的一次 GEMM12 次 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, biasFalse)完成投影对应地sanitize在加载权重时用mx.concatenate(..., axis1)把各oe_embed_proj权重融合为一张 GEMM 权重。indexer epilogue kernelindexer_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_topk8、index_init_tokens2、index_local_tokens4、cli_factor2验证了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-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MLX-VLM 的 LongCat-Flash-Lite-Sparse 支持：LSA 稀疏注意力、n-gram 融合与预填充优化解析
MLX-VLM 的 LongCat-Flash-Lite-Sparse 支持LSA 稀疏注意力、n-gram 融合与预填充优化解析【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm本篇技术指南以 mlx-vlm 仓库中 LongCat-Flash-Lite-Sparse 模型文档 为核心完整讲解该模型在 Apple SiliconMLX上的落地实现包括 LSALongCat 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 branchnum_layers14MLA多头潜在注意力Multi-head Latent Attentionq/kv-LoRA 压缩吸收式embed_q/unembed_out投影kv_lora_rank512q_lora_rank1536LSADeepSeek 风格 lightning indexer 在 MLA 之上挑选 top-index_topk2048个 keyattention_methodLSA零计算 MoE256 个路由专家 128 个 identity 专家top-12 路由n_routed_experts256moe_topk12N-gramoe输入嵌入token 嵌入 word Σ projections约占参数量的 46%oe_vocab_size_ratio、oe_neighbor_num4、oe_split_num4此外默认配置还包括hidden_size3072、ffn_hidden_size6144、expert_ffn_hidden_size1024、vocab_size131072、max_position_embeddings983040、num_attention_heads32、qk_rope_head_dim64、qk_nope_head_dim128、v_head_dim128、routed_scaling_factor6.0、rope_theta1000000.0。模型结构上longcat_flash_sparse.py 中的Model仅封装一个LanguageModellanguage.py 中的LanguageModel内部由LongcatFlashModel嵌入层 14 层LongcatFlashDecoderLayer 末层 RMSNorm与lm_head组成。LSALongCat 稀疏注意力LSA 是本模型最核心的机制。从 Indexer 实现 可以看到索引器结构wq_b将 q-LoRA 表示q_lora_rank维投影到index_n_heads × index_head_dimwk对隐藏状态投影得到索引 key并做 RMSNormindex_k_norm_typermsweights_proj为每个索引头生成加权标量索引查询/键共享 MLA 的 RoPE 配置qk_rope_head_dim、rope_theta、rope_scaling。稀疏选择计算q k后经 ReLU 与头加权求和或调用融合 Metal kernel见下文优化章节得到每查询位置对全部 key 的稀疏分数最终用mx.argpartition(..., kth-index_topk)取出分数最高的index_topk2048个 key 索引。流式感知索引streaming-aware indexingindex_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与整段前向输出一致。零计算 MoELongcatFlashMoE与路由器的实现在 language.py路由器LongcatFlashTopkRouter先对hidden_size做线性分类softmax 得到分数经argpartition取 top-12权重乘routed_scaling_factornorm_topk_prob控制是否归一化。identity 专家配置zero_expert_typeidentity且zero_expert_num0时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-gramoe输入嵌入与融合修正NgramEmbeddinglanguage.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。融合fusionNgramEmbedding.__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_tokensLongcatFlashModel中的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_codeTrue ) print(generate(model, processor, Explain multi-head latent attention., max_tokens256))需要注意两点前提若 Hugging Face 上的 config 缺少model_type需手动补为longcat_flash_sparse才能正确分发见上文调度方式社区已提供 4-bit、6-bit、8-bit 三档 MLX 量化 checkpointmlx-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、第二子块潜在 KVn-gram 模式在最前面追加一个ArraysCache用于保存 n-gram 上下文密集 MLA 模式每层仅两个KVCache。解码时mx.depends将潜在缓存与索引器缓存建立依赖保证take_along_axis的 gather 操作与索引器更新顺序正确。预填充优化README 的 Prefill optimizations 章节列出两项位于计算路径上、不改变权重、且相对参考实现精确到 ≤1e-6的优化优化效果n-gram 投影融合12 个 per-embedder 投影合并为对拼接后查找结果的一次 GEMM12 次 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, biasFalse)完成投影对应地sanitize在加载权重时用mx.concatenate(..., axis1)把各oe_embed_proj权重融合为一张 GEMM 权重。indexer epilogue kernelindexer_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_topk8、index_init_tokens2、index_local_tokens4、cli_factor2验证了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-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考