elffuss-code / js /engine /ops.flash.js
KikoCis's picture
Sync with code.elffuss.com (fc5b0ba): LFM3 on our own engine, installable app, VS Code extensions, new look; README refreshed
4bd8362 verified
Raw History Blame Contribute Delete
17.2 kB
// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 UtopiaIA
// Elffuss Runtime · la atención fusionada como operación: elegir la forma del
// kernel, comprobar que el dispositivo la admite y despacharlo.
// ─────────────────────────────────────────────────────────────────────────────
// Sustituye, cuando se enciende `__ELFFUSS_FLASH`, a la cadena
// attn.scores → nn.softmax → attn.combine (partido + reducción) → mul_cabeza
// por uno o dos despachos (`kernels.flash.wgsl.js`). Con el interruptor apagado
// este módulo ni se llama: el forward es el de siempre, mismos shaders y mismos
// despachos.
//
// La decisión de la forma está en `planFlash`, una función PURA (no toca
// WebGPU): se puede llamar desde Node para ver qué compilaría cada modelo y
// validar justo esos shaders sin dispositivo.
//
// Si la forma no se puede atender —subgrupos que no son de 32, caché en f32,
// otra dimensión de cabeza, memoria de grupo insuficiente— `puede()` dice que no
// y el forward usa la cadena de siempre, que da lo mismo más despacio. Un
// modelo con otra forma tiene que seguir corriendo. Y lo mismo si el
// dispositivo NO COMPILA un kernel que el plan sí admitía: `atencion` devuelve
// null (la cadena hace esa capa), la clave queda apartada y `puede()` dice que
// no a esa forma desde entonces, con un aviso en consola una sola vez.
//
// Interruptores de MEDIDA (solo para elegir defectos; apagados no cambian
// nada, y todo lo que toca el texto del shader va en la clave del pipeline):
// __ELFFUSS_FLASH_TQ consultas por grupo en prefill
// __ELFFUSS_FLASH_NSG subgrupos por grupo
// __ELFFUSS_FLASH_QSH q en memoria de grupo (true) o leída de global (false)
// __ELFFUSS_FLASH_VSH tesela de V en memoria de grupo
// __ELFFUSS_FLASH_PSH probabilidades a P·V por memoria de grupo
// __ELFFUSS_FLASH_PREF prelectura de la tesela de K siguiente
// __ELFFUSS_FLASH_MEM presupuesto de memoria de grupo
// __ELFFUSS_FLASH_PARTES partes del rango de claves, forzadas
// __ELFFUSS_FLASH_GRUPOS grupos que se persiguen antes de partir
// __ELFFUSS_FLASH_CLAVES claves por parte al partir (y se parte desde el doble)
// Y uno de PRUEBA:
// __ELFFUSS_FLASH_EXIGE con el interruptor puesto, una capa que no pueda ir
// por la fusionada LANZA en vez de volver a la cadena:
// así una prueba del modelo entero no da por buena la
// fusionada habiendo corrido la cadena sin saberlo.
//
// Licencia: código propio, Apache-2.0 (ver SPDX arriba y LICENSE). Sin dependencias externas.
import { flashShader, flashReduceShader, flashMemoria, flashPrefetch, FLASH_BK } from './kernels.flash.wgsl.js';
// Memoria de grupo que se permite por defecto, aunque el dispositivo admita más.
// No es un tope del dispositivo sino de ocupación: cuanto más pide un grupo,
// menos grupos caben a la vez en una unidad de cómputo, y con pocos grupos no
// hay con qué esconder la latencia de memoria. Es además el mínimo que la
// especificación garantiza, así que con el presupuesto por defecto la forma
// cabe en cualquier dispositivo. `__ELFFUSS_FLASH_MEM` lo cambia para medir.
const PRESUPUESTO = 16384;
// Cuántos grupos se persiguen antes de partir el rango de claves (y pagar la
// reducción). Con una consulta (decode) hay solo KVH grupos sin partir: casi
// todo el dispositivo parado mientras unos pocos recorren el contexto en serie.
const GRUPOS_OBJETIVO = 128;
// Claves por parte cuando se parte (dos teselas), y no se parte un rango de
// menos del doble: con tres o cuatro teselas, lo que se ahorraría en el camino
// más largo es poco al lado de un despacho más (la reducción) y la espera entre
// los dos. Dónde está de verdad el punto lo dice el barrido
// (`__ELFFUSS_FLASH_CLAVES`), no esta cuenta.
const CLAVES_MIN = 2 * FLASH_BK;
const PARTES_MAX = 32;
// Lee un entero positivo de un interruptor de medida, o null.
const entero = (v) => (Number.isInteger(v) && v > 0 ? v : null);
// La forma del kernel para una llamada. Devuelve { ok:false, motivo } si no se
// puede, y si se puede, todo lo que hace falta para compilar y despachar.
// `dev` = { subgroupSize, limites } con los límites REALES del dispositivo
// (device.limits), no los pedidos.
export function planFlash(cfg, dev) {
const { headDim: D, heads: H, kvHeads: KVH, tokens: T, nPast = 0, ventana = 0,
kvF16 = false, puerta = false } = cfg;
const sg = dev?.subgroupSize || 0;
const lim = dev?.limites || {};
const no = (motivo) => ({ ok: false, motivo });
// El reparto (un carril por clave de la tesela; cada subgrupo, 32 hilos
// consecutivos del grupo) está escrito para subgrupos de 32 exactos.
if (sg !== 32) return no(`subgrupo de ${sg} (hace falta 32 fijo)`);
if (!kvF16) return no('la caché KV no es f16');
if (D !== 128 && D !== 256) return no(`headDim ${D} sin kernel`);
if (!Number.isInteger(H) || !Number.isInteger(KVH) || KVH < 1 || H % KVH !== 0) {
return no(`${H} cabezas no se reparten entre ${KVH} KV`);
}
if (!Number.isInteger(T) || T < 1 || !Number.isInteger(nPast) || nPast < 0) return no('tokens o nPast inválidos');
const G = H / KVH;
// Consultas por grupo. En prefill, las suficientes para que el grupo tenga
// del orden de 16 filas (G·TQ): cada tesela de K se lee una vez para todas.
// En decode hay una.
let TQ = T === 1 ? 1 : Math.max(1, Math.floor(16 / G));
const tqPedido = entero(globalThis.__ELFFUSS_FLASH_TQ);
if (T > 1 && tqPedido) TQ = tqPedido;
TQ = Math.min(TQ, T);
const R = G * TQ;
// Subgrupos por grupo: el mayor divisor de las filas que no pase de 4.
// `__ELFFUSS_FLASH_NSG` lo fuerza para medir (p. ej. 1 en decode: un solo
// subgrupo con todas las filas, que lee la V una vez y no una por subgrupo).
let NSG = [4, 3, 2, 1].find((d) => R % d === 0);
const nsgPedido = entero(globalThis.__ELFFUSS_FLASH_NSG);
if (nsgPedido) {
if (R % nsgPedido !== 0) return no(`${R} filas no se reparten entre ${nsgPedido} subgrupos`);
NSG = nsgPedido;
}
const RS = R / NSG;
const WG = 32 * NSG;
// Cada fila de un subgrupo son registros vivos durante todo el bucle (su
// salida parcial, su máximo y su suma): por encima de 8 se derramarían.
if (RS > 8) return no(`${RS} filas por subgrupo (máximo 8)`);
const maxInv = lim.maxComputeInvocationsPerWorkgroup ?? 256;
if (WG > maxInv) return no(`grupo de ${WG} hilos sobre un tope de ${maxInv}`);
const maxSB = lim.maxStorageBuffersPerShaderStage ?? 8;
if (maxSB < 5) return no(`${maxSB} buffers de almacenamiento por etapa`);
const maxMem = lim.maxComputeWorkgroupStorageSize ?? 16384;
const memPedida = entero(globalThis.__ELFFUSS_FLASH_MEM);
const tope = Math.min(maxMem, memPedida || PRESUPUESTO);
if (flashMemoria({ D, G, TQ, qsh: false, vsh: false }) > maxMem) {
return no(`la tesela de K no cabe en ${maxMem} bytes de memoria de grupo`);
}
// Probabilidades a P·V por memoria de grupo en vez de por barajado, solo si se
// pide y hay más de una fila por subgrupo (con una, un vec4 no ahorra nada).
const psh = globalThis.__ELFFUSS_FLASH_PSH === true && RS >= 2;
// q en memoria de grupo si cabe en el presupuesto; si no, en difusión desde
// global. Los dos interruptores fuerzan una u otra para medir.
let qsh = flashMemoria({ D, G, TQ, qsh: true, vsh: false, psh, NSG }) <= tope;
if (globalThis.__ELFFUSS_FLASH_QSH === true) qsh = true;
if (globalThis.__ELFFUSS_FLASH_QSH === false) qsh = false;
// V en memoria de grupo solo si se pide. Por defecto SOLO la K pasa por
// memoria de grupo: cada subgrupo lee de la caché las filas de V de la tesela
// (los 32 carriles en un tramo contiguo), así que con NSG subgrupos la misma
// tesela de V se pide NSG veces —lecturas repetidas y casi a la vez, que en
// general sirve la caché del dispositivo y no la memoria—. Pasarla una vez por
// memoria de grupo cuesta otra tesela entera, que con q dentro no cabe en el
// presupuesto (habría que leer q de global), y una barrera más de copia. Cuál
// gana no se deduce: lo mide el barrido (`vsh` con q fuera, y en decode
// NSG = 1, que tiene un solo subgrupo y lee la V una vez).
const vsh = globalThis.__ELFFUSS_FLASH_VSH === true;
// Prelectura de la tesela de K a registros, solo si se pide y el reparto lo
// admite (cuesta registros durante todo el cálculo de la tesela).
const pref = globalThis.__ELFFUSS_FLASH_PREF === true && flashPrefetch({ D, NSG }) > 0;
const memoria = flashMemoria({ D, G, TQ, qsh, vsh, psh, NSG });
if (memoria > maxMem) return no(`${memoria} bytes de memoria de grupo sobre un tope de ${maxMem}`);
// Partes del rango de claves. El rango más largo es el de la última tesela de
// consultas (la causal llega más lejos); con ventana, todos rondan ventana+TQ.
const qTiles = Math.ceil(T / TQ);
const qIniUlt = nPast + (qTiles - 1) * TQ;
const kIniUlt = ventana > 0 ? Math.max(0, qIniUlt + 1 - ventana) : 0;
const span = nPast + T - kIniUlt;
const grupos = KVH * qTiles;
const objetivo = entero(globalThis.__ELFFUSS_FLASH_GRUPOS) || GRUPOS_OBJETIVO;
const clavesMin = entero(globalThis.__ELFFUSS_FLASH_CLAVES) || CLAVES_MIN;
let partes = 1;
if (grupos < objetivo && span >= 2 * clavesMin) {
partes = Math.max(1, Math.min(PARTES_MAX, Math.ceil(objetivo / grupos), Math.ceil(span / clavesMin)));
// El kernel redondea el trozo de cada parte a teselas enteras (ver
// `trozo` en el shader). Con ese trozo, las partes que de verdad llevan
// claves en el rango más largo; las de detrás saldrían vacías, y un grupo
// vacío cuesta su lanzamiento y una entrada más en la reducción. La última
// puede quedarse con pocas claves: es el resto, cuesta una tesela como
// cualquiera y meterlo en otra parte alargaría el camino más largo.
partes = Math.ceil(span / (Math.ceil(Math.ceil(span / partes) / FLASH_BK) * FLASH_BK));
}
// Forzadas para medir, con más margen que la regla: el barrido tiene que
// poder ver qué hay por encima del tope que la regla se pone.
const partesPedidas = entero(globalThis.__ELFFUSS_FLASH_PARTES);
if (partesPedidas) partes = Math.min(8 * PARTES_MAX, partesPedidas);
if (KVH * qTiles * partes > 65535 * 65535) return no('rejilla demasiado grande');
const parcial = partes > 1;
// La puerta va en el kernel solo sin partes; con partes la aplica la reducción.
const kernel = { D, G, TQ, NSG, puerta: !!puerta && !parcial, parcial, qsh, vsh, pref, psh };
// TODO lo que cambia el texto del shader va en la clave. Sin eso, un A/B
// reutilizaría el compilado de la otra rama y mediría dos veces lo mismo.
// (`psh` solo añade sufijo cuando está puesto: las claves de siempre no cambian.)
const clave = `flash_${D}_${G}_${TQ}_${NSG}_${kernel.puerta ? 'g' : 'n'}_${parcial ? 'p' : 'd'}` +
`_${qsh ? 'qs' : 'qg'}_${vsh ? 'vs' : 'vg'}_${pref ? 'pf' : 'np'}${psh ? '_ps' : ''}`;
const claveReduce = `flash_reduce_${D}_${puerta ? 'g' : 'n'}`;
return { ok: true, G, TQ, R, NSG, RS, WG, qTiles, partes, span, memoria, kernel, clave, claveReduce };
}
// `despacha(label, pipeline, buffers, grupos)` es el despacho plano del motor
// (ops.dispatchAny): reparte los grupos en dos ejes si pasan del tope.
export function createFlashOps(device, { ctx, despacha, subgroupSize = 0 }) {
const get = ctx.pipeline;
const dev = () => ({ subgroupSize, limites: device.limits });
// Claves que este dispositivo no compiló (clave → mensaje). El plan solo ve
// límites y formas; que el compilador del navegador acepte el kernel no se
// sabe hasta pedirlo. Una clave apartada no se vuelve a intentar.
const rechazadas = new Map();
const exige = () => globalThis.__ELFFUSS_FLASH_EXIGE === true;
const compila = async (clave, hazShader) => {
try {
return await get(clave, hazShader);
} catch (e) {
if (exige()) throw e;
const msg = String((e && e.message) || e);
rechazadas.set(clave, msg);
console.warn(`[flash] ${clave} no compila en este dispositivo; esa forma vuelve a la cadena de siempre: ${msg.slice(0, 300)}`);
return null;
}
};
return {
plan: (cfg) => planFlash(cfg, dev()),
puede(cfg) {
const pl = planFlash(cfg, dev());
const motivo = !pl.ok ? pl.motivo
: rechazadas.has(pl.clave) ? `${pl.clave} no compiló`
: pl.partes > 1 && rechazadas.has(pl.claveReduce) ? `${pl.claveReduce} no compiló` : null;
if (motivo && exige()) throw new Error(`flash exigida y no puede: ${motivo}`);
return !motivo;
},
// Solo diagnóstico: lo que no compiló. Una prueba en el dispositivo tiene que verlo vacío.
rechazadas: () => [...rechazadas.entries()],
// q: [T][H][D] f32 (tras RoPE). kCache/vCache: la caché f16 [ctx][KVH][D]
// con las T posiciones nuevas ya escritas a partir de nPast. `puerta`:
// [T][H] f32 sin sigmoide (lfm3) o null. Devuelve [T][H][D] f32: la entrada
// de la proyección de salida, con la puerta ya aplicada si la hay. O null si
// un kernel no compila: no se ha despachado nada, y quien llama hace esa
// capa por la cadena (la fusionada solo escribe en sus propios buffers).
async atencion(q, kCache, vCache, { headDim, heads, kvHeads, tokens, nPast = 0, ventana = 0, kvF16 = false, puerta = null }) {
const pl = planFlash({ headDim, heads, kvHeads, tokens, nPast, ventana, kvF16, puerta: !!puerta }, dev());
if (!pl.ok) throw new Error(`flash: ${pl.motivo}`);
const D = headDim, H = heads, KVH = kvHeads, T = tokens;
// Los dos pipelines ANTES de despachar nada: si el segundo no compila, el
// primero no ha corrido para nada.
const p = await compila(pl.clave, () => flashShader(pl.kernel));
if (!p) return null;
const pr = pl.partes > 1 ? await compila(pl.claveReduce, () => flashReduceShader({ D, puerta: !!puerta })) : null;
if (pl.partes > 1 && !pr) return null;
// Misma escala que la cadena de siempre: 1/√D en doble, a f32 en el uniform.
const params = ctx.uniform([
new Uint32Array([T, nPast, H, KVH, ventana, pl.qTiles, pl.partes, 0]),
new Float32Array([1 / Math.sqrt(D), 0, 0, 0]),
]);
const grupos = KVH * pl.qTiles * pl.partes;
if (pl.partes === 1) {
const out = ctx.alloc(T * H * D * 4, 'flash.out');
const bufs = pl.kernel.puerta ? [q, kCache, vCache, puerta, out, params] : [q, kCache, vCache, out, params];
await despacha('flash', p, bufs, grupos);
return out;
}
const parcO = ctx.alloc(T * H * pl.partes * D * 4, 'flash.parc');
const parcML = ctx.alloc(T * H * pl.partes * 8, 'flash.ml');
await despacha('flash', p, [q, kCache, vCache, parcO, parcML, params], grupos);
const out = ctx.alloc(T * H * D * 4, 'flash.out');
const parR = ctx.uniform([new Uint32Array([T * H, pl.partes, 0, 0])]);
const bufsR = puerta ? [parcO, parcML, puerta, out, parR] : [parcO, parcML, out, parR];
await despacha('flash_reduce', pr, bufsR, Math.ceil(T * H * (D / 4) / 64));
return out;
},
};
}
// ── Referencia de CPU para las pruebas ──────────────────────────────────────
// Atención con máscara causal y de ventana, en doble y por la definición (sin
// softmax en línea ni teselas): puntuaciones, máximo de las visibles, exp,
// suma, combinación y puerta. Solo calcula las filas (t, h) pedidas en `filas`
// —un prefill entero en JavaScript no cabe en el tiempo de una prueba—.
// k y v son las cachés YA en doble ([nKv][KVH][D]); q es [T][H][D].
export function atencionCPU(q, k, v, { headDim: D, heads: H, kvHeads: KVH, tokens: T, nPast = 0, ventana = 0 },
puerta = null, filas = null) {
const G = H / KVH, scale = 1 / Math.sqrt(D);
const lista = filas || Array.from({ length: T * H }, (_, i) => [Math.floor(i / H), i % H]);
const out = new Map();
for (const [t, h] of lista) {
const kvh = Math.floor(h / G), qAbs = nPast + t;
const ini = ventana > 0 ? Math.max(0, qAbs - ventana + 1) : 0;
const s = new Float64Array(qAbs + 1 - ini);
let mx = -Infinity;
for (let j = ini; j <= qAbs; j++) {
let acc = 0;
for (let d = 0; d < D; d++) acc += q[(t * H + h) * D + d] * k[(j * KVH + kvh) * D + d];
s[j - ini] = acc * scale;
if (s[j - ini] > mx) mx = s[j - ini];
}
let suma = 0;
for (let i = 0; i < s.length; i++) { s[i] = Math.exp(s[i] - mx); suma += s[i]; }
const o = new Float64Array(D);
for (let j = ini; j <= qAbs; j++) {
const w = s[j - ini] / suma;
for (let d = 0; d < D; d++) o[d] += w * v[(j * KVH + kvh) * D + d];
}
if (puerta) {
const sg = 1 / (1 + Math.exp(-puerta[t * H + h]));
for (let d = 0; d < D; d++) o[d] *= sg;
}
out.set(t * H + h, o);
}
return out;
}