Document SwiGLU metadata correction

README.md

@@ -10,6 +10,18 @@ base_model:
 
   Stock llama.cpp builds without bailingmoe3 support will not load the model.
 
+  ### SwiGLU metadata correction in progress
+
+  The original GGUF revisions omitted the trained per-layer SwiGLU clamp metadata declared by the released model configuration. This
+  can cause rare but severe output corruption in later layers. Corrected files are being uploaded under the same filenames.
+
+  Files downloaded before this correction should be downloaded again after completion, or repaired locally with
+  [`add-ling3-clamp-metadata.py`](./add-ling3-clamp-metadata.py). The repair changes GGUF metadata only. It does not alter or requantize
+  tensor data.
+
+  The corrected llama.cpp converter and loader are available in the linked fork. Commit:
+  [`c51308d8`](https://github.com/aetherbird/llama.cpp/commit/c51308d8)
+
   ## Conversion and Quantization
 
   Taken directly from the released `inclusionAI/Ling-3.0-flash` BF16 safetensors.
@@ -92,7 +104,8 @@ base_model:
 
   - BF16 architecture load and tensor round-trip
   - CPU and CUDA execution on a reduced-size BailingMoE3 fixture
-  - Target next-token parity against the Hugging Face implementation
+  - Target next-token parity against the released Hugging Face implementation before the missing trained clamps were identified
+  - Nonzero SwiGLU clamp execution and GGUF round-trip on the reduced-size BailingMoE3 fixture
   - First three recursive MTP proposals matched the Hugging Face implementation
   - Full MXFP4_MOE target and MTP graph smoke test
   - Q8_0 conversion completed successfully with all 938 tensors
@@ -129,4 +142,4 @@ base_model:
   Supports up to 256K context. Reasoning is enabled by default. 
 
   Upstream PR:
-https://github.com/ggml-org/llama.cpp/pull/26608
+https://github.com/ggml-org/llama.cpp/pull/26608

add-ling3-clamp-metadata.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    import gguf
+    from gguf.scripts.gguf_new_metadata import copy_with_new_metadata, get_field_data
+except ModuleNotFoundError as exc:
+    raise SystemExit(
+        "gguf-py is required. Set PYTHONPATH to the gguf-py directory in llama.cpp."
+    ) from exc
+
+
+DEFAULT_EXP = [0.0] * 35 + [4.0] * 7
+DEFAULT_SHEXP = [0.0] * 34 + [5.0] * 6 + [7.0] * 2
+
+
+def load_limits(config_path: Path | None, block_count: int) -> tuple[list[float], list[float]]:
+    if config_path is None:
+        return (
+            (DEFAULT_EXP + [0.0] * block_count)[:block_count],
+            (DEFAULT_SHEXP + [0.0] * block_count)[:block_count],
+        )
+
+    with config_path.open(encoding="utf-8") as config_file:
+        config = json.load(config_file)
+
+    if config.get("num_hidden_layers") != 42:
+        raise ValueError("expected num_hidden_layers=42")
+
+    def padded(key: str) -> list[float]:
+        values = config.get(key)
+        if not isinstance(values, list) or len(values) != 42:
+            raise ValueError(f"expected {key} to contain 42 entries")
+        result = [0.0 if value is None else float(value) for value in values]
+        return (result + [0.0] * block_count)[:block_count]
+
+    return padded("expert_swiglu_limit_list"), padded("share_expert_swiglu_limit_list")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Add Ling 3.0 SwiGLU clamp metadata to a GGUF")
+    parser.add_argument("input", type=Path)
+    parser.add_argument("output", type=Path)
+    parser.add_argument("--config", type=Path)
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+
+    if args.input.resolve() == args.output.resolve():
+        raise ValueError("input and output must be different files")
+    if args.output.exists() and not args.force:
+        raise FileExistsError(f"output already exists: {args.output}")
+
+    reader = gguf.GGUFReader(args.input, "r")
+    arch = get_field_data(reader, gguf.Keys.General.ARCHITECTURE)
+    if arch != "bailingmoe3":
+        raise ValueError(f"expected bailingmoe3 architecture, found {arch!r}")
+
+    block_key = gguf.Keys.LLM.BLOCK_COUNT.format(arch=arch)
+    block_count = get_field_data(reader, block_key)
+    if block_count not in (42, 43):
+        raise ValueError(f"expected 42 or 43 GGUF blocks, found {block_count!r}")
+
+    clamp_exp, clamp_shexp = load_limits(args.config, block_count)
+    if clamp_exp[35:42] != [4.0] * 7 or any(clamp_exp[:35]) or any(clamp_exp[42:]):
+        raise ValueError("unexpected routed-expert clamp layout")
+    if clamp_shexp[34:40] != [5.0] * 6 or clamp_shexp[40:42] != [7.0] * 2:
+        raise ValueError("unexpected shared-expert clamp layout")
+    if any(clamp_shexp[:34]) or any(clamp_shexp[42:]):
+        raise ValueError("unexpected shared-expert clamp padding")
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    writer = gguf.GGUFWriter(args.output, arch=arch, endianess=reader.endianess)
+    alignment = get_field_data(reader, gguf.Keys.General.ALIGNMENT)
+    if alignment is not None:
+        writer.data_alignment = alignment
+
+    writer.add_swiglu_clamp_exp(clamp_exp)
+    writer.add_swiglu_clamp_shexp(clamp_shexp)
+    keys = [
+        gguf.Keys.LLM.SWIGLU_CLAMP_EXP.format(arch=arch),
+        gguf.Keys.LLM.SWIGLU_CLAMP_SHEXP.format(arch=arch),
+    ]
+    copy_with_new_metadata(reader, writer, {}, keys)
+
+
+if __name__ == "__main__":
+    main()