Spaces:
Running
Running
Download js/engine/device.js from UtopiaIA/elffuss-code: direct link, hf CLI and curl.
- Browser
- Download file 15 kB
-
https://huggingface.co/spaces/UtopiaIA/elffuss-code/resolve/main/js/engine/device.js
- Command line
-
hf download hf://spaces/UtopiaIA/elffuss-code/js/engine/device.js
-
curl -L -o device.js https://huggingface.co/spaces/UtopiaIA/elffuss-code/resolve/main/js/engine/device.js
15 kB
| // SPDX-License-Identifier: Apache-2.0 | |
| // Copyright (c) 2026 UtopiaIA | |
| // Elffuss Runtime · creación del GPUDevice y utillaje que hace visibles los fallos. | |
| // ───────────────────────────────────────────────────────────────────────────── | |
| // En WebGPU casi nada lanza. Un buffer inválido, un binding mal alineado o una | |
| // lectura fuera de rango no dan excepción: dan CEROS. Un motor de inferencia | |
| // construido sobre eso genera texto plausible y basura numérica sin un solo | |
| // error en consola. Este módulo existe para que eso no pase: | |
| // · pide los límites de verdad (ver la trampa de abajo, es gorda), | |
| // · comprueba que el device no nace ya perdido, | |
| // · envuelve cualquier operación en scopes de error, | |
| // · y ofrece el round-trip de lectura, que es el único canario fiable. | |
| // | |
| // TRAMPA MAYOR — `requestDevice({ requiredLimits: adapter.limits })` NO falla: | |
| // GPUSupportedLimits expone sus límites como accessors del PROTOTIPO, y la | |
| // conversión a `record<K,V>` de WebIDL solo mira propiedades PROPIAS. Así que | |
| // `{...adapter.limits}` es `{}` y te devuelve un device con los límites POR | |
| // DEFECTO (buffer 256 MiB, binding 128 MiB) sin decir nada. Hay que recorrerlo | |
| // con for..in, que sí pasa por el prototipo. (gpuweb/gpuweb#4277) | |
| // | |
| // Licencia: código propio, Apache-2.0 (ver SPDX arriba y LICENSE). Sin dependencias externas. | |
| // Los dos únicos límites de clase «alignment», donde MEJOR es MENOR y el valor | |
| // debe ser potencia de dos. El resto son de clase «maximum» (mejor = mayor). | |
| // Pedir algo peor que el defecto no da error: se clampa en silencio. | |
| const ALIGNMENT_LIMITS = new Set([ | |
| 'minUniformBufferOffsetAlignment', | |
| 'minStorageBufferOffsetAlignment', | |
| ]); | |
| // Los límites que de verdad deciden si un modelo cabe y cómo hay que trocearlo. | |
| // Se usan como conjunto de reintento si pedirlo todo falla en algún navegador. | |
| const CORE_LIMITS = new Set([ | |
| 'maxBufferSize', | |
| 'maxStorageBufferBindingSize', | |
| 'maxStorageBuffersPerShaderStage', | |
| 'maxBindGroups', | |
| 'minStorageBufferOffsetAlignment', | |
| 'maxComputeInvocationsPerWorkgroup', | |
| 'maxComputeWorkgroupSizeX', | |
| 'maxComputeWorkgroupSizeY', | |
| 'maxComputeWorkgroupStorageSize', | |
| 'maxComputeWorkgroupsPerDimension', | |
| ]); | |
| // Copia los límites del adaptador a un objeto JS plano. for..in y no Object.keys | |
| // ni spread: ver la trampa de la cabecera. Como solo copiamos valores que el | |
| // propio adaptador reporta, por construcción nunca pedimos nada «mejor» que él. | |
| export function maxOutLimits(adapter, only = null) { | |
| const out = {}; | |
| for (const key in adapter.limits) { | |
| if (only && !only.has(key)) continue; | |
| const v = adapter.limits[key]; | |
| if (typeof v !== 'number' || !Number.isFinite(v)) continue; | |
| // Un límite de alineación que no sea potencia de dos es inválido y tumbaría | |
| // la petición entera; se salta en vez de arrastrarlo. | |
| if (ALIGNMENT_LIMITS.has(key) && (v <= 0 || !Number.isInteger(Math.log2(v)))) continue; | |
| out[key] = v; | |
| } | |
| return out; | |
| } | |
| // Crea el device con todo lo que el adaptador dé. Devuelve también si hay f16 y | |
| // la información del adaptador, que es lo que permite detectar un adaptador de | |
| // software haciéndose pasar por uno de verdad. | |
| export async function requestDevice(opts = {}) { | |
| if (!globalThis.navigator?.gpu) { | |
| // Sin secure context (http:// que no sea localhost, o about:blank) el | |
| // navegador ni siquiera define navigator.gpu, y parece un fallo del dispositivo. | |
| throw new Error('sin WebGPU: ¿contexto seguro? (https o 127.0.0.1)'); | |
| } | |
| const adapter = await navigator.gpu.requestAdapter({ | |
| powerPreference: opts.powerPreference || 'high-performance', | |
| }); | |
| if (!adapter) throw new Error('no hay adaptador WebGPU'); | |
| const wantF16 = adapter.features.has('shader-f16') && opts.f16 !== false; | |
| const wantSG = adapter.features.has('subgroups') && opts.subgroups !== false; | |
| // timestamp-query solo se pide si el llamador lo quiere (perfilado); no lo usa | |
| // producción, así que por defecto no se activa. | |
| const wantTS = adapter.features.has('timestamp-query') && opts.timestamp === true; | |
| const required = [...(wantF16 ? ['shader-f16'] : []), ...(wantSG ? ['subgroups'] : []), | |
| ...(wantTS ? ['timestamp-query'] : [])]; | |
| // Tamaño de subgrupo SOLO si es fijo (min==max): con un tamaño fijo un | |
| // workgroup de ese ancho es EXACTAMENTE un subgrupo y `subgroupAdd` da la | |
| // reducción entera sin barreras. Si varía, no se asume nada (queda en 0 = off). | |
| const sgSize = wantSG && adapter.info && adapter.info.subgroupMinSize === adapter.info.subgroupMaxSize | |
| ? (adapter.info.subgroupMinSize || 0) : 0; | |
| let device; | |
| try { | |
| device = await adapter.requestDevice({ | |
| label: opts.label || 'elffuss-engine', | |
| requiredFeatures: required, | |
| requiredLimits: maxOutLimits(adapter), | |
| }); | |
| } catch (e) { | |
| // requestDevice es de UN SOLO USO: tras fallar hay que pedir OTRO adaptador. | |
| // El reintento se queda en el núcleo de límites, por si el navegador reporta | |
| // alguno inconsistente consigo mismo. | |
| const a2 = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' }); | |
| if (!a2) throw e; | |
| device = await a2.requestDevice({ | |
| label: (opts.label || 'elffuss-engine') + ' (reintento)', | |
| requiredFeatures: a2.features.has('shader-f16') && opts.f16 !== false ? ['shader-f16'] : [], | |
| requiredLimits: maxOutLimits(a2, CORE_LIMITS), | |
| }); | |
| } | |
| // requestDevice puede RESOLVER con un device ya perdido en vez de rechazar | |
| // (la spec lo dice literalmente). Sin esta carrera, el primer síntoma sería | |
| // un mapAsync que se cuelga treinta llamadas más tarde. | |
| const lost = device.lost.then(i => i); | |
| const race = await Promise.race([lost, Promise.resolve(ALIVE)]); | |
| if (race !== ALIVE) throw new Error('el device nació perdido: ' + race.reason + ' ' + race.message); | |
| // Red de seguridad. La spec NO garantiza que dispare y permite limitarlo, así | |
| // que no sirve para controlar nada — pero registrar el listener puede silenciar | |
| // el aviso de consola, así que si se registra hay que re-emitirlo. | |
| device.addEventListener?.('uncapturederror', (ev) => { | |
| console.error('[gpu] error no capturado:', ev.error?.constructor?.name, ev.error?.message); | |
| }); | |
| return { | |
| device, | |
| adapter, | |
| info: adapter.info || null, | |
| // Lo que te DIERON, nunca lo que pediste. | |
| hasF16: device.features.has('shader-f16'), | |
| // 32 en muchos adaptadores. 0 si no hay subgrupos o el tamaño no es fijo → el motor cae | |
| // a la reducción en árbol de siempre. | |
| subgroupSize: device.features.has('subgroups') ? sgSize : 0, | |
| hasTimestamp: device.features.has('timestamp-query'), | |
| limits: device.limits, | |
| }; | |
| } | |
| const ALIVE = Symbol('alive'); | |
| // Envuelve una operación en los tres scopes de error. Sin esto, «me devuelve | |
| // ceros» nunca se convierte en «createBindGroup falló porque el offset no es | |
| // múltiplo de 256», que es la misma información con veinte veces más valor. | |
| export async function guard(device, label, fn) { | |
| device.pushErrorScope('validation'); | |
| device.pushErrorScope('out-of-memory'); | |
| device.pushErrorScope('internal'); | |
| let out, thrown = null; | |
| try { out = await fn(); } catch (e) { thrown = e; } | |
| // LIFO, y con await individual: la spec no garantiza el orden de resolución. | |
| const internal = await device.popErrorScope(); | |
| const oom = await device.popErrorScope(); | |
| const validation = await device.popErrorScope(); | |
| if (thrown) throw thrown; | |
| const first = validation || oom || internal; | |
| if (first) { | |
| // El tipo es estable, el mensaje es localizable: se reportan los dos. | |
| throw new Error(`[${label}] ${first.constructor.name}: ${first.message}`); | |
| } | |
| return out; | |
| } | |
| // Lee un rango de un buffer de vuelta a CPU. Es el único canario fiable: en un | |
| // device perdido, mapAsync es la ÚNICA operación que falla de forma observable | |
| // (el resto «aparenta funcionar»). | |
| export async function readback(device, src, offset = 0, size = src.size - offset) { | |
| if (offset % 8) throw new Error('readback: el offset debe ser múltiplo de 8 (mapAsync)'); | |
| if (size % 4) throw new Error('readback: el tamaño debe ser múltiplo de 4'); | |
| // (Salvo si redondear la talla del buffer de lectura pasara de `maxBufferSize`: | |
| // ahí, el de siempre, que lo pide exacto.) | |
| if (globalThis.__ELFFUSS_PLAN === true && | |
| Math.max(256, Math.ceil(size / 256) * 256) <= (device.limits?.maxBufferSize ?? Infinity)) { | |
| return await lecturaPersistente(device, src, offset, size); | |
| } | |
| // MAP_READ solo puede combinarse con COPY_DST. Añadir STORAGE o COPY_SRC deja | |
| // el buffer inválido — y devolviendo ceros, cómo no. | |
| const staging = device.createBuffer({ | |
| label: 'readback', | |
| size, | |
| usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ, | |
| }); | |
| try { | |
| await guard(device, 'readback/copy', async () => { | |
| const enc = device.createCommandEncoder({ label: 'readback' }); | |
| enc.copyBufferToBuffer(src, offset, staging, 0, size); | |
| device.queue.submit([enc.finish()]); | |
| }); | |
| await staging.mapAsync(GPUMapMode.READ, 0, size); | |
| const mapped = staging.getMappedRange(0, size); | |
| // Copiar ANTES de unmap: unmap desacopla el ArrayBuffer (byteLength 0) y | |
| // cualquier vista que hubieras hecho sobre él se queda a cero. Ese es el | |
| // origen del clásico «me sale todo ceros» que no es del dispositivo. | |
| const copy = mapped.slice(0); | |
| staging.unmap(); | |
| return copy; | |
| } finally { | |
| staging.destroy(); | |
| } | |
| } | |
| // La misma lectura con PLAN (`__ELFFUSS_PLAN`): el bucle de generación lee en | |
| // cada token, y cada lectura creaba y destruía su buffer y pagaba tres idas y | |
| // vueltas de ámbitos de error. Aquí los buffers de lectura se GUARDAN, dos por | |
| // tamaño y turnándose (mientras uno está mapeado el otro está libre), y los | |
| // ámbitos de error se quedan donde un fallo de configuración se descubre: la | |
| // primera vez que se usa cada buffer, o si la copia pedida no se puede hacer. | |
| // Una copia inválida sin ámbito no lanza: dejaría en el buffer lo de la lectura | |
| // anterior. Por eso lo que sí se puede comprobar en CPU se comprueba antes, y | |
| // si no cuadra se va por el camino con ámbitos. Lo único que no se puede mirar | |
| // desde la CPU es un origen YA DESTRUIDO: el camino de siempre lanzaría y este | |
| // devolvería datos viejos. Los logits salen del pozo, que no destruye nada. | |
| // `ocupado` marca cada buffer desde que se elige hasta que se desmapea. El | |
| // estado de mapeo NO basta: solo cambia al llamar a mapAsync, y entre la copia | |
| // y esa llamada está la espera del ámbito de la primera vez. Tres lecturas a la | |
| // vez del mismo tamaño elegían así el mismo buffer, y la tercera copia pisaba | |
| // la de la primera antes de que esta lo mapeara. | |
| const pozosLectura = new WeakMap(); // device → Map(tamaño → { bufs, validado, ocupado, turno }) | |
| const CLASES_LECTURA = 8; | |
| async function lecturaPersistente(device, src, offset, size) { | |
| let pozo = pozosLectura.get(device); | |
| if (!pozo) { pozo = new Map(); pozosLectura.set(device, pozo); } | |
| const clase = Math.max(256, Math.ceil(size / 256) * 256); | |
| let e = pozo.get(clase); | |
| if (!e) { | |
| // Con demasiados tamaños distintos (un banco que lee de todo) se suelta la | |
| // clase más vieja que no esté en uso. | |
| if (pozo.size >= CLASES_LECTURA) { | |
| for (const [c, v] of pozo) { | |
| if (!v.ocupado[0] && !v.ocupado[1]) { | |
| for (const b of v.bufs) b?.destroy(); | |
| pozo.delete(c); | |
| break; | |
| } | |
| } | |
| } | |
| e = { bufs: [null, null], validado: [false, false], ocupado: [false, false], turno: 0 }; | |
| pozo.set(clase, e); | |
| } | |
| let k = e.turno; e.turno ^= 1; | |
| if (e.ocupado[k]) k ^= 1; | |
| let staging, temporal = false; | |
| if (e.ocupado[k]) { | |
| // Las dos ocupadas (lecturas concurrentes): una de usar y tirar. | |
| staging = device.createBuffer({ label: 'readback', size: clase, | |
| usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ }); | |
| temporal = true; | |
| } else { | |
| if (!e.bufs[k] || e.bufs[k].mapState !== 'unmapped') { | |
| e.bufs[k] = device.createBuffer({ label: 'readback', size: clase, | |
| usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ }); | |
| e.validado[k] = false; | |
| } | |
| staging = e.bufs[k]; | |
| e.ocupado[k] = true; | |
| } | |
| const copia = () => { | |
| const enc = device.createCommandEncoder({ label: 'readback' }); | |
| enc.copyBufferToBuffer(src, offset, staging, 0, size); | |
| device.queue.submit([enc.finish()]); | |
| }; | |
| const cuadra = typeof src.usage === 'number' && (src.usage & GPUBufferUsage.COPY_SRC) !== 0 && | |
| offset + size <= src.size; | |
| try { | |
| if (temporal || !e.validado[k] || !cuadra) await guard(device, 'readback/copy', async () => copia()); | |
| else copia(); | |
| await staging.mapAsync(GPUMapMode.READ, 0, size); | |
| const copy = staging.getMappedRange(0, size).slice(0); | |
| staging.unmap(); | |
| if (!temporal) e.validado[k] = true; | |
| return copy; | |
| } catch (err) { | |
| // Tras un fallo no se sabe en qué estado queda el buffer: fuera. | |
| if (!temporal) { try { staging.destroy(); } catch { /* — */ } e.bufs[k] = null; e.validado[k] = false; } | |
| throw err; | |
| } finally { | |
| if (temporal) staging.destroy(); | |
| else e.ocupado[k] = false; | |
| } | |
| } | |
| // Preludio del WGSL. Con la extensión se puede ALMACENAR en f16 (que es lo que | |
| // de verdad compra: la mitad de presión en memoria compartida, que es el recurso | |
| // que limita el tamaño de tile del matmul). Sin ella se degrada el rendimiento, | |
| // no se deja de arrancar. Convertir la escala f16→f32 NO necesita la extensión: | |
| // unpack2x16float es del núcleo de WGSL. | |
| export function wgslPrelude(hasF16) { | |
| return hasF16 | |
| ? 'enable f16;\nalias half = f16;\nalias half4 = vec4<f16>;\n' | |
| : 'alias half = f32;\nalias half4 = vec4<f32>;\n'; | |
| } | |
| // ¿El adaptador es de verdad o es software haciéndose pasar por uno? | |
| // Según cómo se arranque Chromium, `requestAdapter()` puede devolver un | |
| // adaptador SwiftShader —software puro— que funciona y miente en cada medición. | |
| export function isSoftwareAdapter(info) { | |
| const s = ((info?.vendor || '') + ' ' + (info?.architecture || '') + ' ' + | |
| (info?.description || '')).toLowerCase(); | |
| return /swiftshader|llvmpipe|lavapipe|software|warp|basic render/.test(s); | |
| } | |
| const GiB = 1024 ** 3, MiB = 1024 ** 2; | |
| // Resumen de una línea para diagnóstico, sin datos del usuario. | |
| export function summarize({ info, hasF16, limits }) { | |
| const gpu = info ? `${info.vendor || '?'}/${info.architecture || '?'}` : 'adaptador anónimo'; | |
| return `${gpu} · buffer≤${(limits.maxBufferSize / GiB).toFixed(1)}GiB` + | |
| ` · binding≤${(limits.maxStorageBufferBindingSize / MiB) | 0}MiB` + | |
| ` · ${limits.maxStorageBuffersPerShaderStage} storage/stage` + | |
| ` · align ${limits.minStorageBufferOffsetAlignment}` + | |
| ` · f16 ${hasF16 ? 'sí' : 'no'}`; | |
| } | |