Polyfill expérimental pour l'API Prompt

Thomas Steiner

Publié le 14 mai 2026

Avec l'API Prompt dans Chrome, vous pouvez 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 participant au programme de preview anticipée ont fait part de leur enthousiasme pour l'API Prompt. La disponibilité de l'API pose un problème de compatibilité dans un avenir prévisible.

Solution

C'est pourquoi nous publions un polyfill expoll expérimental de l'API Prompt conforme aux spécifications (consultez le code source sur GitHub) qui implémente avec précision 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 à attendre qu'un modèle local soit disponible. Les coûts engendrés sont à votre charge, conformément aux informations sur les tarifs 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 à l'API Prompt réelle, 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 disposez de votre clé API, saisissez les informations dans votre fichier de configuration .env.json. Si vous ne spécifiez pas de modelName, le polyfill utilise le modèle par défaut de chaque backend. Toutefois, 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 décidez d'utiliser 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 de modèles compatibles de Hugging Face. Pour certains modèles, vous pouvez sélectionner 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 nommée de manière appropriée, 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 n'est pas compatible.
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 la sortie structurée (à l'exception du backend Transformers.js), gère l'entrée multimodale (à l'exception du backend OpenAI qui n'est pas compatible avec l'audio et l'image ensemble, mais uniquement séparément) et est testé par rapport à la suite complète de tests de la plate-forme Web pour le LanguageModel.

Pour en savoir plus, obtenir des informations détaillées sur l'utilisation et consulter le code source, consultez le README fichier dans le dépôt GitHub.

Différence par rapport à l'API Prompt du navigateur

Si le polyfill est basé sur 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 non 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, aucun modèle local n'est à 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é, ce qui signifie qu'il y aura deux événements, l'un avec une valeur loaded de 0 et l'autre avec 1, comme l'exige la spécification.

Avec l'inférence basée sur le cloud, contrairement à l'inférence sur l'appareil, des coûts potentiels sont associés à l'appel d'API depuis le fournisseur de backend de votre choix. Consultez les informations sur les tarifs, comme celles 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 une application 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 de votre application réelle. Avec certains fournisseurs de services cloud comme Google, vous pouvez également appliquer des vérifications d'origine strictes pour vous assurer que seuls les sites Web autorisés peuvent utiliser l'API.

Au lieu des limites de l'API Prompt, par exemple en ce qui concerne le contextWindow de la session, les limites du fournisseur de backend s'appliquent. Pour le 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. Par conséquent, même si vous devez être conscient de la différence, 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 nouveau 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 la 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. Cette option est utilisée lorsqu'un utilisateur initialise une session sans spécifier de modelName spécifique.

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

Activer le développement et les tests locaux

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 l'exécuteur 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"
}

Effectuer la validation 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 garantit que votre backend gère des éléments tels que AbortSignal, les invites système et le formatage de l'historique exactement comme prévu par la spécification de l'API Prompt.

Conclusion

Le polyfill vous permet d'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 !

Voir aussi

Polyfills expérimentaux pour les API de tâches d'IA intégrées