// SPDX-License-Identifier: Apache-2.0 // Copyright (c) 2026 UtopiaIA // Elffuss Runtime · el estado que sobrevive entre tokens. // ───────────────────────────────────────────────────────────────────────────── // En qwen35 son DOS cosas distintas, y esa asimetría es la que hace barato el // contexto largo: // // · 6 capas de atención → caché KV, que CRECE con el contexto. // · 18 capas SSM → estado recurrente de tamaño FIJO (128×128 por cabeza) más // una ventana de convolución de 3 tokens. No crece nunca. // // Cuentas del modelo de 0.8B, sacadas de sus propios metadatos: // · las 6 capas de atención guardan K y V de cada token: la caché KV crece en // línea recta con el contexto; // · las 18 capas SSM guardan una matriz de 128×128 por cabeza: fija; // · la ventana de convolución es otra parte fija, mucho más pequeña. // // O sea: el estado recurrente de las 18 capas cuesta menos que 800 tokens de // caché KV. Una cuenta de KV que supusiera las 24 capas de atención sobraría // por dos órdenes de magnitud. // // PENDIENTE de verdad (no lo disimulo): la caché se reserva entera al abrir la // sesión, con la longitud de contexto que se pida. Para los 262.144 de contexto // que declara el modelo harían falta páginas: la caché de todo ese contexto no // se reserva de una sentada. Con contextos de conversación normales esto sirve // tal cual. // // Licencia: código propio, Apache-2.0 (ver SPDX arriba y LICENSE). Sin dependencias externas. // Del modulo de shaders, que es texto puro: importar ops.js aqui arrastraria // las globales de WebGPU y state.js dejaria de poder inspeccionarse desde Node. import { SSM_HEAD_DIM } from './kernels.ssm.wgsl.js'; const MiB = 1024 ** 2; export function createState(device, hp, opts = {}) { const ctxLen = opts.contextLen || 2048; if (ctxLen > hp.contextLength) { throw new Error(`contexto ${ctxLen} mayor que el del modelo (${hp.contextLength})`); } const usage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST; const buf = (bytes, label) => device.createBuffer({ label, size: bytes, usage }); // Se decide AQUÍ y se expone en el estado, para que el shader que escribe la // caché y los que la leen no puedan discrepar. Si uno escribiera f16 y otro // leyera f32, no habría error: habría basura. const kvF16 = opts.kvF16 !== undefined ? !!opts.kvF16 : globalThis.__ELFFUSS_KV_F16 !== false; const bytesKv = kvF16 ? 2 : 4; const kv = new Map(); // índice de capa → {k, v} const ssm = new Map(); // índice de capa → {state, conv} let bytes = 0; for (const l of hp.layers) { if (l.kind === 'attn') { // Media precisión en la caché KV: la mitad de memoria y la mitad de // tráfico al leerla. Es el escalón que va ANTES de cualquier cuantización // —f32 no es siquiera la línea base de la industria, que es f16— y el // único que no plantea preguntas de precisión más allá del redondeo. const per = ctxLen * hp.kvHeads * hp.headDim * bytesKv; kv.set(l.index, { k: buf(per, `k${l.index}`), v: buf(per, `v${l.index}`) }); bytes += per * 2; } else { // Un estado de S_k x S_v por cabeza de VALOR, no de clave. La convolución // corta de lfm3 no tiene estado aparte de su ventana: se deja un buffer // mínimo para que instantáneas y reset traten las dos igual. const st = l.kind === 'conv' ? 16 : hp.ssmVHeads * hp.ssmState * hp.ssmState * 4; const cv = (hp.convKernel - 1) * hp.convChannels * 4; ssm.set(l.index, { state: buf(st, `s${l.index}`), conv: buf(cv, `c${l.index}`) }); bytes += st + cv; } } // Buffers sombra para las instantáneas del estado recurrente. Se crean UNA vez // por ranura, la primera que se pida, y se reutilizan: crear ~96 buffers // dentro de un turno es de las cosas que se llevan la pestaña por delante. // `past` a -1 significa «esta ranura no tiene instantánea válida». // // Hay RANURAS CON NOMBRE y no una sola, y la razón es la mitad del asunto. La // reutilización de prefijo exige que el prompt anterior COMPLETO sea prefijo // estricto del nuevo, y con una sola foto —tomada al final del prompt // anterior— eso solo se cumple si la conversación crece por el final y nada // de en medio cambia. En un arnés siempre cambia algo en medio (el estado // vivo), así que la foto única no servía nunca: medido x1,00. // // Con dos ranuras hay dos niveles de rescate: // · 'turno' la de siempre: el final del prompt anterior. Caso ideal. // · 'sistema' tomada justo después del prompt de sistema, y SOBREVIVE a // `reset()`. Cuando el prefijo completo falla, se vuelve aquí y // se reprocesa solo la conversación, no las ~1.300-2.200 fichas // del prompt de sistema. // // Coste: cada ranura es una copia del estado recurrente, FIJA: no crece con // el contexto. En el modelo grande es unas ocho veces la del pequeño, y aun // así dos ranuras no llegan al 5 % de lo que pesan sus pesos; se cambian por // no reprocesar el prompt de sistema en cada turno. const ranuras = new Map(); const ranura = (nombre) => { let r = ranuras.get(nombre); if (!r) { r = { sombra: null, past: -1 }; ranuras.set(nombre, r); } return r; }; const state = { ctxLen, nPast: 0, bytes, kv, ssm, // Lo lee el forward para pedir el shader que corresponde. No es decorativo: // escribir y leer la caché con precisiones distintas no da error, da basura. kvF16, // Arrancar una conversación nueva: el estado recurrente vuelve a cero y la // caché KV se olvida. Es OBLIGATORIO entre secuencias — un estado SSM // arrastrado de otra conversación no da error, da respuestas contaminadas. reset() { state.nPast = 0; for (const { state: s, conv } of ssm.values()) { device.queue.writeBuffer(s, 0, new Float32Array(s.size / 4)); device.queue.writeBuffer(conv, 0, new Float32Array(conv.size / 4)); } // La KV no hace falta limpiarla: la máscara causal solo mira hasta nPast. // // La instantánea del TURNO deja de valer: describe un estado que ya no // existe, y restaurarla después de esto devolvería la conversación // ANTERIOR sin dar ningún error. Se invalida aquí y no en quien llama, // que es donde se olvidaría. ranura('turno').past = -1; // ⚠️ La del SYSTEM **no** se invalida, y es a propósito: describe «el // estado después del prompt de sistema», que no depende de la // conversación. Es justo lo que la hace útil — sobrevive al reset y // permite volver ahí en vez de reprocesar el prompt entero. Quien la // invalida es quien cambia el prompt de sistema, comparando fichas // (provider.js), no esta función. }, advance(n) { if (state.nPast + n > ctxLen) { throw new Error(`la caché se llena: ${state.nPast + n} tokens sobre ${ctxLen} de contexto`); } state.nPast += n; }, // ── Fotografiar el estado para poder volver aquí ────────────────────────── // Sirve para no reprocesar la conversación entera en cada turno. Lo que se // copia es SOLO el estado recurrente del SSM, y eso es deliberado: // // · El recurrente NO se rebobina: es el resultado de haber recorrido toda // la secuencia, así que la única forma de volver atrás es tener copia. // · La KV NO se copia. La máscara causal descarta con un CERO EXACTO todo // k > qAbs = nPast + fila — está así en `kernels.nn.wgsl.js` y en // `softmaxCPU`, escritas por separado y coincidentes—, de modo que // restaurar una posición anterior es devolver `nPast` atrás y dejar que // lo viejo se sobrescriba. Es lo mismo en lo que ya se apoya `reset()`. // // La diferencia no es cosmética: copiar la KV costaría mucho más que el // estado recurrente, y además CRECE con el contexto, mientras el estado // recurrente es de tamaño FIJO. Fotografiar una conversación de 200.000 // tokens cuesta exactamente lo mismo que una de 10. instantanea(nombre = 'turno') { const r = ranura(nombre); if (!r.sombra) { r.sombra = new Map(); for (const [i, { state: s, conv }] of ssm) { r.sombra.set(i, { state: buf(s.size, `snap-${nombre}-s${i}`), conv: buf(conv.size, `snap-${nombre}-c${i}`) }); } } const enc = device.createCommandEncoder({ label: `instantanea:${nombre}` }); for (const [i, { state: s, conv }] of ssm) { const d = r.sombra.get(i); enc.copyBufferToBuffer(s, 0, d.state, 0, s.size); enc.copyBufferToBuffer(conv, 0, d.conv, 0, conv.size); } device.queue.submit([enc.finish()]); r.past = state.nPast; return r.past; }, // Devuelve false si no hay instantánea válida, para que quien llame reinicie // en vez de seguir con un estado que no sabe describir. restaura(nombre = 'turno') { const r = ranuras.get(nombre); if (!r || !r.sombra || r.past < 0) return false; const enc = device.createCommandEncoder({ label: `restaura:${nombre}` }); for (const [i, { state: s, conv }] of ssm) { const d = r.sombra.get(i); enc.copyBufferToBuffer(d.state, 0, s, 0, s.size); enc.copyBufferToBuffer(d.conv, 0, conv, 0, conv.size); } device.queue.submit([enc.finish()]); state.nPast = r.past; return true; }, tieneInstantanea(nombre = 'turno') { const r = ranuras.get(nombre); return !!r && r.past >= 0; }, // Cuántas fichas describe una ranura. Hace falta fuera: quien reutiliza // tiene que saber desde qué posición sigue, y adivinarlo sería volver al // fallo de tener la cuenta en dos sitios. pasadoInstantanea(nombre = 'turno') { const r = ranuras.get(nombre); return r ? r.past : -1; }, olvidaInstantanea(nombre) { if (nombre === undefined) { for (const r of ranuras.values()) r.past = -1; return; } const r = ranuras.get(nombre); if (r) r.past = -1; }, summary() { const kvB = [...kv.values()].reduce((n, x) => n + x.k.size + x.v.size, 0); const ssmB = [...ssm.values()].reduce((n, x) => n + x.state.size + x.conv.size, 0); return `${kv.size} capas KV (${(kvB / MiB).toFixed(0)} MiB a ${ctxLen} de contexto, ${kvF16 ? 'f16' : 'f32'}) · ` + `${ssm.size} capas SSM (${(ssmB / MiB).toFixed(1)} MiB fijos)`; }, destroy() { for (const x of kv.values()) { x.k.destroy(); x.v.destroy(); } for (const x of ssm.values()) { x.state.destroy(); x.conv.destroy(); } // Y los buffers sombra de la instantánea, que se crean aparte y aquí no // estaban: en el 27B son una copia entera del estado recurrente, y se // filtrarían en CADA ciclo de descarga y recarga. El detalle que lo hace // peor de lo que parece es QUIÉN llama a esto: la app invoca `unload()` justo cuando // la memoria va justa, así que la fuga aparecería en el peor momento // posible y disfrazada de «el navegador mató la pestaña». // TODAS las ranuras, no una: desde que hay dos, liberar solo la primera // dejaría la otra colgada, y es el mismo tamaño. for (const r of ranuras.values()) { if (!r.sombra) continue; for (const x of r.sombra.values()) { x.state.destroy(); x.conv.destroy(); } r.sombra = null; } ranuras.clear(); }, }; state.reset(); return state; } // Lee los hiperparámetros del GGUF y clasifica los bloques. Todo sale del // fichero: nada cableado, porque el 27B tiene 65 bloques y el 0.8B 24, y el // patrón de atención sale de su propia clave. // Arquitecturas que este motor sabe ejecutar, y QUÉ las diferencia. // // `qwen35` es híbrida: la mayoría de bloques son recurrentes y uno de cada // cuatro es de atención. `llama` es atención pura — y resulta ser un // SUBCONJUNTO, no un camino aparte: el bloque de atención de qwen35 ya hace // casi exactamente lo que pide llama. // // Las diferencias se declaran como DATOS y no como ramas sueltas por el // forward, porque cada rama nueva en el camino de qwen35 es una oportunidad de // romper los dos modelos que hoy están en producción: // // qGate qwen35 proyecta `attn_q` al DOBLE (Q y una puerta intercalados // por cabeza) y multiplica la salida por esa puerta. llama no. // qkNorm qwen35 normaliza Q y K antes de RoPE. llama no trae esos tensores. // ropeMode ⚠️ EL PELIGROSO. qwen35 empareja como NEOX; `llama` usa NORM // (pares adyacentes) porque el conversor a GGUF ya permuta los // pesos. Equivocarse aquí NO peta: da texto gramatical que se // degrada al crecer el contexto, que es la peor forma de fallar. // ffnNorm se llama `post_attention_norm` en qwen35 y `ffn_norm` en llama. // // `lfm3` (LiquidAI) es otra híbrida, pero su bloque recurrente NO es el SSM de // qwen35: es una CONVOLUCIÓN CORTA con puerta (in_proj → B·x → conv de 7 → // C·y → out_proj), sin estado más allá de la ventana de la convolución. Y trae // cuatro cosas que las otras dos no: // headGate la puerta de la atención es UN escalar por cabeza, de su propio // tensor (`attn_gate`, E→H) con sigmoide; no va intercalada en Q. // postNorms normas «sándwich»: otra RMSNorm sobre la salida del bloque y otra // sobre la del FFN, antes de sumar al residual. ⚠️ Aquí // `post_attention_norm` ES una post-norma, no la norma del FFN como // en qwen35: mismo nombre de tensor, otro papel. // ventanas unas capas de atención miran solo los últimos `sliding_window` // tokens y con otra base de RoPE; las globales usan `rope_freqs`. // conv el bloque no-atención es la convolución corta. // // Los nombres NO se deducen mirando si el tensor existe. Con `has(...)`, un // modelo al que le faltara el tensor dejaría de fallar y empezaría a mentir. const ARQUITECTURAS = { qwen35: { qGate: true, qkNorm: true, ropeMode: 'neox', ffnNorm: 'post_attention_norm', hibrida: true }, llama: { qGate: false, qkNorm: false, ropeMode: 'norm', ffnNorm: 'ffn_norm', hibrida: false }, lfm3: { qGate: false, qkNorm: true, ropeMode: 'neox', ffnNorm: 'ffn_norm', hibrida: true, headGate: true, postNorms: true, conv: true }, }; export function readHParams(meta, tensors = null) { const arch = meta['general.architecture']; const perfil = ARQUITECTURAS[arch]; if (!perfil) { throw new Error(`arquitectura no soportada: ${arch} (conocidas: ${Object.keys(ARQUITECTURAS).join(', ')})`); } const g = (k, def) => { const v = meta[`${arch}.${k}`]; if (v === undefined && def === undefined) throw new Error(`falta la clave qwen35.${k}`); return v === undefined ? def : v; }; const nLayersFichero = g('block_count'); // PREDICCIÓN MULTI-TOKEN. El 27B declara nextn_predict_layers=1: el ÚLTIMO // bloque no pertenece al forward, es una cabeza que predice el token n+2. Si // se ejecuta como una capa normal, el modelo genera tokens reales pero // degenerados («if if if if…») — no peta, solo deja de tener sentido. // // Y explica la anomalía que había atribuido a otra cosa: con 65 bloques, la // regla «uno de cada cuatro es atención» daba 16 y el fichero tenía 17. No // había excepción: el 17º era la capa MTP, que no cuenta. const nextn = meta['qwen35.nextn_predict_layers'] || 0; const nLayers = nLayersFichero - nextn; const interval = g('full_attention_interval', 4); const heads = g('attention.head_count'); // En lfm3 `head_count_kv` es una LISTA por capa: 0 en las de convolución y // las cabezas KV en las de atención. Todas las de atención llevan las mismas // (se comprueba): el resto del motor trabaja con un único número. const kvLista = g('attention.head_count_kv'); let kvHeads = kvLista; // El lector de GGUF puede devolver la lista como array TIPADO: Array.isArray // no lo ve y el número de cabezas quedaba siendo un array (NaN en la KV). if (Array.isArray(kvLista) || ArrayBuffer.isView(kvLista)) { const distintas = [...new Set([...kvLista].map(Number).filter(n => n > 0))]; if (distintas.length !== 1) throw new Error(`cabezas KV distintas por capa: ${distintas.join(', ')}`); kvHeads = distintas[0]; } const embd = g('embedding_length'); // head_dim NO es embd/heads en este modelo: 1024/8 = 128, pero el head_dim // real es 256. Sale de su propia clave. const headDim = g('attention.key_length', Math.floor(embd / heads)); // Se clasifica por los tensores que el fichero TIENE, no por una fórmula. // La fórmula es respaldo y coincide exactamente con la de la referencia: // atención cuando (i+1) % interval == 0, recurrente en el resto. El bloque MTP // también trae attn_q, así que entra en este conjunto — da igual, porque el // bucle solo pregunta por los `nLayers` que sí se ejecutan. const attnSet = tensors ? new Set(tensors .map(t => /^blk\.(\d+)\.attn_q\.weight$/.exec(t.name)) .filter(Boolean).map(m => +m[1])) : null; const esAtencion = (i) => attnSet ? attnSet.has(i) : (i + 1) % interval === 0; // lfm3: ventana y base de RoPE POR CAPA. Las de ventana usan `freq_base_swa` // y no `rope_freqs`; las globales, la base normal y los factores. const patronSwa = perfil.conv ? g('attention.sliding_window_pattern') : null; const nSwa = perfil.conv ? g('attention.sliding_window') : 0; const baseGlobal = g('rope.freq_base', 1e7); const baseSwa = perfil.conv ? g('rope.freq_base_swa') : baseGlobal; const layers = []; for (let i = 0; i < nLayers; i++) { if (!esAtencion(i)) { layers.push({ index: i, kind: perfil.conv ? 'conv' : 'ssm' }); continue; } const swa = !!(patronSwa && patronSwa[i]); layers.push({ index: i, kind: 'attn', ventana: swa ? nSwa : 0, ropeBase: swa ? baseSwa : baseGlobal, ropeFactores: !!perfil.conv && !swa, }); } // DOS recuentos distintos, y confundirlos rompe solo los modelos grandes: // `group_count` son las cabezas de CLAVE (16 en los dos modelos) y // `time_step_rank` las de VALOR (16 en el 0.8B, 48 en el 27B). En el pequeño // coinciden, así que usar uno para todo funciona ahí y solo ahí. const ssmHeads = g('ssm.group_count', 16); const ssmVHeads = g('ssm.time_step_rank', ssmHeads); const ssmState = g('ssm.state_size', SSM_HEAD_DIM); const ssmInner = g('ssm.inner_size', 2048); // Dos supuestos que el motor entero da por ciertos y que aquí se comprueban en // vez de descubrirse como texto raro: que las cabezas de valor son múltiplo de // las de clave (si no, el reparto q/k no está definido) y que la dimensión de // value coincide con la de key (el estado es cuadrado y el shader usa una sola // S para las dos). Los dos se cumplen en el 0.8B y en el 27B. if (ssmVHeads % ssmHeads !== 0) { throw new Error(`cabezas SSM incompatibles: ${ssmVHeads} de valor no es ` + `múltiplo de ${ssmHeads} de clave`); } const headV = ssmInner / ssmVHeads; if (headV !== ssmState) { throw new Error(`el estado SSM no es cuadrado: value_dim ${headV} ` + `(inner ${ssmInner} / ${ssmVHeads} cabezas) contra key_dim ${ssmState}`); } return { arch, ...perfil, nLayers, interval, layers, nextn, nLayersFichero, embd, heads, kvHeads, headDim, ffnLength: g('feed_forward_length'), contextLength: g('context_length'), ropeFreqBase: g('rope.freq_base', 1e7), ropeDims: g('rope.dimension_count', 64), eps: meta[`${arch}.attention.layer_norm_rms_epsilon`] ?? 1e-6, ssmHeads, ssmVHeads, ssmState, ssmInner, // lfm3: la convolución corta va sobre el embedding entero y su kernel es // `shortconv.l_cache` (7). En qwen35 son los canales del qkv fusionado. convKernel: perfil.conv ? g('shortconv.l_cache') : g('ssm.conv_kernel', 4), // conv_dim = 2·key_dim + value_dim, con key_dim = grupos·estado y // value_dim = inner. En el 0.8B los dos valen 2048 y da 6144; en el 27B el // value_dim son 6144 y da 10240. convChannels: perfil.conv ? embd : 2 * ssmHeads * ssmState + ssmInner, nAttn: layers.filter(l => l.kind === 'attn').length, nSSM: layers.filter(l => l.kind !== 'attn').length, }; }