// SPDX-License-Identifier: Apache-2.0 // Copyright (c) 2026 UtopiaIA // Elffuss Runtime · despacho del GEMM del prompt con descuantización dentro (GEMM2). // ───────────────────────────────────────────────────────────────────────────── // Lo llama `quant.matmul` (ops.js) al principio, y SOLO si `__ELFFUSS_GEMM2 === // true`: con el interruptor apagado no se ejecuta ni una línea de aquí y el motor // es el de siempre. Si el plan no aplica a la forma pedida devuelve null y // `quant.matmul` sigue por su camino de siempre. // // Interruptores (todos APAGADOS por defecto; los sub-interruptores solo cuentan // con el principal puesto): // __ELFFUSS_GEMM2 el GEMM exacto sustituye a DRIFT: mismos bits, sin // el búfer de pesos f16 ni su despacho. // __ELFFUSS_GEMM2_TESELA la tesela con memoria compartida en vez del exacto // (tolerancia declarada, no bit a bit). // __ELFFUSS_GEMM2_ACC16 dentro de la tesela, suma en f16 por tesela de k. // __ELFFUSS_GEMM2_FMA32 el kernel de la tesela de DRIFT con la aritmética de // la tesela (FMA f32 por producto): no bit a bit, misma // tolerancia que la tesela; sin efecto con TESELA puesto. // __ELFFUSS_GEMM2_PARTE formas largas y estrechas (k > filas, como ffn_down): // bloques de 8 filas en el exacto (sigue exacto) o k // partida en la tesela (tolerancia de la tesela). // __ELFFUSS_GEMM2_Q4 Q4_0/Q4_0R por el GEMM teselado de 4 a 63 tokens. // __ELFFUSS_GEMM2_COLA última capa del prompt solo para el último token // (lo usa model.js a través de `cola`). // __ELFFUSS_GEMM2_FORMA {BM, BN, TM, TN, doble} para barrer la tesela. // __ELFFUSS_GEMM2_TROZO {nb, doble, tpw, tpt} para barrer el exacto. `tpw` y // `tpt` cambian SOLO su tesela (la de DRIFT sigue con // sus `__ELFFUSS_DRIFT_TPW/TPT`); sigue siendo exacto // con cualquier forma, porque cada salida suma lo mismo // en el mismo orden. Más hilos por grupo reparten la // descuantización de cada trozo entre más tokens. // Todo lo que cambia el WGSL entra en la clave del pipeline: si no, un A/B // mediría dos veces el mismo shader compilado. // // Licencia: código propio, Apache-2.0 (ver SPDX arriba y LICENSE). Sin dependencias externas. import { GEMM2_TIPOS, formaTesela, gemm2ExactoShader, gemm2TeselaShader, gemm2SumaShader, TIPOS_Q4_TESELA, gemmQ4Shader, } from './kernels.gemm2.wgsl.js'; import { f32aF16Shader, DRIFT_TPT, DRIFT_TPW } from './kernels.drift.wgsl.js'; import { TK_POR_DEFECTO } from './kernels.gemm.wgsl.js'; import { AXIS } from './kernels.wgsl.js'; import { TIPOS_R, escalasDesde } from './kernels.bloques.wgsl.js'; import { compruebaBufferR } from './repack.js'; // Una sola lectura de los interruptores por decisión. Los del camino al que // sustituye (DRIFT_DESDE, DRIFT, GEMM, la forma de DRIFT) se leen con la MISMA // expresión que en ops.js: GEMM2 elige lo mismo que elegiría él, no un rango // propio que se desincronice. export function leeInterruptores(g = globalThis) { return { gemm2: g.__ELFFUSS_GEMM2 === true, tesela: g.__ELFFUSS_GEMM2_TESELA === true, acc16: g.__ELFFUSS_GEMM2_ACC16 === true, fma32: g.__ELFFUSS_GEMM2_FMA32 === true, parte: g.__ELFFUSS_GEMM2_PARTE === true, q4: g.__ELFFUSS_GEMM2_Q4 === true, forma: g.__ELFFUSS_GEMM2_FORMA || null, trozo: g.__ELFFUSS_GEMM2_TROZO || {}, driftDesde: g.__ELFFUSS_DRIFT_DESDE || 64, driftApagado: g.__ELFFUSS_DRIFT === false, gemmApagado: g.__ELFFUSS_GEMM === false, tpt: g.__ELFFUSS_DRIFT_TPT || DRIFT_TPT, tpw: g.__ELFFUSS_DRIFT_TPW || DRIFT_TPW, formaGemm: g.__ELFFUSS_GEMM_FORMA || {}, pad: g.__ELFFUSS_PAD_TESELA === 1 ? 1 : 0, llano: g.__ELFFUSS_GEMM_PLANO === true ? 1 : 0, }; } // La tesela estrecha del GEMM teselado según el lote: la MISMA tabla que el // camino GEMM de `quant.matmul` (ops.js). Está copiada a propósito, para no // tocar aquel bloque; si allí cambia, aquí hay que cambiarlo también. const anchoTesela = (n) => (n <= 4 ? { TM: 2, TN: 1, WGM: 16, WGN: 4 } : n <= 8 ? { TM: 2, TN: 1, WGM: 8, WGN: 8 } : n <= 16 ? { TM: 2, TN: 2, WGM: 8, WGN: 8 } : { TM: 2, TN: 4, WGM: 8, WGN: 8 }); // Qué camino toma un matmul. Función pura (sin WebGPU) para poder probarla en Node. // Devuelve null si GEMM2 no aplica y `quant.matmul` debe seguir como siempre. export function planGemm2({ type, rows, k, tokens, f16 = true, maxCompartida = 32768, sw = leeInterruptores() }) { if (!sw.gemm2 || !GEMM2_TIPOS.has(type) || k % 32 !== 0 || !(tokens >= 1)) return null; const bpr = k / 32; // El rango de DRIFT con su mismo predicado (ops.js): lote largo, f16 en el // dispositivo, filas múltiplo de 16. GEMM2 lo sustituye; no lo amplía. if (tokens >= sw.driftDesde && !sw.driftApagado && f16 && rows % 16 === 0) { // Forma «larga y estrecha»: k mayor que las filas. Con la tesela de siempre // salen pocos grupos con bucles largos (ffn_down: la cuarta parte de grupos // que gate/up con bucles cuatro veces más largos). const larga = sw.parte && k > rows; if (sw.tesela) { const F = formaTesela(sw.forma || {}); if (rows % F.BM === 0 && F.HILOS <= 256 && F.compartida <= maxCompartida) { // k partida en tantas partes como veces cabe `rows` en k (así cada grupo // hace una cantidad de trabajo parecida a la de las formas anchas), con // al menos cuatro teselas de k por parte. const partes = larga ? Math.max(1, Math.min(8, Math.ceil(k / rows), Math.floor(bpr / 4))) : 1; return { via: 'tesela', type, bpr, forma: F, acc16: sw.acc16, partes }; } } // Dos bloques por trozo si la fila lo permite (menos barreras por k) y un // solo trozo en memoria compartida (ver `gemm2ExactoShader`). Un trozo de 2 // con un número impar de bloques dejaría el último sin calcular: se baja a 1. const nb = (sw.trozo.nb === 1 || bpr % 2 !== 0) ? 1 : 2; return { via: 'exacto', type, bpr, tpt: (sw.trozo.tpt | 0) || sw.tpt, tpw: (sw.trozo.tpw | 0) || sw.tpw, filas: larga ? 8 : 16, nb, doble: sw.trozo.doble === true, fma32: sw.fma32, }; } // Q4_0/Q4_0R por el GEMM teselado, con las mismas reglas que Q8_0 allí. if (sw.q4 && TIPOS_Q4_TESELA.has(type) && tokens >= 4 && !sw.gemmApagado) { const Fg = sw.formaGemm; const TK = (Fg.TK | 0) || TK_POR_DEFECTO; if (TK % 4 !== 0 || 32 % TK !== 0 || k % TK !== 0) { // Igual que ops.js: un TK pedido a mano que no vale LANZA; nunca se mide // otro camino con la etiqueta de este. if (Fg.TK) throw new Error(`GEMM: TK=${Fg.TK} no vale para «${type}» (bloque 32, k=${k})`); return null; } const A = anchoTesela(tokens); const G = { TM: Fg.TM || A.TM, TN: Fg.TN || A.TN, WGM: Fg.WGM || A.WGM, WGN: Fg.WGN || A.WGN, TK, maxCompartida }; return { via: 'q4', type, bpr, G, pad: sw.pad, llano: sw.llano }; } return null; } // Clave del pipeline de cada plan: TODO lo que cambia el WGSL generado. export function clavePlan(pl) { if (pl.via === 'exacto') return `gemm2x_${pl.type}_${pl.tpt}_${pl.tpw}_f${pl.filas}_n${pl.nb}_d${pl.doble ? 1 : 0}_m${pl.fma32 ? 1 : 0}`; if (pl.via === 'tesela') { const F = pl.forma; return `gemm2t_${pl.type}_${F.BM}_${F.BN}_${F.TM}_${F.TN}_d${F.doble ? 1 : 0}_a${pl.acc16 ? 1 : 0}_p${pl.partes}`; } const G = pl.G; return `gemm_${pl.type}_${G.TM}_${G.TN}_${G.WGM}_${G.WGN}_k${G.TK}_p${pl.pad}_f${pl.llano}_g2q4`; } const rowsToDims = (rows) => (rows <= AXIS ? [rows, 1] : [AXIS, Math.ceil(rows / AXIS)]); // `dispatch`, `dispatchXYZ` y `dispatchN` son los de ops.js (se pasan para que // estos despachos vayan por el mismo sitio que todos: lote, perfilado y scopes). export function createGemm2Ops(ctx, { dispatch, dispatchXYZ, dispatchN }) { const device = ctx.device; const get = ctx.pipeline; const conF16 = () => !!device.features?.has('shader-f16'); const maxComp = () => device.limits?.maxComputeWorkgroupStorageSize || 16384; const plan = (type, rows, k, tokens) => planGemm2({ type, rows, k, tokens, f16: conF16(), maxCompartida: maxComp() }); // ── x → f16, con memoria ─────────────────────────────────────────────────── // La misma activación entra en varios matmuls seguidos (la salida de la norma // va a q, k, v y la puerta; la del FFN a gate y up) y DRIFT la convertía otra // vez en cada uno. La conversión es la misma operación sobre los mismos datos, // así que reutilizarla no cambia ni un bit. // // La clave es la MARCA DE REPARTO (`ctx.marcaDe`), no el búfer: un búfer // reciclado recibe marca nueva al volver a entregarse, así que no puede // confundirse con la activación que fue antes. Y el resultado guardado solo // vale mientras SU marca siga siendo la misma: si el pozo lo ha vuelto a // entregar, alguien lo está reescribiendo. Mientras no lo haya entregado, su // contenido sigue intacto aunque esté en el pozo (nadie lo ha pedido), y el // despacho que lo lee se graba antes que cualquiera que lo pida después. // Supuesto, el mismo que la memoria de rotación de model.js: nadie reescribe // en el sitio un búfer del pozo que ya entregó. // // Y solo se reutiliza una conversión que siga PRESTADA. Una que ya volvió al // pozo conserva su contenido mientras nadie la pida, pero el mismo matmul que // la reutiliza pide después su búfer de salida, y si mide lo mismo el pozo // puede entregarle justo ese: leer y escribir el mismo búfer en un despacho // no es válido, y sin los scopes de error eso no lanza, deja la salida sin // escribir. Con el flujo de model.js no ocurre (las conversiones se reutilizan // dentro de la misma capa, antes de reciclar), pero comprobarlo es barato y // solo corre en el prompt. const prestado = (buf) => ctx.scratch.some((e) => e.buf === buf); const memo = []; async function aF16(xBuf, tokens, k) { const n4 = tokens * k / 4; const marca = ctx.marcaDe?.get(xBuf); if (marca !== undefined) { for (let i = memo.length - 1; i >= 0; i--) { const m = memo[i]; if (m.marca === marca && m.n4 === n4 && ctx.marcaDe.get(m.xh) === m.marcaXh && prestado(m.xh)) return m.xh; } } // El mismo shader y la misma clave que usa DRIFT: es la misma conversión. const px = await get('drift_x16', () => f32aF16Shader(256)); const xh = ctx.alloc(n4 * 8, 'gemm2.x'); await dispatchN(ctx, 'gemm2_x16', px, [xBuf, xh, ctx.uniform([new Uint32Array([n4, 0, 0, 0])])], Math.ceil(n4 / 256)); if (marca !== undefined) { memo.push({ marca, n4, xh, marcaXh: ctx.marcaDe.get(xh) }); if (memo.length > 4) memo.shift(); } return xh; } // Bloques del TENSOR que guarda `wBuf`. En los reordenados (Q8_0R, Q4_0R) las // escalas empiezan tras los cuantos de TODOS sus bloques, y una llamada puede // pedir menos filas de las que tiene el tensor (la cabeza se pide con el // vocabulario del tokenizador): el `rows·bpr` de la llamada no sirve. Sale de // la marca del cargador, con la MISMA comprobación que hace el camino de // siempre (`compruebaBufferR`: marca, tipo y que la llamada no se salga del // tensor), y lanza igual que él: el interruptor no cambia qué búferes se // aceptan. En los formatos del GGUF no hay región de escalas aparte. const bloquesTensor = (type, wBuf, rows, bpr) => (TIPOS_R.has(type) ? compruebaBufferR(type, wBuf, { bloques: rows * bpr }, 'gemm2') : rows * bpr); // La palabra donde empiezan las escalas: la de `escalasDesde` con el N del // tensor; 0 en los del GGUF (el kernel no la lee). const baseEscalasDe = (type, n) => (TIPOS_R.has(type) ? escalasDesde(type, n) : 0); async function exacto(pl, wBuf, xh, rows, k, tokens, baseEsc) { const { type, tpt, tpw, filas, nb, doble, fma32, bpr } = pl; const pg = await get(clavePlan(pl), () => gemm2ExactoShader({ type, tpt, tpw, filas, nb, doble, fma32 })); const y = ctx.alloc(rows * tokens * 4, 'matmul.y'); const og = rows / filas; await dispatchXYZ(ctx, `gemm2x:${type}:r${rows}b${bpr}`, pg, [wBuf, xh, y, ctx.uniform([new Uint32Array([k / 4, rows, tokens, bpr, baseEsc, 0, 0, 0])])], Math.ceil(tokens / (tpw * tpt)), Math.min(og, 65535), Math.ceil(og / 65535)); return y; } async function tesela(pl, wBuf, xh, rows, k, tokens, baseEsc) { const { type, forma: F, acc16, partes, bpr } = pl; const pg = await get(clavePlan(pl), () => gemm2TeselaShader({ type, BM: F.BM, BN: F.BN, TM: F.TM, TN: F.TN, doble: F.doble, acc16, partes, maxCompartida: maxComp(), })); const n = rows * tokens; const dst = ctx.alloc(n * 4 * partes, partes > 1 ? 'gemm2.partes' : 'matmul.y'); const params = ctx.uniform([new Uint32Array([rows, tokens, bpr, k / 4, baseEsc, 0, 0, 0])]); // Teselas de TOKENS en el eje x: los grupos que el dispositivo lanza seguidos // comparten la tesela de pesos, que se lee de memoria una vez y el resto de // veces sale de la caché. await dispatchXYZ(ctx, `gemm2t:${type}:r${rows}b${bpr}`, pg, [wBuf, xh, dst, params], Math.ceil(tokens / F.BN), rows / F.BM, partes); if (partes === 1) return dst; const ps = await get(`gemm2s_${partes}`, () => gemm2SumaShader(partes, 256)); const y = ctx.alloc(n * 4, 'matmul.y'); const n4 = n / 4; await dispatchN(ctx, `gemm2s:r${rows}`, ps, [dst, y, ctx.uniform([new Uint32Array([n4, 0, 0, 0])])], Math.ceil(n4 / 256)); return y; } async function q4(pl, wBuf, xBuf, rows, k, tokens, nTensor) { const { type, G, bpr } = pl; const pg = await get(clavePlan(pl), () => gemmQ4Shader(type, G)); const y = ctx.alloc(rows * tokens * 4, 'matmul.y'); // `nBlocks` solo lo lee la tirada de Q4_0R, y como base de sus escalas // (4 · nBlocks): tienen que ser los bloques del TENSOR, no los de la llamada. const params = ctx.uniform([new Uint32Array([nTensor, bpr, rows, k, tokens, 0, 0, 0])]); const [gx, gy] = rowsToDims(Math.ceil(rows / (G.WGM * G.TM))); await dispatch(ctx, `gemm:${type}:r${rows}b${bpr}`, pg, [wBuf, xBuf, y, params], gx, gy, Math.ceil(tokens / (G.WGN * G.TN))); return y; } return { // Diagnóstico: qué haría con esta forma (null = el camino de siempre). plan, // Para los bancos: vacía la memoria de x→f16, de modo que una medida no se // ahorre conversiones que en la otra rama sí se pagan. olvida() { memo.length = 0; }, async matmul(type, wBuf, xBuf, rows, k, tokens) { // El decode (un token) nunca es de GEMM2 salvo que alguien baje // DRIFT_DESDE a mano: se sale aquí sin leer el resto de interruptores, que // en el bucle de decode serían cientos de lecturas por token para nada. if (tokens < 4 && tokens < (globalThis.__ELFFUSS_DRIFT_DESDE || 64)) return null; const pl = plan(type, rows, k, tokens); if (!pl) return null; const n = bloquesTensor(type, wBuf, rows, pl.bpr); if (pl.via === 'q4') return await q4(pl, wBuf, xBuf, rows, k, tokens, n); const xh = await aF16(xBuf, tokens, k); const baseEsc = baseEscalasDe(type, n); return pl.via === 'tesela' ? await tesela(pl, wBuf, xh, rows, k, tokens, baseEsc) : await exacto(pl, wBuf, xh, rows, k, tokens, baseEsc); }, // ── La cola de la última capa (interruptor GEMM2_COLA, ver model.js) ────── // `x1` es UNA fila: la del último token de un lote de `lote` tokens. Se // calcula con el MISMO plan (mismo shader, misma forma, mismas partes de k) // que habría tocado al lote entero, despachado para un solo token. En los dos // kernels de aquí la salida de un token solo depende de su fila de x y de los // pesos, sumados en el mismo orden, así que da los mismos bits que su fila // dentro del lote. Con otro camino (el matvec de un token suma en otro // orden) eso ya no se cumple: por eso `reproducible` dice antes si se puede. reproducible(type, rows, k, lote) { const pl = plan(type, rows, k, lote); return !!pl && (pl.via === 'exacto' || pl.via === 'tesela'); }, async cola(type, wBuf, x1, rows, k, lote) { const pl = plan(type, rows, k, lote); if (!pl || (pl.via !== 'exacto' && pl.via !== 'tesela')) return null; const baseEsc = baseEscalasDe(type, bloquesTensor(type, wBuf, rows, pl.bpr)); const xh = await aF16(x1, 1, k); return pl.via === 'tesela' ? await tesela(pl, wBuf, xh, rows, k, 1, baseEsc) : await exacto(pl, wBuf, xh, rows, k, 1, baseEsc); }, }; }