Add conditional full-attention KV comparison

README.md

@@ -41,6 +41,8 @@ Explore two different architectures with real Q8_0 tensor captures: Flint's spar
 
 [**Explore the layer map**](https://alphabell-model-observatory.static.hf.space/architecture/index.html) to compare Nanbeige4.3-33B's 52 full-attention layers with the Qwen3.8-27B text decoder's 48 recurrent linear and 16 full-attention layers. This comparison uses published configurations; the measured captures in this Space are Flint and Qwen.
 
+The page also calculates raw f16 full-attention K/V storage across context lengths if a runtime enables caching. Nanbeige's released config sets `use_cache: false`, so this is a conditional calculation rather than measured default memory use.
+
 [Read the architecture explainer](https://huggingface.co/blog/alphabell/nanbeige-qwen-layer-map) for pinned sources and a matched runtime test that could measure how context length affects each model.
 
 ## Five measured experiments

architecture/comparison.css

@@ -24,7 +24,7 @@ h1 em{font-style:normal;color:var(--green)}
 .scope{display:flex;align-items:flex-start;gap:10px;max-width:830px;padding:14px 17px;background:#edf3ec;border:1px solid #d8e6d9;border-radius:9px;color:#4b6658;font-size:12px;line-height:1.5}
 .scope strong{white-space:nowrap;color:var(--green)}
 .scope-dot{flex:none;margin-top:5px;width:7px;height:7px;border-radius:50%;background:var(--green)}
-section.overview,section.layers,section.source{border-top:1px solid var(--line);padding-top:38px;margin-top:18px}
+section.overview,section.kv,section.layers,section.source{border-top:1px solid var(--line);padding-top:38px;margin-top:18px}
 .section-heading{margin-bottom:24px}
 .section-heading .eyebrow{margin-bottom:8px}
 .section-heading h2{font-size:clamp(27px,3.2vw,37px);letter-spacing:-.045em;margin-bottom:10px}
@@ -49,6 +49,25 @@ section.overview,section.layers,section.source{border-top:1px solid var(--line);
 .spec-table thead th{color:var(--muted);font-size:10px;letter-spacing:.1em;text-transform:uppercase}
 .spec-table tbody th{font-weight:550;width:42%}
 .spec-table tbody td{font-variant-numeric:tabular-nums;font-weight:650}
+.kv-panel{background:#fff;border:1px solid var(--line);border-radius:12px;padding:24px}
+.kv-control-heading{display:flex;justify-content:space-between;align-items:baseline;gap:12px;margin-bottom:14px}
+.kv-control-heading label{font-weight:700;font-size:14px}
+.kv-control-heading output{font-weight:750;font-size:18px;font-variant-numeric:tabular-nums;color:var(--green)}
+.kv-control input{display:block;width:100%;accent-color:var(--green);cursor:pointer}
+.kv-endpoints{display:flex;justify-content:space-between;color:var(--muted);font-size:11px;margin-top:6px}
+.kv-share{font-size:11px;color:var(--muted);margin:8px 0 0;text-align:right}
+.kv-results{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:28px}
+.kv-result{min-width:0;border:1px solid var(--line);border-top:4px solid var(--green);border-radius:10px;background:#fafcf9;padding:19px 21px;display:flex;flex-direction:column;gap:4px}
+.kv-result.qwen-kv{border-top-color:var(--blue);background:#f9fcfd}
+.kv-result p{font-size:12px;font-weight:700;color:var(--muted);margin:0 0 5px}
+.kv-result strong{font-size:clamp(31px,4vw,45px);letter-spacing:-.055em;line-height:1.1;font-variant-numeric:tabular-nums}
+.kv-result span{font-size:15px;font-weight:650;font-variant-numeric:tabular-nums}
+.kv-result small{font-size:11px;color:var(--muted);font-variant-numeric:tabular-nums;margin-top:7px}
+.kv-ratio{font-size:13px;font-weight:750;color:var(--green);margin:19px 0 0}
+.kv-formula{font-size:12px;font-weight:600;color:#435e53;margin:13px 0 0;line-height:1.5}
+.kv-scope{font-size:12px;line-height:1.65;color:#526a5f;margin:12px 0 0;max-width:880px}
+.kv-scope code{background:#e9efe7;padding:2px 4px;border-radius:3px}
+.kv-scope a{color:var(--green);font-weight:700}
 .legend{display:flex;gap:24px;flex-wrap:wrap;font-size:12px;font-weight:650;margin-bottom:16px}
 .legend span{display:inline-flex;align-items:center;gap:8px}
 .swatch{width:12px;height:12px;border-radius:3px;display:inline-block}
@@ -90,7 +109,7 @@ footer a{color:var(--green);font-weight:650;text-decoration:none}
 .scope{display:grid;grid-template-columns:8px 1fr;gap:3px 10px}
 .scope span:last-child{grid-column:2}
 .scope-dot{margin-top:5px}
-.overview-grid,.map-pair{grid-template-columns:1fr}
+.overview-grid,.map-pair,.kv-results{grid-template-columns:1fr}
 .model-card{min-height:220px}
 .inspect dl{grid-template-columns:repeat(2,minmax(0,1fr))}
 }
@@ -113,6 +132,10 @@ footer a{color:var(--green);font-weight:650;text-decoration:none}
 .inspect dl{gap:7px}
 .inspect dl>div{padding:10px}
 .inspect dd{font-size:13px}
+.kv-panel{padding:16px}
+.kv-control-heading{display:block}
+.kv-control-heading output{display:block;margin-top:4px}
+.kv-result{padding:16px}
 footer{display:block;padding-left:16px;padding-right:16px}
 footer a{display:block;margin-top:8px}
 }

architecture/comparison.js

@@ -9,6 +9,7 @@ const fmt = value => new Intl.NumberFormat('en-US').format(value);
 const byId = id => document.getElementById(id);
 const configs = {};
 let selected = { model: 'qwen', layer: 3 };
+let kvLengths = [];
 
 function attentionType(model, layer) {
   if (model === 'nanbeige') return 'full';
@@ -35,7 +36,7 @@ function renderSpecs() {
   byId('qwen-layer-count').textContent = `${linear} + ${full}`;
   const rows = [
     ['Decoder layers', fmt(n.num_hidden_layers), fmt(q.num_hidden_layers)],
-    ['Attention pattern', '52 full', `${linear} recurrent linear / ${full} full`],
+    ['Attention pattern', `${n.num_hidden_layers} full`, `${linear} recurrent linear / ${full} full`],
     ['Hidden width', fmt(n.hidden_size), fmt(q.hidden_size)],
     ['Dense feed-forward width', fmt(n.intermediate_size), fmt(q.intermediate_size)],
     ['Full-attention query heads', fmt(n.num_attention_heads), fmt(q.num_attention_heads)],
@@ -46,6 +47,42 @@ function renderSpecs() {
   byId('spec-body').replaceChildren(...rows.map(row => specRow(...row)));
 }
 
+function renderKv() {
+  const control = byId('kv-step');
+  const tokens = kvLengths[Number(control.value)];
+  control.setAttribute('aria-valuetext', `${fmt(tokens)} tokens`);
+  byId('kv-context-label').textContent = `${fmt(tokens)} tokens`;
+  const values = {};
+  for (const [model, prefix] of [['nanbeige', 'nan'], ['qwen', 'qwen']]) {
+    const bytes = window.kvCache.fullAttentionKvBytes(configs[model], tokens);
+    const perToken = window.kvCache.fullAttentionKvBytes(configs[model], 1);
+    values[model] = bytes;
+    byId(`kv-${prefix}-gb`).textContent = `${(bytes / 1e9).toFixed(2)} GB`;
+    byId(`kv-${prefix}-gib`).textContent = `${(bytes / 2 ** 30).toFixed(2)} GiB`;
+    byId(`kv-${prefix}-per-token`).textContent = `${fmt(perToken / 1024)} KiB per token`;
+  }
+  byId('kv-ratio').textContent = `${(values.nanbeige / values.qwen).toFixed(2)}× Nanbeige-to-Qwen ratio for this calculated component`;
+}
+
+function initKv() {
+  if (!window.kvCache || configs.nanbeige.use_cache !== false) throw new Error('Unexpected KV source configuration');
+  const max = Math.min(configs.nanbeige.max_position_embeddings, configs.qwen.max_position_embeddings);
+  kvLengths = [2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144].filter(tokens => tokens <= max);
+  if (!kvLengths.length) throw new Error('No common context length');
+  const control = byId('kv-step');
+  control.max = String(kvLengths.length - 1);
+  const requested = Number(new URLSearchParams(window.location.search).get('tokens'));
+  const requestedIndex = kvLengths.indexOf(requested);
+  control.value = String(requestedIndex >= 0 ? requestedIndex : Math.min(4, kvLengths.length - 1));
+  control.addEventListener('input', () => {
+    renderKv();
+    const url = new URL(window.location.href);
+    url.searchParams.set('tokens', String(kvLengths[Number(control.value)]));
+    window.history.replaceState(null, '', url);
+  });
+  renderKv();
+}
+
 function fact(label, value) {
   const group = document.createElement('div');
   const dt = document.createElement('dt');
@@ -110,12 +147,14 @@ async function init() {
     for (const [model, config] of entries) configs[model] = config;
     if (configs.nanbeige.num_hidden_layers !== 52 || configs.qwen.layer_types.length !== configs.qwen.num_hidden_layers) throw new Error('Unexpected decoder configuration');
     renderSpecs();
+    initKv();
     renderMap('nanbeige');
     renderMap('qwen');
     renderSelection();
   } catch (error) {
     byId('inspect-title').textContent = 'The comparison could not open';
     byId('inspect-description').textContent = 'Reload this page to try the model configurations again.';
+    byId('kv-context-label').textContent = 'Calculation unavailable';
     console.error('Architecture comparison failed', error);
   }
 }

architecture/index.html

@@ -8,6 +8,7 @@
   <title>Nanbeige and Qwen architecture | alphaBell</title>
   <link rel="icon" href="../favicon.svg">
   <link rel="stylesheet" href="comparison.css">
+  <script src="kv-cache.js" defer></script>
   <script src="comparison.js" defer></script>
 </head>
 <body>
@@ -17,7 +18,7 @@
   </header>
   <main>
     <section class="intro" aria-labelledby="page-title">
-      <p class="eyebrow">Architecture comparison <span>01 / 02</span></p>
+      <p class="eyebrow">Architecture comparison <span>01 / 03</span></p>
       <h1 id="page-title">Two dense decoders.<br><em>Different paths through a token.</em></h1>
       <p class="lead">Nanbeige repeats full attention in 52 layers. Qwen alternates recurrent linear attention with full attention across 64 text-decoder layers. Explore the published configuration, one layer at a time.</p>
       <div class="scope"><span class="scope-dot" aria-hidden="true"></span><strong>Configuration view</strong><span>Layer types and dimensions come from pinned model configs. Nanbeige weights, activations and routing were not measured here.</span></div>
@@ -40,8 +41,22 @@
       <div class="spec-wrap"><table class="spec-table"><caption>Published decoder configuration</caption><thead><tr><th scope="col">Configuration</th><th scope="col">Nanbeige</th><th scope="col">Qwen text decoder</th></tr></thead><tbody id="spec-body"></tbody></table></div>
     </section>
 
+    <section class="kv" aria-labelledby="kv-title">
+      <div class="section-heading"><p class="eyebrow">02 / Cache lens</p><h2 id="kv-title">How full-attention K/V would scale</h2><p>Choose a context length to calculate raw f16 key and value tensor storage for one sequence if an inference runtime enables caching.</p></div>
+      <div class="kv-panel">
+        <div class="kv-control"><div class="kv-control-heading"><label for="kv-step">Context length</label><output id="kv-context-label" for="kv-step" aria-live="polite">32,768 tokens</output></div><input id="kv-step" type="range" min="0" max="7" step="1" value="4" aria-describedby="kv-scope"><div class="kv-endpoints"><span>2K tokens</span><span>256K tokens</span></div><p class="kv-share">Copy the page URL to share this context.</p></div>
+        <div class="kv-results">
+          <article class="kv-result nanbeige-kv"><p>Nanbeige4.3-33B</p><strong id="kv-nan-gb" aria-live="polite"></strong><span id="kv-nan-gib"></span><small id="kv-nan-per-token"></small></article>
+          <article class="kv-result qwen-kv"><p>Qwen3.8-27B text decoder</p><strong id="kv-qwen-gb" aria-live="polite"></strong><span id="kv-qwen-gib"></span><small id="kv-qwen-per-token"></small></article>
+        </div>
+        <p class="kv-ratio" id="kv-ratio"></p>
+        <p class="kv-formula">Formula: tokens × full-attention layers × 2 (K and V) × KV heads × head dimension × 2 bytes.</p>
+        <p class="kv-scope" id="kv-scope">Calculation scope: one sequence, f16 K and V for full-attention layers. Nanbeige's released model and <a href="https://huggingface.co/Nanbeige/Nanbeige4.3-33B/blob/c1093c501cc6460427c0ac634db7223d0450c0ee/generation_config.json" target="_blank" rel="noopener noreferrer">generation config</a> set <code>use_cache: false</code>, so its number applies when a runtime enables caching. Qwen's recurrent layers maintain separate state; weights and runtime overhead are separate.</p>
+      </div>
+    </section>
+
     <section class="layers" aria-labelledby="layers-title">
-      <div class="section-heading"><p class="eyebrow">02 / Layer map</p><h2 id="layers-title">Follow the stack</h2><p>Each square is one configured decoder layer. Select a layer to inspect its attention and feed-forward dimensions.</p></div>
+      <div class="section-heading"><p class="eyebrow">03 / Layer map</p><h2 id="layers-title">Follow the stack</h2><p>Each square is one configured decoder layer. Select a layer to inspect its attention and feed-forward dimensions.</p></div>
       <div class="legend" aria-label="Layer colors"><span><i class="swatch full"></i>Full attention</span><span><i class="swatch linear"></i>Recurrent linear attention</span></div>
       <div class="map-pair">
         <div class="map-card"><div class="map-title"><h3>Nanbeige</h3><span>52 layers</span></div><div class="layer-grid" id="nanbeige-grid" role="group" aria-label="Nanbeige layers"></div></div>

architecture/kv-cache.js

@@ -0,0 +1,22 @@
+'use strict';
+
+function fullAttentionLayers(config) {
+  if (Array.isArray(config.layer_types)) {
+    return config.layer_types.filter(type => type === 'full_attention').length;
+  }
+  return config.num_hidden_layers;
+}
+
+function fullAttentionKvBytes(config, tokens, bytesPerValue = 2) {
+  const layers = fullAttentionLayers(config);
+  for (const value of [layers, config.num_key_value_heads, config.head_dim, tokens, bytesPerValue]) {
+    if (!Number.isSafeInteger(value) || value < 1) throw new RangeError('Invalid KV calculation input');
+  }
+  const bytes = tokens * layers * 2 * config.num_key_value_heads * config.head_dim * bytesPerValue;
+  if (!Number.isSafeInteger(bytes)) throw new RangeError('KV calculation exceeds safe integer range');
+  return bytes;
+}
+
+const kvCache = { fullAttentionLayers, fullAttentionKvBytes };
+if (typeof module !== 'undefined' && module.exports) module.exports = kvCache;
+else window.kvCache = kvCache;

tests/architecture.test.cjs

@@ -4,6 +4,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { fullAttentionLayers, fullAttentionKvBytes } = require('../architecture/kv-cache.js');
 const root = path.resolve(__dirname, '..');
 const read = file => fs.readFileSync(path.join(root, file), 'utf8');
 const n = JSON.parse(read('models/nanbeige.json'));
@@ -19,9 +20,22 @@ test('the pinned Nanbeige configuration supports the displayed comparison', () =
   assert.equal(n.num_key_value_heads, 8);
   assert.equal(n.head_dim, 128);
   assert.equal(n.max_position_embeddings, 524288);
+  assert.equal(n.use_cache, false);
   assert.equal(n.num_experts, undefined);
 });
 
+test('conditional f16 full-attention KV sizes use the pinned layer and head dimensions', () => {
+  assert.equal(fullAttentionLayers(n), 52);
+  assert.equal(fullAttentionLayers(q), 16);
+  assert.equal(fullAttentionKvBytes(n, 1), 212992);
+  assert.equal(fullAttentionKvBytes(q, 1), 65536);
+  assert.equal(fullAttentionKvBytes(n, 32768), 6979321856);
+  assert.equal(fullAttentionKvBytes(q, 32768), 2147483648);
+  assert.equal(fullAttentionKvBytes(n, 262144), 55834574848);
+  assert.equal(fullAttentionKvBytes(q, 262144), 17179869184);
+  assert.throws(() => fullAttentionKvBytes(n, 0), RangeError);
+});
+
 test('the pinned Qwen text decoder has three linear layers for each full layer', () => {
   assert.equal(q.model_type, 'qwen3_5_text');
   assert.equal(q.layer_types.length, q.num_hidden_layers);
@@ -38,14 +52,17 @@ test('the architecture route is linked and ships its local assets', () => {
   const home = read('index.html');
   const html = read('architecture/index.html');
   assert.match(home, /href="architecture\/index\.html"/);
-  for (const file of ['architecture/comparison.css', 'architecture/comparison.js', 'models/nanbeige.json', 'models/qwen.json']) {
+  for (const file of ['architecture/comparison.css', 'architecture/comparison.js', 'architecture/kv-cache.js', 'models/nanbeige.json', 'models/qwen.json']) {
     assert.ok(fs.statSync(path.join(root, file)).size > 0, file);
   }
   assert.match(html, /Nanbeige.*?config/s);
   assert.match(html, /c1093c501cc6460427c0ac634db7223d0450c0ee/);
   assert.match(html, /1d4bf0f2ff6012fd82039f2fa52739d0dd7c60c0/);
   assert.match(html, /Nanbeige weights, activations and routing were not measured here/);
-  for (const text of [html, read('architecture/comparison.js'), read('architecture/comparison.css')]) {
+  assert.match(html, /use_cache: false/);
+  assert.match(html, /generation_config\.json/);
+  assert.match(html, /if an inference runtime enables caching/);
+  for (const text of [html, read('architecture/comparison.js'), read('architecture/comparison.css'), read('architecture/kv-cache.js')]) {
     assert.doesNotMatch(text, /\u2014|—|—|—/i);
   }
 });