elffuss-code / js /engine /repack.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
18.1 kB
// 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);
}
}