Polyfill expérimental pour l'API Prompt

Thomas Steiner

Publié le : 14 mai 2026

L'API Prompt de Chrome vous permet d'interagir avec un LLM à l'aide d'une API de navigateur de haut niveau sur window.LanguageModel. Toutefois, la compatibilité est encore limitée et l'implémentation est un processus complexe.

Parallèlement, les développeurs du programme Preview anticipée ont fait part de leur enthousiasme pour l'API Prompt. La disponibilité de l'API pose un problème de compatibilité pour l'avenir prévisible.

Solution

C'est pourquoi nous publions un polyfill de l'API Prompt conforme aux spécifications (consultez le code source sur GitHub) qui implémente précisément l'API Prompt sur des fournisseurs de backend cloud configurables, ainsi que sur un fournisseur de backend local sous la forme de Transformers.js.

Utiliser le polyfill

Pour utiliser le polyfill, procédez comme suit :

1. Téléchargez le polyfill depuis npm :

   npm install prompt-api-polyfill
   

2. Choisissez si vous souhaitez utiliser un fournisseur de backend cloud ou un fournisseur de backend local :

   • Fournisseur de backend cloud : les données utilisateur sont envoyées au cloud pour un traitement à distance, mais vous n'avez pas besoin d'attendre qu'un modèle local soit disponible. Vous êtes responsable de tous les coûts encourus, conformément aux informations tarifaires de votre fournisseur de services cloud.
   • Fournisseur de backend local : les données utilisateur restent dans le navigateur et sont traitées localement, mais vous devez télécharger un modèle qui, contrairement à la véritable API Prompt, ne peut pas être partagé entre différentes origines. Le traitement local n'entraîne aucun coût.

Backend cloud

Choisissez l'un des backends cloud et obtenez une clé API (et tous les identifiants supplémentaires) pour votre fournisseur de backend.

Une fois que vous avez obtenu votre clé API, saisissez les informations dans votre fichier de configuration .env.json. Si vous ne spécifiez pas de modelName, le polyfill utilisera le modèle par défaut de chaque backend. Si vous le faites, vous pouvez sélectionner l'un des modèles compatibles de chaque backend.

{
  "apiKey": "y0ur-Api-k3Y",
  "modelName": "model-name"
}

Backend local

Si vous choisissez un fournisseur de backend local basé sur Transformers.js, vous n'avez besoin que d'une clé API factice. Vous pouvez toutefois configurer l'appareil que Transformers.js doit utiliser. Choisissez "webgpu" pour des performances maximales et "wasm" pour une compatibilité maximale. Vous pouvez éventuellement modifier les paramètres par défaut. Choisissez un autre modèle dans le catalogue Hugging Face des modèles compatibles. Pour certains modèles, vous pouvez choisir parmi différentes quantifications à l'aide du paramètre dtype.

{
  "apiKey": "dummy",
  "device": "webgpu",
  "dtype": "q4f16",
  "modelName": "onnx-community/gemma-3-1b-it-ONNX-GQA"
};

Configurer votre polyfill

Une fois le fichier de configuration en place, vous pouvez commencer à utiliser le polyfill dans votre application.

1. Importez le fichier de configuration et attribuez-le à une variable globale portant un nom approprié, où $BACKEND est le backend de votre choix : window.$BACKEND_CONFIG.
2. Utilisez une importation dynamique pour ne charger le polyfill que lorsque le navigateur sous-jacent ne le prend pas en charge.
3. Appelez les fonctions de l'API Prompt.

import config from './.env.json' with { type: 'json' };

// Set $BACKEND_CONFIG to select a backend
window.$BACKEND_CONFIG = config;

if (!('LanguageModel' in window)) {
  await import('prompt-api-polyfill');
}

const session = await LanguageModel.create({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
await session.prompt('Tell me a joke!');

Le polyfill est compatible avec les sorties structurées (sauf pour le backend Transformers.js), gère les entrées multimodales (sauf pour le backend OpenAI qui ne prend pas en charge l'audio et les images ensemble, mais uniquement séparément) et est testé avec la suite complète de tests de la plate-forme Web pour LanguageModel.

Pour en savoir plus sur le contexte et l'utilisation détaillée, ainsi que sur le code source, consultez le fichier README dans le dépôt GitHub.

Différence avec l'API Prompt du navigateur

Si le polyfill est soutenu par des modèles cloud, certains des avantages de l'exécution côté client ne s'appliquent plus. En d'autres termes, vous ne pouvez plus garantir le traitement local des données sensibles, bien que les règles de confidentialité de votre fournisseur de backend s'appliquent toujours. Votre application ne peut plus utiliser l'IA lorsque l'utilisateur est hors connexion. Pour savoir si vous êtes en ligne ou hors connexion, vous pouvez écouter les événements correspondants.

window.addEventListener("offline", (e) => {
  console.log("offline");
});

window.addEventListener("online", (e) => {
  console.log("online");
});

Si l'inférence d'IA s'exécute sur un modèle dans le cloud, il n'y a pas de modèle local à télécharger. Le polyfill simule les événements downloadprogress. Votre application aura donc l'impression que le modèle intégré a déjà été téléchargé. Il y aura donc deux événements : un avec une valeur loaded de 0 et un avec 1, comme l'exige la spécification.

Contrairement à l'inférence sur l'appareil, l'inférence basée sur le cloud peut entraîner des coûts lorsque vous appelez des API depuis le fournisseur de backend de votre choix. Consultez les informations sur les tarifs, comme ceux de l'API Gemini. Si vous connaissez le coût par jeton, vous pouvez utiliser les informations contextUsage de l'API Prompt pour calculer le coût.

const COST_PER_TOKEN = 123;
const COST_LIMIT = 456;

let costSoFar = 0;

const session = await LanguageModel.create(options);

/…/

if (costSoFar < COST_LIMIT) {
  await session.prompt('Tell me a joke.');
  costSoFar = session.contextUsage * COST_PER_TOKEN;
} else {
  // Show premium AI plan promo.
}

Lorsque vous appelez une API Cloud directement depuis une application mobile ou Web (par exemple, les API qui permettent d'accéder à des modèles d'IA générative), la clé API est vulnérable aux utilisations abusives par des clients non autorisés. Pour protéger ces API, si vous utilisez le SDK hybride Firebase AI Logic, vous devez utiliser Firebase App Check pour vérifier que tous les appels d'API entrants proviennent bien de votre application. Avec certains fournisseurs de services cloud comme Google, vous pouvez également appliquer des vérifications strictes de l'origine pour vous assurer que seuls les sites Web autorisés peuvent utiliser l'API.

Ce sont les limites du fournisseur de backend qui s'appliquent, et non celles de l'API Prompt, par exemple en ce qui concerne le contextWindow de la session. Pour contextWindow, ces limites sont généralement beaucoup plus élevées que sur l'appareil, et vous pouvez traiter de plus grandes quantités de données dans le cloud. Vous devez donc être conscient de cette différence, mais en pratique, vous ne rencontrerez probablement pas de problèmes.

Créer votre propre backend

Pour ajouter votre propre fournisseur de backend, procédez comme suit :

Étendre la classe de backend de base

Créez un fichier dans le répertoire backends/ (par exemple, backends/custom-backend.js). Vous devez étendre la classe PolyfillBackend et implémenter les méthodes de base qui répondent à l'interface attendue.

import PolyfillBackend from './base.js';
import { DEFAULT_MODELS } from './defaults.js';

export default class CustomBackend extends PolyfillBackend {
  constructor(config) {
    // config typically comes from a window global (e.g., window.CUSTOM_CONFIG)
    super(config.modelName || DEFAULT_MODELS.custom.modelName);
  }

  // Check if the backend is configured (e.g., API key is present), if given
  // combinations of modelName and options are supported, or, for local model,
  // if the model is available.
  static availability(options) {
    return window.CUSTOM_CONFIG?.apiKey ? 'available' : 'unavailable';
  }

  // Initialize the underlying SDK or API client. With local models, use
  // monitorTarget to report model download progress to the polyfill.
  createSession(options, sessionParams, monitorTarget) {
    // Return the initialized session or client instance
  }

  // Non-streaming prompt execution
  async generateContent(contents) {
    // contents: Array of { role: 'user'|'model', parts: [{ text: string }] }
    // Return: { text: string, usage: number }
  }

  // Streaming prompt execution
  async generateContentStream(contents) {
    // Return: AsyncIterable yielding chunks
  }

  // Token counting for quota/usage tracking
  async countTokens(contents) {
    // Return: total token count (number)
  }
}

Enregistrer votre backend

Le polyfill utilise une stratégie de "priorité de première correspondance" basée sur la configuration globale. Vous devez enregistrer votre backend dans le fichier prompt-api-polyfill.js en l'ajoutant au tableau statique #backends :

// prompt-api-polyfill.js
static #backends = [
  // ... existing backends
  {
    config: 'CUSTOM_CONFIG', // The global object to look for on `window`
    path: './backends/custom-backend.js',
  },
];

Définir un modèle par défaut

Définissez l'identité du modèle de remplacement dans backends/defaults.js. Il est utilisé lorsqu'un utilisateur initialise une session sans spécifier de modelName.

// backends/defaults.js
export const DEFAULT_MODELS = {
  // ...
  custom: 'custom-model-pro-v1',
};

Activer le développement et les tests en local

Le projet utilise un script de découverte (scripts/list-backends.js) pour générer des matrices de test. Pour inclure votre nouveau backend dans le lanceur de tests, créez un fichier .env-[name].json (par exemple, .env-custom.json) dans le répertoire racine :

{
  "apiKey": "your-api-key-here",
  "modelName": "custom-model-pro-v1"
}

Valider avec les tests de la plate-forme Web (WPT)

La dernière étape consiste à assurer la conformité. Étant donné que le polyfill est basé sur les spécifications, tout nouveau backend doit réussir les tests officiels (ou provisoires) de la plate-forme Web :

npm run test:wpt

Cette étape de validation permet de s'assurer que votre backend gère des éléments tels que AbortSignal, les invites système et la mise en forme de l'historique exactement comme le prévoit la spécification de l'API Prompt.

Conclusion

Le polyfill vous aide à utiliser l'API Prompt sur toutes les plates-formes et tous les appareils. En codant par rapport à l'API bien définie de l'API Prompt, vous devenez plus indépendant des fournisseurs de services cloud et restez aussi proche que possible de la plate-forme.

Sur les appareils compatibles avec l'API Prompt, le polyfill n'est même pas chargé. Vous évitez ainsi à vos utilisateurs de télécharger du code qu'ils n'exécuteront pas. Si vous avez des commentaires ou si vous rencontrez un bug, ouvrez un problème sur GitHub. Nous vous souhaitons une excellente lecture !