Un polyfill experimental para la API de Prompt

Thomas Steiner

Fecha de publicación: 14 de mayo de 2026

Con la API de Prompt en Chrome, puedes interactuar con un LLM usando una API de navegador de alto nivel en window.LanguageModel. Sin embargo, la compatibilidad con esta función sigue siendo limitada, y su implementación es un proceso complejo.

Al mismo tiempo, los desarrolladores que participan en el programa de vista previa anticipada compartieron su entusiasmo por la API de Prompt. La disponibilidad de la API plantea un desafío de compatibilidad en el futuro previsible.

Solución

Por eso, lanzamos un polyfill de la API de Prompt compatible con las especificaciones experimental (consulta el código fuente en GitHub) que implementa con precisión la API de Prompt sobre proveedores de backend configurables en la nube y también sobre un proveedor de backend local en forma de Transformers.js.

Cómo usar el polyfill

Para usar el polyfill, haz lo siguiente:

1. Descarga el polyfill desde npm:

   npm install prompt-api-polyfill
   

2. Elige si deseas usar un proveedor de backend en la nube o un proveedor de backend local:

   • Proveedor de backend en la nube: Los datos del usuario se envían a la nube para su procesamiento remoto, pero no tienes que esperar a que haya un modelo local disponible. Eres responsable de cualquier costo incurrido según la información de precios de tu proveedor de servicios en la nube.
   • Proveedor de backend local: Los datos del usuario permanecen en el navegador y se procesan de forma local, pero debes descargar un modelo que, a diferencia de la API de Prompt real, no se puede compartir entre diferentes orígenes. El procesamiento local no tiene costos.

Backend de Cloud

Elige cualquiera de los backends de Cloud y obtén una clave de API (y cualquier credencial adicional) para tu proveedor de backend.

Una vez que tengas tu clave de API, ingresa los detalles en tu archivo de configuración .env.json. Si no especificas un modelName, el polyfill usará el modelo predeterminado de cada backend, pero, si lo haces, podrás seleccionar uno de los modelos compatibles de cada backend.

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

Backend local

Si decides usar un proveedor de backend local basado en Transformers.js, solo necesitas una clave de API ficticia. Sin embargo, puedes configurar qué dispositivo debe usar Transformers.js. Elige "webgpu" para obtener el máximo rendimiento y "wasm" para obtener la máxima compatibilidad. También puedes cambiar la configuración predeterminada. Elige otro modelo del catálogo de modelos compatibles de Hugging Face. Para algunos modelos, puedes seleccionar diferentes cuantificaciones con el parámetro dtype.

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

Configura tu polyfill

Con el archivo de configuración en su lugar, ahora puedes comenzar a usar el polyfill en tu app.

1. Importa el archivo de configuración y asígnale una variable global con un nombre adecuado, en la que $BACKEND es el backend que elegiste: window.$BACKEND_CONFIG.
2. Usa una importación dinámica para cargar el polyfill solo cuando el navegador subyacente no lo admita.
3. Llama a las funciones de la API de 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!');

El polyfill admite salida estructurada (excepto el backend de Transformers.js), admite entrada multimodal (excepto el backend de OpenAI que no admite audio e imagen juntos, solo por separado) y se prueba con el conjunto completo de pruebas de la plataforma web para LanguageModel.

Para obtener más información sobre los antecedentes y el uso detallado, así como el código fuente, consulta el archivo README en el repo de GitHub.

Diferencia con la API de Prompt del navegador

Si el polyfill se basa en modelos de nube, algunos de los beneficios de ejecutar el código del cliente ya no se aplican. En particular, ya no puedes garantizar el procesamiento local de datos sensibles, aunque se sigan aplicando las políticas de privacidad de tu proveedor de backend. Tu app tampoco puede usar la IA cuando el usuario está sin conexión. Para saber si estás en línea o sin conexión, puedes escuchar los eventos correspondientes.

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

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

Si la inferencia de IA se ejecuta en un modelo en la nube, no hay ningún modelo local para descargar. El polyfill simula los eventos downloadprogress, por lo que, para tu app, parecerá que el modelo integrado ya se descargó, lo que significa que habrá dos eventos, uno con un valor loaded de 0 y otro con 1, que es lo que requiere la especificación.

Con la inferencia basada en la nube, a diferencia de la inferencia en el dispositivo, existe un costo potencial cuando se llaman a las APIs desde el proveedor de backend que elijas. Consulta la información de precios, como la de la API de Gemini. Si conoces el costo por token, puedes usar la información de contextUsage de la API de Prompt para calcular el costo.

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.
}

Cuando llamas a una API de Cloud directamente desde una app web o para dispositivos móviles (por ejemplo, las APIs que permiten el acceso a modelos de IA generativa), la clave de API es vulnerable al abuso por parte de clientes no autorizados. Para ayudar a proteger estas APIs, si usas el SDK híbrido de Firebase AI Logic, debes usar la Verificación de aplicaciones de Firebase para verificar que todas las llamadas entrantes a la API provengan de tu app real. Con algunos proveedores de servicios en la nube, como Google, también puedes aplicar verificaciones de origen estrictas para asegurarte de que solo los sitios web permitidos puedan usar la API.

En lugar de los límites de la API de Prompt, por ejemplo, en relación con el contextWindow de la sesión, se aplican los límites del proveedor de backend. En el caso de contextWindow, estos límites suelen ser mucho más altos que integrado en el dispositivo, y puedes procesar mayores cantidades de datos en la nube, por lo que, si bien debes tener en cuenta la diferencia, en la práctica, es probable que no tengas problemas con esto.

Crea tu propio backend

Para agregar tu propio proveedor de backend, sigue estos pasos:

Extiende la clase de backend base

Crea un archivo nuevo en el directorio backends/, por ejemplo, backends/custom-backend.js. Debes extender la clase PolyfillBackend e implementar los métodos principales que satisfagan la interfaz esperada.

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)
  }
}

Registra tu backend

El polyfill usa una estrategia de "prioridad de la primera coincidencia" basada en la configuración global. Debes registrar tu backend en el archivo prompt-api-polyfill.js agregándolo al array #backends estático:

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

Cómo establecer un modelo predeterminado

Define la identidad del modelo de respaldo en backends/defaults.js. Se usa cuando un usuario inicializa una sesión sin especificar un modelName específico.

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

Habilita el desarrollo y las pruebas locales

El proyecto usa una secuencia de comandos de detección (scripts/list-backends.js) para generar matrices de pruebas. Para incluir tu nuevo backend en el ejecutor de pruebas, crea un archivo .env-[name].json (por ejemplo, .env-custom.json) en el directorio raíz:

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

Verifica con las pruebas de la plataforma web (WPT)

El último paso es garantizar el cumplimiento. Debido a que el polyfill se basa en las especificaciones, cualquier backend nuevo debería pasar las pruebas oficiales (o tentativas) de la Plataforma Web:

npm run test:wpt

Este paso de verificación garantiza que tu backend maneje elementos como AbortSignal, las instrucciones del sistema y el formato del historial exactamente como lo espera la especificación de la API de Prompt.

Conclusión

El polyfill te ayuda a usar la API de Prompt en todas las plataformas y dispositivos. Si escribes código en función de la API bien definida de la API de Prompt, te independizas más de los proveedores de servicios en la nube y te mantienes lo más cerca posible de la plataforma.

En los dispositivos compatibles con la API de Prompt, ni siquiera se carga el polyfill, por lo que evitas que los usuarios descarguen código que no ejecutarán. Si tienes comentarios o encuentras un error, abre un problema en GitHub. ¡Sigue creando instrucciones!

Consulta también

Polyfills experimentales para las APIs de tareas de IA integradas