Taalmodel

Webfuncties: LanguageModel

Met de Prompt API kunnen ontwikkelaars taken voor de verwerking van natuurlijke taal rechtstreeks in de browser uitvoeren met Gemini Nano. Deze ingebouwde AI-aanpak waarborgt de privacy van gebruikers, verlaagt de serverkosten en maakt offline functionaliteit mogelijk.

1. Aan de slag en hardwarevereisten

De Prompt API is op dit moment beschikbaar in Chrome vanaf versie 148 (desktop) voor Windows, macOS, Linux en Chromebook Plus.

Hardwarevereisten

  • Opslag: 22 GB vrije ruimte (voor het eerste profiel en model).
  • Geheugen/CPU: 16 GB RAM en 4+ CPU-kernen.
  • GPU: 4 GB VRAM of meer (vereist voor audio-invoer).
  • Netwerk: Alleen vereist voor de eerste download van het model.

De API initialiseren

Controleer de beschikbaarheid van het model voordat je een download activeert:

const availability = await LanguageModel.availability();

// Do not call create() when unavailable — the model cannot run on this device.
if (availability !== 'unavailable') {
    const session = await LanguageModel.create({
        monitor(m) {
            // Inform the user while the model downloads so the UI doesn't appear frozen.
            m.addEventListener('downloadprogress', (e) => {
                console.log(`Downloaded ${e.loaded * 100}%`);
            });
        },
    });
}

2. Kernfuncties voor prompts

In de sessievoorbeelden in dit gedeelte wordt session.destroy() weggelaten om de voorbeelden kort te houden. Roep session.destroy() altijd aan als een sessie niet meer nodig is om apparaatgeheugen vrij te maken (zie Artikel 5).

Basis- en gestreamde uitvoer

Gebruik prompt() voor korte reacties. Gebruik promptStreaming() voor langere content om een responsievere UI te bieden.

VERPLICHT: Wijs modeluitvoer nooit toe aan innerHTML. De modeluitvoer is niet vertrouwd en kan geïnjecteerde opmaak bevatten. Gebruik altijd textContent of een sanitizer.

const session = await LanguageModel.create();

// prompt() accumulates the full response before resolving — use for short, one-shot output.
const result = await session.prompt('Write a haiku about coding.');
// textContent, not innerHTML — model output is untrusted and must not be parsed as markup.
outputEl.textContent = result;

// promptStreaming() yields independent chunks that must be concatenated;
// use for longer content so each chunk can be rendered progressively.
const stream = session.promptStreaming('Write a long story about a robot.');
let completeResult = '';
for await (const chunk of stream) {
    completeResult += chunk;
    outputEl.append(chunk);
}
console.log('Full story:', completeResult);

Multimodale invoer

De Prompt API ondersteunt tekst-, audio- en visuele invoer (afbeeldingen, canvas, videoframes).

const session = await LanguageModel.create({
    // Declaring expected input types lets the browser optimize model loading.
    expectedInputs: [{ type: 'text' }, { type: 'image' }],
    expectedOutputs: [{ type: 'text' }],
});

const response = await session.prompt([
    {
        role: 'user',
        content: [
            { type: 'text', value: 'What is in this image?' },
            { type: 'image', value: document.querySelector('canvas') },
        ],
    },
]);

3. Geavanceerd sessiebeheer

Met sessies kan het model de context behouden tijdens meerdere interacties.

Context en quotum

Elke sessie heeft een maximale tokenlimiet. U kunt het gebruik controleren via session.contextUsage en session.contextWindow. Als het venster overloopt, worden de oudste berichten (behalve de systeemprompt) verwijderd.

Sessies klonen

Klonen is efficiënt om parallelle gesprekken te starten die dezelfde initiële context delen (zoals een systeempersoonlijkheid) zonder opnieuw te initialiseren.

const mainSession = await LanguageModel.create({
    initialPrompts: [{ role: 'system', content: 'You speak like a pirate.' }],
});

const branchA = await mainSession.clone();
const branchB = await mainSession.clone();
// Destroy the base after cloning — the clones own their own context from here.
mainSession.destroy();

Eerdere sessies herstellen

We werken aan een systeemeigen herstelfunctie, maar je kunt een sessie ook opnieuw maken door de eerdere geschiedenis in te voeren in initialPrompts.

Opmerking: localStorage is niet versleuteld en is permanent. Opgeslagen gespreksgeschiedenis kan PII van gebruikers bevatten. Denk na over de privacygevolgen voordat je de chatgeschiedenis bewaart.

// || '[]' ensures JSON.parse never receives null when the key doesn't exist yet.
const history = JSON.parse(localStorage.getItem('chat_history') || '[]');
const session = await LanguageModel.create({
    initialPrompts: history, // Array of {role, content} objects
});

4. Gestructureerde uitvoer met json-schema

Als je wilt voorkomen dat het model 'babbelt' (bijvoorbeeld 'Natuurlijk, hier is je JSON:'), gebruik je een JSON-schema via het veld responseConstraint. Zo zorg je dat de uitvoer geldige JSON is die onmiddellijk kan worden geparseerd.

Voorbeeld: sentimentclassificatie

// Pass the schema as a plain object — do not JSON.stringify() it first.
const schema = {
    type: 'object',
    properties: {
        rating: { type: 'number', minimum: 1, maximum: 5 },
        is_positive: { type: 'boolean' },
    },
    required: ['rating', 'is_positive'],
};

const result = await session.prompt(
    "Rate the following feedback: 'The food was great!'",
    { responseConstraint: schema },
);

const data = JSON.parse(result);
console.log(data.rating); // 5

Beperkingen en voorvoegsels

Je kunt het model verder begeleiden door de reactie van de assistent vooraf in te vullen met prefix: true.

const character = await session.prompt([
    { role: 'user', content: 'Create a character sheet' },
    { role: 'assistant', content: '```json\n', prefix: true },
]);

5. Best practices en veiligheid

  • Resource Cleanup: Always call session.destroy() when a conversation is finished to free up memory.
  • Uitvoerveiligheid: De modeluitvoer is niet vertrouwd. Schrijf resultaten altijd naar textContent, niet naar innerHTML, om XSS-injectie door schadelijke modeluitvoer te voorkomen.
  • Gebruik een sanitizer zoals de native Sanitizer API of DOMPurify als je beperkte HTML wilt toestaan.
  • Taken afbreken: Gebruik AbortController om gebruikers toe te staan langdurige generaties te stoppen. Geef de signal door aan prompt() of promptStreaming(), niet aan LanguageModel.create().
  • Beveiliging: Gebruik rechtenbeleid om de toegang in iframes te beheren: <iframe src="..." allow="language-model"></iframe>.
  • Ontwerp: Neem het People + AI Guidebook door om te zorgen dat je AI op een verantwoorde manier implementeert.

Door gestructureerde uitvoer te combineren met robuust sessiebeheer, kunnen ontwikkelaars complexe, stateful AI-apps bouwen die volledig op het apparaat van de gebruiker worden uitgevoerd.

Wel en niet doen

Ga naar https://developer.chrome.com/docs/ai/built-in-ai-dos-donts.md.txt voor de volledige lijst met do's-and-don'ts. Hieronder staat de essentie:

Het model op een redelijke tijd voorbereiden

Van toepassing op: alle API's, bijvoorbeeld Summarizer, Translator en Writer.

Doen: Initialiseer de sessie zodra je duidelijk hebt vastgesteld dat de gebruiker de AI-functie wil gebruiken, bijvoorbeeld als een gebruiker naar een relevant AI-toolgebied navigeert, de cursor op een AI-werkruimte plaatst of interactie heeft met de UI rond de functie. Door de sessie vooraf op te warmen, kan het model op de achtergrond in het geheugen worden geladen terwijl de gebruiker de taak instelt. Zo wordt vermijdbare vertraging bij een koude start voorkomen. Probeer een stap voor te blijven door de volgende meest waarschijnlijke AI-taak te starten zodra je het huidige resultaat begint te renderen, bijvoorbeeld als de functie is ontworpen voor iteratief gebruik.

Niet doen: Wacht niet tot de gebruiker op Genereren klikt om de sessie te initialiseren, tenzij dit nodig is. Dit leidt tot een vertraging bij de cold start, omdat het model eerst in het geheugen moet worden geladen en de uitvoeringspipeline moet worden voorbereid.

Stel de eerste prompts in tijdens het maken

Van toepassing op: Prompt API.

Doen: Systeeminstructies geven tijdens de initialisatie van de sessie om de snelheid van de eerste prompt te verbeteren.

Niet doen: Begin met een lege sessie en stuur systeeminstructies als onderdeel van de eerste prompt()-aanroep. Dit verhoogt de latentie omdat het model gedwongen wordt om die instructies op het laatste moment te verwerken.

Sessies klonen voor herhaalde taken

Van toepassing op: Prompt API.

Voor de Prompt API houdt elke sessie de context van het gesprek bij, waarbij rekening wordt gehouden met alle eerdere interacties. Omdat een kloon alles overneemt van de bovenliggende sessie, inclusief de eerste prompts en de hele interactiegeschiedenis tot het moment van klonen, moet je je gebruik zo structureren dat je alleen overneemt wat je nodig hebt.

Doen:

  • Maak een basissessie: Als je niet-gerelateerde taken efficiënt wilt afhandelen, maak je een basissessie die alleen je systeeminstructies bevat en geen eerdere gesprekscontext.
  • De baseline klonen: Gebruik clone() voor die basissessie voor nieuwe taken om de overhead van het opnieuw parseren van systeeminstructies te besparen. Zo kun je parallelle gesprekken maken of een taak resetten naar de basislijn.

Niet doen:

  • Gebruik dezelfde sessie niet opnieuw voor niet-gerelateerde taken en kloon geen sessies die al onnodige interactiegeschiedenis bevatten. Beide patronen kunnen ertoe leiden dat niet-gerelateerde eerdere context je huidige taak verstoort.
  • Roep create() niet herhaaldelijk aan met identieke systeeminstructies. Gebruik in plaats daarvan het kloonpatroon om de prestaties te optimaliseren.

Ongebruikte sessies vernietigen

Van toepassing op: Alle API's.

Doen: Roep destroy() expliciet aan voor sessies die je niet meer nodig hebt om geheugen vrij te maken als een functie niet meer wordt gebruikt. Als je een kloonpatroon gebruikt, behoud je de basissessie en vernietig je de klonen die je niet meer nodig hebt.

Niet doen: Meerdere grote sessies actief houden. Elke sessie verbruikt geheugen, wat onnodig brongebruik veroorzaakt en een probleem kan worden. Sessies worden op een natuurlijke manier opgeschoond door de garbage collector, maar door destroy() aan te roepen, komt er sneller geheugen vrij.

Streamingreacties veilig en efficiënt weergeven

Van toepassing op: Alle API's met streamingondersteuning (Prompt, Summarizer, Writer, Rewriter en Translator).

Doen: Behandel alle LLM-uitvoer als niet-vertrouwde content. Schoon de volledige gecombineerde uitvoer op, niet alleen delen, omdat schadelijke code kan worden opgesplitst in updates. Gebruik vóór de weergave de Sanitizer API, indien ondersteund. Gebruik een streaming Markdown-parser zoals streaming-markdown om een afname in de prestaties te voorkomen.

Niet doen: Stel innerHTML rechtstreeks in bij elke update van een segment. Dit is traag, vooral bij complexe opmaak zoals syntaxismarkering, en kwetsbaar voor injectie.

Invoer optimaliseren voor snelheid

Van toepassing op: Alle API's.

Doen: Geef alleen aan het model door wat strikt noodzakelijk is. Verwijder alles wat niet relevant is voor de taak. Geef voor grote datasets een kort overzicht en een kleine selectie van relevante items.

Niet doen: Onbewerkte tekst, onnodige metadata, HTML-tags of grote ongefilterde lijsten naar de API's sturen. De vertraging neemt aanzienlijk toe met de invoergrootte, waardoor de AI-functie op veel apparaten niet lijkt te werken.

Gestructureerde uitvoer gebruiken voor voorspelbare resultaten

Van toepassing op: Prompt API.

Doen: Als je wilt dat het model gegevens in een specifieke indeling retourneert, gebruik je gestructureerde uitvoer door een responseConstraint-veld te verstrekken om een JSON-schema te leveren. Zo zorg je dat de uitvoer voorspelbaar is en hoef je geen complexe nabewerking of handmatige parsering uit te voeren.

Niet doen: Vertrouw niet alleen op instructies in natuurlijke taal (zoals 'alleen JSON uitvoeren'). Modellen kunnen gespreksvulling bevatten die je parser breekt.

Generatie loskoppelen van lengtebeperkingen

Van toepassing op: Prompt API, omdat dit de enige API is die gestructureerde uitvoerschema's ondersteunt.

Doen: Laat het model de reactie op een natuurlijke manier genereren en gebruik daarna logica aan de clientzijde om de tekst in te korten zodat deze in je UI past.

Niet doen: Strikte tekenlimieten zoals maxLength: 125 afdwingen met gestructureerde uitvoerschema's. Als de reactie van een model langer is dan de limiet die je hebt ingesteld, kan het model overschakelen naar tokens met een hoge dichtheid, zoals vreemde talen of emoji's, om de betekenis te comprimeren. Dit leidt tot onzinnige uitvoer.

Houd de gebruiker op de hoogte

Van toepassing op: Alle API's.

Doen: Gebruik animaties, visuele aanwijzingen en voortgangsindicatoren om de gebruiker op de hoogte te houden, afhankelijk van de complexiteit en de verwachte duur van de taak. De optimale aanpak hangt af van je use case en de verwachte lengte van de API-uitvoer. Enkele ideeën:

  • Streaming voor lange content: Voor samenvattingen of chats maakt streaming standaard een typemachine-effect per token. Dit kan natuurlijk aanvoelen en onmiddellijke feedback geven.
  • Niet-streaming voor korte taken (of lange asynchrone taken): Voor korte uitvoer, zoals alt-tekst, kan niet-streaming een meer gepolijste UI opleveren. Ook is er tijd om de volgende AI-taak voor te bereiden terwijl de huidige taak wordt gerenderd. Deze aanpak werkt ook voor langere asynchrone of achtergrondtaken. Als de gebruiker niet wordt geblokkeerd door de uitvoer om verder te gaan, is er geen dringende noodzaak om de uitvoer te produceren terwijl deze plaatsvindt. Geef in de UI aan dat het proces wordt uitgevoerd.
  • Visuele overgangen voor updates: Gebruik animaties, zoals woordvervorming, als je tekst vertaalt of herschrijft.

Niet doen: De UI updaten zonder visuele aanwijzingen.

Afstemmen op het mentale model van de gebruiker van tijd en werk

Van toepassing op: Alle API's.

Doen: Overweeg een kunstmatige vertraging van 1 of 2 seconden als een reactie bijna onmiddellijk is. Paradoxaal genoeg vinden gebruikers resultaten misschien betrouwbaarder als ze een generatieproces waarnemen dat overeenkomt met de waargenomen moeilijkheidsgraad van de taak. Gebruik animaties om aan te geven dat er AI-verwerking heeft plaatsgevonden.

Niet doen: Gebruikers verrassen met onmiddellijke UI-vervangingen.

Gebruikers toestaan snel te navigeren en AI-bewerkingen ongedaan te maken

Van toepassing op: Alle API's.

Doen: Voorzie je UI van een stepper of navigatiegeschiedenis waarmee gebruikers met vertrouwen verschillende resultaten kunnen verkennen en AI-bewerkingen snel ongedaan kunnen maken. Zo zorg je dat verschillende versies nog steeds makkelijk beschikbaar zijn.

Niet doen: Het vorige concept van de gebruiker of een AI-resultaat dat de gebruiker misschien leuk vond, overschrijven zonder een manier om terug te gaan, de wijzigingen ongedaan te maken of versies te vergelijken.

Gebruikerscontrole en overschrijvingen mogelijk maken

Van toepassing op: Alle API's.

Doen: Maak de gebruiker de uiteindelijke editor van alle gegenereerde content. Bied intuïtieve overschrijvingen, zodat de gebruiker de volledige controle houdt over de uiteindelijke uitvoer. De API's kunnen onjuiste resultaten opleveren.

Niet doen: Een AI-gegenereerd resultaat afdwingen als de enige optie.

Resultaten in het cachegeheugen opslaan voor herhaalde taken

Van toepassing op: Alle API's.

Doen: Implementeer een lokale resultaatcache (bijvoorbeeld met sessionStorage of IndexedDB) voor herhaalde invoer of query's. Normaliseer de invoer door witruimte weg te halen en kleine letters te gebruiken om het aantal hits in de cache te verhogen. Voor zware invoer, zoals afbeeldingen, genereer je een hash om te gebruiken als cachesleutel. Stel een conservatieve TTL (time to live) in voor je cache (of lever resultaten in de cache terwijl je ze op de achtergrond updatet). Laat de gebruiker een nieuwe inferentie activeren als het resultaat niet naar wens is.

Niet doen: Voer dezelfde inferentie niet opnieuw uit voor een herhaalde zoekopdracht of identieke gegevensinvoer waarbij variabiliteit niet wenselijk is, bijvoorbeeld als een gebruiker heen en weer navigeert tussen zoekresultaten. Dit optimaliseert de reactiesnelheid en het efficiënte gebruik van lokale rekenkracht.

6. Reservestrategieën

Check vóór gebruik of het LanguageModel-object beschikbaar is in het algemene bereik:

if ('LanguageModel' in self) {
  // The Prompt API is supported.
} else {
  // Execute fallback strategy
}

Als de Prompt API niet wordt ondersteund of als beschikbaarheidscontroles 'niet beschikbaar' retourneren, moet je op een elegante manier terugvallen:

  • Remote API Fallback: Redirect the detection request to a server endpoint or a cloud API (such as the Vertex AI Gemini API).
  • Lokale API-fallback: Stuur het detectieverzoek door naar een lokaal eindpunt, bijvoorbeeld met Transformers.js.