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
52 changes: 52 additions & 0 deletions npu/pack_import.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -1904,6 +1904,7 @@ Q4nxContainer read_q4nx_container(const std::string& path) {
out.why = path + ": header is not a JSON object";
return out;
}
if (j.contains("__metadata__") && j["__metadata__"].is_object()) out.meta = j["__metadata__"];
for (auto it = j.begin(); it != j.end(); ++it) {
if (it.key() == "__metadata__") continue;
if (!it.value().is_object()) {
Expand Down Expand Up @@ -3313,6 +3314,57 @@ std::string header_witness_refusal(int vote_hdrs, bool declared_qk) {
"neither is being preferred";
}

// 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
// census measured 13 packs carrying `dims` and 29 of 29 carrying config.json, so a silent disagreement is possible and
// a reader has to be able to see which one answered.
ContainerGeometry container_geometry(const json& meta, const json& config) {
ContainerGeometry g;
const json& d = (meta.is_object() && meta.contains("dims") && meta["dims"].is_object()) ? meta["dims"] : json();
const json& cfg = config.is_object() ? config : json();
bool used_dims = false, used_cfg = false;

// an integer from dims first, then config.json; records which one answered
const auto iv = [&](const char* key, int& dst) -> bool {
if (d.is_object() && d.contains(key) && d[key].is_number_integer()) { dst = d[key].get<int>(); used_dims = true; return true; }
if (cfg.is_object() && cfg.contains(key) && cfg[key].is_number_integer()) { dst = cfg[key].get<int>(); used_cfg = true; return true; }
return false;
};
const auto fv = [&](const char* key, float& dst) -> bool {
if (d.is_object() && d.contains(key) && d[key].is_number()) { dst = d[key].get<float>(); used_dims = true; return true; }
if (cfg.is_object() && cfg.contains(key) && cfg[key].is_number()) { dst = cfg[key].get<float>(); used_cfg = true; return true; }
return false;
};
const auto sv = [&](const char* key, std::string& dst) -> bool {
if (d.is_object() && d.contains(key) && d[key].is_string()) { dst = d[key].get<std::string>(); used_dims = true; return true; }
if (cfg.is_object() && cfg.contains(key) && cfg[key].is_string()) { dst = cfg[key].get<std::string>(); used_cfg = true; return true; }
return false;
};

if (!iv("hidden_size", g.dims.hidden)) g.missing.push_back("hidden_size");
if (!iv("num_hidden_layers", g.dims.layers)) g.missing.push_back("num_hidden_layers");
if (!iv("num_attention_heads", g.dims.heads)) g.missing.push_back("num_attention_heads");
if (!iv("num_key_value_heads", g.dims.kv_heads)) g.missing.push_back("num_key_value_heads");
if (!iv("vocab_size", g.dims.vocab)) g.missing.push_back("vocab_size");
if (!iv("intermediate_size", g.dims.intermediate)) g.missing.push_back("intermediate_size");
if (!iv("head_dim", g.dims.head_dim)) {
// derived, and said to be derived: hidden/heads is only head_dim when the pack does not state one, and it is
// wrong for every architecture whose q projection is not square (GQA with an explicit head_dim is common).
if (g.dims.hidden > 0 && g.dims.heads > 0) {
g.dims.head_dim = g.dims.hidden / g.dims.heads;
g.inferred.push_back("head_dim");
} else {
g.missing.push_back("head_dim");
}
}
if (!fv("rope_theta", g.dims.rope_theta)) g.missing.push_back("rope_theta");
sv("model_type", g.dims.model_type); // not load-bearing for the arithmetic; absent is not missing

g.source = used_dims ? "dims" : (used_cfg ? "config.json" : "");
return g;
}

std::string qk_norm_refusal(bool declared, bool found) {
if (declared && !found)
return "this pack declares use_qk_norm and its per-head q/k gains are not where the block layout says "
Expand Down
20 changes: 20 additions & 0 deletions npu/pack_import.h
Original file line number Diff line number Diff line change
Expand Up @@ -289,10 +289,30 @@ struct Q4nxContainer {
int64_t header_bytes = 0;
int64_t payload_bytes = 0;
std::vector<Q4nxTensor> tensors; // in header order
// The safetensors `__metadata__` object, kept because it is where this genre states its own geometry (engine#1786).
// Three quarters of the packs measured on this box carry a `dims` block with hidden/intermediate/layers/heads/vocab;
// two carry no metadata at all (`d3-edge`, `d3-flash`), which is why the reader keeps it as data and does not
// interpret it here.
nlohmann::json meta;
std::string why; // non-empty when the container could not be read; tensors is then empty
};
Q4nxContainer read_q4nx_container(const std::string& path);

// engine#1786 (item F1): the container genre's geometry, from the two places a pack can state it, in order of
// authority -- the container's own `dims` block, then config.json. `source` names which one answered, so a plan can
// never present a declared number and a file's number as the same kind of fact; `missing` names the fields neither
// could fill, and `inferred` the ones derived from other fields (head_dim from hidden/heads).
//
// Pure: no file is opened, so the three genres the census measured -- 13 self-describing, 14 gguf-converted, 2 with
// no metadata at all -- can all be pinned without a pack, which is the point of extracting it from `plan()`.
struct ContainerGeometry {
Dims dims;
std::string source; // "dims", "config.json", or empty when neither answered
std::vector<std::string> missing; // fields no source could fill, by name
std::vector<std::string> inferred; // fields derived from another field, by name
};
ContainerGeometry container_geometry(const nlohmann::json& meta, const nlohmann::json& config);

// 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
61 changes: 61 additions & 0 deletions tests/npu_pack_import_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -4765,6 +4765,66 @@ void test_embedding_f32_component(const std::string& root) {
fs::remove_all(b);
}

// engine#1786 (item F1): the container genre's geometry, pinned as a pure function over the three header shapes the
// census measured on this box -- no pack, no device, no file, which is what makes the two genres with no config.json
// (`d3-edge`, `d3-flash`) pinnable at all.
void test_container_geometry() {
using nlohmann::json;
// 1. self-describing: `dims` answers everything, and config.json must NOT be preferred over it.
{
json meta = {{"dims", {{"hidden_size", 576}, {"intermediate_size", 1536}, {"num_hidden_layers", 30},
{"num_attention_heads", 9}, {"num_key_value_heads", 3}, {"vocab_size", 49152},
{"head_dim", 64}, {"rope_theta", 10000.0}, {"model_type", "llama"}}}};
json cfg = {{"hidden_size", 1024}}; // a deliberate disagreement: the container's own statement wins
const auto g = pi::container_geometry(meta, cfg);
check(g.source == "dims", "self-describing: source is dims");
check(g.dims.hidden == 576, "self-describing: hidden comes from dims, not config.json");
check(g.dims.layers == 30 && g.dims.heads == 9 && g.dims.kv_heads == 3 && g.dims.vocab == 49152,
"self-describing: every field dims states is taken");
check(g.dims.head_dim == 64, "self-describing: a stated head_dim is used as stated");
check(g.missing.empty(), "self-describing: nothing is missing");
check(g.inferred.empty(), "self-describing: nothing is inferred");
}
// 2. gguf-converted: no dims, so config.json answers and the source says so.
{
json meta = {{"converter", "tools/gguf_to_q4nx.py"}, {"format", "q4nx"}, {"source", "x.gguf"}};
json cfg = {{"hidden_size", 1024}, {"num_hidden_layers", 28}, {"num_attention_heads", 16},
{"num_key_value_heads", 8}, {"vocab_size", 151936}, {"intermediate_size", 3072},
{"head_dim", 64}, {"rope_theta", 1000000.0}};
const auto g = pi::container_geometry(meta, cfg);
check(g.source == "config.json", "gguf-converted: source is config.json");
check(g.dims.hidden == 1024 && g.dims.vocab == 151936, "gguf-converted: config.json supplies the geometry");
check(g.missing.empty(), "gguf-converted: nothing is missing when config.json is complete");
}
// 3. silent: neither answers, so every field is named missing rather than left as a zero that reads like a value.
{
const auto g = pi::container_geometry(json::object(), json());
check(g.source.empty(), "silent: no source is claimed");
// eight, and named: the first run of this arm asserted seven and failed in CI -- rope_theta is a required
// field of the arithmetic (it is the RoPE base the forward needs), so the count was wrong and the function
// was right. Asserted by name now, so the next field added to Dims fails this arm instead of shrinking it.
const std::vector<std::string> want = {"hidden_size", "num_hidden_layers", "num_attention_heads",
"num_key_value_heads", "vocab_size", "intermediate_size",
"head_dim", "rope_theta"};
check(g.missing.size() == want.size(), "silent: every required field is named missing");
bool all_named = true;
for (const auto& w : want)
all_named = all_named && std::find(g.missing.begin(), g.missing.end(), w) != g.missing.end();
check(all_named, "silent: the missing list names each required field");
check(g.dims.hidden == 0 && g.dims.layers == 0, "silent: no field is invented");
}
// 4. head_dim absent but derivable: reported as INFERRED, not as declared.
{
json meta = {{"dims", {{"hidden_size", 2048}, {"intermediate_size", 6144}, {"num_hidden_layers", 28},
{"num_attention_heads", 16}, {"num_key_value_heads", 8}, {"vocab_size", 151936},
{"rope_theta", 1000000.0}}}};
const auto g = pi::container_geometry(meta, json());
check(g.dims.head_dim == 128, "inferred: head_dim is hidden/heads");
check(g.inferred.size() == 1 && g.inferred[0] == "head_dim", "inferred: the inference is named");
check(g.missing.size() == 0, "inferred: an inferred field is not also missing");
}
}

// 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 @@ -5490,6 +5550,7 @@ int main(int argc, char** argv) {
test_attn_payload_off();
test_text_config_geometry(golden_dir.empty() ? "." : golden_dir);
test_q4nx_container(golden_dir.empty() ? "." : golden_dir);
test_container_geometry();
test_hybrid_pack_import(golden_dir.empty() ? "." : golden_dir);
test_rope_parameters_theta(golden_dir.empty() ? "." : golden_dir);
test_three_input_matmulnbits(golden_dir.empty() ? "." : golden_dir);
Expand Down
Loading