LanguageModel.measureContextUsage() — Methode · JavaScript-Referenz

Signatur

LanguageModel.prototype.measureContextUsage(input, options)

Beschreibung

Die Methode measureContextUsage() gehört zur experimentellen Prompt API (LanguageModel). Mit ihr lässt sich ermitteln, wie viele Tokens ein Prompt im Kontextfenster der Sitzung belegen würde, bevor man ihn mit prompt() oder promptStreaming() tatsächlich abschickt. Das Modell erzeugt dabei keine Antwort und die Sitzung merkt sich den Input nicht.

Sinnvoll ist das vor allem bei langen Eingaben wie Dokumenten, Chatverläufen oder eingefügtem Text. Den geschätzten Verbrauch vergleicht man mit dem freien Platz, also session.contextWindow - session.contextUsage. Reicht der Platz nicht, kann man kürzen, zusammenfassen oder eine neue Sitzung anlegen. So vermeidet man einen Kontextüberlauf, bei dem der Browser ältere Nachrichten verwirft und das Ereignis contextoverflow auslöst.

Als Input nimmt die Methode dasselbe wie prompt(): einen einfachen String oder ein Array von Nachrichten-Objekten ({ role, content }). Der Rückgabewert ist ein Promise, das mit der geschätzten Token-Zahl erfüllt wird. Das Ergebnis ist eine Schätzung. Es hängt vom Modell und seinem Tokenizer ab und kann sich deshalb je nach Browser und Modellversion unterscheiden.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string \| Array<{ role: string, content: string \| Array }>		Der zu messende Input, im selben Format wie bei `prompt()`: ein String oder ein Array von Nachrichten mit `role` (`"user"`, `"assistant"`, `"system"`) und `content`.
$options	object	{}	Optionales Objekt mit Einstellungen für die Messung.
$options.signal	AbortSignal		Ein `AbortSignal`, mit dem sich die Messung abbrechen lässt. Das Promise wird dann mit einem `AbortError` abgelehnt.
$options.responseConstraint	object \| RegExp		Optionales JSON-Schema oder optionaler regulärer Ausdruck für strukturierte Ausgabe. Eine solche Vorgabe belegt selbst Kontext und kann in die Messung eingehen.

Rückgabewert

Typ

Promise<number>

Beschreibung

Ein Promise, das mit der geschätzten Zahl der Tokens erfüllt wird, die der Input im Kontextfenster belegen würde. Abgelehnt wird es, wenn die Sitzung zerstört wurde (InvalidStateError), die Messung abgebrochen wurde (AbortError) oder der Input ungültig ist.

Beispiele

Token-Verbrauch eines Prompts schätzen

const session = await LanguageModel.create();

const prompt = 'Fasse die Vorteile von Web Workers in drei Sätzen zusammen.';
const tokens = await session.measureContextUsage(prompt);

console.log(`Geschätzter Verbrauch: ${tokens} Tokens`);
console.log(`Belegt: ${session.contextUsage} / ${session.contextWindow}`);

Geschätzter Verbrauch: 14 Tokens Belegt: 0 / 9216

Vor dem Senden prüfen, ob der Kontext reicht

const session = await LanguageModel.create({
  initialPrompts: [{ role: 'system', content: 'Du bist ein präziser Zusammenfasser.' }]
});

const summarize = async (text) => {
  const needed = await session.measureContextUsage(text);
  const free = session.contextWindow - session.contextUsage;

  if (needed > free) {
    console.warn(`Zu lang: ${needed} Tokens benötigt, nur ${free} frei.`);
    return null;
  }
  return session.prompt(text);
};

const article = document.querySelector('article').textContent;
const result = await summarize(article);
console.log(result ?? 'Text bitte kürzen.');

Chatverlauf messen und mit Timeout abbrechen

const session = await LanguageModel.create();

const messages = [
  { role: 'user', content: 'Wie heißt die Hauptstadt von Kanada?' },
  { role: 'assistant', content: 'Ottawa.' },
  { role: 'user', content: 'Und wie viele Einwohner hat sie?' }
];

try {
  const tokens = await session.measureContextUsage(messages, {
    signal: AbortSignal.timeout(2000)
  });
  console.log(`Verlauf belegt ca. ${tokens} Tokens`);
} catch (err) {
  if (err.name === 'AbortError' || err.name === 'TimeoutError') {
    console.warn('Messung abgebrochen.');
  } else {
    throw err;
  }
}

Verlauf belegt ca. 38 Tokens

// Wichtig · Fallstricke

Experimentell: Die Prompt API gibt es bisher nur in Chromium-basierten Browsern, teils nur über Origin Trials, Flags oder in Erweiterungen. Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man per 'LanguageModel' in self und LanguageModel.availability() prüfen, ob sie verfügbar ist.
Umbenennung: In älteren Spezifikationsständen und Chrome-Versionen hieß die Methode measureInputUsage(), die zugehörigen Eigenschaften hießen inputUsage/inputQuota und das Ereignis quotaoverflow. Für ältere Browser kann ein Fallback nötig sein, z. B. (session.measureContextUsage ?? session.measureInputUsage).call(session, input).
Nur eine Schätzung: Die tatsächliche Belegung kann leicht abweichen, etwa durch Rollen-Markierungen oder interne Formatierung. Plane deshalb einen kleinen Puffer ein.
Die Messung selbst beansprucht das Modell und ist nicht kostenlos. Führe sie bei Tastatureingaben nicht für jedes Zeichen aus, sondern entprellt (debounce).
Nach session.destroy() wird das Promise mit einem InvalidStateError abgelehnt.
Multimodale Inhalte wie Bilder oder Audio werden nur gemessen, wenn die Sitzung mit passenden expectedInputs angelegt wurde.

Siehe auch

LanguageModel LanguageModel.create() LanguageModel.prototype.prompt() LanguageModel.prototype.promptStreaming() LanguageModel.contextUsage LanguageModel.contextWindow AbortSignal