Spaces:
Running
Running
Download js/engine/repack.js from UtopiaIA/elffuss-code: direct link, hf CLI and curl.
- Browser
- Download file 18.1 kB
-
https://huggingface.co/spaces/UtopiaIA/elffuss-code/resolve/main/js/engine/repack.js
- Command line
-
hf download hf://spaces/UtopiaIA/elffuss-code/js/engine/repack.js
-
curl -L -o repack.js https://huggingface.co/spaces/UtopiaIA/elffuss-code/resolve/main/js/engine/repack.js
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); | |
| } | |
| } | |