LanguageModel: contextoverflow — Ereignis · JavaScript-Referenz

Signatur

languageModel.addEventListener("contextoverflow", handler)

Beschreibung

Das Ereignis contextoverflow gehört zur experimentellen Prompt API. Jede LanguageModel-Sitzung hat ein begrenztes Kontextfenster (contextWindow, gemessen in Tokens). Mit jedem Prompt, jeder Antwort und jedem append() steigt der Verbrauch (contextUsage). Führt ein Aufruf dazu, dass der Verbrauch das Fenster überschreitet, entfernt der Browser automatisch die ältesten Nachrichten (außer dem System-Prompt) aus dem Verlauf und löst danach contextoverflow aus.

Das Ereignis dient also als Hinweis, dass die Sitzung Teile ihres Gedächtnisses verloren hat. Typische Reaktionen sind: den Nutzer informieren („Ältere Nachrichten werden nicht mehr berücksichtigt“), eine Zusammenfassung des bisherigen Gesprächs erzeugen und in eine neue Sitzung übernehmen oder Telemetrie zur Kontextnutzung erfassen.

Den Handler registriert man entweder per addEventListener("contextoverflow", handler) oder über die Eigenschaft oncontextoverflow. Das übergebene Objekt ist ein einfaches Event ohne zusätzliche Eigenschaften, es ist nicht abbrechbar und bubbelt nicht. Den aktuellen Stand liest man im Handler direkt an der Sitzung ab (session.contextUsage, session.contextWindow).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier `"contextoverflow"`.
$handler Pflicht	(event: Event) => void		Callback, der nach dem Kürzen des Kontexts aufgerufen wird. Erhält ein normales `Event`; `event.target` ist die betroffene `LanguageModel`-Instanz.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (z. B. zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Das Ereignis selbst liefert ein Event-Objekt ohne spezielle Zusatzdaten.

Beispiele

Nutzer über den Kontextverlust informieren (addEventListener)

const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'Du bist ein hilfsbereiter Support-Assistent.' }
  ]
});

session.addEventListener('contextoverflow', (event) => {
  const s = event.target;
  console.warn(
    `Kontext voll: ${s.contextUsage}/${s.contextWindow} Tokens – ältere Nachrichten wurden verworfen.`
  );
  document.querySelector('#hinweis').hidden = false;
});

const antwort = await session.prompt('Wie setze ich mein Passwort zurück?');
console.log(antwort);

Kontext voll: 4012/4096 Tokens – ältere Nachrichten wurden verworfen.

Handler über oncontextoverflow setzen und wieder entfernen

const session = await LanguageModel.create();

session.oncontextoverflow = () => {
  console.log('Kontextfenster überschritten');
};

// Später: Handler entfernen
session.oncontextoverflow = null;

// Alternativ mit addEventListener + AbortController
const controller = new AbortController();
session.addEventListener('contextoverflow', () => {
  console.log('Überlauf erkannt');
}, { signal: controller.signal });

controller.abort(); // Listener wird entfernt

Bei Überlauf Gespräch zusammenfassen und neue Sitzung starten

const systemPrompt = 'Du bist ein Reiseplaner.';
let session = await LanguageModel.create({
  initialPrompts: [{ role: 'system', content: systemPrompt }]
});

const neuStarten = async () => {
  const zusammenfassung = await session.prompt(
    'Fasse unser bisheriges Gespräch in 5 Stichpunkten zusammen.'
  );
  session.destroy();
  session = await LanguageModel.create({
    initialPrompts: [
      { role: 'system', content: systemPrompt },
      { role: 'assistant', content: `Bisheriger Stand:\n${zusammenfassung}` }
    ]
  });
  session.addEventListener('contextoverflow', neuStarten, { once: true });
  console.log('Neue Sitzung mit Zusammenfassung gestartet');
};

session.addEventListener('contextoverflow', neuStarten, { once: true });

Neue Sitzung mit Zusammenfassung gestartet

Überlauf vorbeugen: Verbrauch vorher messen

const session = await LanguageModel.create();
const eingabe = 'Sehr langer Text …';

// Methode je nach Browserversion: measureContextUsage() (neu) bzw. measureInputUsage() (älter)
const kosten = await session.measureContextUsage(eingabe);
const frei = session.contextWindow - session.contextUsage;

if (kosten > frei) {
  console.log('Prompt würde contextoverflow auslösen – Text wird gekürzt.');
} else {
  console.log(await session.prompt(eingabe));
}

Prompt würde contextoverflow auslösen – Text wird gekürzt.

// Wichtig · Fallstricke

Experimentelle API: Die Prompt API ist derzeit nur in Chromium-Browsern mit integriertem Modell verfügbar (z. B. Chrome in Erweiterungen bzw. per Origin Trial/Flag). Vorher immer mit 'LanguageModel' in self und LanguageModel.availability() prüfen.
Umbenennungen: In älteren Implementierungen hieß das Ereignis quotaoverflow (Handler onquotaoverflow) und die Eigenschaften inputUsage/inputQuota sowie die Methode measureInputUsage(). Für Kompatibilität ggf. beide Ereignisnamen registrieren.
Das Ereignis wird nach dem Verwerfen alter Nachrichten ausgelöst – es lässt sich weder abbrechen noch rückgängig machen. Wer den Verlust vermeiden will, muss vorher mit der Messmethode prüfen.
Der System-Prompt bleibt erhalten. Ist schon eine einzelne Eingabe größer als das gesamte Fenster, wird kein Überlauf behandelt; stattdessen wird der Aufruf mit einer DOMException (QuotaExceededError) abgelehnt.
Wird ein Handler in einer neuen Sitzung erneut registriert, { once: true } verwenden oder alte Sitzungen mit destroy() freigeben, um Speicherlecks und doppelte Aufrufe zu vermeiden.

Siehe auch

Element: contextmenu Element: pointerover HTMLCanvasElement: contextlost Animation: cancel Animation: remove