إصدار تجريبي من polyfill لواجهة برمجة التطبيقات Prompt API

Thomas Steiner

تاريخ النشر: 14 مايو 2026

باستخدام Prompt API في Chrome، يمكنك التفاعل مع نموذج لغوي كبير باستخدام واجهة برمجة تطبيقات متصفّح عالية المستوى على window.LanguageModel. ومع ذلك، لا يزال الدعم محدودًا لهذه الميزة، كما أنّ عملية التنفيذ معقّدة.

في الوقت نفسه، عبّر المطوّرون المشاركون في برنامج استخدام المنتج قبل إطلاقه عن حماسهم بشأن Prompt API. سيؤدي توفّر واجهة برمجة التطبيقات إلى حدوث مشكلة في التوافق في المستقبل المنظور.

الحل

لهذا السبب، نطلق إضافة متوافقة مع المواصفات تجريبية لواجهة برمجة التطبيقات Prompt API (يمكنك الاطّلاع على رمز المصدر على GitHub) تنفّذ واجهة برمجة التطبيقات Prompt API بدقة على مستوى موفّري الخلفية السحابية القابلة للإعداد، وكذلك على مستوى موفّر الخلفية المحلية في شكل Transformers.js.

استخدام polyfill

لاستخدام polyfill، اتّبِع الخطوات التالية:

1. نزِّل Polyfill من npm:

   npm install prompt-api-polyfill
   

2. اختَر ما إذا كنت تريد استخدام مقدّم خدمات خلفية سحابية أو مقدّم خدمات خلفية محلية:

   • مقدّم خدمة الخلفية المستندة إلى السحابة الإلكترونية: يتم إرسال بيانات المستخدمين إلى السحابة الإلكترونية للمعالجة عن بُعد، ولكن ليس عليك انتظار توفّر نموذج محلي. وتتحمّل أنت مسؤولية أي تكلفة يتم تكبّدها وفقًا لمعلومات الأسعار التي يقدّمها مزوّد خدمة السحابة الإلكترونية.
   • موفِّر الخلفية المحلية: تبقى بيانات المستخدمين في المتصفح وتتم معالجتها محليًا، ولكن عليك تنزيل نموذج لا يمكن مشاركته على مستوى مصادر مختلفة، على عكس واجهة برمجة التطبيقات الحقيقية لطلبات البحث. لا تتضمّن المعالجة المحلية أي تكلفة.

الخادم الخلفي على السحابة الإلكترونية

اختَر أيًا من الخدمات الخلفية السحابية واحصل على مفتاح واجهة برمجة التطبيقات (وأي بيانات اعتماد إضافية) لمقدّم الخدمة الخلفية.

بعد الحصول على مفتاح واجهة برمجة التطبيقات، أدخِل التفاصيل في ملف الإعداد .env.json. إذا لم تحدّد modelName، ستستخدم أداة Polyfill النموذج التلقائي لكلّ نظام خلفي، ولكن إذا حدّدته، يمكنك اختيار أحد النماذج المتوافقة لكلّ نظام خلفي.

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

الخادم الخلفي المحلي

إذا قرّرت استخدام موفّر خلفية محلي استنادًا إلى Transformers.js، لن تحتاج إلا إلى مفتاح واجهة برمجة تطبيقات وهمي. ومع ذلك، يمكنك ضبط الجهاز الذي يجب أن تستخدمه مكتبة 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 الخلفية التي اخترتها: window.$BACKEND_CONFIG.
2. استخدِم عملية استيراد ديناميكية لتحميل رمز التعبئة فقط عندما لا يتيح المتصفّح الأساسي ذلك.
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!');

يتوافق هذا الرمز مع الناتج المنظَّم (باستثناء الخلفية البرمجية Transformers.js)، ويتعامل مع الإدخال المتعدّد الوسائط (باستثناء الخلفية البرمجية OpenAI التي لا تتوافق مع الصوت والصورة معًا، بل بشكل منفصل فقط)، ويتم اختباره باستخدام مجموعة اختبارات منصة الويب الكاملة للإصدار LanguageModel.

لمزيد من المعلومات الأساسية والتفصيلية حول الاستخدام، بالإضافة إلى رمز المصدر، يُرجى الاطّلاع على ملف README في مستودع GitHub.

الاختلاف عن واجهة برمجة التطبيقات Prompt API في المتصفّح

إذا كانت أداة polyfill تستند إلى نماذج مستضافة على السحابة الإلكترونية، لن تنطبق بعض مزايا التشغيل من جهة العميل بعد الآن. ويعني ذلك أنّه لم يعُد بإمكانك ضمان المعالجة المحلية للبيانات الحسّاسة، على الرغم من أنّ سياسات الخصوصية لمقدّم الخدمات الخلفية لا تزال سارية. ولن يتمكّن تطبيقك أيضًا من استخدام الذكاء الاصطناعي عندما يكون المستخدم بلا إنترنت. لمعرفة ما إذا كنت متصلاً بالإنترنت أو غير متصل، يمكنك الاستماع إلى الأحداث المناسبة.

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

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

إذا تم تنفيذ استنتاج الذكاء الاصطناعي باستخدام نموذج في السحابة الإلكترونية، لن يكون هناك نموذج محلي لتنزيله. تتظاهر أداة التعبئة بأنّها أحداث downloadprogress، لذا سيبدو لتطبيقك كما لو كان النموذج المضمّن قد تم تنزيله بالفعل، ما يعني أنّه سيكون هناك حدثان، أحدهما بقيمة loaded تساوي 0 والآخر بقيمة 1، وهو ما تتطلّبه المواصفات.

باستخدام الاستنتاج المستند إلى السحابة الإلكترونية، على عكس الاستنتاج على الجهاز فقط، هناك تكلفة محتملة عند طلب البيانات من واجهات برمجة التطبيقات من مقدّم الخدمات الخلفية الذي تختاره. اطّلِع على معلومات الأسعار، مثل أسعار 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.
}

عند استدعاء واجهة برمجة تطبيقات على السحابة الإلكترونية مباشرةً من تطبيق على الأجهزة الجوّالة أو تطبيق ويب (مثل واجهات برمجة التطبيقات التي تسمح بالوصول إلى نماذج الذكاء الاصطناعي التوليدي)، يكون مفتاح واجهة برمجة التطبيقات عرضة لإساءة الاستخدام من قِبل البرامج العميلة غير المصرّح لها. للمساعدة في حماية واجهات برمجة التطبيقات هذه، إذا كنت تستخدم حزمة تطوير البرامج (SDK) المختلطة "Firebase AI Logic"، عليك استخدام فحص التطبيقات من Firebase للتأكّد من أنّ جميع طلبات البيانات الواردة من واجهة برمجة التطبيقات تأتي من تطبيقك الفعلي. مع بعض مقدّمي الخدمات السحابية، مثل Google، يمكنك أيضًا فرض عمليات تحقّق صارمة من المصدر للتأكّد من أنّ المواقع الإلكترونية المسموح بها فقط يمكنها استخدام واجهة برمجة التطبيقات.

بدلاً من حدود Prompt API، على سبيل المثال، فيما يتعلق contextWindow للجلسة، تنطبق حدود موفّر الخلفية. بالنسبة إلى contextWindow، تكون هذه الحدود عادةً أعلى بكثير من الحدود على الجهاز فقط، ويمكنك معالجة كميات أكبر من البيانات على السحابة الإلكترونية، لذا على الرغم من أنّه عليك الانتباه إلى الفرق، من غير المرجّح أن تواجه مشاكل في هذا الصدد.

إنشاء الخلفية الخاصة بك

لإضافة موفّر خلفية خاص بك، اتّبِع الخطوات التالية:

تمديد فئة الخلفية الأساسية

أنشئ ملفًا جديدًا في الدليل 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)
  }
}

تسجيل الخلفية

يستخدم رمز polyfill استراتيجية "الأولوية للمطابقة الأولى" استنادًا إلى الإعدادات العامة. عليك تسجيل الخلفية في ملف 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) لإنشاء مصفوفات الاختبار. لتضمين الخلفية الجديدة في أداة تنفيذ الاختبار، أنشئ ملف .env-[name].json (على سبيل المثال، .env-custom.json) في الدليل الجذر:

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

إثبات التوافق مع Web Platform Tests (WPT)

الخطوة الأخيرة هي ضمان الامتثال. بما أنّ polyfill مستند إلى المواصفات، يجب أن يجتاز أي نظام خلفي جديد اختبارات Web Platform الرسمية (أو المؤقتة):

npm run test:wpt

تضمن خطوة التحقّق هذه أنّ الخلفية تعالج عناصر مثل AbortSignal وطلبات النظام وتنسيق السجلّ تمامًا كما هو متوقّع في مواصفات Prompt API.

الخاتمة

يساعدك polyfill في استخدام Prompt API على جميع المنصات والأجهزة. من خلال الترميز باستخدام واجهة برمجة التطبيقات المحدّدة جيدًا في Prompt API، يمكنك الاستغناء عن موفّري الخدمات السحابية والاقتراب من المنصة قدر الإمكان.

على الأجهزة المتوافقة التي تتيح استخدام Prompt API، لا يتم حتى تحميل polyfill، وبالتالي لن يضطر المستخدمون إلى تنزيل رمز لن يتم تنفيذه. إذا كانت لديك ملاحظات أو واجهت خطأً، يُرجى فتح مشكلة على GitHub. استمتِع برحلتك في عالم الذكاء الاصطناعي