Spaces:
Running
Running
File size: 20,812 Bytes
4bd8362 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 | // 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,
};
}
|