Executando LLMs no Navegador — Um Guia Completo sobre WebLLM

Introdução

"Quero usar LLMs, mas gerenciar chaves de API é tão trabalhoso…" "Não quero enviar a entrada do usuário para a nuvem…"

O WebLLM resolve esses dois problemas de uma vez.

O WebLLM é um mecanismo de inferência de alto desempenho que executa LLMs diretamente no navegador — completamente sem servidor e sem backend. Diferente dos serviços de IA baseados em nuvem como ChatGPT ou Claude, todo o processamento de inferência é concluído inteiramente no dispositivo do usuário.

Este artigo fornece uma explicação completa da arquitetura, funcionalidades e métodos de implementação do WebLLM.

O Que é o WebLLM?

O WebLLM (@mlc-ai/web-llm) é uma biblioteca JavaScript de código aberto desenvolvida pelo projeto MLC-AI. Foi construída principalmente por pesquisadores da Carnegie Mellon University, Shanghai Jiao Tong University e NVIDIA, e foi publicada no final de 2024 como o artigo "WebLLM: A High-Performance In-Browser LLM Inference Engine".

Em resumo:

Um framework que transforma o navegador em um ambiente de execução para LLMs.

Principais Funcionalidades

Como Funciona

A razão pelo qual o WebLLM oferece alto desempenho é que ele aproveita completamente as mais recentes tecnologias de navegador.

1. WebGPU — Aceleração de GPU

WebGPU é uma nova Web API para acesso de baixo nível à GPU a partir do navegador. Diferente do WebGL mais antigo, é projetado especificamente para computação de propósito geral em GPU (GPGPU), permitindo operações matriciais de alta velocidade necessárias para LLMs.

Internamente, o WebLLM usa Apache TVM e MLC-LLM para otimizar grafos de computação de modelos para WebGPU. Técnicas de otimização de inferência de ponta como PagedAttention e FlashAttention também são incorporadas.

O que é particularmente significativo é o benefício da abstração de dispositivo. Implementações nativas tradicionais exigiam bases de código separadas para cada fornecedor — CUDA (NVIDIA), Metal (Apple), etc. — mas com WebGPU, uma única implementação pode atingir múltiplas GPUs.

graph LR
    A[Abordagem Tradicional] --> B[Implementação CUDA]
    A --> C[Implementação Metal]
    A --> D[Implementação OpenCL]
    A --> E[...]
    
    F[Abordagem WebLLM] --> G[WebGPU único para todas as GPUs ✨]

2. WebAssembly (Wasm) — Fallback de CPU

O WebAssembly desempenha um papel importante quando a GPU está indisponível ou para computações auxiliares de CPU. Como pode executar código computacional avançado escrito em C/C++ em velocidade próxima ao nativo no navegador, ele lida eficientemente com certos processamentos de modelo no lado da CPU.

3. Web Workers — Isolamento da Thread da UI

A inferência de LLM é extremamente intensiva em recursos. Executá-la na thread principal congelaria a UI. O WebLLM executa o processamento de inferência em um Web Worker, mantendo a responsividade da interface do usuário.

graph LR
    A[Thread Principal] <-->|Passagem de Mensagens| B[Web Worker]
    A --> C[Atualizações da UI]
    B --> D[Inferência LLM]

4. Cache Storage — Inicialização Rápida Após o Primeiro Carregamento

Os modelos LLM geralmente têm centenas de megabytes a vários gigabytes. O WebLLM salva os modelos baixados no Cache Storage do navegador, para que inicializações subsequentes carreguem instantaneamente a partir do cache.

Visão Geral da Arquitetura

A arquitetura do WebLLM consiste em três componentes principais.

graph TB
    A[Aplicação Web<br/>API JavaScript semelhante à OpenAI]
    B[MLCEngine Web Worker<br/>Descarrega inferência pesada da thread da UI]
    C[WebGPU / WebAssembly<br/>Aceleração de GPU / Computação auxiliar de CPU]
    
    A --> B
    B --> C

Desempenho

De acordo com os resultados de avaliação do artigo "WebLLM: A High-Performance In-Browser LLM Inference Engine" (arXiv:2412.15803):

Ao comparar o WebLLM (WebGPU + JavaScript/Wasm) com o MLC-LLM (Metal + Python/C++) em um Apple MacBook Pro M3 Max, o WebLLM reteve até 80% da velocidade de decodificação nativa.

Apesar de rodar no navegador, atingir até 80% do desempenho nativo demonstra que chegou a um nível prático de usabilidade.

Modelos Suportados

O WebLLM suporta uma ampla gama de modelos (exemplos selecionados):

• Série Llama 3.1 / 3.2
• Série Phi 3.5 / 4
• Série Gemma 2
• Série Mistral
• Série Qwen 2.5

Múltiplos formatos de quantização (como q4f16_1 e q4f32_1) estão disponíveis, permitindo escolher com base na capacidade de memória do seu dispositivo.

Implementação

Criei uma aplicação de chat usando o WebLLM. Aqui está uma captura de tela em funcionamento:

Um assistente de IA privado que roda inteiramente no navegador. Todo o processamento é executado localmente.

Vamos ver como implementar uma aplicação assim.

Instalação

npm install @mlc-ai/web-llm

Implementação Básica de Chat

import * as webllm from "@mlc-ai/web-llm";

async function main() {
  // Selecionar um modelo (quantizado)
  const selectedModel = "Llama-3.2-3B-Instruct-q4f16_1-MLC";

  // Inicializar o engine (progresso do download via callback)
  const engine = await webllm.CreateMLCEngine(selectedModel, {
    initProgressCallback: (progress) => {
      console.log(`Carregando: ${Math.round(progress.progress * 100)}%`);
    },
  });

  // Chat usando a API compatível com OpenAI
  const reply = await engine.chat.completions.create({
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "Tell me about WebLLM." },
    ],
  });

  console.log(reply.choices[0].message.content);
}

main();

Implementação com Web Worker (Recomendado)

Para evitar congelamentos da UI, usar Web Workers é recomendado em produção.

import * as webllm from "@mlc-ai/web-llm";

const handler = new webllm.WebWorkerMLCEngineHandler();
self.onmessage = (msg) => {
  handler.onmessage(msg);
};

import * as webllm from "@mlc-ai/web-llm";

const selectedModel = "Llama-3.2-3B-Instruct-q4f16_1-MLC";

// Criar um engine Web Worker
const engine = new webllm.WebWorkerMLCEngine(
  new Worker(new URL("./worker.js", import.meta.url), { type: "module" })
);

// Configurar o callback de progresso
engine.setInitProgressCallback((progress) => {
  console.log(`Carregando: ${Math.round(progress.progress * 100)}%`);
});

// Carregar o modelo
await engine.reload(selectedModel);

// Depois é só chamar engine.chat.completions.create() normalmente

Suporte a Streaming

const stream = await engine.chat.completions.create({
  messages: [{ role: "user", content: "Fale sobre o Monte Fuji" }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(delta); // Saída em tempo real
}

Advertências e Limitações

Embora o WebLLM seja uma tecnologia muito atraente, é importante entender suas limitações atuais.

Suporte a WebGPU nos Navegadores (em fevereiro de 2026): A situação melhorou significativamente no final de 2025, e agora todos os quatro principais navegadores — Chrome, Edge, Firefox e Safari — têm WebGPU habilitado por padrão. No entanto, o suporte varia por plataforma.

Como o suporte também depende do hardware e do status do driver da GPU, a detecção de recursos via navigator.gpu e uma implementação de fallback via WebAssembly ainda são recomendadas.

Configurações de Aceleração de Hardware
Mesmo em máquinas equipadas com GPU, as configurações do navegador podem restringir a renderização ao modo de software. Se o WebGPU mostrar "Software only" em chrome://gpu:

1. Habilitar aceleração de hardware: Ativar "Usar aceleração de hardware quando disponível" em chrome://settings/system
2. Desabilitar lista de bloqueio de GPU: Habilitar "Substituir lista de renderização de software" em chrome://flags
3. Reiniciar completamente o navegador: Fechar todas as janelas antes de reiniciar

Após a configuração, verifique se o status do WebGPU mostra "Hardware acelerado" em chrome://gpu.

Download Inicial Pesado
Os modelos devem ser baixados no primeiro início. Mesmo a versão quantizada do Llama-3.2-3B tem aproximadamente 2–3 GB, tornando a implementação de indicador de progresso essencial para uma boa experiência do usuário.

Modelos Não São Compartilhados Entre Origens
Modelos em cache são compartilhados apenas dentro da mesma origem. Usar o mesmo modelo em um app web diferente requer um download separado.

Sanitizando a Saída do LLM
Inserir texto gerado diretamente no DOM apresenta riscos de XSS. Sempre sanitize a saída usando bibliotecas como DOMPurify.

// ❌ Perigoso
element.innerHTML = llmOutput;

// ✅ Seguro
element.innerHTML = DOMPurify.sanitize(llmOutput);

Casos de Uso

Aqui estão cenários onde o WebLLM é particularmente eficaz.

Aplicações Focadas em Privacidade
Em campos que lidam com informações sensíveis — como saúde, jurídico e finanças — é crucial que os dados não sejam enviados para a nuvem. O WebLLM conclui todo o processamento no dispositivo.

Aplicações com Capacidade Offline
Uma vez baixado o modelo, recursos de IA podem ser fornecidos sem conexão à internet. Combinado com PWA, você pode construir assistentes de IA que funcionam offline.

Redução de Custos
Como as taxas de chamada de API são eliminadas, economias significativas de custo podem ser esperadas para aplicações de alto uso.

Inferência Híbrida
Uma arquitetura híbrida — usando WebLLM no navegador para tarefas leves e APIs na nuvem para as mais pesadas — também é uma abordagem eficaz.

Perspectivas Futuras

A especificação WebGPU ainda está evoluindo, e a adição de novos recursos como subgrupos deve trazer melhorias adicionais de desempenho. Suporte aprimorado para o backend Metal do Apple Silicon e dispositivos móveis também é esperado.

À medida que os navegadores amadurecem como ambientes de execução de IA na borda, o WebLLM está preparado para se tornar uma escolha padrão para o desenvolvimento de aplicações de IA com foco em privacidade.

Resumo

O WebLLM é uma tecnologia que está reformulando o pressuposto de que "a IA roda na nuvem." Experimente a demonstração oficial em WebLLM Chat para vivenciar o LLM no navegador.

Referências

• Documentação Oficial do WebLLM
• GitHub: mlc-ai/web-llm
• Artigo: WebLLM: A High-Performance In-Browser LLM Inference Engine (arXiv:2412.15803)
• web.dev: Build a local, offline-ready chatbot with WebLLM