transformers - 💡(How to fix) Fix [deepseek_v4] conversion_mapping doesn't cover mtp.* paths — MTP keys silently random-init even after _keys_to_ignore is empty

# (assumes huggingface/transformers#46127 is applied — DeepseekV4NextNPredictor
#  exists, _keys_to_ignore_on_load_unexpected = [])
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("<DSv4-Flash BF16 with mtp.* keys>")

# Compare loaded vs source
import safetensors.torch as st
from pathlib import Path
loaded_w = model.model.mtp[0].self_attn.q_a_proj.weight
for shard in sorted(Path("<path>").glob("model-*.safetensors")):
    with st.safe_open(shard, framework="pt") as f:
        if "mtp.0.attn.wq_a.weight" in f.keys():
            source_w = f.get_tensor("mtp.0.attn.wq_a.weight")
            break

diff = (loaded_w.cpu().float() - source_w.cpu().float()).abs().max().item()
print(f"max_diff = {diff}")
# Without conversion mapping for mtp.*: diff ≈ random Gaussian range (e.g. 0.1+)
# With the mtp.* mapping extension: diff ≈ 0

---

^layers\.(\d+)\.attn_norm\.                      → layers.\1.input_layernorm.
^layers\.(\d+)\.ffn_norm\.                       → layers.\1.post_attention_layernorm.
^layers\.(\d+)\.hc_attn_fn$                       → layers.\1.attn_hc.fn
^layers\.(\d+)\.hc_attn_base$                     → layers.\1.attn_hc.base
^layers\.(\d+)\.hc_attn_scale$                    → layers.\1.attn_hc.scale
^layers\.(\d+)\.hc_ffn_fn$                        → layers.\1.ffn_hc.fn
^layers\.(\d+)\.hc_ffn_base$                      → layers.\1.ffn_hc.base
^layers\.(\d+)\.hc_ffn_scale$                     → layers.\1.ffn_hc.scale
^layers\.(\d+)\.attn\.                            → layers.\1.self_attn.
^layers\.(\d+)\.ffn\.                             → layers.\1.mlp.
^layers\.(\d+)\.self_attn\.attn_sink$             → layers.\1.self_attn.sinks
^layers\.(\d+)\.self_attn\.(.*?)\.wq_a\.          → layers.\1.self_attn.\2.q_a_proj.
^layers\.(\d+)\.self_attn\.(.*?)\.wq_b\.          → layers.\1.self_attn.\2.q_b_proj.
^layers\.(\d+)\.self_attn\.(.*?)\.wkv\.           → layers.\1.self_attn.\2.kv_proj.
^layers\.(\d+)\.self_attn\.(.*?)\.wgate\.         → layers.\1.self_attn.\2.gate_proj.
^layers\.(\d+)\.self_attn\.(.*?)\.wo_a\.          → layers.\1.self_attn.\2.o_a_proj.
^layers\.(\d+)\.self_attn\.(.*?)\.wo_b\.          → layers.\1.self_attn.\2.o_b_proj.
^layers\.(\d+)\.self_attn\.wq_a\.                 → layers.\1.self_attn.q_a_proj.
^layers\.(\d+)\.self_attn\.wq_b\.                 → layers.\1.self_attn.q_b_proj.
^layers\.(\d+)\.self_attn\.wkv\.                  → layers.\1.self_attn.kv_proj.
^layers\.(\d+)\.self_attn\.wo_a\.                 → layers.\1.self_attn.o_a_proj.
^layers\.(\d+)\.self_attn\.wo_b\.                 → layers.\1.self_attn.o_b_proj.
^layers\.(\d+)\.self_attn\.q_norm\.               → layers.\1.self_attn.q_a_norm.
^layers\.(\d+)\.mlp\.gate\.bias$                  → layers.\1.mlp.gate.e_score_correction_bias
^layers\.(\d+)\.mlp\.shared_experts\.w1\.         → layers.\1.mlp.shared_experts.gate_proj.
^layers\.(\d+)\.mlp\.shared_experts\.w2\.         → layers.\1.mlp.shared_experts.down_proj.
^layers\.(\d+)\.mlp\.shared_experts\.w3\.         → layers.\1.mlp.shared_experts.up_proj.

---

from transformers.conversion_mapping import (
    get_checkpoint_conversion_mapping,
    register_checkpoint_conversion_mapping,
)
existing = get_checkpoint_conversion_mapping("deepseek_v4")
added = []
for entry in existing:
    sp = getattr(entry, "source_patterns", None)
    tp = getattr(entry, "target_patterns", None)
    if sp is None or tp is None:
        continue
    sp_list = sp if isinstance(sp, (list, tuple)) else [sp]
    tp_list = tp if isinstance(tp, (list, tuple)) else [tp]
    new_sp, new_tp = [], []
    for s, t in zip(sp_list, tp_list):
        if isinstance(s, str) and s.startswith(r"^layers\.(\d+)\."):
            new_sp.append(s.replace(r"^layers\.(\d+)\.", r"^mtp\.(\d+)\.", 1))
            new_tp.append(t.replace("layers.\\1.", "mtp.\\1.", 1))
    if new_sp:
        added.append(type(entry)(
            source_patterns=new_sp if len(new_sp) > 1 else new_sp[0],
            target_patterns=new_tp if len(new_tp) > 1 else new_tp[0],
        ))
register_checkpoint_conversion_mapping(
    "deepseek_v4", list(existing) + added, overwrite=True)

---

import safetensors.torch as st
from pathlib import Path

loaded_w = model.model.mtp[0].self_attn.q_a_proj.weight
source_w = None
for shard in sorted(Path(model_path).glob("model-*.safetensors")):
    with st.safe_open(shard, framework="pt") as f:
        if "mtp.0.attn.wq_a.weight" in f.keys():
            source_w = f.get_tensor("mtp.0.attn.wq_a.weight")
            break
assert source_w is not None
diff = (loaded_w.cpu().float() - source_w.cpu().float()).abs().max().item()
assert diff < 1e-4, f"MTP weight mismatch: {diff} (silent random-init?)"