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, aún hay compatibilidad limitada para esto, y la implementación es un proceso complejo.

Al mismo tiempo, los desarrolladores del 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 experimental de la API de Prompt compatible con las especificaciones (consulta el código fuente en GitHub) que implementa con precisión la API de Prompt sobre proveedores de backend en la nube configurables y también sobre un proveedor de backend local en forma de Transformers.js.

Usa el polyfill

Para usar el polyfill, haz lo siguiente:

1. Descarga el polyfill desde npm:

   npm install prompt-api-polyfill
   

2. Elige si quieres 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 el procesamiento remoto, pero no tienes que esperar a que esté disponible un modelo local. 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 en diferentes orígenes. No hay ningún costo asociado con el procesamiento local.

Backend en la nube

Elige cualquiera de los backends en la nube 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, puedes 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. De manera opcional, puedes cambiar la configuración predeterminada. Elige otro modelo del catálogo de modelos compatibles de Hugging Face. Para algunos modelos, puedes seleccionar entre 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ígnalo a una variable global con un nombre adecuado, en la que $BACKEND sea el backend elegido: 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 resultados estructurados (excepto para el backend de Transformers.js), se ocupa de la entrada multimodal (excepto para 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 el LanguageModel.

Para obtener más información general y detallada sobre el uso, así como el código fuente, consulta el archivo README en el repositorio de GitHub.

Diferencia de la API de Prompt del navegador

Si el polyfill está respaldado por modelos en la nube, ya no se aplican algunos de los beneficios de la ejecución del cliente. Es decir, 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 conectado o no, 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 integrado en el dispositivo, existe un costo potencial cuando se llama a las APIs del 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 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 la nube 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 proteger estas APIs, si usas el SDK híbrido de Firebase AI Logic, debes usar Verificación de aplicaciones de Firebase para verificar que todas las llamadas a la API entrantes 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. Para el 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 estático #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',
  },
];

Establece un modelo predeterminado

Define la identidad del modelo de resguardo 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 descubrimiento (scripts/list-backends.js) para generar matrices de prueba. 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 especificaciones, cualquier backend nuevo debe pasar las pruebas oficiales (o tentativas) de la plataforma web:

npm run test:wpt

Este paso de verificación garantiza que tu backend controle 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 codificas en función de la API de Prompt bien definida, te vuelves más independiente 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, el polyfill ni siquiera se carga, 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!