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

Thomas Steiner

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

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

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

الحل

لهذا السبب، سنطرح إضافة متوافقة مع المواصفات Prompt API polyfill تجريبية (يمكنك الاطّلاع على رمز المصدر على 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");
});

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

عند استدعاء واجهة برمجة تطبيقات على السحابة الإلكترونية مباشرةً من تطبيق على الأجهزة الجوّالة أو تطبيق ويب (مثل واجهات برمجة التطبيقات التي تتيح الوصول إلى نماذج الذكاء الاصطناعي التوليدي)، يكون مفتاح واجهة برمجة التطبيقات عرضة لإساءة الاستخدام من قِبل العملاء غير المصرّح لهم. للمساعدة في حماية واجهات برمجة التطبيقات هذه، إذا كنت تستخدم حزمة Firebase AI Logic Hybrid SDK، عليك استخدام فحص التطبيقات من 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. استمتِع برحلتك في عالم الذكاء الاصطناعي

انظر أيضًا

إضافات تجريبية لواجهات برمجة تطبيقات مهام الذكاء الاصطناعي المدمجة