WebLLM: ein KI-Modell im navigateur

#WebLLM: Was die Bibliothek leistet

Bei Ollama lädt ein auf dem Rechner installiertes Programm das Modell und antwortet auf http://localhost:11434. Bei WebLLM läuft alles über eine Webseite: Diese lädt den JavaScript- und WebAssembly-Code der Engine, ruft die Modellgewichte ab und schickt die Berechnungen dann über WebGPU an die GPU. Es muss weder ein Dienst gestartet noch ein Port geöffnet werden.

Für Entwickler folgt die API der Form der OpenAI-API: Man erstellt eine Engine und ruft dann engine.chat.completions.create mit einer Liste von Nachrichten auf. Eine für dieses Format geschriebene Anwendung lässt sich daher recht schnell anpassen. Die Engine lebt jedoch in der Seite: Sie ist kein HTTP-Server, an den sich Open WebUI, ein Code-Editor oder ein Python-Skript anbinden könnten.

WebGPU

Browser-API, die Zugriff auf die GPU für Berechnungen gewährt. Ohne sie oder ohne verfügbaren Adapter kann die Engine nicht auf der GPU laufen.

WebAssembly

Format, in dem ein Teil der Engine ausgeliefert wird. Es gehört ebenso wie das JavaScript zu dem, was die Seite laden muss.

Die Gewichte des Modells

Große Dateien, getrennt vom Code der Seite. Sie werden von der in der Konfiguration angegebenen Adresse heruntergeladen und anschließend vom Browser zwischengespeichert.

Das MLC-Format

WebLLM verwendet für seine Engine kompilierte Modelle, erkennbar am Suffix MLC in ihren Kennungen. Eine für Ollama oder LM Studio heruntergeladene GGUF-Datei lässt sich nicht unverändert laden.

#WebLLM oder Ollama: Welches Tool für welchen Bedarf?

WebLLM ersetzt keine klassische lokale Installation. Sein Wert liegt woanders: eine KI-Funktion in einer Webseite anzubieten, für Menschen, die nichts installieren werden.

WebLLM eignet sich für

Eine öffentliche Demo, ein internes Webtool, ein in eine Anwendung integrierter Assistent, ein schneller Test auf einem Rechner, auf dem man nichts installieren darf.

Ollama oder LM Studio eignen sich für

Tägliche Nutzung, Auswahl aus einem großen Katalog, größere Modelle, eine von anderen Tools wiederverwendbare API, ein Betrieb, der nicht von den Grenzen eines Tabs abhängt.

Die Kosten, die Sie in Kauf nehmen müssen

Der Katalog hängt von den im MLC-Format kompilierten Modellen ab, der verfügbare Speicher hängt auch von den Grenzen des Browsers ab, und der Cache kann ohne Vorwarnung gelöscht werden.

Wir geben keinen Geschwindigkeitsvergleich an: Keine Messung mit dokumentiertem Vorgehen und dokumentierter Hardware stützt diesen Leitfaden. Wenn das für Ihr Projekt wichtig ist, messen Sie auf Ihren Zielgeräten, mit demselben Modell und derselben Quantisierung, und notieren Sie die Browser- und Treiberversion.

#Voraussetzungen und WebGPU-Kompatibilität

MDN stufte WebGPU auf seiner am 2. September 2026 geänderten Seite noch als eingeschränkt verfügbar ein, also nicht Baseline: Die API funktioniert in einigen weit verbreiteten Browsern nicht. Die Unterstützung hängt von der Kombination aus Browser, Betriebssystem und Grafiktreiber ab. Ein Browser kann WebGPU also auf einem System bereitstellen und auf einem anderen nicht. Statt einer schnell veralteten Versionsliste sollten Sie die Kompatibilitätstabelle von MDN konsultieren und dann jedes Zielgerät testen.

Sicherer Kontext

Laut MDN ist die gesamte API nur in einem sicheren Kontext verfügbar: Liefern Sie die Seite über HTTPS aus, oder während der Entwicklung über localhost. Eine per HTTP unter einer lokalen Netzwerkadresse geöffnete Seite eignet sich nicht.

Browser und Treiber

Beide auf dem neuesten Stand. Eine aktuelle GPU reicht nicht aus, wenn der Treiber oder der Browser den Zugriff blockiert.

GPU-Speicher

QuelLLM-Richtwerte in Q4 auf dem üblichen Stack: 3B etwa 2 GB, 7B etwa 5 GB. Das sind Größenordnungen, keine WebLLM-Messungen.

Speicherplatz und Verbindung

Genug, um das Modell zu speichern und es mindestens einmal herunterzuladen. Prüfen Sie die tatsächliche Größe in der Ladefortschrittsanzeige.

Dieser Test wird in die Konsole der Entwicklertools eingefügt, auf einer Seite unter HTTPS oder localhost. Er beruht auf der Standard-API und lädt kein Modell. Laut MDN gibt requestAdapter null zurück, wenn kein geeigneter Adapter verfügbar ist: Das Vorhandensein von navigator.gpu reicht also für eine Schlussfolgerung nicht aus.

if (!navigator.gpu) {
  console.log('WebGPU absent : navigateur non compatible, API désactivée ou contexte non sécurisé');
} else {
  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    console.log('API présente, mais aucun adaptateur disponible');
  } else {
    console.log('shader-f16 :', adapter.features.has('shader-f16'));
    console.log('maxBufferSize :', adapter.limits.maxBufferSize);
    console.log('maxStorageBufferBindingSize :', adapter.limits.maxStorageBufferBindingSize);
  }
}

Die Zeile shader-f16 hilft bei der Wahl der Variante. Die WebLLM-Kennungen unterscheiden in der Regel zwischen q4f16-Modellen, die diese Funktion voraussetzen, und q4f32-Modellen, die ohne sie auskommen. Die beiden Puffergrenzen zeigen, was der Browser zu allozieren bereit ist; sie können ein großes Modell blockieren, selbst wenn die Grafikkarte genug Speicher hat.

#Was der Download mit sich bringt

Beim ersten Laden ruft die Seite die Modelldateien und den zugehörigen kompilierten Code von den Adressen in ihrer Konfiguration ab. In der vorgefertigten Liste von WebLLM verweisen diese Adressen unseres Wissens auf externe Repositorys wie Hugging Face und GitHub: Überprüfen Sie dies im Tab „Netzwerk“. Diese Hoster sehen dann Ihre IP-Adresse und das angeforderte Modell, auch wenn noch keine Nachricht gesendet wurde.

Die Dateien werden anschließend im Browser-Speicher abgelegt, der an den Ursprung (Origin) der Seite gebunden ist. MDN nennt die wichtigen Regeln: Standardmäßig arbeitet dieser Speicher im Best-Effort-Modus, und der Browser kann ihn bei Speicherknappheit ohne Rückfrage beim Nutzer räumen, beginnend mit den am längsten nicht genutzten Ursprüngen. Ein geräumter Ursprung verliert alle seine Daten auf einmal. Safari kann zudem per Skript erzeugte Daten eines Ursprungs löschen, mit dem seit sieben Tagen Browsernutzung keine Interaktion stattfand, wenn die Verhinderung von websiteübergreifendem Tracking aktiv ist.

const { usage, quota } = await navigator.storage.estimate();
console.log('Utilisé :', usage, 'octets sur un quota estimé de', quota);

const persistant = await navigator.storage.persist();
console.log('Stockage persistant accordé :', persistant);

#WebLLM in eine Seite einbinden: die Schritte

Diese Anleitung setzt ein JavaScript-Projekt mit einem Build-Tool voraus, zum Beispiel Vite. Wenn Sie das Paket im Projekt installieren, statt es von einem CDN zu importieren, vermeiden Sie eine zusätzliche Drittanbieter-Domain beim Laden der Seite und erleichtern den Offline-Betrieb.

npm install @mlc-ai/web-llm

1. 01
   Version festschreiben

   Notieren Sie die installierte Version in package-lock.json und lesen Sie die zugehörige README. Prüfen Sie dabei die Lizenz des Pakets und die des Modells – das sind zwei verschiedene Dinge.
2. 02
   Verfügbare Modelle auflisten

   Kopieren Sie keine Kennung aus einem Artikel: Die Liste ändert sich. Lesen Sie sie in der installierten Version aus, mit dem ersten Codeausschnitt unten. Das darin angegebene Speicherfeld dient als Ausgangspunkt, nicht als Garantie.
3. 03
   Klein anfangen

   Wählen Sie zunächst das kleinste brauchbare Modell, in q4f32, falls der vorherige Test anzeigt, dass shader-f16 fehlt. Ein erster erfolgreicher Versuch trennt Codeprobleme von Speicherproblemen.
4. 04
   Fortschritt anzeigen

   Der Download kann lange dauern. Ohne visuelle Rückmeldung wirkt die Seite blockiert: initProgressCallback liefert den Fortschrittstext zur Anzeige.
5. 05
   In einen Web Worker auslagern

   Laden und Generierung können die Oberfläche beeinträchtigen, wenn sie im Hauptthread laufen. WebLLM bietet dafür CreateWebWorkerMLCEngine an, mit dem Handler WebWorkerMLCEngineHandler auf Worker-Seite. Planen Sie dies vor der Veröffentlichung ein.
6. 06
   Auf den Zielgeräten testen

   Ein Ergebnis auf einer Entwicklungsworkstation sagt nichts über einen Laptop mit integrierter GPU aus. Sehen Sie eine klare Meldung vor, falls WebGPU fehlt, statt einer leeren Seite.

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

console.table(prebuiltAppConfig.model_list.map((m) => ({
  id: m.model_id,
  vramMo: m.vram_required_MB,
})));

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

// Remplacez par un identifiant relevé dans la liste ci-dessus
const modelId = 'IDENTIFIANT_DU_MODELE';

const engine = await CreateMLCEngine(modelId, {
  initProgressCallback: (p) => console.log(p.text),
});

const stream = await engine.chat.completions.create({
  messages: [{ role: 'user', content: 'Explique WebGPU en deux phrases.' }],
  stream: true,
});

let reponse = '';
for await (const chunk of stream) {
  reponse += chunk.choices[0]?.delta?.content || '';
}
console.log(reponse);

#Eine WebLLM-Seite prüfen: Netzwerk, Skripte, Offlinebetrieb

WebLLM garantiert bestenfalls, wo die Berechnung ausgeführt wird. Der Rest hängt von der Seite ab, die es einbindet: Ein Analytics-Skript, ein Widget oder eine Sendefunktion kann den Inhalt des Eingabefelds lesen und übertragen, denn jedes in die Seite geladene Skript hat Zugriff auf sie. Diese Prüfung gilt für jede Website, die eine KI im Browser bewirbt, auch für Ihre eigene.

1. 01
   Ein sauberes Profil vorbereiten

   Öffnen Sie ein Browserprofil ohne Erweiterungen: Eine auf der Seite zugelassene Erweiterung kann lesen, was dort angezeigt wird, und verfälscht das Ergebnis. Öffnen Sie den Tab „Netzwerk“ und aktivieren Sie das Beibehalten des Protokolls.
2. 02
   Den Ladevorgang protokollieren

   Laden Sie die Seite und notieren Sie dann jede kontaktierte Domain und ihre Rolle: Seite, Engine, Modell, Schriftart, Reichweitenmessung, Werbung. Jede Domain ohne klare Rolle muss noch erklärt werden.
3. 03
   Das Senden einer Nachricht protokollieren

   Leeren Sie das Protokoll, sobald das Modell geladen ist. Senden Sie eine Nachricht mit einer erfundenen Markierung, zum Beispiel TEST-MARQUEUR-7Q2X, und suchen Sie sie dann mit der Suchfunktion des Netzwerk-Tabs im Protokoll. Prüfen Sie außerdem jede Anfrage, die während der Generierung abgeschickt wird, einschließlich WebSocket-Nachrichten.
4. 04
   Skripte und Sicherheits-Header untersuchen

   Listen Sie im Tab „Sources“ die Herkunftsdomains der Skripte auf. Suchen Sie in den Antwort-Headern des Dokuments nach Content-Security-Policy: Eine strikte connect-src-Direktive schränkt die möglichen Ziele ein, ihr Fehlen beweist nichts.
5. 05
   Prüfen, was auf der Festplatte verbleibt

   Öffnen Sie im Tab „Anwendung“ oder „Speicher“ IndexedDB, Cache und den lokalen Speicher. Das Modell ist dort normalerweise zu finden, aber auch Ihre Unterhaltungen können dort liegen, im Klartext für jeden, der diese Sitzung nutzt.
6. 06
   Das Netzwerk wirklich trennen

   Schließen Sie die Seite, deaktivieren Sie das WLAN oder ziehen Sie das Kabel ab, öffnen Sie dann die Adresse erneut und senden Sie eine neue Nachricht. Die Seite muss laden und antworten. Wiederholen Sie dies, nachdem Sie den Browser geschlossen haben.

Diese Prüfungen haben ihre Grenzen. Ein nicht auffindbarer Marker schließt eine verschlüsselte oder von einem Skript kodierte Übertragung nicht aus. WebRTC-Verbindungen erscheinen im Tab „Netzwerk“ nicht als gewöhnliche Anfragen: In Chrome lassen sie sich über chrome://webrtc-internals aufspüren. Schließlich gilt das Ergebnis nur für die getestete Version, denn der Betreiber der Website kann seine Skripte jederzeit ändern.

Sie können „funktioniert offline“ sagen

Wenn das erneute Öffnen und eine neue Nachricht bei getrennter Netzwerkverbindung gelingen, im getesteten Browser, zum Zeitpunkt des Tests. Weisen Sie darauf hin, dass der Cache geräumt werden kann.

Sie können „keine Übertragung beobachtet“ sagen

Wenn das Protokoll keine Anfrage im Zusammenhang mit der Nachricht zeigt, für die getestete Version und nach dem beschriebenen Vorgehen. Es handelt sich um eine datierte Beobachtung.

Sie können nicht „vollständig privat“ sagen

Es sei denn, Sie kontrollieren den gesamten ausgelieferten Code und dessen Updates, ganz ohne Skripte von Drittanbietern, und ergänzen diese Prüfung durch eine Durchsicht des Codes. Selbst dann sieht der Hoster des Modells den Download, und Erweiterungen bleiben ein Risiko.

#Alles von der eigenen Domain ausliefern

Für ein internes Tool ist die am leichtesten kontrollierbare Konfiguration, Seite, Engine und Modell vom selben Origin auszuliefern, ganz ohne Skripte von Drittanbietern. WebLLM akzeptiert eine benutzerdefinierte Konfiguration, in der jedes Modell die Adresse seiner Gewichte und die seiner kompilierten Bibliothek angibt. Die folgenden Pfade sind anzupassende Beispiele.

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

const appConfig = {
  model_list: [{
    model: 'https://outil.example.fr/modeles/mon-modele/',
    model_id: 'mon-modele',
    model_lib: 'https://outil.example.fr/libs/mon-modele.wasm',
  }],
};

const engine = await CreateMLCEngine('mon-modele', { appConfig });

Die Engine bildet die Dateiadressen selbst aus diesem Präfix. Sie erwartet möglicherweise eine Verzeichnisstruktur ähnlich der von Hugging Face: Wenn Anfragen mit 404 fehlschlagen, sehen Sie im Netzwerk-Tab nach den genau angeforderten Pfaden und bilden Sie diese auf Ihrem Server nach. Die kompilierte Bibliothek muss zum Modell passen: Kombinieren Sie sie nicht wahllos mit einem anderen.

Sobald alles lokal bereitgestellt ist, kann eine Sicherheitsrichtlinie aus einem Versprechen eine technische Vorgabe machen: Laut MDN beschränkt connect-src unter anderem fetch, XMLHttpRequest, WebSocket, EventSource und sendBeacon und greift auf default-src zurück, wenn es fehlt. Das folgende Beispiel wurde nicht mit WebLLM getestet. Setzen Sie es zunächst im Modus Content-Security-Policy-Report-Only ein und lesen Sie die Konsole.

Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; worker-src 'self'; connect-src 'self'

Dieser Header blockiert auch Downloads von Hugging Face: Das ist gewollt, und das Modell muss dann von Ihrer Domain ausgeliefert werden. Er deckt nicht alle möglichen Ausgänge ab, etwa eine Navigation zu einer anderen Adresse. Für den Offlinebetrieb fügen Sie einen Service Worker hinzu, der die Dateien der Seite zwischenspeichert. WebLLM bietet für diesen Kontext auch eine Engine an, CreateServiceWorkerMLCEngine: Ziehen Sie dazu die README zurate.

#Fehlerbehebung

navigator.gpu ist undefined

Prüfen Sie zuerst die Adresse: HTTPS oder localhost. Sehen Sie dann in der Kompatibilitätstabelle von MDN nach, was für Ihren Browser und Ihr System gilt, und aktualisieren Sie anschließend beide.

requestAdapter gibt null zurück

Die API existiert, aber kein geeigneter Adapter ist verfügbar. Aktualisieren Sie den Treiber und prüfen Sie, ob die Hardwarebeschleunigung des Browsers aktiviert ist. Probieren Sie einen anderen Browser, um die Ursache einzugrenzen.

Fehler im Zusammenhang mit shader-f16

Das gewählte Modell benötigt eine Funktion, die Ihrem Adapter fehlt. Nehmen Sie seine q4f32-Variante, falls vorhanden.

QuotaExceededError

Das Kontingent des Origins ist überschritten: MDN nennt diesen Fehler für IndexedDB, Cache und OPFS. Geben Sie Speicherplatz frei oder wählen Sie ein kleineres Modell, und fangen Sie den Fehler im Code ab.

Absturz am Ende des Ladevorgangs oder Verlust der GPU

Wahrscheinlich zu wenig Speicher oder Puffergrenze erreicht. Schließen Sie ressourcenhungrige Tabs, wählen Sie eine Modellgröße kleiner und prüfen Sie die genaue Meldung in der Konsole.

Das Modell wird erneut heruntergeladen

Privates Surfen, Bereinigung des Speichers, gelöschte Websitedaten oder ein Wechsel des Origins, da jede Domain ihren eigenen Speicher hat. Das Paket stellt unseres Wissens hasModelInCache bereit, um dies vor dem Start des Ladevorgangs zu prüfen.

Die Oberfläche friert während der Generierung ein

Die Engine läuft im Hauptthread. Wechseln Sie zu CreateWebWorkerMLCEngine.

Fehler der Sicherheitsrichtlinie in der Konsole

Die Meldung nennt die blockierte Direktive und Adresse. Prüfen Sie, ob diese Adresse legitim ist, bevor Sie die Regel erweitern, insbesondere wenn Sie eine Seite ohne externe Übertragung ankündigen.

#Weiterführende Informationen

Wenn Sie einen Assistenten für sich selbst suchen und keine in eine Seite integrierte Funktion, ist eine klassische lokale Installation leichter zu kontrollieren: Der Vergleich der kostenlosen Lösungen ist dafür der richtige Ausgangspunkt. Ergänzen Sie bei sensibler Nutzung die Prüfungen dieses Leitfadens durch die Datenschutz-Checkliste.