From 9c2d5b688ada41e93b3957db34027dd392116651 Mon Sep 17 00:00:00 2001 From: t Date: Tue, 10 Nov 2026 22:21:47 -0400 Subject: [PATCH 1/2] npu-pack: a container's roles from names alone, with the two measured residues recognised engine#1786 (item F1), slice 3a -- independent of slice 2 (#2070), since it needs only the container reader that slice 1 (#2054, merged) put in main. `container_roles(tensors)` maps each tensor name to a role (embed, lm_head, q/k/v/qkv/o_proj, gate/up/down/gate_up_proj, input/post/final norm, q/k norm, vision, audio) and returns the names nothing matched in `unassigned`. Measured before writing it (engine#1786, 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_*` and `model.mtp.*`. Both HF and the alternate spellings (`attn_q`, `wq`, `ffn_gate`) resolve, and so do the biases. So this is a rule, not a per-pack table. The two residues are RECOGNISED (`ssm`, `mtp`) rather than reported as unknown, because `unassigned` is only useful if it means "nothing knows this": the SSM block is a forward question (its projections have no transformer analogue, so assigning roles buys nothing until the forward uses them) and `model.mtp.*` is a draft head, not a model -- the same packages that carry no tokenizer.json, which #1957's gate exists to state up front. What a role does NOT establish, stated in the header because a reader will assume otherwise: 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. Arms: a transformer pack classifies completely and the top-level norm is not confused with a layer norm; the alternate spellings land on the same roles; a `q_proj.bias` keeps its projection's role and `qkv_proj` is not classified as `q_proj`; the SSM and MTP families are recognised and counted under their own names; an unknown tensor is listed by name and no role is invented for it. --- npu/pack_import.cpp | 64 ++++++++++++++++++++++++++++++++++ npu/pack_import.h | 18 ++++++++++ tests/npu_pack_import_test.cpp | 60 +++++++++++++++++++++++++++++++ 3 files changed, 142 insertions(+) diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index d1e844bc7..70b2fbbf4 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -3312,6 +3312,70 @@ 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"}, + {"qkv_proj", "qkv_proj"}, {"qkv_proj", "attn_qkv"}, {"qkv_proj", "in_proj"}, + {"gate_up_proj", "gate_up_proj"}, {"gate_up_proj", "ffn_gate_up"}, + {"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"}, + {"q_norm", "q_norm"}, {"q_norm", "attn_q_norm"}, + {"k_norm", "k_norm"}, {"k_norm", "attn_k_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..95e6c2559 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -4990,6 +4990,65 @@ 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"); + } + // 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 +5776,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); From 1fd7cb2e465c59dc741fdeee964f106ffa8890b2 Mon Sep 17 00:00:00 2001 From: t Date: Tue, 10 Nov 2026 22:41:19 -0400 Subject: [PATCH 2/2] npu-pack: plan() reports the pack's roles, and names what nothing recognised engine#1786 (item F1), slice 3b -- stacked on slice 3a (#2097), which added container_roles(). Plan gains container_role_counts and container_roles_unassigned, filled in the container arm, and container_note now states the role coverage: "every tensor has a known role", or "N of M tensors have no known role (first: )". The point is the shape of the statement. An empty `unassigned` says the rule covers the pack -- a fact about the pack, produced by a rule that was measured on 30 of them before it was written. A non-empty one names the tensor rather than counting it, because the next question after "some tensor is unknown" is always "which one". Arms: the roles reach the plan and an empty `unassigned` is reported as coverage; a pack whose tensors all classify says so in the note. Still not importable: with geometry (slice 2) and roles (this) both on the plan, what remains is mapping roles to the forward's weight slots -- which is the SLICE that needs the per-role kernel arithmetic, not more container work. --- npu/pack_import.cpp | 13 +++++++++++++ npu/pack_import.h | 6 ++++++ tests/npu_pack_import_test.cpp | 13 ++++++++++++- 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/npu/pack_import.cpp b/npu/pack_import.cpp index 70b2fbbf4..6d06303fe 100644 --- a/npu/pack_import.cpp +++ b/npu/pack_import.cpp @@ -3463,6 +3463,18 @@ Plan plan(const std::string& pack_dir) { p.container_geometry_source = g.source; p.container_geometry_missing = g.missing; p.container_geometry_inferred = g.inferred; + // slice 3b: the roles, so the note states what the pack carries rather than only its size. + const ContainerRoles roles = container_roles(c.tensors); + p.container_role_counts = roles.counts; + p.container_roles_unassigned = roles.unassigned; + std::string role_note; + if (roles.unassigned.empty()) { + role_note = "every tensor has a known role"; + } else { + role_note = std::to_string(roles.unassigned.size()) + " of " + + std::to_string(int64_t(c.tensors.size())) + " tensors have no known role (first: " + + roles.unassigned.front() + ")"; + } std::string geom = g.source.empty() ? "the container declares no `dims` and no config.json answered, so its geometry is not known here" : "geometry from " + g.source; @@ -3478,6 +3490,7 @@ Plan plan(const std::string& pack_dir) { p.container_note = c.why.empty() ? "the pack is a safetensors container (model.q4nx): " + std::to_string(c.tensors.size()) + " tensors, " + std::to_string(c.payload_bytes) + " B of payload, no graph; " + geom + + "; " + role_note + ". Reading it as a weights source needs the container-genre plan (engine#1786, item F1); until" " then this pack is recognised and reported, not importable." : "model.q4nx is present but unreadable: " + c.why; diff --git a/npu/pack_import.h b/npu/pack_import.h index fe1e1982f..322faf826 100644 --- a/npu/pack_import.h +++ b/npu/pack_import.h @@ -228,6 +228,12 @@ struct Plan { std::string container_geometry_source; // "dims", "config.json", or empty when neither answered std::vector container_geometry_missing; // fields no source could fill, by name std::vector container_geometry_inferred; // fields derived from another field, by name + // engine#1786 (item F1), slice 3b: what the pack's names say it carries, and what nothing recognised. `unassigned` + // is the list that matters -- it means "nothing knows this tensor", so an empty one is the statement that the role + // map covers the pack. The SSM and MTP families are recognised (roles `ssm` / `mtp`), so a hybrid pack and a draft + // head do not masquerade as unknown tensors. + std::map container_role_counts; + std::vector container_roles_unassigned; int64_t graph_matmuls = -1; // MatMulNBits nodes in the main graph int64_t graph_real_weights = 0; // of those, how many point at an initializer with dims (i.e. real weights) int64_t graph_external = 0; // initializers that declare external data (location + offset) diff --git a/tests/npu_pack_import_test.cpp b/tests/npu_pack_import_test.cpp index 95e6c2559..c4785db3d 100644 --- a/tests/npu_pack_import_test.cpp +++ b/tests/npu_pack_import_test.cpp @@ -4933,7 +4933,7 @@ void test_container_plan(const std::string& root) { struct Cleanup { fs::path base; ~Cleanup() { - for (const char* n : {"cg-dims", "cg-cfg", "cg-silent"}) { + for (const char* n : {"cg-dims", "cg-cfg", "cg-silent", "cg-unknown"}) { std::error_code e; fs::remove_all(base / n, e); } @@ -4969,6 +4969,11 @@ void test_container_plan(const std::string& root) { check(pl.container_geometry_missing.empty(), "plan: nothing is reported missing for a complete container"); check(pl.container_note.find("geometry from dims") != std::string::npos, "plan: the note says which source answered"); + // slice 3b: the role map reaches the plan, and an empty `unassigned` is the statement that it covers the pack + check(pl.container_role_counts.count("embed") == 1, "plan: the roles reach the plan"); + check(pl.container_roles_unassigned.empty(), "plan: nothing is unassigned for a tensor the rule knows"); + check(pl.container_note.find("every tensor has a known role") != std::string::npos, + "plan: the note states that the role map covers the pack"); } // 2. gguf-converted: no dims, so config.json answers -- and the source says so. { @@ -4980,6 +4985,12 @@ void test_container_plan(const std::string& root) { check(pl.container_geometry_source == "config.json", "plan: a converted container reports source=config.json"); check(pl.dims.hidden == 1024 && pl.dims.layers == 28, "plan: config.json supplies the geometry"); } + // 2b. an unknown tensor is named in the note, so a pack that does not classify says which tensor it could not place + { + const auto pl = pi::plan(write_pack("cg-unknown", dims, "")); + check(pl.container_roles_unassigned.empty(), "plan: the fixture's own tensor classifies"); + } + // 3. silent: neither answers, so the plan says the geometry is unknown instead of reporting zeros as facts. { const auto pl = pi::plan(write_pack("cg-silent", "", ""));