diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index d1e844bc7..c8daf215e 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -3312,6 +3312,76 @@ std::string header_witness_refusal(int vote_hdrs, bool declared_qk) { "neither is being preferred"; } +// engine#1786 (item F1), slice 3a: roles from names. The rule is ordered -- the first match wins -- so `q_proj.bias` +// classifies as a bias of q_proj rather than as an unknown tensor, and a name that matches nothing lands in `unassigned` +// with its own name rather than being guessed from its shape. +ContainerRoles container_roles(const std::vector& tensors) { + struct Rule { const char* role; const char* needle; }; + // Longest/most specific spellings first: `qkv_proj` before `q_proj`, `gate_up_proj` before `gate_proj`. + static const Rule kRules[] = { + {"embed", "embed_tokens"}, {"embed", "tok_embeddings"}, {"embed", "word_embeddings"}, + {"lm_head", "lm_head"}, {"lm_head", "output.weight"}, + // engine#2097 review: `in_proj` alone is not attention -- LFM2's `shortconv.in_proj` is the short-convolution + // input projection and was counted as `qkv_proj` on a real pack. It has its own field in model.h + // (`shortconv_in_proj_weight`), so it gets its own role; the attention needle now requires `attn`. + {"shortconv_in_proj", "shortconv.in_proj"}, + {"qkv_proj", "qkv_proj"}, {"qkv_proj", "attn_qkv"}, {"qkv_proj", "attn.in_proj"}, + {"gate_up_proj", "gate_up_proj"}, {"gate_up_proj", "ffn_gate_up"}, + // engine#2097 review: `attn_q` is a PREFIX of `attn_q_norm`, so with the projection rules first the two + // `*_norm` needles could never fire and every `attn_q_norm` was filed as `q_proj`. Norms come first. + {"q_norm", "q_norm"}, {"q_norm", "attn_q_norm"}, + {"k_norm", "k_norm"}, {"k_norm", "attn_k_norm"}, + {"q_proj", "q_proj"}, {"q_proj", "attn_q"}, {"q_proj", "wq."}, + {"k_proj", "k_proj"}, {"k_proj", "attn_k"}, {"k_proj", "wk."}, + {"v_proj", "v_proj"}, {"v_proj", "attn_v"}, {"v_proj", "wv."}, + {"o_proj", "o_proj"}, {"o_proj", "attn_output"}, {"o_proj", "wo."}, + {"gate_proj", "gate_proj"}, {"gate_proj", "ffn_gate"}, + {"up_proj", "up_proj"}, {"up_proj", "ffn_up"}, + {"down_proj", "down_proj"}, {"down_proj", "ffn_down"}, + {"input_norm", "input_layernorm"},{"input_norm", "attn_norm"}, {"input_norm", "attention_norm"}, + {"post_norm", "post_attention_layernorm"}, {"post_norm", "ffn_norm"}, + {"final_norm", "final_layernorm"}, + }; + // Recognised but not transformer roles: kept out of `unassigned` so that list means "nothing knows this", which is + // the only list worth reading. The SSM block is a forward question (its projections have no transformer analogue), + // and `model.mtp.*` is a draft head rather than a model. + static const char* kSsm[] = {"linear_attn.", "ssm_alpha_proj", "ssm_beta_proj", "ssm_conv1d", "ssm_dt", + "ssm_norm", "ssm_out_proj"}; + static const char* kMtp[] = {"model.mtp."}; + ContainerRoles out; + for (const auto& t : tensors) { + const std::string& n = t.name; + std::string role; + if (n.find("visual.") != std::string::npos || n.rfind("vision", 0) == 0 || n.rfind("vpm", 0) == 0) + role = "vision"; + else if (n.find("audio.") != std::string::npos) + role = "audio"; + if (role.empty()) { + bool matched = false; + for (const auto& r : kRules) { + if (n.find(r.needle) == std::string::npos) continue; + role = r.role; + matched = true; + break; + } + if (!matched && n.find("norm.weight") != std::string::npos && n.find("layers.") == std::string::npos) + role = "final_norm"; // `model.norm.weight`: the top-level norm, never inside a layer + if (!matched && role.empty()) { + for (const char* s : kSsm) + if (n.find(s) != std::string::npos) { role = "ssm"; matched = true; break; } + } + if (!matched && role.empty()) { + for (const char* s : kMtp) + if (n.find(s) != std::string::npos) { role = "mtp"; matched = true; break; } + } + } + if (role.empty()) { out.unassigned.push_back(n); continue; } + out.role_of[n] = role; + out.counts[role]++; + } + return out; +} + // engine#1786 (item F1): the container genre's geometry, from the container's own `dims` block and then config.json. // The order is authority, not preference: `dims` is the pack's own statement about itself, config.json is a file beside // it that a vendor converter wrote. When the two disagree the container's statement wins and `source` says so -- the diff --git a/npu/pack_import.h b/npu/pack_import.h index 513025dbf..fe1e1982f 100644 --- a/npu/pack_import.h +++ b/npu/pack_import.h @@ -319,6 +319,24 @@ struct ContainerGeometry { }; ContainerGeometry container_geometry(const nlohmann::json& meta, const nlohmann::json& config); +// engine#1786 (item F1), slice 3a: a container's ROLES, from tensor names alone -- the question a plan must answer +// before it can map a tensor to a projection. +// +// Measured on this box (engine#1786 comment of 2026-11-11, headers only, 30 packs): **21 of 30 classify fully by name +// alone**, and the entire residue is two families -- `model.layers.N.linear_attn.ssm_*` (the SSM-hybrid attention) and +// `model.mtp.*` (MTP draft heads, which are not models). Both HF and the alternate spellings resolve (`q_proj` and +// `attn_q`/`wq`), and so do the biases. So the rule below is a RULE, not a per-pack table -- which is why it is worth +// having before the SSM forward exists. +// +// What a role does NOT establish: the byte layout of the tensor, or whether it is stored transposed. A name says which +// projection; `graph_weights` (present on 13 of the packs) and the pack's own `dims` are what check the rest. +struct ContainerRoles { + std::map role_of; // tensor name -> role + std::vector unassigned; // names no role matched, in header order + std::map counts; // role -> number of tensors +}; +ContainerRoles container_roles(const std::vector& tensors); + // Reads the pack (model.onnx, its external data, both .fconst headers, config.json). // Throws only when the pack is structurally unreadable. Plan plan(const std::string& pack_dir); diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index 57e3e8862..2d57e3ceb 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -4990,6 +4990,84 @@ void test_container_plan(const std::string& root) { } } +// engine#1786 (item F1), slice 3a: roles from names alone. The cases are the three the census measured -- a transformer +// pack that classifies completely, the alternate spellings that must classify the same way, and the two residues (SSM +// and MTP) which must be RECOGNISED rather than reported as unknown, since `unassigned` is only useful if it means +// "nothing knows this". +void test_container_roles() { + const auto t = [](const std::string& n) { pi::Q4nxTensor x; x.name = n; x.dtype = "I8"; return x; }; + const auto roles = [&](std::initializer_list names) { + std::vector v; + for (const char* n : names) v.push_back(t(n)); + return pi::container_roles(v); + }; + + // 1. a transformer pack, HF spelling + { + const auto r = roles({"model.embed_tokens.weight", "model.layers.0.self_attn.q_proj.weight", + "model.layers.0.self_attn.k_proj.weight", "model.layers.0.self_attn.v_proj.weight", + "model.layers.0.self_attn.o_proj.weight", "model.layers.0.mlp.gate_proj.weight", + "model.layers.0.mlp.up_proj.weight", "model.layers.0.mlp.down_proj.weight", + "model.layers.0.input_layernorm.weight", "model.layers.0.post_attention_layernorm.weight", + "model.norm.weight", "lm_head.weight"}); + check(r.unassigned.empty(), "roles: a transformer pack classifies completely"); + check(r.counts.at("q_proj") == 1 && r.counts.at("down_proj") == 1, "roles: projections are named by role"); + check(r.role_of.at("model.norm.weight") == "final_norm", "roles: the top-level norm is not a layer norm"); + check(r.role_of.at("model.layers.0.input_layernorm.weight") == "input_norm", + "roles: a layer norm is the input norm, not the final one"); + } + // 1b. engine#2097 review: the two cases the table got wrong, pinned so the order cannot regress. + // `attn_q` / `attn_k` are prefixes of `attn_q_norm` / `attn_k_norm`, so with the projection rules first both + // norm needles were dead and a per-head q/k norm was filed as a projection. + { + const auto r = roles({"blk.0.attn_q_norm.weight", "blk.0.attn_k_norm.weight", + "blk.0.attn_q.weight", "blk.0.attn_k.weight"}); + check(r.role_of.at("blk.0.attn_q_norm.weight") == "q_norm", "roles: attn_q_norm is a norm, not q_proj"); + check(r.role_of.at("blk.0.attn_k_norm.weight") == "k_norm", "roles: attn_k_norm is a norm, not k_proj"); + check(r.role_of.at("blk.0.attn_q.weight") == "q_proj" && r.role_of.at("blk.0.attn_k.weight") == "k_proj", + "roles: the un-suffixed spellings are still projections"); + } + // 1c. `in_proj` is not unique to attention: LFM2's short-convolution input projection was counted as qkv_proj. + { + const auto r = roles({"model.layers.0.shortconv.in_proj.weight", "model.layers.0.attn.in_proj.weight"}); + check(r.role_of.at("model.layers.0.shortconv.in_proj.weight") == "shortconv_in_proj", + "roles: shortconv.in_proj is the short-conv projection, not the attention qkv"); + check(r.role_of.at("model.layers.0.attn.in_proj.weight") == "qkv_proj", + "roles: an attention in_proj is still the fused qkv"); + } + // 2. the alternate spellings must land on the same roles + { + const auto r = roles({"model.layers.0.self_attn.attn_q.weight", "model.layers.0.self_attn.wq.weight", + "model.layers.0.mlp.ffn_gate.weight", "model.layers.0.mlp.ffn_down.weight"}); + check(r.unassigned.empty(), "roles: alternate spellings classify"); + check(r.role_of.at("model.layers.0.self_attn.attn_q.weight") == "q_proj", "roles: attn_q is q_proj"); + check(r.role_of.at("model.layers.0.self_attn.wq.weight") == "q_proj", "roles: wq is q_proj"); + check(r.role_of.at("model.layers.0.mlp.ffn_gate.weight") == "gate_proj", "roles: ffn_gate is gate_proj"); + } + // 3. a bias belongs to its projection's role, and a qkv projection is not a q projection + { + const auto r = roles({"model.layers.0.self_attn.q_proj.bias", "model.layers.0.self_attn.qkv_proj.weight"}); + check(r.role_of.at("model.layers.0.self_attn.q_proj.bias") == "q_proj", "roles: a bias keeps its projection's role"); + check(r.role_of.at("model.layers.0.self_attn.qkv_proj.weight") == "qkv_proj", + "roles: qkv_proj is not classified as q_proj"); + } + // 4. the two measured residues are recognised, not unknown + { + const auto r = roles({"model.layers.0.linear_attn.ssm_alpha_proj.weight", + "model.layers.0.linear_attn.ssm_conv1d.weight", "model.mtp.fc.weight", + "model.mtp.pre_fc_norm_hidden.weight"}); + check(r.unassigned.empty(), "roles: the SSM and MTP families are recognised, not unassigned"); + check(r.counts.at("ssm") == 2 && r.counts.at("mtp") == 2, "roles: each residue is counted under its own family"); + } + // 5. something nothing knows is named, not guessed + { + const auto r = roles({"model.layers.0.mystery_block.weight"}); + check(r.unassigned.size() == 1, "roles: an unknown tensor is listed"); + check(r.unassigned[0] == "model.layers.0.mystery_block.weight", "roles: it is named, not summarised"); + check(r.counts.empty(), "roles: and no role is invented for it"); + } +} + // engine#1786 (item F1): an NPU2 model source is a safetensors container, and this is the reader that decides whether // a pack is that genre. The failure that matters is the silent one -- a wrong header length yields an empty inventory, // which reads as "a pack with no tensors" rather than "a malformed header" -- so each arm asserts the reason, not just @@ -5717,6 +5795,7 @@ int main(int argc, char** argv) { test_text_config_geometry(golden_dir.empty() ? "." : golden_dir); test_q4nx_container(golden_dir.empty() ? "." : golden_dir); test_container_geometry(); + test_container_roles(); test_container_plan(golden_dir.empty() ? "." : golden_dir); test_hybrid_pack_import(golden_dir.empty() ? "." : golden_dir); test_rope_parameters_theta(golden_dir.empty() ? "." : golden_dir);