feat(glm53): #227 split-K head-gate 를 main 에 반영 (v2 브랜치로 머지된 것)

[choiceoh]

#227 이 base 브랜치 feat/glm53-prep-fused-v2 로 머지된 시점에 #226 은 이미 main 에 들어가 있어서 split-K 커밋(83d9eae)이 main 에 없다. 이 PR 의 diff 는 #227 과 동일 (모듈 glm53_indexer_gate_splitk, opt-in, EXP-9, 41,165 checks OK).

🤖 Generated with Claude Code

---

Note

Medium Risk
Opt-in numerics change on sparse indexer head-gates (non bit-exact fp32 reduction) can affect top-k pool selection; mitigated by default-off, M≤16 routing, and required quality bracket.

Overview
Adds overlay module glm53_indexer_gate_splitk so the sparse indexer’s fp32 head-gate matmul ([M,4096]×[4096,16], 11 layers/step) can use a split-K Triton kernel instead of cuBLAS’s two-block gemmSN path on decode-sized batches (M≤16). Larger shapes and default-off behavior keep torch.mm.

Wiring: New glm53_indexer_gate.py exposes head_gate() gated by VLLM_GLM53_INDEXER_GATE_SPLITK=1 (profile default 0). glm5next_attention.py and glm53_prefill_fastpath.py route Indexer / fused-k-gate forwards through a shared helper (lazy import in fastpath when the module isn’t mounted). Manifest, profiles/glm53.env, and glm53_model_wiring prefill hunk stay in sync.

Validation & ops: Offline probe probes/indexer_gate_check.py, test_glm53_indexer_gate_splitk_contracts, and per-profile overlay symbol checks in test_overlay_symbol_contracts. Docs record ~50→10 µs microbench, ~0.65%/step ceiling, and RUNBOOK EXP-9 (ride on EXP-7/8 boots, not solo).

^{Reviewed by Cursor Bugbot for commit 2abc932. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-02T11:25:43.387964Z	2abc932	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[Copilot]

🟡 Changes recommended

The new Triton split-K path lacks basic applicability guards (CUDA/device/shape) and contiguity handling, which can lead to runtime failures or incorrect results under valid tensor layouts.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR ports PR #227’s opt-in GLM53 sparse indexer fp32 head-gate split-K path onto main, adding a new overlay module (glm53_indexer_gate_splitk) that can replace the small-M decode torch.mm(hidden.float(), _wp_fp32) with a Triton split-K kernel when explicitly armed.

Changes:

• Add glm53_indexer_gate_splitk overlay (pinned attention.py overlay + new glm53_indexer_gate.py helper/kernel) and wire it into both the indexer and fused-K-gate fastpath via a shared helper.
• Extend contract tests to validate per-profile overlay symbol ownership, and add explicit contracts for the new split-K module and profile knob defaulting to stock.
• Update profile defaults and documentation/runbook/measurements to record arming, numerics caveat, and expected performance impact.

File summaries

File	Description
tests/test_logic.py	Makes overlay symbol-contract checking profile-aware; adds split-K module contract tests and updates fastpath contract symbol set.
STEP_KERNEL_MAP.md	Notes the new split-K head-gate module as the intended optimization target.
RUNBOOK_KERNEL_CAMPAIGN2.md	Adds EXP-9 runbook entry describing split-K head-gate, gating, numerics, and measurement procedure.
profiles/glm53.env	Mounts glm53_indexer_gate_splitk and ships VLLM_GLM53_INDEXER_GATE_SPLITK=0 default knob.
probes/indexer_gate_check.py	Adds an offline probe script to compare numerics and measure CUDA-graph replay timing.
overlay/modules/glm53_model_wiring/glm53_prefill_fastpath.py	Adds lazy-resolved _glm53_head_gate helper and routes fused-indexer forward through it with ImportError fallback.
overlay/modules/glm53_indexer_gate_splitk/requires	Declares dependency on glm53_model_wiring for the fastpath hunk.
overlay/modules/glm53_indexer_gate_splitk/README.md	Documents motivation, numerics caveat, offline timings, and arming procedure.
overlay/modules/glm53_indexer_gate_splitk/manifest.tsv	Pins attention.py overlay and adds new glm53_indexer_gate.py file (absent in base).
overlay/modules/glm53_indexer_gate_splitk/glm5next_attention.py	Replaces the fp32 head-gate torch.mm with the shared head_gate helper import/call.
overlay/modules/glm53_indexer_gate_splitk/glm53_indexer_gate.py	Introduces Triton split-K kernel + applicability checks + head_gate wrapper behind env knob.
MEASUREMENTS.md	Records offline timing and numerics measurements and notes EXP-9 gating/ceiling.
build/glm53/manifest.tsv	Adds built artifacts for the pinned attention overlay and new gate helper/kernel file.
build/glm53/glm5next_attention.py	Built snapshot of the attention overlay reflecting the head-gate helper routing.
build/glm53/glm53_prefill_fastpath.py	Built snapshot of fastpath with the lazy head-gate helper routing.
build/glm53/glm53_indexer_gate.py	Built snapshot of the split-K helper/kernel module.

Review details

Suppressed comments (1)

overlay/modules/glm53_indexer_gate_splitk/glm53_indexer_gate.py:74

• splitk_applicable doesn't verify tensors are CUDA / on the same device (or even that x and w are 2D and shape-compatible). If VLLM_GLM53_INDEXER_GATE_SPLITK=1 is set in a CPU run, head_gate can route into Triton and fail at runtime.

def splitk_applicable(x: torch.Tensor, w: torch.Tensor) -> bool:
    return (x.shape[0] <= MAX_M and w.dtype == torch.float32 and w.is_contiguous()
            and w.shape[1] <= 16 and w.shape[0] % (_SPLIT * _BLOCK_K) == 0)

• Files reviewed: 16/16 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cursor]

Approved: Cursor Bugbot completed successfully with no findings that require human review. No reviewers were assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}