File size: 18,113 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
// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 UtopiaIA
// Elffuss Runtime · reordenar Q8_0 y Q4_0 al cargar (`__ELFFUSS_REPACK`).
// ─────────────────────────────────────────────────────────────────────────────
// El formato está en `kernels.bloques.wgsl.js`: los cuantos de todos los bloques
// primero, alineados a 16 bytes, y las escalas después (tipos internos Q8_0R y
// Q4_0R). Aquí está quien lo FABRICA a partir de los bytes del GGUF, y lo que
// necesita el cargador para subirlo.
//
// ── POR QUÉ EN LA CPU, MIENTRAS LLEGAN LOS BYTES, Y NO EN EL DISPOSITIVO ────
// La alternativa era subir los bytes tal cual a un buffer temporal y que un
// kernel los reordenara en el definitivo. Se descarta por dos motivos, y la
// memoria NO es uno de ellos:
//   · SE PUEDE COMPROBAR SIN DISPOSITIVO. Es una permutación de bytes, y la
//     MISMA función que corre el cargador se prueba bit a bit en node: vectores
//     conocidos, ida y vuelta, bloques impares, relleno, y trocear igual que
//     entero. Un kernel de reordenado solo se podría probar con dispositivo.
//   · NI COMPILAR NI DESPACHAR DURANTE LA CARGA. El reordenado en la CPU es una
//     pasada lineal sobre bytes que ya están en memoria, con lecturas y
//     escrituras de 32 bits y desenrollada por parejas de bloques.
// Lo que cuesta, por camino:
//   · TRAMOS (casi todos los tensores): ya se hacía una copia de cada tensor
//     para rellenarla a 4 bytes (`pad`), y ahora se reordena DENTRO de esa copia
//     en vez de copiar tal cual. Ni un byte más de memoria; la pasada es varias
//     veces más cara que la copia que sustituye.
//   · TROZOS (un tensor mayor que un tramo: la tabla de embeddings): antes cada
//     trozo leído se escribía TAL CUAL, sin copia. Ahora se reordena en dos
//     búferes que se reutilizan entre trozos, así que hay una pasada que antes
//     no había y un trozo más de memoria en la CPU.
// Sobre la memoria, para que nadie lo lea al revés: un reordenado en el
// dispositivo de un tensor ENTERO sí lo tendría dos veces a la vez, pero uno
// por trozos (un buffer temporal del tamaño de un trozo y un kernel que reparta
// cada trozo en sus dos regiones) costaría también un trozo, como aquí. No es lo
// que decide. Lo que cueste de verdad en la carga entera se mide con y sin el
// interruptor (la parte tmodelo del banco del reordenado, que recarga en cada
// ronda) antes de encenderlo.
//
// ── EL INTERRUPTOR SE LEE AL CARGAR, NO AL MULTIPLICAR ─────────────────────
// `__ELFFUSS_REPACK` decide qué formato tiene cada tensor en el momento de
// subirlo, y ese formato queda escrito en su descriptor (`typeName` = 'Q8_0R' o
// 'Q4_0R'). Los kernels eligen por el TIPO, así que un modelo cargado con el
// interruptor puesto sigue siendo coherente aunque luego se quite, y al revés:
// formato y lector no pueden desacoplarse. Y como el tipo va en todas las claves
// de pipeline (`matmul_${type}…`, `drift_deq_${type}`, `gather_${type}`…), los
// shaders de un formato y del otro nunca comparten compilado.
//
// Por lo mismo, un A/B que cargue el modelo UNA vez y conmute el interruptor
// entre rondas mide el mismo formato en las dos y da ×1,00: hay que cargar de
// nuevo en cada ronda (`INTERRUPTORES_DE_CARGA`, abajo, es la lista que miran
// los bancos para negarse).
//
// Apagado, nada de esto se ejecuta: mismos buffers, mismos bytes, mismos
// descriptores que antes.
//
// Licencia: código propio, Apache-2.0 (ver SPDX arriba y LICENSE). Sin dependencias externas.
import { TIPO_R, TIPOS_R, GEOMETRIA, bytesReordenado, bytesBufferR } from './kernels.bloques.wgsl.js';

// Un solo sitio que lee el interruptor.
export function reordenActivo() {
  return globalThis.__ELFFUSS_REPACK === true;
}

// Interruptores que actúan AL CARGAR el modelo y no al multiplicar.
export const INTERRUPTORES_DE_CARGA = Object.freeze(['__ELFFUSS_REPACK']);

// El tipo reordenado de un tensor del GGUF, o null si no se reordena
// (interruptor apagado, o un tipo que no es Q8_0 ni Q4_0). `activo` se pasa
// para que una carga entera use la foto que tomó al empezar.
export function tipoReordenado(t, activo = reordenActivo()) {
  return activo ? (TIPO_R[t.typeName] || null) : null;
}

// El descriptor que viaja con el buffer. Es una COPIA del de parseGGUF con el
// tipo interno: la tabla de tensores del fichero no se toca (otra carga del
// mismo `g` tiene que ver los tipos del fichero), y quien elige kernel por
// `w.t.typeName` —el forward, el gather, las pruebas— recibe el que corresponde
// a los bytes que hay en el dispositivo.
export function comoReordenado(t, tipoR) {
  return { ...t, typeName: tipoR, typeNameGGUF: t.typeName };
}

// Bloques de un tensor Q8_0/Q4_0 (32 pesos por bloque en los dos).
export function bloquesDe(t) {
  return t.nElements / GEOMETRIA[t.typeName].elems;
}

const LE = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
const alineado = (a) => a.byteOffset % 4 === 0;

// ── El camino rápido, por PAREJAS de bloques ───────────────────────────────
// Dos bloques Q8_0 son 68 bytes = 17 palabras enteras (Q4_0: 36 = 9). Dentro de
// la pareja:
//   · el bloque PAR tiene la escala en la media palabra baja de w0 y los
//     cuantos desde el byte 2, así que cada palabra de cuantos es la mitad alta
//     de una palabra y la baja de la siguiente;
//   · el bloque IMPAR tiene la escala en la mitad alta de la palabra 8 (Q4: 4),
//     la misma que cierra los cuantos del par, y sus cuantos ya alineados: se
//     copian tal cual;
//   · las dos escalas van juntas en una palabra de la región de escalas: la del
//     par en la mitad baja (media palabra par) y la del impar en la alta.
// Desenrollado a mano y uno por tipo: con el bucle interno de 8 (o 4) vueltas
// la pasada costaba varias veces más, y es la que paga la carga.
function pares8(s32, q32, e32, pares) {
  for (let p = 0, s = 0, q = 0; p < pares; p++, s += 17, q += 16) {
    const w0 = s32[s], w1 = s32[s + 1], w2 = s32[s + 2], w3 = s32[s + 3], w4 = s32[s + 4],
      w5 = s32[s + 5], w6 = s32[s + 6], w7 = s32[s + 7], w8 = s32[s + 8];
    q32[q] = (w0 >>> 16) | (w1 << 16);
    q32[q + 1] = (w1 >>> 16) | (w2 << 16);
    q32[q + 2] = (w2 >>> 16) | (w3 << 16);
    q32[q + 3] = (w3 >>> 16) | (w4 << 16);
    q32[q + 4] = (w4 >>> 16) | (w5 << 16);
    q32[q + 5] = (w5 >>> 16) | (w6 << 16);
    q32[q + 6] = (w6 >>> 16) | (w7 << 16);
    q32[q + 7] = (w7 >>> 16) | (w8 << 16);
    q32[q + 8] = s32[s + 9];
    q32[q + 9] = s32[s + 10];
    q32[q + 10] = s32[s + 11];
    q32[q + 11] = s32[s + 12];
    q32[q + 12] = s32[s + 13];
    q32[q + 13] = s32[s + 14];
    q32[q + 14] = s32[s + 15];
    q32[q + 15] = s32[s + 16];
    e32[p] = (w0 & 0xFFFF) | (w8 & 0xFFFF0000);
  }
}
function pares4(s32, q32, e32, pares) {
  for (let p = 0, s = 0, q = 0; p < pares; p++, s += 9, q += 8) {
    const w0 = s32[s], w1 = s32[s + 1], w2 = s32[s + 2], w3 = s32[s + 3], w4 = s32[s + 4];
    q32[q] = (w0 >>> 16) | (w1 << 16);
    q32[q + 1] = (w1 >>> 16) | (w2 << 16);
    q32[q + 2] = (w2 >>> 16) | (w3 << 16);
    q32[q + 3] = (w3 >>> 16) | (w4 << 16);
    q32[q + 4] = s32[s + 5];
    q32[q + 5] = s32[s + 6];
    q32[q + 6] = s32[s + 7];
    q32[q + 7] = s32[s + 8];
    e32[p] = (w0 & 0xFFFF) | (w4 & 0xFFFF0000);
  }
}

/**
 * Reordena `nb` bloques consecutivos en formato GGUF (`src`, Uint8Array) a dos
 * destinos: `cuantos` (bytes de cuantos, 32·nb o 16·nb) y `escalas` (2·nb
 * bytes, la escala f16 del bloque k en los bytes 2k y 2k+1). Son las dos
 * regiones del formato: el trozo [i0, i0+nb) de un tensor va a la posición
 * cuantos·i0 de la primera y 2·i0 de la segunda.
 *
 * El camino rápido (arriba) exige un host little-endian —los bytes del GGUF lo
 * son, y las palabras se recomponen con desplazamientos— y las tres vistas
 * alineadas a 4. Si no se cumple, o para el bloque suelto de un número impar,
 * se copia byte a byte, que da exactamente los mismos bytes.
 */
export function reordenaBloques(tipo, src, nb, cuantos, escalas) {
  const g = GEOMETRIA[tipo];
  if (!g) throw new Error(`reordena: tipo sin formato reordenado: «${tipo}»`);
  const B = g.bytes, Q = g.cuantos, P = g.palabras;
  if (!(nb >= 0) || nb % 1 !== 0) throw new Error(`reordena: número de bloques inválido: ${nb}`);
  if (src.byteLength < B * nb) throw new Error(`reordena: faltan bytes de origen (${src.byteLength} < ${B * nb})`);
  if (cuantos.byteLength < Q * nb) throw new Error(`reordena: destino de cuantos corto (${cuantos.byteLength} < ${Q * nb})`);
  if (escalas.byteLength < 2 * nb) throw new Error(`reordena: destino de escalas corto (${escalas.byteLength} < ${2 * nb})`);

  let hechos = 0;
  const pares = nb >> 1;
  if (LE && pares > 0 && alineado(src) && alineado(cuantos) && alineado(escalas)) {
    const s32 = new Uint32Array(src.buffer, src.byteOffset, pares * (B >> 1));
    const q32 = new Uint32Array(cuantos.buffer, cuantos.byteOffset, pares * 2 * P);
    const e32 = new Uint32Array(escalas.buffer, escalas.byteOffset, pares);
    (P === 8 ? pares8 : pares4)(s32, q32, e32, pares);
    hechos = 2 * pares;
  }
  // Byte a byte: lo que no fue por parejas.
  for (let i = hechos; i < nb; i++) {
    const s = i * B;
    escalas[2 * i] = src[s];
    escalas[2 * i + 1] = src[s + 1];
    const q = i * Q;
    for (let j = 0; j < Q; j++) cuantos[q + j] = src[s + 2 + j];
  }
}

/**
 * Reordena un tensor ENTERO de `nBloques` bloques. `dst` (opcional) es donde se
 * escribe —el cargador pasa su copia de relleno— y tiene que medir al menos
 * `bytesReordenado`; lo que sobre detrás de las escalas se deja a cero.
 * Devuelve `dst`. Por defecto mide `bytesBufferR`, lo mismo que el buffer.
 */
export function reordena(tipo, src, nBloques, dst = null) {
  const g = GEOMETRIA[tipo];
  if (!g) throw new Error(`reordena: tipo sin formato reordenado: «${tipo}»`);
  const out = dst || new Uint8Array(bytesBufferR(tipo, nBloques));
  const total = bytesReordenado(tipo, nBloques);
  if (out.byteLength < total) {
    throw new Error(`reordena: el destino mide ${out.byteLength} y hacen falta ${total}`);
  }
  const W = g.cuantos * nBloques;
  reordenaBloques(tipo, src, nBloques, out.subarray(0, W), out.subarray(W, W + 2 * nBloques));
  out.fill(0, W + 2 * nBloques);
  return out;
}

// La inversa: del formato reordenado al del GGUF (34 o 18 bytes por bloque).
// No la usa la carga; existe para la ida y vuelta de las pruebas y para quien
// necesite los bytes originales de un tensor ya reordenado.
export function vuelveAlGGUF(tipo, src, nBloques) {
  const g = GEOMETRIA[tipo];
  if (!g) throw new Error(`vuelveAlGGUF: tipo sin formato reordenado: «${tipo}»`);
  const B = g.bytes, Q = g.cuantos, W = Q * nBloques;
  if (src.byteLength < W + 2 * nBloques) {
    throw new Error(`vuelveAlGGUF: faltan bytes (${src.byteLength} < ${W + 2 * nBloques})`);
  }
  const out = new Uint8Array(B * nBloques);
  for (let i = 0; i < nBloques; i++) {
    const d = i * B;
    out[d] = src[W + 2 * i];
    out[d + 1] = src[W + 2 * i + 1];
    out.set(src.subarray(Q * i, Q * i + Q), d + 2);
  }
  return out;
}

// ── LA MARCA: cuántos bloques tiene DE VERDAD cada buffer reordenado ────────
// Los lectores R deducen N —y con él dónde empiezan las escalas— del tamaño del
// buffer atado (kernels.bloques.wgsl.js). Con un buffer de otro tamaño no fallan:
// leen las escalas de otro sitio y sale basura plausible. Y es fácil tener uno:
// `upload` y `ctx.alloc` de ops.js redondean a 256 bytes (un Q8_0R de 64
// bloques necesita 2.176 y el pozo da 2.304, que se lee como 67 bloques), y un
// troceado o un binding con offset harían lo mismo. Ni siquiera basta con mirar
// el tamaño: un Q4_0R de 34 bloques en 768 bytes se lee como 42, y 768 es
// también el buffer correcto de 42. Hace falta saber el N del tensor, y eso solo
// lo sabe quien crea el buffer: lo apunta aquí, y ops.js lo comprueba antes de
// cada despacho de un lector R (`compruebaBufferR`). Es aritmética de JS por
// despacho, sin tocar el dispositivo.
//
// WeakMap y no una propiedad pegada al GPUBuffer: no toca un objeto de la
// plataforma, y la marca se va con el buffer cuando se libera.
const MARCAS = new WeakMap();

// Apunta que `buf` guarda un tensor `tipoR` de `nBloques` bloques. El buffer
// tiene que medir exactamente `bytesBufferR` (múltiplo de 16, que también es lo
// que pide la vista vec4 de los lectores).
export function marcaBufferR(buf, tipoR, nBloques) {
  if (!TIPOS_R.has(tipoR)) throw new Error(`marcaBufferR: «${tipoR}» no es un tipo reordenado`);
  if (!(nBloques > 0) || nBloques % 1 !== 0) throw new Error(`marcaBufferR: número de bloques inválido: ${nBloques}`);
  const esperado = bytesBufferR(tipoR, nBloques);
  if (buf.size !== esperado) {
    throw new Error(`marcaBufferR: «${buf.label || '?'}» mide ${buf.size} bytes y un ${tipoR} de ` +
      `${nBloques} bloques tiene que medir ${esperado}: los lectores sacan del tamaño dónde empiezan las escalas`);
  }
  MARCAS.set(buf, { tipo: tipoR, bloques: nBloques });
  return buf;
}

// El N del TENSOR que guarda un buffer reordenado (undefined si no lleva marca).
// Es el que necesita quien pase W por uniformes en vez de deducirlo del tamaño:
// el `rows·bpr` de una llamada no vale (la cabeza se pide con el vocabulario).
export function bloquesR(buf) {
  const m = MARCAS.get(buf);
  return m ? m.bloques : undefined;
}

/**
 * Antes de despachar un lector R sobre `buf`: que lleve la marca, que sea del
 * tipo que se va a leer y que la llamada no se salga del tensor. `bloques` son
 * los que lee la llamada (matmul: filas·bpr; dequant: nBlocks) y `porFila`, en
 * el gather, los bloques de una fila (la tabla tiene que ser de filas enteras).
 * Lanza con el porqué; devuelve el N del tensor.
 */
export function compruebaBufferR(tipo, buf, { bloques = 0, porFila = 0 } = {}, que = 'lector') {
  const m = MARCAS.get(buf);
  if (!m) {
    throw new Error(`${que} ${tipo}: el buffer «${buf.label || '?'}» no lleva la marca de un tensor reordenado. ` +
      'Los lectores R sacan del tamaño del buffer dónde empiezan las escalas, así que tiene que crearlo ' +
      'creaBufferR (o marcarlo marcaBufferR, con el tamaño de bytesBufferR); `upload` redondea a 256 ' +
      'bytes y con otro tamaño se leerían escalas de otro sitio sin un error');
  }
  if (m.tipo !== tipo) {
    throw new Error(`${que}: el buffer «${buf.label || '?'}» guarda un ${m.tipo} y se iba a leer como ${tipo}`);
  }
  if (bloques > m.bloques) {
    throw new Error(`${que} ${tipo}: la llamada lee ${bloques} bloques y el tensor de «${buf.label || '?'}» tiene ${m.bloques}`);
  }
  if (porFila > 0 && m.bloques % porFila !== 0) {
    throw new Error(`${que} ${tipo}: el tensor de «${buf.label || '?'}» (${m.bloques} bloques) no son filas enteras de ${porFila} bloques`);
  }
  return m.bloques;
}

// El buffer de un tensor reordenado: el formato redondeado a 16 bytes (ver
// `bytesBufferR`), con su marca puesta. No lleva la holgura de 4 bytes de los
// otros: los lectores de este formato leen palabras alineadas y nunca la palabra
// siguiente al tensor. Pasarse del tope de binding no lanzaría aquí sino al
// atarlo, y en WebGPU eso es un despacho que no hace nada: se comprueba antes.
export function creaBufferR(device, t, tipoR) {
  const nBloques = bloquesDe(t);
  const size = bytesBufferR(tipoR, nBloques);
  const tope = device.limits.maxStorageBufferBindingSize;
  if (size > tope) {
    throw new Error(`«${t.name}» reordenado mide ${size} bytes y el límite de binding es ${tope}`);
  }
  const buf = device.createBuffer({
    label: t.name,
    size,
    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
  });
  return marcaBufferR(buf, tipoR, nBloques);
}

/**
 * Sube un tensor demasiado grande para un tramo, por trozos y reordenado. Es el
 * camino de trozos de siempre con dos cambios: cada trozo son bloques ENTEROS y
 * en número PAR (para que sus escalas empiecen en palabra: writeBuffer exige
 * offset y tamaño múltiplos de 4), y cada trozo se escribe en DOS sitios del
 * buffer, su tramo de cuantos y su tramo de escalas.
 *
 * `cuenta(msLeer, msSubir, bytes)` se llama por trozo, para que el cargador
 * siga repartiendo el tiempo y avisando del progreso igual que antes.
 */
export async function subeReordenadoPorTrozos({ device, ranged, t, buf, tipoR, trozo, ahora, cuenta }) {
  const g = GEOMETRIA[tipoR];
  const B = g.bytes, Q = g.cuantos;
  const N = bloquesDe(t);
  const W = Q * N;                                   // byte donde empiezan las escalas
  const porTrozo = Math.max(2, Math.floor(trozo / (2 * B)) * 2);
  // Los dos destinos se reutilizan entre trozos: writeBuffer copia al llamarse.
  const cuantos = new Uint8Array(Q * Math.min(porTrozo, N));
  const escalas = new Uint8Array(Math.ceil(2 * Math.min(porTrozo, N) / 4) * 4);
  for (let i0 = 0; i0 < N; i0 += porTrozo) {
    const nb = Math.min(porTrozo, N - i0);
    const t0 = ahora();
    const raw = new Uint8Array(await ranged.slice(t.start + i0 * B, nb * B));
    const t1 = ahora();
    // Un trozo corto entraría como PESOS sin un solo error.
    if (raw.byteLength !== nb * B) {
      throw new Error(`trozo incompleto en «${t.name}»: pedidos ${nb * B} bytes y llegaron ${raw.byteLength}`);
    }
    const nE = Math.ceil(2 * nb / 4) * 4;
    escalas.fill(0, 0, nE);
    reordenaBloques(tipoR, raw, nb, cuantos, escalas.subarray(0, 2 * nb));
    device.queue.writeBuffer(buf, Q * i0, cuantos, 0, Q * nb);
    // Con nb impar (solo el último trozo de un N impar) se escriben dos bytes de
    // relleno detrás de la última escala: caben, el buffer va redondeado a 16.
    device.queue.writeBuffer(buf, W + 2 * i0, escalas, 0, nE);
    cuenta(t1 - t0, ahora() - t1, nb * B);
  }
}