Le guide ultime de WebLLM : LLMs dans le navigateur avec WebGPU

Les modèles de langage (LLMs) sont devenus une composante essentielle du développement IA, mais la majorité de l'écosystème repose encore sur de lourds serveurs cloud. WebLLM change ce paradigme en exécutant les modèles LLM modernes entièrement dans le navigateur de l'utilisateur, en utilisant WebGPU pour une inférence en temps réel tout en préservant la confidentialité.

Dans ce guide nous allons :

1. Montrer comment installer et configurer WebLLM.
2. Charger et exécuter des modèles populaires (Llama‑3, Phi‑3, Mistral, etc.).
3. Utiliser l'API compatible OpenAI pour le chat, le streaming et le mode JSON.
4. Étendre WebLLM avec des Web Workers, des Service Workers et des extensions Chrome.
5. Déployer une démo de chatbot léger et local.

Plongeons dedans.

1. Qu'est‑ce que WebLLM ?

WebLLM (abréviation de Web Large Language Model) est :

• Dans le navigateur – Pas d'appels serveur.
• Performant – Utilise WebGPU pour l'accélération matérielle.
• Compatible OpenAI – Même API que l'on trouve dans le SDK d'OpenAI.
• Extensible – Chargez vos propres modèles ou exécutez‑les sur des Web Workers.
• Prêt pour la production – Offre le streaming, le mode JSON et prévoit un appel de fonction.

Lien rapide : https://webllm.mlc.ai

2. Installation

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

CDN

Si vous préférez un tag script, WebLLM est disponible via jsDelivr:

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

3. Construire une application de chat minimal

Ci‑dessous une version vanilla‑JS. La même logique fonctionne dans React, Vue ou tout autre 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();

Points clés : - CreateMLCEngine à la fois construit le moteur et charge le modèle. - initProgressCallback rapporte la progression du téléchargement. - L'API retournée est une copie d'OpenAI : chat.completions.create.

4. Chat en streaming

WebLLM supporte stream:true, retournant 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. Mode JSON et sortie structurée

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);

Le moteur garantit que la réponse respecte le schéma lorsqu'on fixe response_format.

6. Exécution sur Web Workers

Utiliser un Web Worker dédié garde l'UI réactive.

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 });
   

Ce schéma permet de déplacer les calculs lourds hors du thread principal.

7. Service Workers pour la mise en cache hors‑ligne

Avec les Service Workers, le modèle persiste entre les rechargements de page ; utilisez‑le pour des expériences hors‑ligne ou à faible latence.

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

Puis registrez‑le dans l'application principale :

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

8. Modèles personnalisés

WebLLM peut ingérer n’importe quel modèle compilé au format MLC. Fournissez model et model_lib dans un app config :

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 });

Cela rend triviale l’initialisation de modèles locaux ou privés.

9. Exemple d’extension Chrome

WebLLM fournit des scaffolds d’extension – soit une interface légère, soit un worker de fond persistant. Référez‑vous au dossier examples/chrome-extension du dépôt pour une configuration complète injectant un assistant local sur n’importe quelle page web.

10. Performance & Compatibilité

Accélération matérielle

Le principal gain de vitesse provient de WebGPU. Les benchmarks montrent une réduction de latence de 3 × ‑ 5 × par rapport à du JS « plain » pour l’inférence de modèles 8‑B. Sur les systèmes sans GPU, le moteur se dégrade automatiquement vers WebAssembly.

11. Obtenir de l’aide & Contribuer

• Documentation & Blog – https://webllm.mlc.ai/docs
• Communauté Discord – Rejoignez pour de l’aide rapide.
• Issues GitHub – Signalez des problèmes ou des demandes de fonctionnalités.
• Pull Requests – Contribuez au code, aux exemples ou à la documentation.

12. En résumé

WebLLM apporte la puissance des LLMs au navigateur sans coûts serveur ni compromis en matière de confidentialité. Que vous prototypiez un chatbot IA, construisiez une extension Chrome ou expérimentiez vos propres modèles, l’API modulaire et l’accélération WebGPU font de cette solution un choix très attractif.

Prochaines étapes ? - Essayez le playground sur https://webllm.mlc.ai. - Clonez le dépôt et essayez examples/get-started. - Expérimentez en créant votre propre extension Chrome.

Bon code et à bientôt dans le navigateur !