Polyfill eksperimental untuk Prompt API

Thomas Steiner

Dipublikasikan: 14 Mei 2026

Dengan Prompt API di Chrome, Anda dapat berinteraksi dengan LLM menggunakan API browser tingkat tinggi di window.LanguageModel. Namun, dukungan untuk hal ini masih terbatas dan implementasinya merupakan proses yang kompleks.

Pada saat yang sama, developer dalam program pratinjau awal telah menyampaikan antusiasme mereka terhadap Prompt API. Ketersediaan API ini menimbulkan tantangan kompatibilitas untuk masa mendatang.

Solusi

Oleh karena itu, kami merilis polyfill Prompt API yang sesuai dengan spesifikasi eksperimental (lihat kode sumber di GitHub) yang menerapkan Prompt API secara akurat di atas penyedia backend cloud yang dapat dikonfigurasi dan juga di atas penyedia backend lokal dalam bentuk Transformers.js.

Menggunakan polyfill

Untuk menggunakan polyfill, lakukan hal berikut:

1. Download polyfill dari npm:

   npm install prompt-api-polyfill
   

2. Pilih apakah Anda ingin menggunakan penyedia backend cloud atau penyedia backend lokal:

   • Penyedia backend cloud: Data pengguna dikirim ke cloud untuk pemrosesan jarak jauh, tetapi Anda tidak perlu menunggu model lokal tersedia. Anda bertanggung jawab atas biaya yang dikeluarkan sesuai dengan informasi harga penyedia cloud Anda.
   • Penyedia backend lokal: Data pengguna tetap berada di browser dan diproses secara lokal, tetapi Anda perlu mendownload model, yang, tidak seperti Prompt API sebenarnya, tidak dapat dibagikan di berbagai origin. Tidak ada biaya yang terkait dengan pemrosesan lokal.

Backend cloud

Pilih salah satu backend cloud dan dapatkan kunci API (dan kredensial tambahan apa pun) untuk penyedia backend Anda.

Setelah memiliki kunci API, masukkan detailnya di file konfigurasi .env.json. Jika Anda tidak menentukan modelName, polyfill akan menggunakan model default setiap backend, tetapi jika Anda melakukannya, Anda dapat memilih salah satu model yang didukung dari setiap backend.

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

Backend lokal

Jika Anda memutuskan untuk menggunakan penyedia backend lokal berdasarkan Transformers.js, Anda hanya memerlukan kunci API dummy. Namun, Anda dapat mengonfigurasi perangkat yang harus digunakan Transformers.js. Pilih "webgpu" untuk performa maksimum, dan "wasm" untuk kompatibilitas maksimum. Anda dapat mengubah setelan default secara opsional. Pilih model lain dari katalog model yang kompatibel dari Hugging Face. Untuk beberapa model, Anda dapat memilih dari kuantisasi yang berbeda menggunakan parameter dtype.

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

Mengonfigurasi polyfill

Dengan file konfigurasi yang sudah ada, Anda kini dapat mulai menggunakan polyfill di aplikasi Anda.

1. Impor file konfigurasi dan tetapkan ke variabel global yang diberi nama dengan tepat, dengan $BACKEND adalah backend yang Anda pilih: window.$BACKEND_CONFIG.
2. Gunakan impor dinamis untuk hanya memuat polyfill saat browser yang mendasarinya tidak mendukungnya.
3. Panggil fungsi Prompt API.

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!');

Polyfill mendukung output terstruktur (kecuali untuk backend Transformers.js), menangani input multimodal (kecuali untuk backend OpenAI yang tidak mendukung audio dan gambar secara bersamaan, hanya secara terpisah), dan diuji terhadap rangkaian lengkap Web Platform Tests untuk LanguageModel.

Untuk mengetahui latar belakang dan informasi penggunaan mendetail serta kode sumber, lihat file README di repo GitHub.

Perbedaan dari Prompt API browser

Jika polyfill didukung oleh model cloud, beberapa manfaat menjalankan sisi klien tidak lagi berlaku. Yaitu, Anda tidak dapat lagi menjamin pemrosesan lokal data sensitif, meskipun kebijakan privasi penyedia backend Anda tetap berlaku. Aplikasi Anda juga tidak dapat lagi menggunakan AI saat pengguna offline. Untuk mengetahui apakah Anda online atau offline, Anda dapat memproses peristiwa yang sesuai.

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

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

Jika inferensi AI berjalan terhadap model di cloud, tidak ada model lokal yang dapat didownload. Polyfill memalsukan peristiwa downloadprogress, sehingga aplikasi Anda akan terlihat seolah-olah model bawaan telah didownload, yang berarti akan ada dua peristiwa, satu dengan nilai loaded sebesar 0 dan satu dengan 1, yang merupakan persyaratan spesifikasi.

Dengan inferensi berbasis cloud, tidak seperti inferensi di perangkat, ada potensi biaya yang terlibat saat memanggil API dari penyedia backend pilihan Anda. Periksa informasi harga, seperti untuk Gemini API. Jika mengetahui biaya per token, Anda dapat menggunakan informasi contextUsage Prompt API untuk menghitung biaya.

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

Saat Anda memanggil Cloud API langsung dari aplikasi seluler atau aplikasi web (misalnya, API yang memungkinkan akses ke model AI generatif), Kunci API rentan disalahgunakan oleh klien yang tidak sah. Untuk membantu melindungi API ini, jika Anda menggunakan Firebase AI Logic Hybrid SDK, Anda harus menggunakan Firebase App Check untuk memverifikasi bahwa semua panggilan API masuk berasal dari aplikasi Anda yang sebenarnya. Dengan beberapa penyedia cloud seperti Google, Anda juga dapat menerapkan pemeriksaan origin yang ketat untuk memastikan hanya situs yang diizinkan dapat menggunakan API.

Bukan batas Prompt API, misalnya, terkait contextWindow sesi, batas penyedia backend berlaku. Untuk contextWindow, batas ini biasanya jauh lebih tinggi daripada di perangkat, dan Anda dapat memproses data dalam jumlah yang lebih besar di cloud, sehingga meskipun Anda harus mengetahui perbedaannya, dalam praktiknya, Anda mungkin tidak akan mengalami masalah dengan hal ini.

Membuat backend Anda sendiri

Untuk menambahkan penyedia backend Anda sendiri, ikuti langkah-langkah berikut:

Memperluas class backend dasar

Buat file baru di direktori backends/, misalnya, backends/custom-backend.js. Anda harus memperluas class PolyfillBackend dan menerapkan metode inti yang memenuhi antarmuka yang diharapkan.

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

Mendaftarkan backend Anda

Polyfill menggunakan strategi "Prioritas Kecocokan Pertama" berdasarkan konfigurasi global. Anda harus mendaftarkan backend di file prompt-api-polyfill.js dengan menambahkannya ke array #backends statis:

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

Menetapkan model default

Tentukan identitas model penggantian di backends/defaults.js. Hal ini digunakan saat pengguna menginisialisasi sesi tanpa menentukan modelName tertentu.

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

Mengaktifkan pengembangan dan pengujian lokal

Project ini menggunakan skrip penemuan (scripts/list-backends.js) untuk membuat matriks pengujian. Untuk menyertakan backend baru Anda di peluncur pengujian, buat file .env-[name].json (misalnya, .env-custom.json) di direktori root:

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

Memverifikasi dengan Web Platform Tests (WPT)

Langkah terakhir adalah memastikan kepatuhan. Karena polyfill didorong oleh spesifikasi, backend baru harus lulus Web Platform Tests resmi (atau tentatif):

npm run test:wpt

Langkah verifikasi ini memastikan bahwa backend Anda menangani hal-hal seperti AbortSignal, perintah sistem, dan pemformatan histori persis seperti yang diharapkan oleh spesifikasi Prompt API.

Kesimpulan

Polyfill membantu Anda menggunakan Prompt API di semua platform dan perangkat. Dengan membuat kode terhadap API Prompt API yang ditentukan dengan baik, Anda menjadi lebih independen dari penyedia cloud dan tetap sedekat mungkin dengan platform.

Di perangkat yang mendukung Prompt API, polyfill bahkan tidak dimuat, sehingga Anda tidak perlu mendownload kode yang tidak akan dieksekusi. Jika Anda memiliki masukan atau menemukan bug, buka Masalah di GitHub. Selamat menulis perintah!

Lihat juga

Polyfill eksperimental untuk API tugas AI bawaan