nemotron-30b-cpu-256k
Health Pass
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 71 GitHub stars
Code Warn
- network request — Outbound network request in gateway/sse_gateway.py
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
♟️ llama-modchip v2.1: Run 30B Sparse MoE LLMs on Pure CPU (0 GPUs) at 20–60.4 tok/s with a 256K Context Window via a 1.64MB Stockfish-PVS + RouteCrack L3 Drafter, 2MB HugePages & AVX-512 VNNI
llama-modchip v2.1 & 256K CPU Co-Design: Running 30B Hybrid SSM-MoE & GQA Models on Pure CPU at 20–60+ tok/s (0 GPUs)
llama-modchip ("Priiloader for CPU GGUF Inference") + RouteCrack & Stockfish-PVS v2 (M=7): How a 1.64 MB Chess-Engine Search Inside L3 Cache + 2MB HugePages + _MM_HINT_NTA Unlocks 48.4–60.4 tok/s on Nemotron-3.5-30B-A3B (256K Context) and +38.5% Decode on Qwen3-30B-A3B with Zero GPUs
📄 Documentation Navigation:
- Overview, 60-Second Quickstart,
Stockfish-PVSvs Neural Draft & Leaderboard (README.md) — You are here- Full Technical Paper & Mathematical Proofs (
ARCHITECTURE.md) — Deep dive into Mamba-2/GQA physics,_MM_HINT_NTA,2MBHugePages STLB math,LLAMA_MOE_TOP_K=4norm preservation,RouteCrack + Stockfish-PVS v2break-even theorem, negative ablations, and Linux Kernel auditing benchmarksRouteCrack + Stockfish-PVS v2Catalog of 96+ Techniques (speculative/ROUTECRACK_TECHNIQUES.md) — How Chess-Engine PVS + Zobrist Transposition Tables unlocked 4 dormant RouteCrack techniques (M=7Singular Horizon Extension,60.40 tok/speak,mean len = 6.90)- Engineering FAQ & Xeon/EPYC Server Scaling (
FAQ.md) — SWA vs Full 256K NIAH retrieval, Mamba-2 zero-rollback gating, Stockfish-PVS L3 cache physics, and Intel Xeon Scalable / AMD EPYC multi-agent scaling- Release Notes (
RELEASE_NOTES.md) — What's new inv2.1.0(Stockfish-PVS v2 Sweet Spot, Apple Silicon M4 Pro & Fedora Ryzen 8745HS support)
1. What This Repo Does (Direct Summary & Live Production Numbers)
- The Goal: Run 30B-class Sparse MoE LLMs on a pure CPU (0 GPUs) at 20–60+ tok/s with up to a 262,144-token (256K) context window for real autonomous coding (
Claude Codewith 40 tools). - How It Works: 9 low-level C++ / Linux kernel optimizations for
llama.cpp(ggml-cpu), paired withRouteCrack + Stockfish-PVS v2 (Sweet Spot, M=7)(a draftless C++ speculative engine combining an 8-level FNV-64 hash cascade, Online Trie, Macro Codebook, and a1.64 MBL2/L3-resident Chess-Engine Principal Variation Search / Zobrist Transposition Table executing in< 0.005 ms) andllama-modchip(v0.9 Public Beta) — a "Priiloader for CPU GGUF Inference" (scripts/llama_modchip.py) that inspects any.ggufheader + CPU topology in< 5 ms, engages architecture Safety Locks, and tunesllama-serverlive via/dev/shm/llama_modchip.bin. - What Is Tested vs. Beta:
- Certified in Daily Production (
Tier 1): AMD Ryzen 9 9955HX (Zen 5, 16C/32T, Dual-CCD 64 MB L3, AVX-512 VNNI) + 64 GB DDR5 + Linux 6.8+ (2MB THP), tested across 4 real GGUF architectures (Nemotron-3.5-30B-A3Bat 256K context,Qwen3-30B-A3Bat+38.5%base decode,Nemotron-H-8B, andLlama-40L). - Public Beta & Community Platforms (
Tier 2): Auto-adaptive support for AMDZen 4 / Zen 3 / EPYC(including verifiedfedora/setup on AMD Ryzen 7 8745HSGEEKOM A8), IntelAVX2 / AVX-512CPUs, andapple-silicon/(Apple M4 Pro 24 GB Metal at47–49 tok/sup to128K).
- Certified in Daily Production (
Metric (Ryzen 9 9955HX Live Telemetry — Zero GPU) |
Stock MoE Baseline (Qwen3-30B-A3B) |
Optimized Stack (Nemotron 3.5 30B-A3B + RouteCrack + Stockfish-PVS v2) |
Improvement |
|---|---|---|---|
| Max Usable Context Window on CPU | ~14,000 tokens (Timeout >16K) | 262,144 tokens (256K) | 18.7x Larger |
Full 256K Global KV Cache (LLAMA_ATTN_WINDOW=0) |
7,078 MB (~7.1 GB) | 384–432 MB (Q4_0 / EAKV Q8/Q4) / 624 MB (static -ctk q8_0 -ctv q4_0) (Exact 6-layer GQA over 256K with _MM_HINT_NTA) |
91.2%–94.6% RAM Saved |
Hot L3 KV Working Set (LLAMA_ATTN_WINDOW=4096 SWA) |
7,078 MB (No SSM state) | 6.31–9.76 MB in 64 MB L3 (GQA capped to 4,112 tok; 46 non-attn blocks [23 Mamba-2 + 23 MoE] carry 256K state) | 100% L3-Resident |
Slot 0 Cold Snapshot Restore (22.2K tok) |
130.8 s (Full cold re-eval) | 17.2–39.3 ms (POST /slots/0?action=restore from /dev/shm) |
~6,800x Faster |
Warm Interactive TTFT (22K–35K Context) |
546.1 s | 0.40 – 0.50 s (Evaluates only user delta tokens) |
>1,000x Faster |
| Cold Prompt Prefill Throughput | < 20.0 tok/s (at 28K) | 165.2 – 241.0 tok/s (Peak: 306.8 tok/s at -b 2048) |
~8.5x Faster |
| Decode — Base Physical Floor (No Spec) | ~4.5 tok/s (at 30K) | 17.2 tok/s (at 33K ctx) / 25.3–32.7 tok/s (short ctx) |
+49% to 3.8x |
Decode — Technical Prose + New Code (27K ctx) |
~4.5 tok/s | 18.8 – 20.9 tok/s *(Peak 39.3 tok/s, 85.0% prose draft acceptance)* |
4.5x Faster |
Decode — Agent <tool_call> / JSON / XML (22.3K ctx) |
~4.5 tok/s | 28.0 – 34.52 tok/s *(Full tool turn in 1.88–2.45 s, 83.3% acceptance, mean len = 4.18)* |
6.5x Faster |
Decode — Mixed Code & Architecture Refactor (26.4K ctx) |
~4.5 tok/s | 28.61 tok/s avg / 48.47 tok/s peak (86.1% draft acceptance, mean len = 4.66) |
~7x Faster |
Decode — In-Context Refactoring & Macro Burst (M=7) |
~4.5 tok/s | 48.39 tok/s avg / 60.40–65.0 tok/s peak (96.4%–98.0% acceptance, mean len = 6.90 tok/step) |
>11x Faster |
⚡ 60-Second Quickstart (./modchip Unified CLI, Live Web HUD & Terminal Chat)
# 1. Clone & run the automated installer (builds patched llama.cpp + Stockfish-PVS & downloads GGUF):
git clone https://github.com/synchopate/nemotron-30b-cpu-256k.git && cd nemotron-30b-cpu-256k
./modchip setup # Or Bring-Your-Own-GGUF: ./modchip setup --skip-model --model /path/to/any.gguf
# 2. Start the 256K CPU Engine + Live Web Telemetry HUD in the background:
./modchip start # Or pass any GGUF: ./modchip start /path/to/model.gguf
# 3. Pick how you want to interact & verify your tok/s immediately:
./modchip chat # 💬 Interactive terminal chat with live tok/s & Stockfish-PVS telemetry
./modchip bench # 📊 30s automated 2-stage benchmark + shareable CPU scorecard
./modchip web # 🌐 Open Live Web Chat & Telemetry HUD at http://127.0.0.1:8787
./modchip claude # 🤖 Launch Claude Code CLI wired to the local 256K CPU engine
♟️ Why a 1.64 MB Stockfish Chess Engine in L3 Cache Beats a 1B Neural Draft Model on CPU
On GPUs (3,350 GB/s HBM3), running a 1B neural draft model takes < 1 ms. On a CPU (71.7 GB/s Dual-Channel DDR5), small neural draft models fail catastrophically because streaming 600 MB of 1B draft weights for 5 steps (3.0 GB from DDR5) takes 40 ms — slower than running the 30B Sparse MoE target model itself (1.8 GB active $\rightarrow 25\text{ ms}$), while completely flushing the 64 MB L3 cache!
Instead, we paired RouteCrack (an 8-level FNV-64 Hash Cascade + Online Session Trie + 11,382-entry Macro Codebook acting as an $O(1)$ candidate move generator) with StockfishDrafter (rc_stockfish.h) — a Chess-Engine Principal Variation Search (PVS) + 4-Way Bucketed Zobrist Transposition Table that lives in 1.64 MB (2.5% of L3 cache):
| Speculative Drafter Architecture (on CPU + Sparse MoE) | Memory Footprint | DDR5 Read per 5-Step Draft | Draft Latency | L3 Cache Eviction | Live 25K-Ctx Refactoring Speed (Nemotron-30B-A3B) |
|---|---|---|---|---|---|
1B Neural Draft Model (Q4_0) |
~600 MB |
3,000 MB (5 × 600 MB) |
~40.0 ms |
🔴 100% Flushed | ~11.5 tok/s (Net Slowdown vs No-Spec!) |
Vanilla llama.cpp ngram-simple |
< 1 MB |
0 MB |
0.005 ms |
🟢 0% |
~16.2 tok/s (41% wasted MoE reads + Mamba-2 rollbacks) |
RouteCrack Static Cascade (M=5) |
~14 MB |
0 MB |
0.002 ms |
🟢 < 20% |
40.91 tok/s avg / 45.43 tok/s peak (mean len = 5.47) |
♟️ RouteCrack + Stockfish-PVS v2 (M=7) |
1.64 MB Zobrist TT (+Cascade) |
0 MB (100% L2/L3) |
< 0.005 ms |
🟢 2.5% of 64MB L3 |
48.39 tok/s avg / 60.40 tok/s peak (96.4% acc, mean len = 6.90!) |
🏆 Verified Community CPU & Unified-Memory Leaderboard
Run ./modchip bench on your machine and ➕ Click Here to Submit Your CPU Scorecard (1-Click GitHub Issue) to be added to the table below!
Hardware Platform (CPU / SoC) |
Cores / CCDs / Cache | Memory Subsystem | Prompt Prefill (tok/s) |
Decode — Prose / Agent (tok/s) |
Decode — Refactor / Stockfish M=7 (tok/s) |
Contributor & Config |
|---|---|---|---|---|---|---|
AMD Ryzen 9 9955HX (Zen 5) |
16C/32T (2 CCDs, 64 MB L3, AVX-512 VNNI) |
64 GB DDR5 Dual-Ch (0 GPUs) |
241.0 *(Peak 306.8)* |
20.7 – 34.52 tok/s (85.0% acc) |
48.39 avg / 60.40 peak (mean len 6.90) |
@synchopate (Linux 256K) |
Apple M4 Pro (14-Core SoC) |
14C CPU + 20C Metal |
24 GB Unified (273 GB/s, 0 Swap) |
256.0 – 549.0 |
47.0 – 48.0 tok/s (at 128K ctx) |
49.0+ tok/s |
@jarorosFork (apple-silicon/) |
AMD Ryzen 7 8745HS (GEEKOM A8) |
8C/16T (1 CCD Zen 4, 16 MB L3, AVX-512) |
64 GB DDR5-5600 (Mini-PC) |
Verified Fedora 44 | Verified (--spec-type ngram) |
Verified (CPU & 780M) |
@jarorosFork (fedora/) |
| AMD Threadripper PRO 7985WX | 64C/128T (8 CCDs, 256 MB L3, AVX-512) |
256 GB DDR5-6000 (8-Channel) |
Testing in #1 | Auto-tuned -t 32 -tb 64 |
Submit via ./modchip bench! |
@aifartist (Issue #1) |
Your CPU (Ryzen / EPYC / Xeon / M-Series) |
Run ./modchip bench |
Any >=24 GB RAM |
? | ? | ➕ Submit Scorecard | You! |
2. llama-modchip (v0.9 Public Beta): "Priiloader for CPU GGUF Inference" & Verified Hardware/Software Matrix
Inspired by console homebrew patchers (Priiloader / hacks.ini), scripts/llama_modchip.py turns our 9 low-level C++/kernel optimizations into a generalized, safety-locked auto-profiler and /dev/shm runtime controller that operates at two complementary levels across any GGUF model:
- Startup & Graph-Construction Profile (
< 5 msGGUF + Topology Inspect): Parses the binary.ggufheader (general.architecture,ssm.*vsattention.head_count_kv,expert_count,expert_used_count,expert_weights_norm) and Linux host topology (/proc/cpuinfoISA flags,/sys/devices/system/cpu/cpu*/cache/index3L3 CCD domains, physical core IDs,2MBTHP) to configure load-time graph parameters (LLAMA_MOE_TOP_K,--repack,MADV_HUGEPAGE,1:1 Core Pinning,-ctk q8_0 -ctv q4_0). - Per-Forward-Pass Live
/dev/shm/llama_modchip.binControl: Exposes a 48-byte POSIX shared-memory control block read on every forward/draft pass byggml-cpu/ops.cppandcommon/ngram-map.cpp, enabling zero-restart runtime tuning of SWA window (attn_window), attention sinks (attn_sinks), interleaved stride (swa_stride), L3_MM_HINT_NTAboundary (l3_window), andRouteCrackcertainty gates (rc_enabled,rc_cert_d0/d1/d2). - Architecture Safety Locks: Automatically blocks optimizations that would corrupt a model's memory (e.g., blocking full 4K SWA on pure GQA Transformers and switching them to fail-closed 3:1 Interleaved SWA via
LLAMA_SWA_STRIDE=4, or locking MoE Top-K pruning on dense models).
🔬 Public Beta Disclosure: Where It Is Tested & Certified
[!IMPORTANT]
llama-modchip v0.9is currently in Public Beta. Below is the exact hardware, OS/kernel stack, and GGUF model matrix verified in production and live benchmarks, versus configurations where we are actively seeking community benchmarks.
| Category | Verified & Certified in Production (Tier 1) |
Auto-Adaptive / Community Testing (Tier 2 Beta) |
|---|---|---|
| CPU Microarchitecture | AMD Ryzen 9 9955HX (Zen 5) — 16 Physical Cores / 32 Threads, Dual-CCD (2x 32 MB = 64 MB Victim L3), AVX-512F + AVX-512_VNNI + AVX-512_BF16 + AVX2 |
AMD Zen 4 (Ryzen 7000/9000, EPYC Genoa/Turin), AMD Zen 3 (AVX2 repacking fallback), Intel Raptor/Arrow Lake & Xeon Sapphire/Emerald Rapids |
| Memory & Cache Subsystem | 64 GB DDR5 Dual-Channel (~71.7 GB/s sustained multi-core read), 2MB Transparent HugePages = always / defer+madvise, POSIX /dev/shm |
32 GB – 512 GB DDR5 (Dual / Quad / 8-Channel / 12-Channel), 128 GB Mini-PCs for hybrid RAM+NVMe MoE |
| OS, Kernel & Engine | Linux Kernel 6.8+ (Debian 12 / Proxmox LXC), GCC 12+, llama.cpp (commit d2f83055 + zen5-nemotron-256k-optimizations.patch) |
Ubuntu 22.04/24.04, Fedora, Arch, WSL2 (with .wslconfig THP enabled) |
| Agentic Clients | Claude Code CLI (40 tools, 22.3K–35K active context via gateway/sse_gateway.py) |
OpenAI-compatible SSE clients (Aider, Continue, Cline, OpenHands) |
📊 Live Multi-Model Verification Matrix (python3 scripts/llama_modchip.py --audit)
Tested GGUF Model (Ryzen 9 9955HX) |
GGUF Arch & Layers | KV / Token (Q8_0/Q4_0 EAKV) |
Auto L3_WINDOW ($\le 25%$ L3) |
Safety-Locked SWA Policy (LLAMA_SWA_STRIDE) |
RouteCrack Gate |
MoE Top-K Pruning (LLAMA_MOE_TOP_K) |
Verified Result |
|---|---|---|---|---|---|---|---|
NVIDIA-Nemotron-3.5-30B-A3B-Q4_0.gguf (17.60 GiB) |
nemotron_h_moe (23 Mamba-2 + 23 MoE + 6 GQA) |
2.44 KB/tok (1.73 KB in Q4/Q4) |
2048 tok (4.88 MiB) |
🟢 Full SWA (stride=1) (All 6 GQA layers) |
Strict (84/92/96) |
🟢 6 -> 4 (norm=True, -33% DRAM) |
256K Production (20–50+ tok/s, 306.8 tok/s prefill) |
qwen3-30b-a3b.gguf (17.28 GiB) |
qwen3moe (0 SSM + 48 GQA) |
39.00 KB/tok (27.65 KB in Q4/Q4) |
384 tok (14.62 MiB) |
🟡 Safety Lock 3:1 (stride=4) (36 SWA + 12 Global) |
CPU-MoE (80/90/95) |
🟢 8 -> 4 (norm=True in qwen3moe.cpp:144, -50% DRAM) |
25.12 -> 34.80 tok/s (+38.5% decode), 224.1 tok/s pp512 |
nvidia_Nemotron-H-8B-Reasoning-128K.gguf (4.64 GiB) |
nemotron_h (48 SSM + 4 GQA) |
6.50 KB/tok |
2048 tok (13.00 MiB) |
🟢 Full SWA (stride=1) (All 4 GQA layers) |
Strict (84/92/96) |
⚪ LOCKED (Dense, 0 Experts) | Verified (147.6 tok/s prefill, 128K context) |
security-specialist-q8.gguf (23.33 GiB) |
llama (0 SSM + 40 GQA) |
65.00 KB/tok |
256 tok (16.25 MiB) |
🟡 Safety Lock 3:1 (stride=4) (30 SWA + 10 Global) |
Balanced (78/88/94) |
⚪ LOCKED (Dense, 0 Experts) | Verified (L3 protected from 65 KB/tok KV bloat) |
Run the 1-Command Hardware Check & llama-modchip Inspector:
# 1. Zero-dependency CPU readiness & DRAM bandwidth estimator (no GGUF required):
curl -sL https://raw.githubusercontent.com/synchopate/nemotron-30b-cpu-256k/main/scripts/check_cpu_readiness.py | python3
# 2. Inspect ANY GGUF model, apply live /dev/shm/llama_modchip.bin hooks & print optimal launch command:
python3 scripts/llama_modchip.py --model /path/to/model.gguf --apply-shm --print-cmd
# 3. Run 1-command A/B benchmark (Stock vs llama-modchip), multi-model audit, or interactive Curses TUI:
python3 scripts/llama_modchip.py --model /path/to/model.gguf --bench
python3 scripts/llama_modchip.py --audit model1.gguf model2.gguf
python3 scripts/llama_modchip.py --model /path/to/model.gguf --tui
3. The 9 Microarchitectural Optimizations (llama-modchip Stack)
Every single optimization is documented with full mathematical derivations and C/C++ code in ARCHITECTURE.md (§3.1–§3.10) and controlled at runtime by scripts/llama_modchip.py:
- Architecture-Aware Sliding Window Attention + 16 Sinks (
LLAMA_ATTN_WINDOW=0vs4096,LLAMA_SWA_STRIDE) (ARCHITECTURE.md§3.1 & §3.10)- Full 256K Exact Mode (
LLAMA_ATTN_WINDOW=0, Default insystemd/nemotron-256k.service) vs. SWA Mode (LLAMA_ATTN_WINDOW=4096,LLAMA_SWA_STRIDE=1): SettingLLAMA_ATTN_WINDOW=0retains exact 6-layer GQA attention across all 262,144 tokens (occupying 384 MB raw / 432 MB in symmetricQ4_0/Q4_0at1.73 KB/tok, ~432 MB in dynamic entropy-gated EAKVQ8_0/Q4_0, or 624 MB in static--cache-type-k q8_0 --cache-type-v q4_0at2.44 KB/tok, streamed via_MM_HINT_NTA). SettingLLAMA_ATTN_WINDOW=4096bounds GQA attention to[0..15] U [cur_pos-4096..cur_pos](6.31–9.76 MBhot working set inside L3), relying on the 46 non-attention blocks (23 Mamba-2 SSM + 23 Sparse MoE) for >4K global state. - On Pure GQA (
Qwen3-30B-A3B,Llama):llama-modchipengages a Safety Lock (LLAMA_SWA_STRIDE=4) — applying L3 SWA to 3 out of 4 layers (75%) while keeping every 4th layer (25%) at full 256K global attention.
- Full 256K Exact Mode (
- Bidirectional L3 Cache Isolation via
_MM_HINT_NTA(LLAMA_KV_L3_WINDOW=2048) (ARCHITECTURE.md§3.2)
Distinct fromLLAMA_ATTN_WINDOW(which bounds the attention horizon),LLAMA_KV_L3_WINDOW=2048controls the hardware cache-line prefetch hint insideggml-cpu/ops.cpp: recent KV tokens withinLLAMA_KV_L3_WINDOWare prefetched with temporal_MM_HINT_T0(kept warm in L3), while older KV blocks and the 1.88 GB/token MoE weight stream inarch/x86/quants.cuse non-temporal_MM_HINT_NTA(LLAMA_KV_L3_WINDOWauto-sized to $\le 25%$ of L3 capacity). - ISA-Adaptive In-Memory Weight Tile Repacking (
--repack/q4_0_8x8) (ARCHITECTURE.md§3.3)
Eliminates 30% bit-unpacking overhead via single-cycleVPDPBUSD(AVX-512 VNNI) orAVX2matrix tiles (+19%GEMV/GEMM). - 2MB Transparent HugePages (
MADV_HUGEPAGEArena + MMap) (ARCHITECTURE.md§3.4)
Collapses 4.9M 4KB pages into ~9,300 2MB pages (19.04 GiB), expanding per-core L2 STLB coverage from 12 MB to 6.14 GB and eliminating 24% page-table walk overhead across sparse MoE jumps. - Dual-CCD 1:1 Physical Core Pinning + Static GQA Partition (
LLAMA_KV_DISABLE_CHUNKING=1) (ARCHITECTURE.md§3.5)
Locks OpenMP threads 1:1 to non-SMT physical cores (OMP_PROC_BIND=close,OMP_PLACES=cores), eliminating SMT contention and 40ns cross-CCD Infinity Fabric L3 snoops (306.8 tok/sprefill). - Draftless C++ Speculative Engine (
RouteCrack + Stockfish-PVS v2via--spec-type ngram-simple --spec-ngram-simple-size-m 7) (ARCHITECTURE.md§3.6 ·speculative/ROUTECRACK_TECHNIQUES.md)common/ngram-map.cppoverridescommon_ngram_simple_draft()to hijack--spec-type ngram-simpleand execute the L3-resident C++RouteCrack + Stockfish-PVS v2ensemble (speculative/cpp/rc_stockfish.h,speculative/cpp/rc_predictor.h,speculative/cpp/rc_trie_v2.h:8-level FNV-64 Hash Cascade + Online Session Trie Rescue + 11,382-Entry Macro Codebook + Chess-Engine Principal Variation Search / Zobrist Transposition Table + Two-Zone 16K Hot / 24K Prefix Matcher, loaded fromRC_TABLES_DIR) in< 0.005 msinside1.64 MBof L2/L3 cache. By cross-validating statistical predictions against the live-session Zobrist TT (tt5/tt4/tt3+ Countermove + Continuation History),Stockfish-PVS v2unlocks 4 dormantRouteCracktechniques (including Singular Horizon ExtensionM=7), delivering+223accepted tokens with0extra wasted tokens (-32Mamba-2 rollbacks) on our77,456-token held-out benchmark and reaching48.39 tok/saverage /60.40 tok/speak (mean len = 6.90tokens/step,96.4%acceptance) on live 25K-context code refactoring and85.0%draft acceptance on technical prose! - Entropy-Guided Asymmetric KV Quantization (
EAKV+VPI,-ctk q8_0 -ctv q4_0) (ARCHITECTURE.md§3.7)
Cuts KV cache memory footprint and DRAM bandwidth by 58%–62.5% (384 MBraw /432 MBin symmetricQ4_0,~432 MBin dynamic EAKVQ8_0/Q4_0, and624 MBin static--cache-type-k q8_0 --cache-type-v q4_0across all 262,144 tokens) while preservingFP16-equivalent needle retrieval on keys. - Zero-Prefill Agentic Loops (
HARP-CachePrefix Tracker + Native/dev/shmSlot Restore + SSE Gateway) (ARCHITECTURE.md§3.8)
Separates gateway-level prefix tracking from native C++ tensor persistence:kv_cache/harp_cache.pyprovides the gateway's 32-token FNV-1a Radix Tree & bounded/dev/shmLRU page tracker (and standalone algorithmic reference), whilellama-server --slot-save-path /dev/shm --cache-reuse 256(scripts/prewarm_agent_prefix.py+_ensure_slot0_restored()ingateway/sse_gateway.py) performs native C++ serialization/restoration of the85 MBMamba-2 + GQA state in17.2–18.9 ms. - Norm-Preserving Dynamic MoE Top-K Pruning (
LLAMA_MOE_TOP_K=4) (ARCHITECTURE.md§3.9)- On
Nemotron-3.5-30B-A3B(🟢 SAFE): Prunes active routed experts from6 -> 4(8 -> 6total expert-units including the double-width shared expert,-33.3%routed MoE DRAM traffic). Becauseexpert_weights_norm=True(scale=2.5),llama.cppautomatically renormalizes the surviving 4 gates to sum to1.0 * 2.5. - On
Qwen3-30B-A3B&Qwen3.5-MoE(🟢 SAFE): Prunes routed experts from8 -> 4(-50%routed MoE DRAM traffic,+38.5%decode). Even though the GGUF converter omitsqwen3moe.expert_weights_norm,llama.cpphardcodesnorm_w = true(LLM_FFN_SILU, true) insidesrc/models/qwen3moe.cpp:144(build_moe_ffn) (weights = ggml_div(ctx0, weights, weights_sum)), automatically renormalizing the surviving 4 experts so $\sum_{i=1}^{4} \tilde{g}_i = 1.0$ without L2 norm collapse! Auto-locked on Dense models.
- On
4. Quickstart & Reproducible Setup
Option A: 1-Command Automated Installer (Starting from Zero)
If you are starting from a fresh Linux machine, install.sh automates the entire stack end-to-end:
- Runs the hardware readiness audit (
scripts/check_cpu_readiness.py), checks/installs system build tools (cmake,g++,openmp), and configures2MBTransparent HugePages. - Clones
llama.cppat the tested commit (d2f83055), appliespatches/zen5-nemotron-256k-optimizations.patch, injects the nativeRouteCrackC++ engine (speculative/cpp/), and compilesllama-serverwith auto-detected SIMD flags (AVX-512 VNNI+BF16orAVX2). - Downloads
NVIDIA-Nemotron-3.5-Lightning-30B-A3B-Q4_0.gguf(17.60 GiB, auto-resumable) from Hugging Face (or links your existing GGUF via--model /path/to/model.gguf). - Tokenizes a local coding +
<tool_call>corpus against the 131K Nemotron vocabulary and builds the 8-levelRouteCrackFNV-64 hash cascade, hot token rules, and macro codebook. - Generates auto-tuned
./start_server.shand./start_gateway.shscripts matched to your physical core count and RAM.
# One-liner from scratch:
curl -sL https://raw.githubusercontent.com/synchopate/nemotron-30b-cpu-256k/main/install.sh | bash
# Or clone and use the unified ./modchip CLI:
git clone https://github.com/synchopate/nemotron-30b-cpu-256k.git
cd nemotron-30b-cpu-256k
./modchip setup # Or custom corpus: ./modchip setup --corpus /path/to/codebase
./modchip start # Starts server (8789) + Web UI & SSE Gateway (8787) in background
# Verify speed & chat immediately (Terminal, Browser Web HUD, Benchmark, or curl):
./modchip chat # Interactive terminal chat with live tok/s footer
./modchip bench # Automated 2-stage benchmark + shareable CPU scorecard
./modchip web # Opens http://127.0.0.1:8787 (Dark-Mode Web Chat + Live Telemetry HUD)
./modchip claude # Launches Claude Code CLI wired to local 256K CPU engine
# Or test directly with a 1-line curl smoke test:
./modchip chat -p "Write a cache-aligned C++20 spinlock in 15 lines."
Option B: Manual Step-by-Step Build
Step 1: Enable 2MB Transparent HugePages (Linux Host)
echo always | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
echo defer+madvise | sudo tee /sys/kernel/mm/transparent_hugepage/defrag
sudo cp systemd/thp-llm.conf /etc/tmpfiles.d/thp-llm.conf
Step 2: Build llama.cpp with Zen 5 / AVX-512 Patch & RouteCrack Engine
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
git apply /path/to/nemotron-30b-cpu-256k/patches/zen5-nemotron-256k-optimizations.patch
# Integrate the native RouteCrack + Stockfish-PVS C++ predictor into common/
cp /path/to/nemotron-30b-cpu-256k/speculative/cpp/rc_predictor.h common/
cp /path/to/nemotron-30b-cpu-256k/speculative/cpp/rc_trie_v2.h common/
cp /path/to/nemotron-30b-cpu-256k/speculative/cpp/rc_stockfish.h common/
cp /path/to/nemotron-30b-cpu-256k/speculative/cpp/ngram-map.cpp common/
cmake -B build \
-DCMAKE_BUILD_TYPE=Release \
-DGGML_NATIVE=ON \
-DGGML_AVX512=ON \
-DGGML_AVX512_VNNI=ON \
-DGGML_AVX512_VBMI=ON \
-DGGML_AVX512_BF16=ON \
-DGGML_OPENMP=ON
cmake --build build --config Release -j $(nproc) --target llama-server
Step 3: Build Native Nemotron RouteCrack Tables (Optional Custom Corpus)
g++ -O3 -std=c++17 speculative/cpp/rc_tokenize_nemotron.cpp -o rc_tokenize_nemotron \
-I/path/to/llama.cpp/include -I/path/to/llama.cpp/ggml/include \
-L/path/to/llama.cpp/build/bin -lllama -Wl,-rpath,/path/to/llama.cpp/build/bin
g++ -O3 -std=c++17 speculative/cpp/rc_build_tables.cpp -o rc_build_tables
./rc_tokenize_nemotron ./workspace/models/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-Q4_0.gguf \
train.txt ./workspace/routecrack/corpus_nemotron_train.bin
./rc_build_tables ./workspace/routecrack/corpus_nemotron_train.bin ./workspace/routecrack
Step 4: Launch Production Service & Instant Slot 0 Pre-Warmer
See systemd/nemotron-256k.service and scripts/prewarm_agent_prefix.py for the complete systemd units.
5. Repository Structure
nemotron-30b-cpu-256k/
├── LICENSE # Apache 2.0 License
├── modchip # Unified CLI (setup | start | chat | bench | web | claude | stop)
├── install.sh # 1-Command Zero-to-Running Automated Installer
├── README.md # Executive Overview, Quickstart & Hardware Check
├── ARCHITECTURE.md # Full Technical Paper, Proofs & Kernel Benchmarks
├── FAQ.md # Engineering Trade-Offs, NIAH Retrieval & Xeon/EPYC Scaling
├── RELEASE_NOTES.md # Detailed Release Notes (v2.1.0 Stockfish-PVS v2 & Multi-Platform)
├── patches/
│ └── zen5-nemotron-256k-optimizations.patch # Unified C/C++ Patch for llama.cpp (ggml-cpu)
├── speculative/ # RouteCrack + Stockfish-PVS Draftless Speculative Engine
│ ├── ROUTECRACK_TECHNIQUES.md # Master Catalog of 96+ Studied RouteCrack Techniques & PVS v2 Ablations
│ ├── cpp/
│ │ ├── ngram-map.cpp # Drop-in llama-server integration (RouteCrack + Stockfish-PVS v2 M=7)
│ │ ├── rc_stockfish.h # 1.64 MB L2/L3 Chess-Engine PVS + Zobrist TT (tt5/tt4/tt3) + Countermove
│ │ ├── rc_predictor.h # 8-Level Hash Cascade, Online Trie, PPM, Skipgram, Hot Rules, Probes
│ │ ├── rc_trie_v2.h # 4M-Node Arena Online Learning Trie (O(1) lookup, LRU eviction)
│ │ ├── rc_tokenize_nemotron.cpp # Native GGUF vocabulary corpus tokenizer (131,072 tokens)
│ │ ├── rc_build_tables.cpp # Laplace-smoothed cascade, hot rules & macro codebook builder
│ │ ├── test_synergy.cpp # 3-Way Held-out benchmark (77,456 tok: Baseline vs PVS v1 vs PVS v2 M=7)
│ │ └── rc_engine.cpp # Standalone C++ Speculative Engine with BFS Tree Verification
│ └── tools/ # Linear & Hot-Logit Probe trainers and distillation scripts
├── kv_cache/ # HARP-Cache (/dev/shm) & EAKV + VPI Asymmetric Quantization
├── gateway/ # Agentic SSE Reverse Proxy + Live Web Chat & Telemetry HUD (sse_gateway.py)
├── scripts/
│ ├── chat.py # Zero-dependency Interactive Terminal Chat & 2-Stage Benchmark Scorecard
│ ├── llama_modchip.py # "Priiloader for CPU LLM" (GGUF Inspector, Safety Lock & Live SHM TUI)
│ ├── check_cpu_readiness.py # Zero-dependency CPU compatibility & tok/s estimator script
│ ├── prewarm_agent_prefix.py # 18.9ms Slot 0 disk snapshot restore & prefix pre-warmer
│ ├── build_zen5_llama.sh # CMake build script for Zen 5 AVX-512 VNNI
│ └── fill_kv_cache_256k.py # 256K context scaling & TTFT stress test
├── systemd/ # Production systemd unit & 2MB Transparent HugePages config
├── apple-silicon/ # Apple M4 Pro (24 GB) Metal setup, scripts & 128K benchmarks
├── fedora/ # Fedora 44 / AMD Ryzen 7 8745HS (GEEKOM A8) setup & web chat script
├── benchmarks/ # Detailed KV scaling & Hybrid SSM vs Dense GQA reports
└── reviews/ # Microarchitectural audit & 4-Case Kernel Code Auditing evaluation
🔗 Continue Reading:
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found