File size: 17,164 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
// 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;
}