La Guía Definitiva de WebLLM: LLMs en el Navegador con WebGPU

Los Modelos de Lenguaje Grande (LLMs) se han convertido en una pieza esencial del desarrollo de IA, pero la mayoría del ecosistema sigue dependiendo de servidores en la nube pesados.

WebLLM cambia ese paradigma al ejecutar LLMs modernos completamente en el navegador del usuario, aprovechando WebGPU para inferencia en tiempo real y preservando la privacidad.

En esta guía:

1. Mostrar cómo instalar y configurar WebLLM.
2. Cargar y ejecutar modelos populares (Llama‑3, Phi‑3, Mistral, etc.).
3. Usar la API compatible con OpenAI para chat, streaming y modo JSON.
4. Extender WebLLM con Web Workers, Service Workers y extensiones de Chrome.
5. Desplegar una demostración de chatbot ligero y local.

Vamos a sumergirnos.

1. ¿Qué es WebLLM?

WebLLM (abreviatura de Web Large Language Model) significa:

• En el navegador – Sin llamadas al servidor.
• Alto rendimiento – Utiliza WebGPU para aceleración por hardware.
• Compatible con OpenAI – La misma API que usas en el SDK de OpenAI.
• Extensible – Inserta modelos personalizados o ejecútalos en Web Workers.
• Preparado para producción – Ofrece streaming, modo JSON y llamada de funciones planificada.

Enlace rápido: https://webllm.mlc.ai

2. Instalación

# npm
npm install @mlc-ai/web-llm
# yarn
yarn add @mlc-ai/web-llm
# pnpm
pnpm add @mlc-ai/web-llm

CDN

Si prefieres una etiqueta <script>, WebLLM está disponible a través de jsDelivr:

<script type="module">
  import * as webllm from "https://esm.run/@mlc-ai/web-llm";
  // …
</script>

3. Construyendo una aplicación mínima de chat

A continuación una versión vanilla‑JS. La misma lógica funciona en React, Vue o cualquier framework.

import { CreateMLCEngine } from '@mlc-ai/web-llm';

const initProgress = (p) => console.log(`Loading: ${p.percentage}%`);
const modelId = 'Llama-3.1-8B-Instruct-q4f32_1-MLC';

async function init() {
  const engine = await CreateMLCEngine(modelId, { initProgressCallback: initProgress });
  const chat = async (messages) => {
    const result = await engine.chat.completions.create({ messages });
    return result.choices[0].message.content;
  };
  // Demo call
  const reply = await chat([
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'Tell me a joke.' }
  ]);
  console.log('AI:', reply);
}
init();

Puntos clave: - CreateMLCEngine tanto construye el motor como carga el modelo. - initProgressCallback informa el progreso de la descarga. - La API devuelta es idéntica a la de OpenAI: chat.completions.create.

4. Chat en streaming

WebLLM admite stream:true, que devuelve un AsyncGenerator.

const streamGen = await engine.chat.completions.create({
  messages,
  stream: true,
  stream_options: { include_usage: true }
});

let text = '';
for await (const chunk of streamGen) {
  text += chunk.choices[0]?.delta.content ?? '';
  console.log(text);
}
console.log('Total tokens:', chunk.usage?.total_tokens);

5. Modo JSON y salida estructurada

const reply = await engine.chat.completions.create({
  messages,
  temperature: 0.2,
  response_format: { type: 'json_object' }
});
const json = JSON.parse(reply.choices[0].message.content);

El motor garantiza que la respuesta cumpla con el esquema cuando se establece response_format.

6. Ejecución en Web Workers

Usar un Web Worker dedicado mantiene la UI receptiva.

1. worker.ts

   import { WebWorkerMLCEngineHandler } from '@mlc-ai/web-llm';
   const handler = new WebWorkerMLCEngineHandler();
   self.onmessage = handler.onmessage;
   

2. main.ts

   import { CreateWebWorkerMLCEngine } from '@mlc-ai/web-llm';
   const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' });
   const engine = await CreateWebWorkerMLCEngine(worker, modelId, { initProgressCallback });
   

Este patrón permite que el cálculo pesado se ejecute fuera del hilo principal.

7. Service Workers para caché offline

Con Service Workers, el modelo persiste entre recargas de página; úsalo para experiencias offline o de baja latencia.

self.addEventListener('activate', () => {
  /* init handler */
});

Luego registra en la app principal:

navigator.serviceWorker.register('./sw.ts', { type: 'module' });
const engine = await CreateServiceWorkerMLCEngine(modelId, { initProgressCallback });

8. Modelos personalizados

WebLLM puede ingerir cualquier modelo compilado al formato MLC. Proporciona URLs model y model_lib en una configuración de app:

const appConfig = { model_list: [{
  model: 'https://mydomain.com/my-llama',
  model_id: 'MyLlama-3B',
  model_lib: 'https://mydomain.com/myllama3b.wasm'
}] };
const engine = await CreateMLCEngine('MyLlama-3B', { appConfig });

Esto facilita iniciar modelos locales o privados.

9. Ejemplo de extensión de Chrome

WebLLM incluye plantillas de extensión – ya sea una UI ligera o un trabajador de fondo persistente. Consulta la carpeta examples/chrome-extension en el repositorio para una configuración completa que inyecta un asistente local en cualquier página web.

10. Rendimiento y compatibilidad

Aceleración por hardware

El principal aumento de velocidad proviene de WebGPU. Las pruebas muestran una reducción de 3 a 5 vez en la latencia sobre JS puro para inferencias de modelos de 8 B. En sistemas sin GPU, el motor degrada de forma transparente a WebAssembly.

11. Obtener ayuda y contribuir

• Documentación y Blog – https://webllm.mlc.ai/docs
• Discord Community – Únete para ayuda rápida.
• GitHub Issues – Reporta problemas o solicita nuevas funciones.
• Pull Requests – Contribuye al código, ejemplos o documentación.

12. Resumen

WebLLM lleva la potencia de los LLM al navegador sin costos de servidor ni compromisos de privacidad. Ya sea que estés prototipando un chatbot de IA, construyendo una extensión de Chrome o experimentando con modelos personalizados, la API modular y la aceleración WebGPU hacen de WebLLM una opción atractiva.

¿Próximos pasos? - Prueba el playground en https://webllm.mlc.ai. - Clona el repositorio y prueba examples/get-started. - Experimenta construyendo tu propia extensión de Chrome.

¡Feliz codificación y nos vemos en el navegador!