fix(recipe): correct NF4 Lloyd env vars after kernel source inspection

Pulled production-hybrid-1.4 on dgx1.lan and read the kernel source in vLLM (b12x_moe.py) and the b12x package (w4a16/prepare.py + kernel.py). Three findings corrected the recipe:

1. VLLM_NF4_LAYERS is a PATH to a JSON file ({"layers":[3,4,...,77]}), not a range string. The code does open(path) then json.load — "3-77" would have failed silently (unreadable file → NF4 disabled → E2M1 decode on Lloyd weights → garbage).

2. VLLM_NF4_EXPERTS_PATH does not exist — removed. The only NF4 env var is VLLM_NF4_LAYERS. Expert weights load through vLLM's standard weight loader (the Lloyd L{n}.safetensors have standard tensor names).

3. The _NF4_CODEBOOK is GLOBAL and hardcoded in the b12x binary (fitted as the mean of 71 per-layer Lloyd–Max tables). The per-layer grids/L{n}.json files in the Lloyd repo are reference artifacts — NOT loaded at runtime.

The Lloyd L{n}.safetensors must be overlaid onto the MXFP4 snapshot dir (same filenames, same tensor names — they replace the E2M1 experts with NF4-packed codes). Documented as a manual prerequisite: copy L*.safetensors + create nf4_layers.json in the Lloyd snapshot dir. VLLM_NF4_LAYERS="{{lloyd_experts}}/nf4_layers.json" resolves per-node via the existing placeholder mechanism.

recipes/glm52-nf4-lloyd-experts-gptq/recipe.toml

@@ -13,22 +13,34 @@
 # cannot be served standalone. The base checkpoint is
 # aidendle94/GLM-5.2-MXFP4-Experts-GPTQ (full model: config.json with
 # quant_method="hybrid_mxfp4_ct", hybrid-ct-*.safetensors non-expert weights
-# in block-FP8/NVFP4, tokenizer, mtp-draft). The Lloyd NF4 experts overlay
-# the MXFP4 experts for layers 3–77 (all 75 MoE layers) via the nf4_e8m0_k32
-# kernel baked into production-hybrid-1.4, activated per-layer by
-# VLLM_NF4_LAYERS. The Lloyd repo path is resolved per-node from the HF
-# cache (refs/main → latest snapshot) and substituted into VLLM_NF4_EXPERTS_PATH.
+# in block-FP8/NVFP4, tokenizer, mtp-draft). The Lloyd NF4 experts REPLACE
+# the MXFP4 E2M1 experts for layers 3–77 (all 75 MoE layers): the Lloyd
+# L{n}.safetensors files have the same filenames and tensor names as the
+# MXFP4 repo's, so they must be copied into the MXFP4 snapshot directory
+# (filesystem overlay). vLLM loads them through the standard weight loader;
+# the nf4_e8m0_k32 kernel (baked in production-hybrid-1.4) decodes them with
+# the global _NF4_CODEBOOK instead of the E2M1 bit-twiddle. Which layers use
+# the NF4 path is controlled by VLLM_NF4_LAYERS — a path to a JSON file
+# {"layers": [3, 4, ..., 77]}, NOT a range string.
 #
 # Image: sparkrun-vllm-ds4-gb10:glm52
 #   Built from docker-images/glm52/Dockerfile, which FROMs
 #   aidendle94/sparkrun-vllm-ds4-gb10:production-hybrid-1.4 (bakes the
 #   nf4_e8m0_k32 / nf4_packed kernel — inert without VLLM_NF4_LAYERS).
 #
-# PREREQUISITES:
-#   - Both repos cached on every node via HF_HOME:
-#       huggingface-cli download aidendle94/GLM-5.2-MXFP4-Experts-GPTQ
-#       huggingface-cli download aidendle94/GLM-5.2-NF4-Lloyd-Experts-GPTQ
-#     (MXFP4 base ~390 GB, Lloyd experts ~385 GB)
+# PREREQUISITES (manual, on EVERY node):
+#   1. Download both repos via HF_HOME:
+#        huggingface-cli download aidendle94/GLM-5.2-MXFP4-Experts-GPTQ
+#        huggingface-cli download aidendle94/GLM-5.2-NF4-Lloyd-Experts-GPTQ
+#      (MXFP4 base ~390 GB, Lloyd experts ~385 GB)
+#   2. Overlay the Lloyd NF4 experts onto the MXFP4 snapshot directory:
+#        MXFP4=$(readlink -f ~/.cache/huggingface/hub/models--aidendle94--GLM-5.2-MXFP4-Experts-GPTQ/snapshots/main)
+#        LLOYD=$(readlink -f ~/.cache/huggingface/hub/models--aidendle94--GLM-5.2-NF4-Lloyd-Experts-GPTQ/snapshots/main)
+#        cp "$LLOYD"/L*.safetensors "$MXFP4"/
+#      Without this overlay the kernel decodes E2M1 weights with the NF4
+#      codebook → garbage output (the model card warns about this).
+#   3. Create the NF4 layer-list JSON in the Lloyd snapshot dir:
+#        echo '{"layers":[3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77]}' > "$LLOYD"/nf4_layers.json
 #
 # REFERENCE:
 #   https://huggingface.co/aidendle94/GLM-5.2-NF4-Lloyd-Experts-GPTQ
@@ -107,12 +119,12 @@ repo = "aidendle94/GLM-5.2-MXFP4-Experts-GPTQ"
 subfolder = "mtp-draft"
 container = "mtp_draft"
 
-# Lloyd NF4 expert overlay — the Lloyd repo is experts-only (L{n}.safetensors
-# + grids/L{n}.json codebooks). Resolved at serve time, per node, from the HF
-# cache (refs/main → latest snapshot). The launcher substitutes
-# {{lloyd_experts}} into VLLM_NF4_EXPERTS_PATH below, giving the 1.4 image's
-# baked-in nf4_e8m0_k32 kernel the path to the per-layer expert weights.
-# VLLM_NF4_LAYERS activates the NF4 path for layers 3–77 (all 75 MoE layers).
+# Lloyd repo path reference — resolved at serve time, per node, from the HF
+# cache (refs/main → latest snapshot). {{lloyd_experts}} is substituted into
+# VLLM_NF4_LAYERS below so the kernel can find the nf4_layers.json file
+# (created by the operator in step 3 of the prerequisites above). This is a
+# path reference, NOT a bind-mount — the HF cache is already mounted at
+# /root/.cache/huggingface, so the resolved path's symlinks resolve correctly.
 [[extra_mounts]]
 repo = "aidendle94/GLM-5.2-NF4-Lloyd-Experts-GPTQ"
 container = "lloyd_experts"
@@ -120,11 +132,12 @@ container = "lloyd_experts"
 
 [env]
 # ── NF4 Lloyd expert overlay ──────────────────────────────────────────────
-# Activates the nf4_e8m0_k32 kernel (baked in production-hybrid-1.4) for
-# layers 3–77 (all 75 MoE layers). {{lloyd_experts}} is substituted per-node
-# with the resolved HF cache path to the Lloyd repo snapshot.
-VLLM_NF4_LAYERS = "3-77"
-VLLM_NF4_EXPERTS_PATH = "{{lloyd_experts}}"
+# Path to a JSON file listing which layers use the nf4_e8m0_k32 decode path
+# (vs the default fp4_e8m0_k32 E2M1 bit-twiddle). The kernel reads this file
+# at init: {"layers": [3, 4, ..., 77]}. {{lloyd_experts}} is substituted
+# per-node with the resolved HF cache path to the Lloyd repo snapshot, where
+# the operator creates nf4_layers.json (see PREREQUISITES step 3 above).
+VLLM_NF4_LAYERS = "{{lloyd_experts}}/nf4_layers.json"
 
 # ── b12x suite ────────────────────────────────────────────────────────────
 VLLM_USE_V2_MODEL_RUNNER = "1"