‫polyfill ניסיוני ל-Prompt API

Thomas Steiner

תאריך פרסום: 14 במאי 2026

באמצעות Prompt API ב-Chrome, אתם יכולים ליצור אינטראקציה עם מודל LLM באמצעות API ברמה גבוהה לדפדפן ב-window.LanguageModel. עם זאת, התמיכה בזה עדיין מוגבלת וההטמעה היא תהליך מורכב.

במקביל, מפתחים בתוכנית הגישה המוקדמת הביעו התלהבות מממשק ה-API של ההנחיות. הזמינות של ה-API יוצרת אתגר תאימות בעתיד הנראה לעין.

פתרון

לכן אנחנו משיקים פוליפיל של Prompt API (ראו את קוד המקור ב-GitHub) שהוא תואם למפרט וניסיוני, ומיישם בצורה מדויקת את Prompt API על גבי ספקי קצה עורפי (backend) בענן שניתנים להגדרה, וגם על גבי ספק קצה עורפי מקומי בצורה של Transformers.js.

שימוש ב-polyfill

כדי להשתמש ב-polyfill:

1. מורידים את ה-polyfill מ-npm:

   npm install prompt-api-polyfill
   

2. בוחרים אם רוצים להשתמש בספק עורפי בענן או בספק עורפי מקומי:

   • ספק בק-אנד בענן: נתוני משתמש נשלחים לענן לעיבוד מרחוק, אבל לא צריך לחכות עד שמודל מקומי יהיה זמין. אתם אחראים לכל עלות שנוצרה בהתאם לפרטי התמחור של ספק שירותי הענן שלכם.
   • ספק בק-אנד מקומי: נתוני משתמשים נשארים בדפדפן ומעובדים באופן מקומי, אבל צריך להוריד מודל, שבשונה מ-Prompt API אמיתי, אי אפשר לשתף בין מקורות שונים. העיבוד המקומי לא כרוך בתשלום.

קצה עורפי בענן

בוחרים אחד מבין ה-בק-אנדים בענן ומקבלים מפתח API (וכל פרטי כניסה נוספים) לספק ה-בק-אנד.

אחרי שמקבלים את מפתח ה-API, מזינים את הפרטים בקובץ ההגדרות .env.json. אם לא מציינים modelName, ה-polyfill ישתמש במודל ברירת המחדל של כל קצה עורפי, אבל אם מציינים, אפשר לבחור אחד מהמודלים הנתמכים של כל קצה עורפי.

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

קצה עורפי מקומי

אם תבחרו להשתמש בספק בק-אנד מקומי שמבוסס על Transformers.js, תצטרכו רק מפתח API פיקטיבי. עם זאת, אתם יכולים להגדיר באיזה מכשיר Transformers.js ישתמש. בוחרים באפשרות "webgpu" כדי למקסם את הביצועים, ובאפשרות "wasm" כדי למקסם את התאימות. אפשר לשנות את הגדרות ברירת המחדל. בוחרים מודל אחר מקטלוג המודלים התואמים של Hugging Face. בחלק מהמודלים אפשר לבחור מבין קוונטיזציות שונות באמצעות הפרמטר dtype.

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

הגדרת ה-polyfill

אחרי שיוצרים את קובץ ההגדרות, אפשר להתחיל להשתמש ב-polyfill באפליקציה.

1. מייבאים את קובץ ההגדרות ומקצים אותו למשתנה גלובלי עם שם מתאים, כאשר $BACKEND הוא שם ה-Backend שבחרתם: window.$BACKEND_CONFIG.
2. משתמשים בייבוא דינמי כדי לטעון את ה-polyfill רק כשהדפדפן הבסיסי לא תומך בו.
3. שליחת קריאה לפונקציות של 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 תומך בפלט מובנה (חוץ מה-backend של Transformers.js), מטפל בקלט מולטי-מודאלי (חוץ מה-backend של OpenAI שלא תומך באודיו ובתמונות ביחד, אלא רק בנפרד), ונבדק מול חבילת הבדיקות המלאה של פלטפורמת האינטרנט עבור LanguageModel.

מידע נוסף על הרקע ועל השימוש המפורט, וגם קוד המקור, זמין בקובץ README במאגר GitHub.

ההבדל מ-Prompt API בדפדפן

אם ה-polyfill מבוסס על מודלים בענן, חלק מהיתרונות ההפעלה בצד הלקוח כבר לא רלוונטיים. כלומר, אתם כבר לא יכולים להבטיח עיבוד מקומי של מידע אישי רגיש, אבל מדיניות הפרטיות של ספק ה-Backend שלכם עדיין חלה. בנוסף, האפליקציה שלך לא יכולה יותר להשתמש ב-AI כשהמשתמש במצב אופליין. כדי לדעת אם אתם במצב אונליין או אופליין, אתם יכולים להאזין לאירועים המתאימים.

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

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

אם ההסקה של ה-AI מופעלת על מודל בענן, אין מודל מקומי להורדה. ה-polyfill מזייף את האירועים downloadprogress, כך שבאפליקציה ייראה כאילו המודל המובנה כבר הורד, מה שאומר שיהיו שני אירועים, אחד עם ערך loaded של 0 ואחד עם 1, שזה מה שנדרש במפרט.

בניגוד להסקת מסקנות במכשיר, בהסקת מסקנות מבוססת-ענן יש עלות פוטנציאלית כשקוראים לממשקי API מהספק של הקצה העורפי שבחרתם. כדאי לעיין במידע על התמחור, כמו זה של Gemini API. אם אתם יודעים את העלות לכל טוקן, אתם יכולים להשתמש במידע contextUsage של Prompt API כדי לחשב את העלות.

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

כשקוראים ל-Cloud API ישירות מאפליקציה לנייד או מאפליקציית אינטרנט (לדוגמה, ממשקי ה-API שמאפשרים גישה למודלים של AI גנרטיבי), מפתח ה-API חשוף לניצול לרעה על ידי לקוחות לא מורשים. כדי להגן על ממשקי ה-API האלה, אם אתם משתמשים ב-Firebase AI Logic Hybrid SDK, כדאי להשתמש ב-Firebase App Check כדי לוודא שכל קריאות ה-API הנכנסות מגיעות מהאפליקציה בפועל. אצל חלק מספקי הענן, כמו Google, אפשר גם לאכוף בדיקות מקור קפדניות כדי לוודא שרק אתרים מורשים יכולים להשתמש ב-API.

במקום המגבלות של Prompt API, למשל לגבי contextWindow של הסשן, חלות המגבלות של ספק ה-Backend. ב-contextWindow, המגבלות האלה בדרך כלל גבוהות בהרבה מאשר במכשיר, ואפשר לעבד כמויות גדולות יותר של נתונים בענן. לכן, למרות שחשוב להיות מודעים להבדל, סביר להניח שלא תיתקלו בבעיות בנושא הזה.

יצירת קצה עורפי משלכם

כדי להוסיף ספק משלכם לשרת העורפי:

הרחבת מחלקת הבסיס של ה-Backend

יוצרים קובץ חדש בספרייה backends/, לדוגמה, backends/custom-backend.js. צריך להרחיב את המחלקה PolyfillBackend ולהטמיע את שיטות הליבה שמספקות את הממשק הצפוי.

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

רישום ה-backend

ה-polyfill משתמש בשיטת 'עדיפות להתאמה ראשונה' שמבוססת על הגדרה גלובלית. כדי לרשום את ה-backend בקובץ prompt-api-polyfill.js, מוסיפים אותו למערך הסטטי #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',
  },
];

הגדרת מודל ברירת מחדל

מגדירים את זהות מודל הגיבוי ב-backends/defaults.js. הפרמטר הזה משמש כשמשתמש מאתחל סשן בלי לציין modelName ספציפי.

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

הפעלת פיתוח ובדיקה מקומיים

הפרויקט משתמש בתסריט גילוי (scripts/list-backends.js) כדי ליצור מטריצות בדיקה. כדי לכלול את ה-Backend החדש ב-Test Runner, יוצרים קובץ .env-[name].json (לדוגמה, .env-custom.json) בספריית הבסיס:

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

אימות באמצעות Web Platform Tests‏ (WPT)

השלב האחרון הוא לוודא שהכול תקין. מכיוון שה-polyfill מבוסס על מפרט, כל בק-אנד חדש צריך לעבור את הבדיקות הרשמיות (או הזמניות) של פלטפורמת האינטרנט:

npm run test:wpt

שלב האימות הזה מבטיח שהקצה העורפי מטפל בדברים כמו AbortSignal, הנחיות למערכת ועיצוב ההיסטוריה בדיוק כמו שמצוין במפרט של Prompt API.

סיכום

ה-polyfill עוזר לכם להשתמש ב-Prompt API בכל הפלטפורמות והמכשירים. קידוד באמצעות ממשק ה-API המוגדר היטב של Prompt API מאפשר לכם להיות יותר עצמאיים מספקי ענן ולהישאר קרובים ככל האפשר לפלטפורמה.

במכשירים תומכים שכוללים את Prompt API, הפוליפיל לא נטען בכלל, כך שהמשתמשים לא צריכים להוריד קוד שלא יופעל. אם יש לכם משוב או שנתקלתם בבאג, אתם יכולים לפתוח בקשה בקשר לבעיה ב-GitHub. בהצלחה בכתיבת ההנחיות!