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 penerapannya merupakan proses yang rumit.

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

Solusi

Itulah sebabnya kami merilis polyfill Prompt API yang sesuai dengan spesifikasi eksperimental (lihat kode sumber di GitHub) yang secara akurat mengimplementasikan Prompt API 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 hingga model lokal tersedia. Anda bertanggung jawab atas semua 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) untuk penyedia backend Anda.

Setelah Anda memiliki kunci API, masukkan detailnya dalam 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 maksimal, dan "wasm" untuk kompatibilitas maksimal. 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 berbagai kuantisasi menggunakan parameter dtype.

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

Mengonfigurasi polyfill

Dengan adanya file konfigurasi, Anda kini dapat mulai menggunakan polyfill di aplikasi.

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 pokok 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 ini 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 Web Platform Tests lengkap untuk LanguageModel.

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

Perbedaan dengan Prompt API browser

Jika polyfill didukung oleh model cloud, beberapa manfaat menjalankan sisi klien tidak berlaku lagi. Artinya, Anda tidak dapat lagi menjamin pemrosesan data sensitif secara lokal, meskipun kebijakan privasi penyedia backend Anda tetap berlaku. Aplikasi Anda juga tidak dapat lagi menggunakan AI saat pengguna offline. Untuk mengetahui apakah Anda sedang 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 perlu didownload. Polyfill memalsukan peristiwa downloadprogress, sehingga bagi aplikasi Anda, akan tampak seolah-olah model bawaan sudah didownload, yang berarti akan ada dua peristiwa, satu dengan nilai loaded 0 dan satu dengan 1, yang sesuai dengan 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 harga 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 secara langsung dari aplikasi seluler atau 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 yang masuk berasal dari aplikasi Anda yang sebenarnya. Dengan beberapa penyedia cloud seperti Google, Anda juga dapat menerapkan pemeriksaan asal yang ketat untuk memastikan hanya situs yang diizinkan yang dapat menggunakan API.

Daripada batas Prompt API, misalnya, terkait contextWindow sesi, batas penyedia backend yang berlaku. Untuk contextWindow, batas ini biasanya jauh lebih tinggi daripada di perangkat, dan Anda dapat memproses data dalam jumlah yang lebih besar di cloud, jadi 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 mengimplementasikan 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 perlu 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. Ini digunakan saat pengguna memulai 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 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"
}

Verifikasi 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 yang terdefinisi dengan baik Prompt API, Anda akan lebih mandiri dari penyedia cloud dan tetap sedekat mungkin dengan platform.

Pada perangkat yang kompatibel yang mendukung Prompt API, polyfill bahkan tidak dimuat, sehingga Anda menghemat pengguna dari mendownload kode yang tidak akan mereka jalankan. Jika Anda memiliki masukan atau menemukan bug, buka Masalah di GitHub. Selamat menulis perintah!