FlyCockpit/GLM-5.2-NVFP4-AQLM-Abliterated-Vision

1# GLM-5.2 AQLM convergence plan (executable runbook)2 3Goal: (1) finish the lite activation-aware convergence, rebuild + validate +4upload all three checkpoints — take the win; (2) run full AQLM (full-Hessian5beam encoding + blockwise PV-tuning against a streamed BF16 teacher), then6rebuild + validate + upload again. Sanity gates between every step; a mixed7NVFP4+AQLM checkpoint must LOAD and INFER before anything ships.8 9This runbook assumes no context beyond this file. Follow it top to bottom.10When a gate FAILS: stop, do not delete anything, record the failing output11in /data/glm52-RUNLOG.md, and fix or escalate before proceeding.12 13--------------------------------------------------------------------------14## 0. Ground rules and environment15 16Every shell that touches vLLM must run this preamble:17 18```bash19cd /home/coder/git/glm52/vllm && source ../.venv/bin/activate20export CUDA_HOME=/home/coder/git/glm52/.venv/lib/python3.12/site-packages/nvidia/cu1321```22 23Standing serve env (the ONLY blessed recipe; 8xB200 emulating 4x96GB):24 25```bash26export VLLM_PP_LAYER_PARTITION="21,19,19,19"27export NCCL_MAX_NCHANNELS=4 NCCL_BUFFSIZE=104857628export VLLM_SPARSE_INDEXER_MAX_LOGITS_MB=25629SERVE_FLAGS="--pipeline-parallel-size 4 --gpu-memory-utilization 0.509 \30  --kv-cache-dtype fp8_ds_mla --max-num-seqs 2 \31  --max-num-batched-tokens 2048 --enforce-eager --port 8199"32```33 34Hard-won footguns — DO NOT repeat these mistakes:35- NEVER `pkill -f <pattern>` where <pattern> appears in your own command36  line or in a launch you make in the same Bash call (it kills itself /37  the new launch). Kill in one call, verify GPUs free with nvidia-smi in38  the same call, launch in a SEPARATE call.39- /tmp is volatile on this box (was wiped once). Teacher downloads live in40  /tmp/glm52-hot-dl2 — if missing, regenerate via41  `tools/make_hot_manifest2.py` + `tools/range_download.py` (manifest42  source /data/glm52-need-experts.json).43- `hf upload-large-folder` only targets a repo's main branch. It is44  resumable; rerun on failure.45- A vLLM serve that dies with "Engine core initialization failed" has the46  real error higher up in the log: grep for `ValueError|KeyError` first.47- Long jobs: run_in_background + `until <condition>; do sleep 30; done`48  waiters. Never a bare long sleep.49 50Checkpoint inventory (do not delete any of these):51 52| path | what |53|---|---|54| /data/glm52 | LIVE 1M two-tier (v5): 30% hot NVFP4 / 70% cold 2-bpw AQLM |55| /data/glm52-500k, /data/glm52-250k | variants: 48% / 57% hot |56| /data/glm52-v4-uniform | pre-demotion two-tier (hot-array superset source) |57| /data/glm52-v3-3tier, /data/glm52-old-layerwise | older tiers; old-layerwise also = teacher for layers 3,4,5,8,74-77 (all-256 per-expert NVFP4) |58| /data/glm52-aqlm-parts | init-grade AQLM parts, ALL layers, 2-book w2 |59| /data/glm52-aqlm-conv | converger output (this plan, phase 1) |60| /data/glm52-acts | calibration activations, 24k routed tokens/layer |61| /data/glm52-expert-stats-v2.npz, /data/glm52-expert-assignment*.json | routing stats + assignments |62| /data/glm52-sm120-golden | golden bundle (must be RE-CAPTURED whenever weights change) |63| /tmp/glm52-hot-dl2 | teacher NVFP4 regions (cold experts, 67 layers) |64 65HF repos (public, overwrite in place):66jarrelscy/GLM-5.2-NVFP4-AQLM-hybrid {,-500k,-250k}67 68--------------------------------------------------------------------------69## 1. Sanity-check toolbox (reusable gates)70 71Run gates in this order; each assumes the previous passed. "CKPT" = the72checkpoint directory under test.73 74### SC-1 Schema check (seconds, no GPU)75```bash76python tools/sanity/sc1_schema.py CKPT77```78Verifies: index total_size == sum of shard tensor bytes; every layer 3..7779has the full two-tier tensor set with shapes consistent with80config.json aqlm_layer_books (n_nvfp4+n_cold=256, n_base=0); hyb_kind81counts match; no NaN/Inf in any fp16/fp32 tensor sampled per layer;82codebooks are fp16 [1,65536,8]; codes int16. PASS = prints `SC1 PASS`.83 84### SC-2 Dequant statistics (1 GPU, ~2 min)85```bash86python tools/sanity/sc2_dequant_stats.py CKPT --layers 3,21,40,60,7787```88For each listed layer: dequantize 4 cold experts (AQLM) and 4 hot experts89(NVFP4) to fp16; check per-tensor RMS in [1e-3, 1.0], zero-fraction < 30%,90no NaN; cosine similarity of AQLM dequant vs the pure-torch reference == 1.91PASS = `SC2 PASS`.92 93### SC-3 Kernel tests (1 GPU, ~1 min)94```bash95CUDA_VISIBLE_DEVICES=7 python -m pytest tests/kernels/quantization/test_aqlm_moe.py -q96```97PASS = 32 passed.98 99### SC-4 Load + short-context serve smoke (4 GPUs, ~6 min)100```bash101timeout 900 python -m vllm.entrypoints.cli.main serve CKPT $SERVE_FLAGS \102  --max-model-len 8192 > /tmp/sc4.log 2>&1 &103until grep -qE "startup complete|initialization failed" /tmp/sc4.log; do sleep 15; done104```105PASS = "Application startup complete" and no Traceback. Leave running for106SC-5.107 108### SC-5 Coherence probes (against SC-4 server, ~1 min)109```bash110python tools/validate_serve.py --port 8199111```112PASS = all three completions coherent (Paris / correct fibonacci or113quicksort / H2O), decode >= 10 tok/s. A model with broken cold experts114produces repetitive garbage here — this is the primary "weights kaput"115detector.116 117### SC-6 Perplexity delta (against SC-4 server, ~5 min)118```bash119python tools/sanity/sc6_ppl.py --port 8199 --ref /data/glm52-heldout.txt120```121Teacher-forced logprob over ~50k held-out tokens (code+prose+medical,122NOT in the calibration set) via the completions API with echo/logprobs.123Record ppl in RUNLOG. PASS rule: after any requantization, ppl must be124<= previous shipped ppl + 1% (phase-1) / must IMPROVE (phase-2 gates).125 126### SC-7 Full-context revalidation (4 GPUs, ~15 min) — 1M checkpoint only127Serve with --max-model-len 1048576 (full SERVE_FLAGS recipe), then:128```bash129python tools/validate_serve.py --port 8199 --long 200000130```131PASS = KV >= 1,048,576 tokens; needle answer contains BLUEBERRY42;132worst GPU <= 97,887 MiB.133 134### SC-8 Golden e2e comparison (against SC-4 server)135```bash136python tools/verify_sm120.py /data/glm52-sm120-golden --port 8199 --stages ""137```138Compares greedy generations vs stored goldens. NOTE: after INTENTIONAL139weight changes text may legitimately differ; the check is that outputs are140coherent and >= 40/50 top-50 logprob overlap on early steps. After each141shipped rebuild, RE-CAPTURE goldens (tools/capture_golden.py + 142make_kernel_vectors.py) so the bundle matches shipped weights.143 144### Gate bundles145- GATE-A (any rebuilt checkpoint): SC-1, SC-2, SC-4, SC-5146- GATE-B (before any upload): GATE-A + SC-6 recorded + (1M only) SC-7147- GATE-C (after any fitting phase, per ~8 layers): spot SC-2 on parts +148  fitting-metric monotonicity (err_after < err_before on every layer;149  any layer where err_after > err_before*0.999 -> refit that layer)150 151TODO(first task): tools/sanity/sc1_schema.py, sc2_dequant_stats.py,152sc6_ppl.py and the held-out set /data/glm52-heldout.txt do not exist yet.153Build them exactly to the contracts above (~200 lines total; reuse154_dequant_reference from nvfp4_aqlm_hybrid.py and the FP4 LUT from155tools/aqlm_quantize.py). Held-out: take 25 files from vllm docs/ + 15156MedQA paragraphs + 10 code files NOT matched by the corpus builder's157random.Random(42) selection; ~50k tokens total.158 159--------------------------------------------------------------------------160## 2. PHASE 1 — finish lite convergence, ship it (est. 6-9 h wall)161 162### 1.1 Confirm smoke, then launch the full run163Smoke (layer 40, GPU 4) is running; on completion check164`/data/glm52-aqlm-conv/smoke.log` shows `saved` and err_after < err_before165for both w13 and w2. Then:166```bash167# GPUs must be idle first (nvidia-smi). Launch (resumable; skips done layers):168python tools/aqlm_converge.py > /data/glm52-aqlm-conv/run.log 2>&1 &169# progress: grep -c "saved" /data/glm52-aqlm-conv/run.log  (target 75)170```171~10-20 min/layer/GPU => 75 layers on 8 GPUs ≈ 2-4 h. Monitor with a172tail|grep on "saved|Error|Traceback|OutOfMemory". If a worker OOMs:173rerun with that layer alone on an idle GPU (memory fragmentation clears).174 175### 1.2 GATE-C on the parts176All 75 layer files present; every layer's `*_err_after < *_err_before`;177`python tools/sanity/sc2_dequant_stats.py --parts /data/glm52-aqlm-conv`178(parts mode: reference-dequant a few experts per layer; RMS/NaN checks).179 180### 1.3 Rebuild the three checkpoints (cold arrays only)181Write tools/build_checkpoint_v7.py (clone of v6's writer): for each target182in {/data/glm52, /data/glm52-500k, /data/glm52-250k}: stream every shard;183copy all tensors EXCEPT layers' `w13_codes|w13_codebooks|w13_scales|184w2c_codes|w2c_codebooks|w2c_scales`, which are replaced by slicing the185conv parts: `sel = positions of the target's cold ids (from its hyb_kind)186within parts.expert_ids` (parts cover the 1M cold set = superset; assert187every target cold id is found). Write to <target>-conv, then GATE-A it,188then swap: `mv <target> <target>-preconv && mv <target>-conv <target>`.189Order: 1M first, then 500k, then 250k.190 191### 1.4 GATE-B per checkpoint1921M: full GATE-B incl SC-7. 500k/250k: GATE-A + SC-6 (serve at193--max-model-len 8192 is fine for the gate; partitions unchanged).194Record all ppl values in RUNLOG. Abort rule: if 1M ppl regresses > 1%195vs pre-conv, STOP — swap back (`mv` reversal) and investigate.196 197### 1.5 Re-capture goldens (weights changed)198```bash199python tools/capture_golden.py && python tools/make_kernel_vectors.py200```201(armed-marker flow is automatic; outputs overwrite /data/glm52-sm120-golden.)202 203### 1.6 Upload — DEFERRED (revised 2026-07-07)204Do NOT upload here. The gated conv checkpoints are the fallback artifacts;205proceed directly to phase 1.5 (REAP re-tier), gate it, then upload ONCE:206the REAP version if its gates pass (ppl <= conv ppl), else the conv207version. This halves upload traffic; the win still ships strictly better208than what is currently on HF. Original upload commands (run after 1.5):209```bash210hf upload-large-folder jarrelscy/GLM-5.2-NVFP4-AQLM-hybrid      /data/glm52      --repo-type model --num-workers 12211hf upload-large-folder jarrelscy/GLM-5.2-NVFP4-AQLM-hybrid-500k /data/glm52-500k --repo-type model --num-workers 12212hf upload-large-folder jarrelscy/GLM-5.2-NVFP4-AQLM-hybrid-250k /data/glm52-250k --repo-type model --num-workers 12213```214Sequential; each ends with `committed: N/N`. Also `hf upload ... /data/glm52/code code`215if tools changed, and update model-card READMEs to note the216activation-aware convergence. Verify each repo's file count via HfApi.217 218--------------------------------------------------------------------------219## 2.5 PHASE 1.5 — REAP-based expert re-selection (est. 4-6 h, after the220phase-1 upload so the win ships first)221 222Motivation: the shipped hot/cold split ranks experts by routing FREQUENCY223(bincount of topk_ids). That demotes rarely-fired experts whose outputs are224large and decisive when they do fire. Adopt REAP's router-weighted225activation saliency, adapted for precision demotion (not pruning):226 227    score_e = SUM_t  g_{t,e} * ||f_e(x_t)||_2   *   relerr_e228      g       = router weight (topk_weights, captured in /data/glm52-acts)229      f_e(x)  = down(silu(gate x) * up x) with TEACHER weights230      relerr_e= h-weighted 2-bit reconstruction error of expert e231                (from conv/full parts; near-uniform, catches fragile tails)232 233Steps:234a. tools/score_experts_reap.py: per layer load acts + teachers for ALL 256235   experts (hot: dequant the live checkpoint's nvfp4_* arrays; cold:236   /tmp/glm52-hot-dl2 regions / old-layerwise), compute score_e ->237   /data/glm52-reap-scores.npz [75,256]. 8-GPU layer-parallel, ~2 h.238   Sanity: per layer, spearman(score, old counts) printed — expect 0.4-0.8239   (correlated but meaningfully different); investigate if < 0.2.240b. Re-solve assignments for all three budgets with the same byte-exact241   solver, ranking by score (floor 8/cap 176). Print overlap vs current242   hot sets; expect 60-85%.243c. Fit AQLM (converger, warm start from full codebook of that layer) for244   newly-cold experts only; promote newly-hot from teacher bytes already245   on disk (cold-teacher superset — no downloads needed).246d. Rebuild all three (build_checkpoint_v7 slicing by new assignment),247   GATE-A each, GATE-B the 1M; ppl must improve or match (this changes248   WHICH experts are 2-bit, same byte budget — if ppl regresses, the REAP249   scores or fit are wrong: stop and investigate, keep -prereap dirs).250e. This assignment becomes phase 2's fit universe (its cold sets).251f. UPLOAD NOW (single combined upload of phase 1 + 1.5): the three repos,252   using the commands in §1.6, plus the code bundle; verify file counts;253   record commit URLs in RUNLOG.254 255--------------------------------------------------------------------------256## 3. PHASE 2 — full AQLM (est. 2.5-3.5 days wall)257 258### 2.0 Staging (CPU/network only — run DURING phase 1, no GPU contention)259a. Calibration corpus v3, ~15M tokens, saved as token-id shards260   /data/glm52-calib-v3/*.npy: reuse corpus builder mix + download261   supplements (HF datasets: a code sample, an instruction set, keep the262   MedQA textbooks; ~30-50 GB). Hold out 50k tokens -> /data/glm52-heldout.txt.263b. BF16 teacher streamer: tools/bf16_stream.py with contract264   `get_expert(layer, expert, proj) -> bf16 tensor`, backed by ranged265   HTTP reads of zai-org/GLM-5.2 (index + shard headers cached once;266   LRU on-disk cache /data/bf16-cache, cap 400 GB). Verify vs NVFP4267   teacher: cosine > 0.98 on 10 random experts.268c. Baseline evals: SC-6 ppl of the phase-1-shipped 1M checkpoint +269   teacher NVFP4 model (serve lukealonso config on 8 GPUs PP=8 briefly);270   plus 20-problem HumanEval subset + 50-problem GSM8K subset through the271   server (tools/sanity/bench_small.py; greedy; record scores in RUNLOG).272 273### 2.1 Full-Hessian beam encoding (days 1-2 of phase 2)274tools/aqlm_full.py, upgrade of aqlm_converge.py per (layer, projection):275- Hessians: per-expert FULL H = X_e^T X_e (w13: 6144^2 fp32 = 151 MB276  transient per expert; w2: 2048^2). Accumulate from calib-v3 activations277  (re-capture acts at 128k tokens/layer with the existing hook — one278  ~30-min PP=4 pass over calib-v3). Damping: H += 1e-2*mean(diag)*I.279- Teacher: BF16 via streamer (fallback NVFP4 regions if a fetch fails).280- Encode: GPTQ-order sequential CD with error feedback within each row281  (process groups in descending diag(H) order; after fixing a group,282  propagate residual via H off-diagonal to remaining groups), candidates283  by beam-4: top-4 codebook entries under the diag metric (GEMM+topk),284  exact H-scored selection among the 4.285- Alternate with weighted codebook update + scale refit (as lite), 3 outer286  iterations. Early-stop per layer when H-weighted err improves < 0.1%.287- Output: /data/glm52-aqlm-full/layer_N.pt (same schema as conv parts).288- GATE-C every 8 layers; on any layer regression vs conv parts, keep the289  conv version for that layer (per-layer best-of).290Budget check: must average <= 3.5 h/layer on one GPU (75 layers/8 GPUs/2912 days); if the first 4 layers exceed it, reduce beam to 2 and/or292subsample H tokens; record the decision.293 294### 2.2 Blockwise PV-tuning (days 2-3.5 of phase 2)295tools/pv_tune.py per transformer block (layer-parallel, 1 block/GPU):296- Student block: BF16 non-expert weights + hot NVFP4 dequantized frozen +297  cold experts as differentiable dequant (codebook gather x scales);298  trainable: codebooks, scales (cold), NOTHING else. Teacher block: same299  block with BF16 streamed experts everywhere.300- Data: block inputs recorded once per phase (run calib-v3 through the301  phase-2.1 model with a hidden-state capture hook at each block boundary,302  save 256k tokens per block boundary, bf16, ~3 GB/block).303- Loss: MSE(student_out, teacher_out) token-weighted by router prob mass;304  Adam lr 1e-4 (codebooks) / 1e-3 (scales), bs 4096 tokens, ~600 steps;305  every 200 steps: straight-through re-encode (beam-1 full-H) and reset306  optimizer state for reassigned entries. Early-stop on plateau.307- Output: /data/glm52-aqlm-pv/layer_N.pt. GATE-C per 8 blocks + one308  mid-phase GATE-A+SC-6 rebuild of the 1M checkpoint after ~half the309  blocks (catch systemic drift early; expect ppl improvement already).310 311### 2.3 Final rebuild + gates + upload312- Rebuild all three from pv parts (fallback per layer: pv > full > conv,313  choose best by held-out block-output error; record table in RUNLOG).314- GATE-B all three (1M incl SC-7 needle at 200k). Run bench_small.py:315  ppl must improve vs phase-1; HumanEval/GSM8K must not regress > 1 item.316- Re-capture goldens; update model cards ("PV-tuned AQLM"); upload all317  three repos + code bundle; verify file counts; final RUNLOG summary.318 319--------------------------------------------------------------------------320## 4. Rollback321Every swap keeps the previous directory as <target>-preconv / -prefull /322-prepv. HF keeps full commit history — revert = re-upload the kept dir or323`huggingface-cli` revert to a commit. Never delete a -pre* dir until the324next phase's GATE-B passes.325 326## 5. RUNLOG327Append every gate result, metric, decision, and anomaly to328/data/glm52-RUNLOG.md with a timestamp. The uploads' commit URLs go there329too. If context is lost, this file + PLAN.md are sufficient to resume.330