DeepSeek-V4 接入 AMCT 大模型量化框架MLA Compressor Indexer Hyper-Connections 架构适配实战【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct本文基于 AMCT 开源仓库的 DeepSeek-V4 适配案例deepseekv4.md整理而成聚焦于把官方DeepseekV4ForCausalLM这一“不在 transformers 标准类库中”的模型接入 AMCT blockwise PTQ 量化链路时的完整思路。文章覆盖 v4 独特的 MLA 单 head 共享 KV、o_groups分组低秩wo、Compressor/Indexer 双子模块、Hyper-Connections 4D hidden state 与自定义 forward 签名等结构差异并结合仓库源码给出双向 Config 翻译、空载构图、sharded 多卡加载、量化 wrapper 设计与典型问题复盘的完整方案。读完本文你将掌握“接非 transformers 自定义 modeling MLA 类 MoE 类”模型的通用接入方法论并能直接复用于 DeepSeek-V4-Pro / V4-Flash 的量化适配。一、案例背景与触发信号DeepSeek-V4DeepSeek-V4-Pro系列标记deepseek、结构mla-moe是 AMCT 案例库casebook中“接入非 transformers 自定义 modeling”L2 经验的首遇例也是仓内 MLA Compressor Indexer Hyper-Connections 结构最特殊的模型。其 modeling 上游源自 DeepSeek-V4-Flash 的inference/model.pyPro 与 Flash 两变体结构同源、仅config.json不同共用同一套 adapter。触发这类模型接入的信号很明确在案例文档中被归纳为两条官方config.json中architectures: [DeepseekV4ForCausalLM]但当前 transformers 版本里没有这个类需要自实现 PreTrainedModel 化版本并完成注册config 中同时出现kv_lora_rankMLA 特征与n_routed_expertsMoE 特征。遇到这种组合时案例库建议先读 L2 · 结构家族MLA / MoE / 自定义 modeling 和 L1 · 跨网络通用坑再对照本案例。二、v4 架构的特殊性与标准 HF decoder 的四个关键差异与系列默认路径v3.2 DSA相比v4 的 decoder block 同时包含 attention 侧与 MoE 侧但结构上有四个显著差异直接决定了适配方案不能照搬现有抽象。1. MLA 是单 head 共享 KVwo是o_groups维度的分组低秩投影从源码 modeling_deepseek_v4.py 可以看到Q 侧走wq_a → q_norm → wq_b的低秩投影链KV 侧则由wkv一次性生成共享 KV 再经kv_norm输出投影被拆成wo_awo_b两级其中wo_a的权重形状为[n_heads * head_dim // n_groups, n_groups * o_lora_rank]前向时通过self.wo_a.weight.view(self.n_local_groups, self.o_lora_rank, -1)重塑后走torch.einsum(bsgd,grd-bsgr, o, wo_a)的分组 einsumL679-L684。这意味着wo_a不能像普通 Linear 那样直接 wrap 成QuantLinearQuantLinear.forward走F.linear的调用约定与 grouped einsum 语义不兼容必须做单点例外处理详见第六节。2. Compressor Indexer 双子模块v4 的 attention 在滑动窗口之外还引入了 KV 压缩Compressor通过可学习的 gated pooling 对连续compress_ratio个 token 的 KV 做压缩ratio4时启用 overlap 重叠窗口见 modeling_deepseek_v4.py#L270-L422Indexer用自己的压缩 KV 为稀疏注意力挑选 top-k 位置其内部还嵌了一个独立的CompressorrotateTrue带 Hadamard 旋转L448。因此量化 wrapper 需要做两层嵌套QuantV4Attention内部再挂QuantV4Compressor/QuantV4Indexer而QuantV4Indexer内部又嵌一个QuantV4Compressor见 quant_module.py#L169-L200。3. Hyper-ConnectionsHC全程 4D hidden statev4 不使用简单的残差连接而是维护hc_mult份 hidden state 拷贝Block 之间通过hc_pre把[b, s, hc_mult, d]压缩回一维与hc_post再展开回hc_mult份混合混合系数来自 Sinkhorn 迭代hc_split_sinkhorn_torch。最后的ParallelHead也是 HC-aware 的L938-L951并通过hc_head_fn / hc_head_scale / hc_head_base三个顶层参数完成从 4D 到 1D 的收束。这意味着 embedding 之后 hidden state 就变成 4D[b, s, hc_mult, d]adapter 的do_embedding_forward / do_block_forward / do_head_forward三个 hook 都要按 4D 语义重写见第五节。4. 自定义 forward 签名(x, start_pos, input_ids)v4 的Block.forward签名是(x, start_pos0, input_idsNone)L884-L905与标准 HF decoder 完全不同没有attention_mask / position_ids / position_embeddings。其中input_ids需要在 hash-routed MoE 层前n_hash_layers层参与路由Gate在self.hash为真时直接查tid2eid[input_ids]得到专家索引L700-L738。这一差异的连锁影响是框架的Catcher数据捕获器要求可捕获的 forward 能以**kwargs接收参数。v4 的Block.forward将参数改为带默认值后恰好与Catcher.forward(inp, **kwargs)对齐因此可以直接复用框架原版Catcher无需新建_V4Catcher——这是案例中明确记录的一个“巧劲”。三、适配方案总览复用框架抽象 最小本地新增复用的框架抽象案例文档明确列出了 v4 适配中直接复用、零改动的框架能力均可在源码中印证复用的抽象作用源码位置BaseModeladapter 基类提供 blockwise 遍历、加载、PTQ 参数管理等骨架base.pyPtqUnit / make_ptq_unit / iter_indexed_unitsPTQ 单元构造与枚举ptq_units.pyQuantLinear全部常规 Linear 的权重量化wq_a/wq_b/wkv/wo_b Compressorwkv/wgate Indexerwq_b/weights_proj Indexer.compressor 内两个 Linear Expertw1/w2/w3quant_linear.pyQuantGatedMLPQuantV4Expert子类化它通过 facade 适配w1→gate_proj等命名差quant_apply.pyActivationQuantizer每个 Linear 输入 q/kv cache 节点的激活量化quant_base.pyapply_quant_to_moe_mlpMoE wrapper 递归应用把block.ffn当 root 传入即可quant_apply.pyCatcher数据捕获框架原版不新建 v4 专属版本capture.pyinit_empty_weights(include_buffersTrue)空载构图accelerate 工具库BaseModel.do_block_forward的 per-sample state 通道self.input_ids列表字段BaseModel 新增默认 None其它 adapter 用不到base.py其中 per-sampleinput_ids通道值得一提v4 在do_embedding_forward末尾设置self.input_ids list(samples)deepseekv4.py#L193继承自BaseModel的do_block_forwardforward loop 会自动按 zip 注入v4 自己的do_block_forward因此退化成纯 pass-through没有 30 行重复实现。新增适配的最小集合所有新增代码被严格限制在amct_pytorch/common/models/llm/deepseek/deepseek_v4/目录下共 5 个文件文件职责modeling/configuration_deepseek_v4.pyDeepseekV4Config(PretrainedConfig)双向命名翻译 嵌套rope_scaling/quantization_config拆包modeling/modeling_deepseek_v4.pyTransformer(nn.Module)→DeepseekV4ForCausalLM(DeepseekV4PreTrainedModel)Block/Attention/Compressor/Indexer/MoE/Expert/Gate/RMSNorm/ParallelHead完全保持上游风格作为浮点对照基准quant_module.pyQuantV4Attention / QuantV4Compressor / QuantV4Indexer / QuantV4Expertprefill-onlywrapper 内不持有 cache bufferdeepseekv4.pyadapter 主体empty_weights_model、嵌入/头部加载含顶层hc_head_*参数、三个 forward hook 的 v4 重写、apply_quant_attn / apply_quant_moe_mlp / iter_ptq_units / iter_deploy_bindings的 v4 命名 override、sharded 多卡加载__init__.pyAutoConfig.register(deepseek_v4, ...)AutoModelForCausalLM.register(DeepseekV4Config, DeepseekV4ForCausalLM, exist_okTrue)L34-L35适配时特别要注意 v4 的子模块命名是block.attn / block.ffnv3.2 是block.self_attn / block.mlp因此框架的apply_quant_to_attn不能直接用。adapter 在apply_quant_attn中直接单点替换decoder_layer.attn QuantV4Attention(self.args, decoder_layer.attn)deepseekv4.py#L121-L123而apply_quant_to_moe_mlp把block.ffn当 root 传进去递归内部仍能匹配到experts/shared_expertsL125-L130。同时iter_ptq_units必须 override——父类按self_attn / mlp找v4 找不到L256-L273。四、双向命名翻译 ConfigDeepseekV4Config官方config.json使用 HF 标准命名hidden_size / num_hidden_layers / qk_rope_head_dim / rms_norm_eps / sliding_window / max_position_embeddings / rope_scaling / quantization_config而 v4 modeling 代码Block / Attention / MoE读取的是ModelArgs风格命名dim / n_layers / ...。DeepseekV4Config的核心设计是同时声明两套命名HF 名做翻译ModelArgs 名做运行时绑定且当两者同时出现时 HF 名优先见 configuration_deepseek_v4.py#L21-L27。关键字段对照表HF 标准名 → ModelArgs 名 → 默认值HF 标准名ModelArgs 名默认值语义hidden_sizedim4096模型宽度num_hidden_layersn_layers7Transformer 层数num_attention_headsn_heads64attention head 数moe_intermediate_sizemoe_inter_dim4096MoE 中间维度num_experts_per_tokn_activated_experts2每 token 激活专家数qk_rope_head_dimrope_head_dim64RoPE 子维度rms_norm_epsnorm_eps1e-6RMSNorm epsilonsliding_windowwindow_size128滑动窗口大小scoring_funcscore_funcsqrtsoftplus路由打分函数routed_scaling_factorroute_scale1.0路由权重缩放num_hash_layersn_hash_layers0hash 路由层数num_nextn_predict_layersn_mtp_layers1MTP 层数max_position_embeddingsmax_seq_len4096最大序列长度除此之外还有两组嵌套 dict 拆包逻辑L121-L137rope_scalingdict 拆成扁平 YaRN 字段factor → rope_factor、original_max_position_embeddings → original_seq_len、beta_fast/beta_slowquantization_configdict 拆出quant_method fp8 → dtype fp8与scale_fmt。dtype 撞名问题与arch_dtype重命名案例文档记录的问题 6是一个极易踩中的深坑v4ModelArgs的dtype字段是架构量化格式选择器fp8/bf16字符串而现代 transformers 的PretrainedConfig会把dtype设成torch_dtype的同 slot 别名运行时加载 dtype如torch.bfloat16对象。两个语义同名却不同义在同一 config 上互斥——super().__init__(**kwargs)之后self.dtype fp8会被覆盖成torch.bfloat16。修法是重命名为arch_dtypeL208modeling 里config.dtype fp8相应改为config.arch_dtype fp8modeling_deepseek_v4.py#L976。ModelArgs输入参数名保持不变仍是dtypefp8内部翻译到arch_dtype不影响用户侧调用。双向暴露只翻不存会挂 AttributeError案例问题 5指出如果 Config 只做“输入归一化”而不把 HF 名也存回selfHF 通用工具generation、tokenizer max-length 检查、transformers internals直接读config.max_position_embeddings就会抛AttributeError。因此DeepseekV4Config.__init__末尾对每个 HF 标准名做了对称镜像L184-L198hidden_size / num_hidden_layers / num_attention_heads / moe_intermediate_size / num_experts_per_tok / qk_rope_head_dim / rms_norm_eps / sliding_window / scoring_func / routed_scaling_factor / num_hash_layers / num_nextn_predict_layers / max_position_embeddings / rope_scaling / quantization_config全部铺开。机械规则是凡是__init__接受的 HF 名Config 末尾都要self.hf_name ...一份即使 ModelArgs 名也存了。五、空载构图与权重加载路径v4 是 61 层、max_seq_len1048576量级的超大模型空载构图与加载路径的正确性直接决定能否在有限内存下推进量化。1.init_empty_weights(include_buffersTrue)否则空载即 OOM问题 1v4 的Attention / Compressor / Indexer在__init__阶段就用register_buffer(torch.zeros / torch.full(-inf, ...))分配了大量与max_batch_size / max_seq_len / compress_ratio相关的 state buffer如 modeling_deepseek_v4.py#L307-L325、L449-L455、L549-L553。默认的init_empty_weights()只把 Parameter 重定向到 meta、不动 buffer于是 61 层全模型构图会真分配 CPU 内存——kv_cache单层就能上百 MB全建必然 OOM。修法就是显式init_empty_weights(include_buffersTrue)deepseekv4.py#L222-L234让 buffer 跟 Parameter 一起到 meta。通用规避规则任何上游模型若register_buffer用了实分配 factory 且 buffer 大小与max_seq_len / max_batch_size相关默认开include_buffersTrue。2.lru_cache的 meta 张量污染与cache_clear()问题 0上游precompute_freqs_cis是lru_cache(2)装饰的modeling_deepseek_v4.py#L131-L170。当empty_weights_model在 meta 上下文里首次调用它时返回值是 meta 张量并被缓存后续block(layer_idx)在真 CPU 上下文里再调用Attention.__init__命中缓存直接返还 meta 张量给register_buffer(freqs_cis, ...).to(device)时就会报 “Cannot copy out of meta tensor; no data!”。修法是在empty_weights_model()收尾显式precompute_freqs_cis.cache_clear()deepseekv4.py#L233之后按层 build block 时在真 CPU 上下文重新计算、共享同一个 cached 真张量。通用规避规则任何模块级lru_cache / cache装饰的、返回值为 tensor / device-dependent 对象的工厂函数若在with torch.device(meta)或init_empty_weights上下文里被调过离开上下文时必须.cache_clear()。3.block()双路分流PTQ 的 CPU staging 与 eval 的 sharded 直送案例现状更新中最关键的设计是block()override 为双路分流deepseekv4.py#L132-L141sharded_blockTrueeval / 真权重大模型走_block_sharded——在 meta 上下文构造单层用_build_block_device_map_dispatch_block_NoMoveAlignDevicesHook把 stem / attention / indexer / 各 expert 直接钉在多张 NPU 上加载即就位绕开BaseModel.block()约 35GB 的 CPU stagingper-tensor 只对浮点参数做.to(bf16)L290-L344。设备分配策略见_build_block_device_mapnpu:0给 stem、npu:1给 attn、npu:2给 indexer若存在、剩余卡对 experts 轮询分配L346-L368。sharded_blockFalsePTQ仍走super().block()的 CPU staging因为 PTQ 需要在 per-MLP 学习时把单个 expert 逐批搬到 NPU而 sharded 路径的AlignDevicesHook把 expert 钉死在固定卡会和 PTQ 的.to(device)/.cpu()循环打架。两路不可统一这是案例明确记录的设计结论。此外顶层hc_head_*三个参数由_load_top_level_hc_head_params在load_embed_state_dict时从 checkpoint 取回并转为 fp32L388-L406do_head_forward会先校验其不在 meta 上再搬运L196-L220。4. 已知 dtype 风险等权重到位后修BaseModel.block()末尾的decoder_layer.eval().bfloat16()会把 v4 里set_dtype(fp32)声明的子参数Block.hc_attn_fn / hc_ffn_fn / hc_*_base / hc_*_scale、RMSNorm.weight、ParallelHead.weight等也一并 cast 到 bf16前向时hc_pre里F.linear(x.float(), hc_fn)会撞到float ! BFloat16的 dtype 不匹配。现状已部分缓解empty_weights_model()路径已修好——改用AutoModelForCausalLM.from_config(self.config, torch_dtypetorch.bfloat16)from_config内部用set_default_dtype(bf16)包住实例化Block.__init__里with set_dtype(fp32):嵌套生效fp32 子参数正确停在 fp32smoke 验证通过hc_attn_fn / attn_norm.weight / attn_sink仍 fp32、wq_a.weight仍 bf16、所有 buffer 在 meta。仍有 bug 的是BaseModel.block(layer_idx)的单层构造evalsharded路径 per-tensor 只对浮点.to(bf16)、dtype 正确V4-Pro/Flash BF16 baseline 已在此路径跑出PTQ 路径仍走super().block()的全量 cast该 bug 未修待进 PTQ 时在 PTQ 分支按set_default_dtype方式处理。六、量化 wrapper 设计prefill-only 与 wo_a 单点例外quant_module.py里的四个 wrapper 全部遵循prefill-only约定forward内assert start_pos 0wrapper 不注册kv_cache / kv_state / score_statebuffer那些仍留在被 wrap 的上游模块实例上prefill 下不会被用到。cache_scheme()中kv_cache_scheme为 8-bit float、li_cache_scheme为 8-bit int/float 按quant_dtype切换deepseekv4.py#L279-L288。QuantV4Attention与wo_a单点例外QuantV4Attentionquant_module.py#L235-L447在attn-lineartarget 下量化wq_a / wq_b / wkv / wo_b四个常规 Linear全部走QuantLinear其中wq_a输出经q_norm后由wq_b展开为多头且做 RMS 归一化 RoPEQK / PV 两个稀疏 attention matmul 用QuantizedMatmul承载attn-cachetarget 的量化q/k/p/v cache bits 来自bit_policy.cache_bits见 L304-L317wo_a保留为原nn.Linear旁路挂一个WeightQuantizer在_wo_a_apply里手动跑observe_input weight_quantizer 重塑 einsum全流程L426-L435因为 grouped einsum 与QuantLinear.forward的F.linear调用方式不兼容。sparse_attn是上游Attention.sparse_attn的逐位拷贝纯计算、无状态内部用QuantizedMatmul替代原始torch.matmulL332-L359。QuantV4Compressor/QuantV4IndexerQuantV4Compressor量化wkv / wgate两个 Linearcomp_wkv / comp_wgatebits并复刻上游的 overlap 变换、gated pooling、RoPE 与可选的 Hadamard 旋转rotate逻辑L95-L161QuantV4Indexer量化wq_b / weights_projidx_wq_b / idx_weights_projbits并内嵌一个QuantV4Compressor作为其压缩 KV 打分路径L164-L232。两个 wrapper 在enable_attn_linear为假时退化回PlainLinearnn.Identity()保证关闭量化时浮点等价。QuantV4Expert复用QuantGatedMLP的 facade 技巧v4 的Expert是 SwiGLU FFNw1 / w2 / w3而框架QuantGatedMLP期望gate_proj / up_proj / down_proj / hidden_size / intermediate_size / act_fn。QuantV4Expert构造一个薄 facade 模块做名字别名facade.gate_proj expert.w1等再让父类以QuantLinear包装并重写forward实现 v4 的 clamp-then-silu 语义与可选路由权重quant_module.py#L52-L92。PTQ 单元枚举与部署绑定iter_ptq_units按 target 路由attn-linear / attn-cache时 yield 单个attn单元并直接返回moe时用iter_indexed_units对ffn.experts逐专家枚举并附带expert_idxmetadatadeepseekv4.py#L256-L273。build_quant_block同时拒绝quant_targetmlp——v4 是 MoE 模型L143-L153。七、官方 checkpoint 实际布局以事实为准案例文档给出一个关键认知architectures: [DeepseekV4ForCausalLM]这个名字虽符合 HF 约定但官方 checkpoint 的 state_dict 是扁平结构不是 HF 标准的model.X嵌套。修 modeling / load 路径前必须先拉model.safetensors.index.json看实际 key不要靠命名推断问题 3 正是因此翻车。核对后的事实顶层 6 个 keyembed.weight / head.weight / norm.weight / hc_head_fn / hc_head_scale / hc_head_base——没有model.前缀主 backbone 61 层layers.0..60.*按四类签名分布与 config 的num_hash_layers3和compress_ratios数组index 2/4/6/.../60 4严格对应层路由类型Compressor / Indexercompress_ratio0/1hash-routedffn.gate.tid2eidCompressor无 Indexer1282hash-routedffn.gate.tid2eidCompressor Indexer43,5,7,...,59score-routedffn.gate.biasCompressor无 Indexer—4,6,8,...,60score-routedffn.gate.biasCompressor Indexer4**MTP 模块mtp.{m}.***存在于 checkpoint 顶层结构类似 Block另有e_proj / h_proj / enorm / hnorm四个连接到主 backbone 的组件。当前 modeling不实例化 MTPadapter 的 load 路径按layers.N. / embed. / norm. / head.特定前缀取 key与mtp.*自然不相交strict load 也不会失败——主 backbone PTQ 走通之前不接命名验证attn不是self_attn、ffn不是mlp、ffn.experts.{e}显式逐 expert、ffn.shared_experts单数模块名全部与 modeling 对齐。八、典型问题复盘案例文档保留了 v4 完整 repro问题 0/1/2/3/5/6 已上抽为 L2/L1 通用条目此处保留作为该家族最详尽的参考#现象根因修法0block(layer_idx).to(device)报 “Cannot copy out of meta tensor”precompute_freqs_cis的lru_cache在 meta 上下文缓存了 meta 张量后续真 CPU 构造命中缓存empty_weights_model()收尾cache_clear()1空载 OOMregister_buffer实分配且include_buffersFalse只重定向 Parameterinit_empty_weights(include_buffersTrue)2dim是默认值 4096应 7168但不报错Config 只接收 ModelArgs 名HF 名走**kwargs只存为旁路属性同时声明两套命名并做翻译3按architectures推断 HF 嵌套结构HF 命名约定不保证 checkpoint 用嵌套结构v4 实际是扁平动 modeling 前先拉model.safetensors.index.json看真实 key5运行时 AttributeError翻译只做“输入归一化”没把 HF 名存回 selfConfig 末尾对每个 HF 名做对称镜像6cfg.dtype被覆盖成torch.bfloat16HF 的dtype是torch_dtype别名与 v4 的架构 quant 格式字段撞名重命名arch_dtypeHF 语义保留其中问题 2 的更深层教训是接 HF 系模型先抓官方config.json把字段一栏一栏对照ModelArgs/ 代码内 attr缺什么补什么问题 6 的机械规则是——写双向 Config 时先列出 modern HFPretrainedConfig已占用的 attribute slotdtype / torch_dtype / hidden_size / num_hidden_layers / num_attention_heads / max_position_embeddings / vocab_size / pad_token_id / bos_token_id / eos_token_id / use_cache / tie_word_embeddings / rope_scaling / quantization_config / ...自家字段若撞名优先在 Config 内部重命名不要靠“在 super 后再赋值”硬抢。九、量化进展与结论截至案例文档记录时点BF16 baseline 已出DeepSeek-V4-Pro ppl1.9946同一 modeling/Config 覆盖 V4-FlashDP-Flashppl4.1517——两变体结构同源、仅 config.json 不同共用本 adapter关闭量化后保持浮点等价未做当时权重未下载真权重现可加载具备验证条件最小 PTQ unit 闭环部分——在小 confign_layers2, dim128, n_routed_experts4上跑通空载 smokeBlock 构建meta CPU 都过→apply_quant_attn / apply_quant_moe_mlp→25 个 QuantLinear 19 个 ActivationQuantizer→iter_ptq_units(attn-linear)1 个 unit、iter_ptq_units(moe)4 个 unit →iter_deploy_bindings16 个 binding →expert.export_ptq_params()返回 3 keys真权重 GT 路径未跑过第一版直转量化方案暂未确定预计起点与 v3.2 类似attn-linear w8a8 / attn-cache q/k 16-bit / moe routed w8 shared w8直转结果与最终方案待权重验证后确定。量化状态的口径在 deepseek 系列总览 中有配套约定BF16 baseline 一般用 Wikitext PPL 的 blockwise 口径直转量化delta 0.2或做过一轮粗粒度误差定位后通常进入 PTQ。十、最终建议下次接入类似模型的 Checklist下次遇到类似模型MLA Compressor Indexer HC 自定义 forward 签名优先参考本案例 deepseek-v3.2MLA 部分 longcat_nextPreTrainedModel 化 AutoModel 注册。先做什么抓官方config.json做字段表对照HF 标准名 vs 模型代码 attr 名写双向 Config抓官方model.safetensors.index.json走 modelscope 镜像HF 直链有 LFS 重定向 WebFetch 10MB 限制都不稳解析顶层 key 代表层 key 不同签名的层——这一步比读上游源码更直接在小 confign_layers2, dim128, expert4上跑通“空载 smoke”——Block 构建 apply_quant_*iter_ptq_unitsexport_ptq_params所有 Linear / ActivationQuantizer 数对得上再去找权重上游 modeling 文件原样保留只改明显坏掉的 import。不建议一开始做什么一上来就裁上游 modeling 的 kv_cache / decode 分支——那是 wrapper 的事modeling 要做浮点对照基准直接复用同系列前一代的 quant 模块v3.2 → v4 直接抄QuantDSA这种——结构差异大语义错位会很隐蔽在框架级quant_apply.py改name in [...]列表去匹配新模型的命名——wrapper 在 adapter 里做单点替换 overrideiter_ptq_units更干净靠 HF 命名约定推断 checkpoint 嵌套结构——看architectures字段不能代替看model.safetensors.index.json的真实 key看到.scale配对就先实现 FP8 dequant 路径——先确认最终权重格式不要替用户做“以后可能要做”的事一上来就把 MTP / 额外 head 等非主 backbone 模块塞进 modeling——skill 阶段任务是主链跑通非主链结构在 load 路径里“自然不被请求”即可。相关仓库路径速查adapter 主体 deepseekv4.py、量化 wrapper quant_module.py、双向 Config configuration_deepseek_v4.py、上游风格 modeling modeling_deepseek_v4.py、注册入口init.py、框架基类 base.py、MoE 量化应用 quant_apply.py、PTQ 单元 ptq_units.py。【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepSeek-V4 接入 AMCT 大模型量化框架：MLA + Compressor + Indexer + Hyper-Connections 架构适配实战
DeepSeek-V4 接入 AMCT 大模型量化框架MLA Compressor Indexer Hyper-Connections 架构适配实战【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct本文基于 AMCT 开源仓库的 DeepSeek-V4 适配案例deepseekv4.md整理而成聚焦于把官方DeepseekV4ForCausalLM这一“不在 transformers 标准类库中”的模型接入 AMCT blockwise PTQ 量化链路时的完整思路。文章覆盖 v4 独特的 MLA 单 head 共享 KV、o_groups分组低秩wo、Compressor/Indexer 双子模块、Hyper-Connections 4D hidden state 与自定义 forward 签名等结构差异并结合仓库源码给出双向 Config 翻译、空载构图、sharded 多卡加载、量化 wrapper 设计与典型问题复盘的完整方案。读完本文你将掌握“接非 transformers 自定义 modeling MLA 类 MoE 类”模型的通用接入方法论并能直接复用于 DeepSeek-V4-Pro / V4-Flash 的量化适配。一、案例背景与触发信号DeepSeek-V4DeepSeek-V4-Pro系列标记deepseek、结构mla-moe是 AMCT 案例库casebook中“接入非 transformers 自定义 modeling”L2 经验的首遇例也是仓内 MLA Compressor Indexer Hyper-Connections 结构最特殊的模型。其 modeling 上游源自 DeepSeek-V4-Flash 的inference/model.pyPro 与 Flash 两变体结构同源、仅config.json不同共用同一套 adapter。触发这类模型接入的信号很明确在案例文档中被归纳为两条官方config.json中architectures: [DeepseekV4ForCausalLM]但当前 transformers 版本里没有这个类需要自实现 PreTrainedModel 化版本并完成注册config 中同时出现kv_lora_rankMLA 特征与n_routed_expertsMoE 特征。遇到这种组合时案例库建议先读 L2 · 结构家族MLA / MoE / 自定义 modeling 和 L1 · 跨网络通用坑再对照本案例。二、v4 架构的特殊性与标准 HF decoder 的四个关键差异与系列默认路径v3.2 DSA相比v4 的 decoder block 同时包含 attention 侧与 MoE 侧但结构上有四个显著差异直接决定了适配方案不能照搬现有抽象。1. MLA 是单 head 共享 KVwo是o_groups维度的分组低秩投影从源码 modeling_deepseek_v4.py 可以看到Q 侧走wq_a → q_norm → wq_b的低秩投影链KV 侧则由wkv一次性生成共享 KV 再经kv_norm输出投影被拆成wo_awo_b两级其中wo_a的权重形状为[n_heads * head_dim // n_groups, n_groups * o_lora_rank]前向时通过self.wo_a.weight.view(self.n_local_groups, self.o_lora_rank, -1)重塑后走torch.einsum(bsgd,grd-bsgr, o, wo_a)的分组 einsumL679-L684。这意味着wo_a不能像普通 Linear 那样直接 wrap 成QuantLinearQuantLinear.forward走F.linear的调用约定与 grouped einsum 语义不兼容必须做单点例外处理详见第六节。2. Compressor Indexer 双子模块v4 的 attention 在滑动窗口之外还引入了 KV 压缩Compressor通过可学习的 gated pooling 对连续compress_ratio个 token 的 KV 做压缩ratio4时启用 overlap 重叠窗口见 modeling_deepseek_v4.py#L270-L422Indexer用自己的压缩 KV 为稀疏注意力挑选 top-k 位置其内部还嵌了一个独立的CompressorrotateTrue带 Hadamard 旋转L448。因此量化 wrapper 需要做两层嵌套QuantV4Attention内部再挂QuantV4Compressor/QuantV4Indexer而QuantV4Indexer内部又嵌一个QuantV4Compressor见 quant_module.py#L169-L200。3. Hyper-ConnectionsHC全程 4D hidden statev4 不使用简单的残差连接而是维护hc_mult份 hidden state 拷贝Block 之间通过hc_pre把[b, s, hc_mult, d]压缩回一维与hc_post再展开回hc_mult份混合混合系数来自 Sinkhorn 迭代hc_split_sinkhorn_torch。最后的ParallelHead也是 HC-aware 的L938-L951并通过hc_head_fn / hc_head_scale / hc_head_base三个顶层参数完成从 4D 到 1D 的收束。这意味着 embedding 之后 hidden state 就变成 4D[b, s, hc_mult, d]adapter 的do_embedding_forward / do_block_forward / do_head_forward三个 hook 都要按 4D 语义重写见第五节。4. 自定义 forward 签名(x, start_pos, input_ids)v4 的Block.forward签名是(x, start_pos0, input_idsNone)L884-L905与标准 HF decoder 完全不同没有attention_mask / position_ids / position_embeddings。其中input_ids需要在 hash-routed MoE 层前n_hash_layers层参与路由Gate在self.hash为真时直接查tid2eid[input_ids]得到专家索引L700-L738。这一差异的连锁影响是框架的Catcher数据捕获器要求可捕获的 forward 能以**kwargs接收参数。v4 的Block.forward将参数改为带默认值后恰好与Catcher.forward(inp, **kwargs)对齐因此可以直接复用框架原版Catcher无需新建_V4Catcher——这是案例中明确记录的一个“巧劲”。三、适配方案总览复用框架抽象 最小本地新增复用的框架抽象案例文档明确列出了 v4 适配中直接复用、零改动的框架能力均可在源码中印证复用的抽象作用源码位置BaseModeladapter 基类提供 blockwise 遍历、加载、PTQ 参数管理等骨架base.pyPtqUnit / make_ptq_unit / iter_indexed_unitsPTQ 单元构造与枚举ptq_units.pyQuantLinear全部常规 Linear 的权重量化wq_a/wq_b/wkv/wo_b Compressorwkv/wgate Indexerwq_b/weights_proj Indexer.compressor 内两个 Linear Expertw1/w2/w3quant_linear.pyQuantGatedMLPQuantV4Expert子类化它通过 facade 适配w1→gate_proj等命名差quant_apply.pyActivationQuantizer每个 Linear 输入 q/kv cache 节点的激活量化quant_base.pyapply_quant_to_moe_mlpMoE wrapper 递归应用把block.ffn当 root 传入即可quant_apply.pyCatcher数据捕获框架原版不新建 v4 专属版本capture.pyinit_empty_weights(include_buffersTrue)空载构图accelerate 工具库BaseModel.do_block_forward的 per-sample state 通道self.input_ids列表字段BaseModel 新增默认 None其它 adapter 用不到base.py其中 per-sampleinput_ids通道值得一提v4 在do_embedding_forward末尾设置self.input_ids list(samples)deepseekv4.py#L193继承自BaseModel的do_block_forwardforward loop 会自动按 zip 注入v4 自己的do_block_forward因此退化成纯 pass-through没有 30 行重复实现。新增适配的最小集合所有新增代码被严格限制在amct_pytorch/common/models/llm/deepseek/deepseek_v4/目录下共 5 个文件文件职责modeling/configuration_deepseek_v4.pyDeepseekV4Config(PretrainedConfig)双向命名翻译 嵌套rope_scaling/quantization_config拆包modeling/modeling_deepseek_v4.pyTransformer(nn.Module)→DeepseekV4ForCausalLM(DeepseekV4PreTrainedModel)Block/Attention/Compressor/Indexer/MoE/Expert/Gate/RMSNorm/ParallelHead完全保持上游风格作为浮点对照基准quant_module.pyQuantV4Attention / QuantV4Compressor / QuantV4Indexer / QuantV4Expertprefill-onlywrapper 内不持有 cache bufferdeepseekv4.pyadapter 主体empty_weights_model、嵌入/头部加载含顶层hc_head_*参数、三个 forward hook 的 v4 重写、apply_quant_attn / apply_quant_moe_mlp / iter_ptq_units / iter_deploy_bindings的 v4 命名 override、sharded 多卡加载__init__.pyAutoConfig.register(deepseek_v4, ...)AutoModelForCausalLM.register(DeepseekV4Config, DeepseekV4ForCausalLM, exist_okTrue)L34-L35适配时特别要注意 v4 的子模块命名是block.attn / block.ffnv3.2 是block.self_attn / block.mlp因此框架的apply_quant_to_attn不能直接用。adapter 在apply_quant_attn中直接单点替换decoder_layer.attn QuantV4Attention(self.args, decoder_layer.attn)deepseekv4.py#L121-L123而apply_quant_to_moe_mlp把block.ffn当 root 传进去递归内部仍能匹配到experts/shared_expertsL125-L130。同时iter_ptq_units必须 override——父类按self_attn / mlp找v4 找不到L256-L273。四、双向命名翻译 ConfigDeepseekV4Config官方config.json使用 HF 标准命名hidden_size / num_hidden_layers / qk_rope_head_dim / rms_norm_eps / sliding_window / max_position_embeddings / rope_scaling / quantization_config而 v4 modeling 代码Block / Attention / MoE读取的是ModelArgs风格命名dim / n_layers / ...。DeepseekV4Config的核心设计是同时声明两套命名HF 名做翻译ModelArgs 名做运行时绑定且当两者同时出现时 HF 名优先见 configuration_deepseek_v4.py#L21-L27。关键字段对照表HF 标准名 → ModelArgs 名 → 默认值HF 标准名ModelArgs 名默认值语义hidden_sizedim4096模型宽度num_hidden_layersn_layers7Transformer 层数num_attention_headsn_heads64attention head 数moe_intermediate_sizemoe_inter_dim4096MoE 中间维度num_experts_per_tokn_activated_experts2每 token 激活专家数qk_rope_head_dimrope_head_dim64RoPE 子维度rms_norm_epsnorm_eps1e-6RMSNorm epsilonsliding_windowwindow_size128滑动窗口大小scoring_funcscore_funcsqrtsoftplus路由打分函数routed_scaling_factorroute_scale1.0路由权重缩放num_hash_layersn_hash_layers0hash 路由层数num_nextn_predict_layersn_mtp_layers1MTP 层数max_position_embeddingsmax_seq_len4096最大序列长度除此之外还有两组嵌套 dict 拆包逻辑L121-L137rope_scalingdict 拆成扁平 YaRN 字段factor → rope_factor、original_max_position_embeddings → original_seq_len、beta_fast/beta_slowquantization_configdict 拆出quant_method fp8 → dtype fp8与scale_fmt。dtype 撞名问题与arch_dtype重命名案例文档记录的问题 6是一个极易踩中的深坑v4ModelArgs的dtype字段是架构量化格式选择器fp8/bf16字符串而现代 transformers 的PretrainedConfig会把dtype设成torch_dtype的同 slot 别名运行时加载 dtype如torch.bfloat16对象。两个语义同名却不同义在同一 config 上互斥——super().__init__(**kwargs)之后self.dtype fp8会被覆盖成torch.bfloat16。修法是重命名为arch_dtypeL208modeling 里config.dtype fp8相应改为config.arch_dtype fp8modeling_deepseek_v4.py#L976。ModelArgs输入参数名保持不变仍是dtypefp8内部翻译到arch_dtype不影响用户侧调用。双向暴露只翻不存会挂 AttributeError案例问题 5指出如果 Config 只做“输入归一化”而不把 HF 名也存回selfHF 通用工具generation、tokenizer max-length 检查、transformers internals直接读config.max_position_embeddings就会抛AttributeError。因此DeepseekV4Config.__init__末尾对每个 HF 标准名做了对称镜像L184-L198hidden_size / num_hidden_layers / num_attention_heads / moe_intermediate_size / num_experts_per_tok / qk_rope_head_dim / rms_norm_eps / sliding_window / scoring_func / routed_scaling_factor / num_hash_layers / num_nextn_predict_layers / max_position_embeddings / rope_scaling / quantization_config全部铺开。机械规则是凡是__init__接受的 HF 名Config 末尾都要self.hf_name ...一份即使 ModelArgs 名也存了。五、空载构图与权重加载路径v4 是 61 层、max_seq_len1048576量级的超大模型空载构图与加载路径的正确性直接决定能否在有限内存下推进量化。1.init_empty_weights(include_buffersTrue)否则空载即 OOM问题 1v4 的Attention / Compressor / Indexer在__init__阶段就用register_buffer(torch.zeros / torch.full(-inf, ...))分配了大量与max_batch_size / max_seq_len / compress_ratio相关的 state buffer如 modeling_deepseek_v4.py#L307-L325、L449-L455、L549-L553。默认的init_empty_weights()只把 Parameter 重定向到 meta、不动 buffer于是 61 层全模型构图会真分配 CPU 内存——kv_cache单层就能上百 MB全建必然 OOM。修法就是显式init_empty_weights(include_buffersTrue)deepseekv4.py#L222-L234让 buffer 跟 Parameter 一起到 meta。通用规避规则任何上游模型若register_buffer用了实分配 factory 且 buffer 大小与max_seq_len / max_batch_size相关默认开include_buffersTrue。2.lru_cache的 meta 张量污染与cache_clear()问题 0上游precompute_freqs_cis是lru_cache(2)装饰的modeling_deepseek_v4.py#L131-L170。当empty_weights_model在 meta 上下文里首次调用它时返回值是 meta 张量并被缓存后续block(layer_idx)在真 CPU 上下文里再调用Attention.__init__命中缓存直接返还 meta 张量给register_buffer(freqs_cis, ...).to(device)时就会报 “Cannot copy out of meta tensor; no data!”。修法是在empty_weights_model()收尾显式precompute_freqs_cis.cache_clear()deepseekv4.py#L233之后按层 build block 时在真 CPU 上下文重新计算、共享同一个 cached 真张量。通用规避规则任何模块级lru_cache / cache装饰的、返回值为 tensor / device-dependent 对象的工厂函数若在with torch.device(meta)或init_empty_weights上下文里被调过离开上下文时必须.cache_clear()。3.block()双路分流PTQ 的 CPU staging 与 eval 的 sharded 直送案例现状更新中最关键的设计是block()override 为双路分流deepseekv4.py#L132-L141sharded_blockTrueeval / 真权重大模型走_block_sharded——在 meta 上下文构造单层用_build_block_device_map_dispatch_block_NoMoveAlignDevicesHook把 stem / attention / indexer / 各 expert 直接钉在多张 NPU 上加载即就位绕开BaseModel.block()约 35GB 的 CPU stagingper-tensor 只对浮点参数做.to(bf16)L290-L344。设备分配策略见_build_block_device_mapnpu:0给 stem、npu:1给 attn、npu:2给 indexer若存在、剩余卡对 experts 轮询分配L346-L368。sharded_blockFalsePTQ仍走super().block()的 CPU staging因为 PTQ 需要在 per-MLP 学习时把单个 expert 逐批搬到 NPU而 sharded 路径的AlignDevicesHook把 expert 钉死在固定卡会和 PTQ 的.to(device)/.cpu()循环打架。两路不可统一这是案例明确记录的设计结论。此外顶层hc_head_*三个参数由_load_top_level_hc_head_params在load_embed_state_dict时从 checkpoint 取回并转为 fp32L388-L406do_head_forward会先校验其不在 meta 上再搬运L196-L220。4. 已知 dtype 风险等权重到位后修BaseModel.block()末尾的decoder_layer.eval().bfloat16()会把 v4 里set_dtype(fp32)声明的子参数Block.hc_attn_fn / hc_ffn_fn / hc_*_base / hc_*_scale、RMSNorm.weight、ParallelHead.weight等也一并 cast 到 bf16前向时hc_pre里F.linear(x.float(), hc_fn)会撞到float ! BFloat16的 dtype 不匹配。现状已部分缓解empty_weights_model()路径已修好——改用AutoModelForCausalLM.from_config(self.config, torch_dtypetorch.bfloat16)from_config内部用set_default_dtype(bf16)包住实例化Block.__init__里with set_dtype(fp32):嵌套生效fp32 子参数正确停在 fp32smoke 验证通过hc_attn_fn / attn_norm.weight / attn_sink仍 fp32、wq_a.weight仍 bf16、所有 buffer 在 meta。仍有 bug 的是BaseModel.block(layer_idx)的单层构造evalsharded路径 per-tensor 只对浮点.to(bf16)、dtype 正确V4-Pro/Flash BF16 baseline 已在此路径跑出PTQ 路径仍走super().block()的全量 cast该 bug 未修待进 PTQ 时在 PTQ 分支按set_default_dtype方式处理。六、量化 wrapper 设计prefill-only 与 wo_a 单点例外quant_module.py里的四个 wrapper 全部遵循prefill-only约定forward内assert start_pos 0wrapper 不注册kv_cache / kv_state / score_statebuffer那些仍留在被 wrap 的上游模块实例上prefill 下不会被用到。cache_scheme()中kv_cache_scheme为 8-bit float、li_cache_scheme为 8-bit int/float 按quant_dtype切换deepseekv4.py#L279-L288。QuantV4Attention与wo_a单点例外QuantV4Attentionquant_module.py#L235-L447在attn-lineartarget 下量化wq_a / wq_b / wkv / wo_b四个常规 Linear全部走QuantLinear其中wq_a输出经q_norm后由wq_b展开为多头且做 RMS 归一化 RoPEQK / PV 两个稀疏 attention matmul 用QuantizedMatmul承载attn-cachetarget 的量化q/k/p/v cache bits 来自bit_policy.cache_bits见 L304-L317wo_a保留为原nn.Linear旁路挂一个WeightQuantizer在_wo_a_apply里手动跑observe_input weight_quantizer 重塑 einsum全流程L426-L435因为 grouped einsum 与QuantLinear.forward的F.linear调用方式不兼容。sparse_attn是上游Attention.sparse_attn的逐位拷贝纯计算、无状态内部用QuantizedMatmul替代原始torch.matmulL332-L359。QuantV4Compressor/QuantV4IndexerQuantV4Compressor量化wkv / wgate两个 Linearcomp_wkv / comp_wgatebits并复刻上游的 overlap 变换、gated pooling、RoPE 与可选的 Hadamard 旋转rotate逻辑L95-L161QuantV4Indexer量化wq_b / weights_projidx_wq_b / idx_weights_projbits并内嵌一个QuantV4Compressor作为其压缩 KV 打分路径L164-L232。两个 wrapper 在enable_attn_linear为假时退化回PlainLinearnn.Identity()保证关闭量化时浮点等价。QuantV4Expert复用QuantGatedMLP的 facade 技巧v4 的Expert是 SwiGLU FFNw1 / w2 / w3而框架QuantGatedMLP期望gate_proj / up_proj / down_proj / hidden_size / intermediate_size / act_fn。QuantV4Expert构造一个薄 facade 模块做名字别名facade.gate_proj expert.w1等再让父类以QuantLinear包装并重写forward实现 v4 的 clamp-then-silu 语义与可选路由权重quant_module.py#L52-L92。PTQ 单元枚举与部署绑定iter_ptq_units按 target 路由attn-linear / attn-cache时 yield 单个attn单元并直接返回moe时用iter_indexed_units对ffn.experts逐专家枚举并附带expert_idxmetadatadeepseekv4.py#L256-L273。build_quant_block同时拒绝quant_targetmlp——v4 是 MoE 模型L143-L153。七、官方 checkpoint 实际布局以事实为准案例文档给出一个关键认知architectures: [DeepseekV4ForCausalLM]这个名字虽符合 HF 约定但官方 checkpoint 的 state_dict 是扁平结构不是 HF 标准的model.X嵌套。修 modeling / load 路径前必须先拉model.safetensors.index.json看实际 key不要靠命名推断问题 3 正是因此翻车。核对后的事实顶层 6 个 keyembed.weight / head.weight / norm.weight / hc_head_fn / hc_head_scale / hc_head_base——没有model.前缀主 backbone 61 层layers.0..60.*按四类签名分布与 config 的num_hash_layers3和compress_ratios数组index 2/4/6/.../60 4严格对应层路由类型Compressor / Indexercompress_ratio0/1hash-routedffn.gate.tid2eidCompressor无 Indexer1282hash-routedffn.gate.tid2eidCompressor Indexer43,5,7,...,59score-routedffn.gate.biasCompressor无 Indexer—4,6,8,...,60score-routedffn.gate.biasCompressor Indexer4**MTP 模块mtp.{m}.***存在于 checkpoint 顶层结构类似 Block另有e_proj / h_proj / enorm / hnorm四个连接到主 backbone 的组件。当前 modeling不实例化 MTPadapter 的 load 路径按layers.N. / embed. / norm. / head.特定前缀取 key与mtp.*自然不相交strict load 也不会失败——主 backbone PTQ 走通之前不接命名验证attn不是self_attn、ffn不是mlp、ffn.experts.{e}显式逐 expert、ffn.shared_experts单数模块名全部与 modeling 对齐。八、典型问题复盘案例文档保留了 v4 完整 repro问题 0/1/2/3/5/6 已上抽为 L2/L1 通用条目此处保留作为该家族最详尽的参考#现象根因修法0block(layer_idx).to(device)报 “Cannot copy out of meta tensor”precompute_freqs_cis的lru_cache在 meta 上下文缓存了 meta 张量后续真 CPU 构造命中缓存empty_weights_model()收尾cache_clear()1空载 OOMregister_buffer实分配且include_buffersFalse只重定向 Parameterinit_empty_weights(include_buffersTrue)2dim是默认值 4096应 7168但不报错Config 只接收 ModelArgs 名HF 名走**kwargs只存为旁路属性同时声明两套命名并做翻译3按architectures推断 HF 嵌套结构HF 命名约定不保证 checkpoint 用嵌套结构v4 实际是扁平动 modeling 前先拉model.safetensors.index.json看真实 key5运行时 AttributeError翻译只做“输入归一化”没把 HF 名存回 selfConfig 末尾对每个 HF 名做对称镜像6cfg.dtype被覆盖成torch.bfloat16HF 的dtype是torch_dtype别名与 v4 的架构 quant 格式字段撞名重命名arch_dtypeHF 语义保留其中问题 2 的更深层教训是接 HF 系模型先抓官方config.json把字段一栏一栏对照ModelArgs/ 代码内 attr缺什么补什么问题 6 的机械规则是——写双向 Config 时先列出 modern HFPretrainedConfig已占用的 attribute slotdtype / torch_dtype / hidden_size / num_hidden_layers / num_attention_heads / max_position_embeddings / vocab_size / pad_token_id / bos_token_id / eos_token_id / use_cache / tie_word_embeddings / rope_scaling / quantization_config / ...自家字段若撞名优先在 Config 内部重命名不要靠“在 super 后再赋值”硬抢。九、量化进展与结论截至案例文档记录时点BF16 baseline 已出DeepSeek-V4-Pro ppl1.9946同一 modeling/Config 覆盖 V4-FlashDP-Flashppl4.1517——两变体结构同源、仅 config.json 不同共用本 adapter关闭量化后保持浮点等价未做当时权重未下载真权重现可加载具备验证条件最小 PTQ unit 闭环部分——在小 confign_layers2, dim128, n_routed_experts4上跑通空载 smokeBlock 构建meta CPU 都过→apply_quant_attn / apply_quant_moe_mlp→25 个 QuantLinear 19 个 ActivationQuantizer→iter_ptq_units(attn-linear)1 个 unit、iter_ptq_units(moe)4 个 unit →iter_deploy_bindings16 个 binding →expert.export_ptq_params()返回 3 keys真权重 GT 路径未跑过第一版直转量化方案暂未确定预计起点与 v3.2 类似attn-linear w8a8 / attn-cache q/k 16-bit / moe routed w8 shared w8直转结果与最终方案待权重验证后确定。量化状态的口径在 deepseek 系列总览 中有配套约定BF16 baseline 一般用 Wikitext PPL 的 blockwise 口径直转量化delta 0.2或做过一轮粗粒度误差定位后通常进入 PTQ。十、最终建议下次接入类似模型的 Checklist下次遇到类似模型MLA Compressor Indexer HC 自定义 forward 签名优先参考本案例 deepseek-v3.2MLA 部分 longcat_nextPreTrainedModel 化 AutoModel 注册。先做什么抓官方config.json做字段表对照HF 标准名 vs 模型代码 attr 名写双向 Config抓官方model.safetensors.index.json走 modelscope 镜像HF 直链有 LFS 重定向 WebFetch 10MB 限制都不稳解析顶层 key 代表层 key 不同签名的层——这一步比读上游源码更直接在小 confign_layers2, dim128, expert4上跑通“空载 smoke”——Block 构建 apply_quant_*iter_ptq_unitsexport_ptq_params所有 Linear / ActivationQuantizer 数对得上再去找权重上游 modeling 文件原样保留只改明显坏掉的 import。不建议一开始做什么一上来就裁上游 modeling 的 kv_cache / decode 分支——那是 wrapper 的事modeling 要做浮点对照基准直接复用同系列前一代的 quant 模块v3.2 → v4 直接抄QuantDSA这种——结构差异大语义错位会很隐蔽在框架级quant_apply.py改name in [...]列表去匹配新模型的命名——wrapper 在 adapter 里做单点替换 overrideiter_ptq_units更干净靠 HF 命名约定推断 checkpoint 嵌套结构——看architectures字段不能代替看model.safetensors.index.json的真实 key看到.scale配对就先实现 FP8 dequant 路径——先确认最终权重格式不要替用户做“以后可能要做”的事一上来就把 MTP / 额外 head 等非主 backbone 模块塞进 modeling——skill 阶段任务是主链跑通非主链结构在 load 路径里“自然不被请求”即可。相关仓库路径速查adapter 主体 deepseekv4.py、量化 wrapper quant_module.py、双向 Config configuration_deepseek_v4.py、上游风格 modeling modeling_deepseek_v4.py、注册入口init.py、框架基类 base.py、MoE 量化应用 quant_apply.py、PTQ 单元 ptq_units.py。【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
