【免费下载链接】K2-Horizon-3.7B-4bit项目地址https://ai.gitcode.com/hf_mirrors/mlx-community/K2-Horizon-3.7B-4bit点击查看免费下载K2-Horizon-3.7B-4bit 是 IFM K2-Horizon 系列 3.7B 稠密模型在 Apple 芯片上的 4bit 量化 MLX 版本磁盘占用仅 4.1 GB。这篇文章带你做代码级解析核心文件 k2_horizon.py 中 GroupedRMSNorm 分组归一化、GQA 分组查询注意力、MoVAMixture-of-Values值专家路由三大组件的实现原理以及用 mlx-lm 快速加载这个模型的方法。一、仓库速览K2-Horizon-3.7B-4bit 参数与量化方案这个仓库是 IFM/K2-Horizon-3.7B 的混合精度 4bit MLX 量化版由 bf16 版转换而来等效 6.5 bits/weight权重文件 model.safetensors 共 4.1 GB短 prompt 峰值内存4.3 GB16 GB 的 Mac 即可运行实测Mac Studio M4 Max 128GB生成速度109.6 tok/s支持512K上下文。config.json 关键参数一览配置项值含义hidden_size2560隐藏层维度num_hidden_layers36解码层数num_attention_heads/num_key_value_heads32 / 8GQA每个 KV 头服务 4 个 Query 头head_dim128每头维度intermediate_size10240MLP 中间维度max_position_embeddings524288512K 上下文layernorm_num_groups2GroupedRMSNorm 分组数vocab_size250624词表大小num_experts/mova_num_experts0 / 0本 checkpoint 为稠密MoE 与 MoVA 关闭rope_theta在rope_parameters内10000000.0RoPE 基频一个有意思的细节model.safetensors.index.json 的 metadata 显示参数总量约 5.06B含 250624 词表的 embedding 与 lm_head3.7B 是官方命名。量化策略config.json的quantization字段affine 整数量化MLP 权重gate_proj/up_proj/down_proj4-bitgroup_size 32——参数最多压得最狠其余全部注意力 Q/K/V/O、embeddings、lm_head8-bitgroup_size 64——更敏感保留精度。README.md 给了对比数据纯 4bit全部 group 64会让 WikiText-2 困惑率上升 21.5%而这套混合精度方案只有4.4%18.324 vs bf16 的 17.552。注意K2-Horizon 是一个模型家族更大的成员使用 MoE MoVA 稀疏层。k2_horizon.py 是全家族共用的 MLX 移植版源自官方 PyTorch 实现modeling_k2_horizon.py在 fp32 下逐层校验到 4e-6 相对误差。而这份 3.7B checkpoint 是稠密模型mlp_only_layers覆盖 0–35 全部层MoVA 分支处于就绪但未启用状态。二、GroupedRMSNorm 原理2560 维为什么分 2 组归一化普通 RMSNorm 对整条向量做一次归一化GroupedRMSNorm把hidden_size切成layernorm_num_groups个等长分组每组独立归一化再乘一个全宽的缩放权重。本模型中 groups2即 2560 2 × 1280。核心实现见 k2_horizon.py 的GroupedRMSNorm分三步先转fp32并 reshape 成(..., 2, 1280)——归一化只在 fp32 下做避免低精度误差调用融合内核mx.fast.rms_norm(y, None, eps)此时不传权重reshape 回原形状乘全宽的self.weight再转回输入精度。源码里还有一条groups1 的快速路径直接mx.fast.rms_norm(x, weight, eps)让内核一次完成归一化加乘权重。但注释特意说明本 checkpoint 的所有归一化都走 groups2 分支不会碰快速路径。它在代码里出现三处全部使用layernorm_num_groups2DecoderLayer的input_layernorm与post_attention_layernormk2_horizon.pyK2HorizonModel的最终输出归一化k2_horizon.py。配合 Pre-norm 残差结构k2_horizon.py每层计算逻辑非常直白h x self_attn(input_layernorm(x), mask, cache) h h mlp(post_attention_layernorm(h))三、GQA 实现32 个 Q 头共享 8 组 KV 的代码路径GQAGrouped-Query Attention介于标准 MHA 与 MQA 之间Q 有 32 个头K/V 只有 8 个头每个 KV 头被 4 个 Query 头共享。好处是KV 缓存直接缩小到 1/4长上下文推理更省内存。Attention类k2_horizon.py的关键实现点投影层q_proj2560→409632×128k_proj/v_proj2560→10248×128o_proj4096→2560。attention_biasfalse全部无偏置QK 归一化本 checkpointquery_key_normfalse所以不创建q_norm/k_norm代码中保留了按头分组的 GroupedRMSNorm 路径供家族中需要它的配置使用RoPEtraditionalFalse的 rotate-half 布局基频 1e7 来自rope_parameters带缓存时位置号直接取自cache.offset无需额外传position_ids注意力核心调用 mlx-lm 的融合scaled_dot_product_attentionk2_horizon.py原生支持 GQA不需要把 KV 头repeat_kv复制成 32 份KV 缓存使用 mlx-lm 的KVCache对象cache.update_and_fetch(keys, values)一步完成写入和读取。KV 缓存有多大每层 KV 8 头 × 128 维 × 2K 和 V× 2 字节bf16 4 KB/token乘 36 层 ≈144 KB/token。128K 上下文约 18 GB超长上下文建议配合--max-kv-size与 KV 量化--kv-bits 8控制内存。四、MoVA 架构值张量如何走专家路由MoVAMixture-of-Values是 K2-Horizon 的核心创新普通注意力里 V 张量来自单个v_proj在 MoVA 层里V 由一组值专家路由混合产生——相当于把 MoE 的思想从 FFN 延伸到了注意力。4.1 Router五步路由算法Router类k2_horizon.py被 MoE 块和 MoVA 共用流程五步logits x W.T只用权重、不用偏置按模型精度计算转fp32后算sigmoid本家族配置或softmax得到 scores用scores bias取 top-k——bias 只决定选谁不影响权重这点搞错输出会差很远取被选专家的未加偏置分数作为权重可选归一化和为 1再乘router_scaling_factor本模型为 1.0。两个移植细节值得注意torch.topk换成mx.argpartition不排序因为专家输出最后会求和顺序无关权重全程保持 fp32PyTorch 版会先转 bf16结果只多不出错。4.2 SwitchValueExperts一次内核算完所有命中专家SwitchValueExpertsk2_horizon.py负责值的混合参考实现里 64 个无偏置值专家各是一个独立nn.LinearPyTorch 原版用 Python 循环逐个专家处理、index_add_累加——这在 MLX 的惰性图里又慢又难支持移植后所有专家权重被压成一个[64, 1024, 2560]张量由sanitize完成见下一节一次gather_mm内核调用跑完全部选中专家当 (token, expert) 对数 ≥ 64 时即长 prompt 预填充阶段先按专家排序_gather_sort让内核顺序读取权重算完再散回原序逐 token 解码时跳过排序SiLU 在加权求和之前对每个专家输出单独施加顺序与参考实现一致加权和在 fp32 下完成再转回原精度。4.3 在 Attention 中MoVA 分支长什么样关键只有两行k2_horizon.pyif self.mova: values self.v_experts(x, *self.v_router(x)) # 路由出的值专家混合 else: values self.v_proj(x) # 普通投影MoVA 层里没有v_proj取而代之的是v_routerv_experts。由于值张量仍是 8×128 的形状、按 token 从层输入算出它进入 KV 缓存的方式与普通 V 完全一致——MoVA 不需要任何特殊缓存这是设计上的一个优雅之处。层的判定规则在DecoderLayerk2_horizon.py层不在mlp_only_layers中、且num_experts 0、且层号命中decoder_sparse_step节奏时才是稀疏层MoE FFN MoVA 注意力。本 3.7B checkpoint 的mlp_only_layers覆盖全部 36 层所以mova恒为False走普通路径。五、MoE 块与 sanitize稀疏层的完整链路SparseMoeBlockk2_horizon.py是 FFN 侧的稀疏部分gate复用上文Router本模型norm_topk_probtrue时会归一化权重switch_mlpSwitchGLU路由专家SwiGLU 激活共享专家num_shared_experts 0时是一个更宽的 MLP输出直接相加、不加门控。前向流程gate出(indices, scores)→ 专家计算 → fp32 加权和 → 加共享专家输出。本 checkpointnum_experts0、moe_intermediate_size0此类根本不会被实例化。权重加载由Model.sanitizek2_horizon.py完成三件事把 MoE 层中每个专家的独立权重堆叠成一个[num_experts, out, in]张量——gather_mm单张量推理的前提同样堆叠 MoVA 的v_experts权重丢弃不需要加载的rotary_emb.inv_freqRoPE 频率运行时现算词表共享时丢弃lm_head。该函数幂等重复执行也安全。六、mlx-lm 运行指南加载 4bit 模型的一键步骤由于 mlx-lm 尚未内置k2_horizon架构本仓库直接携带 MLX 模型代码 k2_horizon.py并由 config.json 的model_file字段指向它官方 mlx-lm 开箱即用pip install -U mlx-lm git clone https://gitcode.com/hf_mirrors/mlx-community/K2-Horizon-3.7B-4bit mlx_lm.generate --model K2-Horizon-3.7B-4bit --trust-remote-code \ --prompt 用两句话解释 mixture-of-experts。 --max-tokens 2048 使用提示新版 mlx-lm 必须加--trust-remote-code它会加载并运行仓库内的自定义模型文件文件注释详尽建议先读模型会先思考后作答输出包在ifm|think … /ifm|think标签内max_tokens要预留空间思考力度可在 chat_template.jinja 的reasoning_effort参数设为high/medium/low分词器与生成配置见 tokenizer.json、tokenizer_config.json、generation_config.jsonmlx_lm.chat与mlx_lm.server同样支持但 server 目前会把思考文本直接放在content字段里。七、常见问题 FAQQ1这个 3.7B 模型启用了 MoVA 吗没有。config.json中mova_num_experts0、num_experts036 层全部是稠密 MLP。MoVA/MoE 代码是为家族中稀疏成员准备的本 checkpoint 只走稠密路径。Q2为什么 4bit 只掉 4.4% 困惑率靠混合精度方案占参数大头的 MLP 用 4bitgroup 32敏感的注意力/embedding/lm_head 保留 8bitgroup 64。若全部 4bit困惑率会恶化 21.5%。Q3为什么 Router 的权重不参与量化Router是自定义模块而非nn.Linearmlx-lm 的量化规则不会触碰它路由权重保持全精度——保证选哪个专家这个决策不受量化误差干扰。Q4512K 上下文真的能跑吗max_position_embeddings524288支持它但 KV 缓存约 144 KB/tokenbf16128K 上下文就约 18 GB。实际使用中用--max-kv-size限制缓存、--kv-bits 8压缩 KV按需取舍。总结k2_horizon.py 仅 628 行却完整覆盖了 K2-Horizon 家族的三大架构特征——用 fp32 分组的 GroupedRMSNorm 保证归一化精度、原生 GQA 融合注意力内核压缩 KV 缓存、gather_mm 单次内核实现的 MoVA 值专家路由。对这个 3.7B 4bit checkpoint 而言实际生效的是稠密路径 混合精度量化也正是这三点组合让它以 4.1 GB 的体积在 16 GB Mac 上跑出 109.6 tok/s 的速度。赞分享【免费下载链接】K2-Horizon-3.7B-4bit项目地址https://ai.gitcode.com/hf_mirrors/mlx-community/K2-Horizon-3.7B-4bit点击查看免费下载相关推荐Horizon代码架构解析可复用组件设计与模块化开发Horizon代码架构解析可复用组件设计与模块化开发 Horizon是一个现代化的银行平台采用了先进的Next.js框架和模块化架构设计。该项目通过精心设计Melty的代码分析引擎语法解析与语义理解的完整架构Melty的代码分析引擎语法解析与语义理解的完整架构 Melty代码分析引擎 是这款革命性代码编辑器的智能核心它通过 多层次的语法解析 和 深度语义分AI 应用开发工具拆解GhostESP代码架构ESP-IDF原生固件分层设计与扩展机制完整指南拆解GhostESP代码架构ESP IDF原生固件分层设计与扩展机制完整指南 GhostESP 是一款面向 ESP32 的开源无线研究平台wireless上一篇Redlock的未来发展分布式锁技术的演进路线图与社区规划下一篇dxwrapper修复黑屏与 DirectDraw 闪退让老游戏在 Windows 10/11 上重新跑起来创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考