Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions npu/pack_import.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<Q4nxTensor>& 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
Expand Down
18 changes: 18 additions & 0 deletions npu/pack_import.h
Original file line number Diff line number Diff line change
Expand Up @@ -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<std::string, std::string> role_of; // tensor name -> role
std::vector<std::string> unassigned; // names no role matched, in header order
std::map<std::string, int> counts; // role -> number of tensors
};
ContainerRoles container_roles(const std::vector<Q4nxTensor>& 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);
Expand Down
79 changes: 79 additions & 0 deletions tests/npu_pack_import_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<const char*> names) {
std::vector<pi::Q4nxTensor> 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
Expand Down Expand Up @@ -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);
Expand Down
Loading