Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C

fix(doctor): require core tensor ROLES, not GLM-5.2's names (#1365)

JustVugge223fd991ecb
diff --git a/c/doctor.py b/c/doctor.py
index 3bdc8c82..59f41b7c 100644
--- a/c/doctor.py
+++ b/c/doctor.py
@@ -32,13 +32,68 @@ SAFETENSORS_DTYPES = {
"F8_E8M0": 1,
"F8_E8M0FNU": 1,
}
-REQUIRED_CORE_TENSORS = (
- "model.embed_tokens.weight",
- "model.norm.weight",
- "lm_head.weight",
+def _is_embedding(name):
+ return name.endswith("embed_tokens.weight")
+
+
+def _is_final_norm(name):
+ # Every block has norms too. The final one is the norm that sits OUTSIDE
+ # the layer stack, so exclude anything under `.layers.`, and exclude
+ # `layernorm` outright: GLM-5.3-Flash's vision tower has
+ # `model.visual.post_layernorm.weight`, which would otherwise stand in for
+ # a final norm that is not there.
+ return (name.endswith(".norm.weight")
+ and ".layers." not in name
+ and "layernorm" not in name)
+
+
+def _is_output_head(name):
+ return name.endswith("lm_head.weight")
+
+
+#: What a checkpoint must contain to be a language model at all, stated as
+#: ROLES rather than names.
+#:
+#: #1365: the previous form was three literal names taken from GLM-5.2, and it
+#: reported "2 required core tensor(s) are missing" for every GLM-5.3-Flash
+#: download, converted or pre-converted. Nothing was missing. Flash's root is
+#: the vision wrapper, so the language model is nested and the tensors are
+#: `model.language_model.embed_tokens.weight` and
+#: `model.language_model.norm.weight`. Two of three names did not match, and
+#: the doctor called a healthy model broken.
+#:
+#: Matching on the tail rather than the whole name is what makes this hold for
+#: families nobody has written yet: it is prefix-agnostic, which is exactly
+#: what the engines already are. `qwen38.c` probes
+#: `model.language_model.embed_tokens.weight` and falls back to
+#: `model.embed_tokens.weight`; every engine discovers its prefix at load time.
+#: The doctor was the one place that assumed the prefix was a constant.
+CORE_TENSOR_ROLES = (
+ ("token embedding", _is_embedding),
+ ("final norm", _is_final_norm),
+ ("output head", _is_output_head),
)
+def missing_core_roles(tensor_names, config=None):
+ """Which core roles no tensor fills. Empty means the model is complete.
+
+ `tie_word_embeddings` makes the output head legitimately absent: the
+ embedding matrix is reused as the head, and there is no `lm_head.weight`
+ to find. Requiring one anyway would trade this bug for the same bug on a
+ different checkpoint.
+ """
+ tied = bool((config or {}).get("tie_word_embeddings"))
+ missing = []
+ for role, matches in CORE_TENSOR_ROLES:
+ if any(matches(name) for name in tensor_names):
+ continue
+ if role == "output head" and tied:
+ continue
+ missing.append(role)
+ return missing
+
+
def _check(identifier, status, summary, **details):
item = {"id": identifier, "status": status, "summary": summary}
if details:
@@ -281,16 +336,28 @@ def deep_container_report(model, mirror_dir=None):
except (OSError, UnicodeDecodeError, json.JSONDecodeError, ValueError) as error:
index = {"status": "fail", "summary": f"model index is invalid: {error}"}
- missing_core = [name for name in REQUIRED_CORE_TENSORS if name not in tensor_sources]
+ # Read here rather than take it as an argument: the signature is used by
+ # callers and tests, and the only thing needed is one optional flag.
+ core_config = {}
+ try:
+ with (model / "config.json").open("rb") as stream:
+ loaded = json.loads(stream.read(MODEL_INDEX_MAX_BYTES))
+ if isinstance(loaded, dict):
+ core_config = loaded
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError, ValueError):
+ pass # no config is already its own failed check
+ missing_core = missing_core_roles(tensor_sources, core_config)
required = {
"status": "fail" if missing_core else "pass",
"summary": (
- f"{len(missing_core)} required core tensor(s) are missing"
+ # Name the roles, not a count. "2 required core tensor(s) are
+ # missing" sent someone to re-download 195 GB twice before asking.
+ "no tensor fills these core roles: " + ", ".join(missing_core)
if missing_core else "required core tensors are present"
),
"details": {
- "required_tensors": len(REQUIRED_CORE_TENSORS),
- "missing_tensors": missing_core,
+ "required_roles": [role for role, _ in CORE_TENSOR_ROLES],
+ "missing_roles": missing_core,
},
}
diff --git a/c/tests/test_doctor.py b/c/tests/test_doctor.py
index c1ce4273..3b309aeb 100644
--- a/c/tests/test_doctor.py
+++ b/c/tests/test_doctor.py
@@ -10,6 +10,8 @@ from unittest import mock
from doctor import (
_tensor_layout,
+ deep_container_report,
+ missing_core_roles,
cuda_linkage,
exit_code,
format_doctor,
@@ -434,9 +436,12 @@ class DoctorTest(unittest.TestCase):
self.assertEqual(checks["model.container"]["status"], "pass")
self.assertEqual(checks["model.required"]["status"], "fail")
- self.assertEqual(checks["model.required"]["details"]["missing_tensors"], [
- "model.norm.weight",
- "lm_head.weight",
+ # Roles, not names (#1365). The shard above holds only an embedding,
+ # so what is genuinely absent is a final norm and an output head --
+ # true whatever prefix the family puts in front of them.
+ self.assertEqual(checks["model.required"]["details"]["missing_roles"], [
+ "final norm",
+ "output head",
])
def test_deep_check_reports_runtime_equivalent_partial_mirror(self):
@@ -517,5 +522,109 @@ class DoctorTest(unittest.TestCase):
self.assertIn("model.container", checks)
+class CoreTensorRoleTest(unittest.TestCase):
+ """#1365: `coli doctor` reported "2 required core tensor(s) are missing"
+ for every GLM-5.3-Flash checkpoint, converted locally or downloaded
+ pre-converted. Nothing was missing. The check held three literal tensor
+ names taken from GLM-5.2, and Flash nests its language model under the
+ vision wrapper, so two of the three names did not match a healthy model.
+
+ The reporter tried both sources before asking, which is the cost of a
+ check that says a number instead of what it looked for."""
+
+ FLASH = [
+ "model.language_model.embed_tokens.weight",
+ "model.language_model.norm.weight",
+ "lm_head.weight",
+ "model.visual.post_layernorm.weight",
+ "model.language_model.layers.0.input_layernorm.weight",
+ "model.language_model.layers.0.shared_head.norm.weight",
+ ]
+ FLAT = [
+ "model.embed_tokens.weight",
+ "model.norm.weight",
+ "lm_head.weight",
+ "model.layers.0.input_layernorm.weight",
+ ]
+
+ def test_the_nested_layout_that_started_this_is_complete(self):
+ self.assertEqual(missing_core_roles(self.FLASH), [])
+
+ def test_the_flat_layout_is_still_complete(self):
+ self.assertEqual(missing_core_roles(self.FLAT), [])
+
+ def test_a_prefix_nobody_has_written_yet_also_works(self):
+ """The property that makes this hold for future families is that the
+ rule is prefix-agnostic, so assert the property rather than a list of
+ the prefixes we happen to know today. Every engine already discovers
+ its prefix at load time; qwen38.c probes the nested name and falls
+ back to the flat one. Only the doctor assumed a constant."""
+ invented = [
+ "backbone.text_tower.v2.embed_tokens.weight",
+ "backbone.text_tower.v2.norm.weight",
+ "backbone.lm_head.weight",
+ ]
+ self.assertEqual(missing_core_roles(invented), [])
+
+ def test_a_truncated_download_still_fails(self):
+ # The check must keep doing its job: this is the same nested model
+ # with the embedding shard absent.
+ truncated = [n for n in self.FLASH if "embed_tokens" not in n]
+ self.assertEqual(missing_core_roles(truncated), ["token embedding"])
+
+ def test_a_block_norm_does_not_stand_in_for_the_final_norm(self):
+ only_block_norms = [
+ "model.embed_tokens.weight",
+ "model.layers.0.shared_head.norm.weight",
+ "lm_head.weight",
+ ]
+ self.assertEqual(missing_core_roles(only_block_norms), ["final norm"])
+
+ def test_a_vision_tower_layernorm_does_not_either(self):
+ """`model.visual.post_layernorm.weight` ends in "norm.weight" and sits
+ outside the layer stack, so a tail match alone would accept it as the
+ language model's final norm and pass a checkpoint that is missing one."""
+ vision_only = [
+ "model.language_model.embed_tokens.weight",
+ "model.visual.post_layernorm.weight",
+ "lm_head.weight",
+ ]
+ self.assertEqual(missing_core_roles(vision_only), ["final norm"])
+
+ def test_tied_embeddings_need_no_output_head(self):
+ tied = [
+ "model.embed_tokens.weight",
+ "model.norm.weight",
+ ]
+ self.assertEqual(missing_core_roles(tied, {"tie_word_embeddings": True}), [])
+ self.assertEqual(missing_core_roles(tied, {"tie_word_embeddings": False}),
+ ["output head"])
+ self.assertEqual(missing_core_roles(tied, None), ["output head"])
+
+ def test_the_report_names_the_roles_it_could_not_fill(self):
+ """A count sends someone to re-download. A name sends them to the
+ right question."""
+ model = Path(self.tmp.name) / "nested"
+ model.mkdir()
+ (model / "config.json").write_text(json.dumps({"model_type": "glm5_next"}))
+ write_shard(model / "model.safetensors",
+ [(name, 8) for name in self.FLASH])
+ report = deep_container_report(model)
+ required = next(c for c in report if c["id"] == "model.required") \
+ if isinstance(report, list) else report["required"]
+ self.assertEqual(required["status"], "pass", required["summary"])
+
+ write_shard(model / "model.safetensors",
+ [(n, 8) for n in self.FLASH if "embed_tokens" not in n])
+ required = deep_container_report(model)["required"]
+ self.assertEqual(required["status"], "fail")
+ self.assertIn("token embedding", required["summary"])
+ self.assertEqual(required["details"]["missing_roles"], ["token embedding"])
+
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.tmp.cleanup)
+
+
if __name__ == "__main__":
unittest.main()