Prompt API

Thomas Steiner

Alexandra Klepper

تاريخ النشر: 20 مايو 2025، تاريخ آخر تعديل: 21 سبتمبر 2025

شرح	الويب	الإضافات	حالة Chrome	النيّة بالشراء
Github	في مرحلة التجربة والتقييم	الإصدار 138 من Chrome	العرض	نية إجراء تجربة

باستخدام Prompt API، يمكنك إرسال طلبات باللغة الطبيعية إلى Gemini Nano في المتصفّح.

يمكنك استخدام Prompt API بطرق عديدة. على سبيل المثال، يمكنك إنشاء ما يلي:

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

هذه مجرد بعض الاحتمالات، ونحن متحمّسون لرؤية ابتكاراتك.

استخدام Prompt API

تستخدم واجهة برمجة التطبيقات Prompt API نموذج Gemini Nano في Chrome. مع أنّ واجهة برمجة التطبيقات مدمجة في Chrome، يتم تنزيل النموذج بشكل منفصل في المرة الأولى التي يستخدم فيها مصدر واجهة برمجة التطبيقات. قبل استخدام واجهة برمجة التطبيقات هذه، يجب الموافقة على سياسة الاستخدام المحظور للذكاء الاصطناعي التوليدي من Google.

لتحديد ما إذا كان النموذج جاهزًا للاستخدام، استدعِ الدالة LanguageModel.availability().

const availability = await LanguageModel.availability();

قبل أن يتم تنزيل النموذج، يجب أن يكون هناك تفاعل من المستخدم، مثل النقر أو الضغط أو الضغط على مفتاح.

إذا كان الرد downloadable أو downloading، يعني ذلك أنّ النموذج وواجهات برمجة التطبيقات متوفرة ولكن يجب تنزيلها قبل أن تتمكّن من استخدام الميزات. يجب أن يتفاعل المستخدم مع الصفحة (مثل النقر أو الضغط على مفتاح) للسماح بالتنزيل.

لتنزيل النموذج وإنشاء مثيل له، استدعِ الدالة create().

const session = await LanguageModel.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

إذا كان الردّ على availability() هو downloading، استمع إلى مستوى التقدّم في عملية التنزيل وأبلِغ المستخدم بذلك، لأنّ عملية التنزيل قد تستغرق بعض الوقت.

مَعلمات النموذج

تُعلمك الدالة params() بمعلَمات النموذج اللغوي. يحتوي العنصر على الحقول التالية:

• defaultTopK: القيمة التلقائية لأعلى K.
• maxTopK: تمثّل الحد الأقصى لقيمة أعلى K.
• ‫defaultTemperature: درجة الحرارة التلقائية
• ‫maxTemperature: تمثّل هذه السمة الحدّ الأقصى لدرجة الحرارة.

await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

إنشاء جلسة

بعد أن تصبح واجهة برمجة التطبيقات Prompt API جاهزة للتشغيل، يمكنك إنشاء جلسة باستخدام الدالة create().

يمكن تخصيص كل جلسة باستخدام topK وtemperature باستخدام عنصر خيارات اختياري. يتم عرض القيم التلقائية لهذه المَعلمات من LanguageModel.params().

const params = await LanguageModel.params();
// Initializing a new session must either specify both `topK` and
// `temperature` or neither of them.
const slightlyHighTemperatureSession = await LanguageModel.create({
  temperature: Math.max(params.defaultTemperature * 1.2, 2.0),
  topK: params.defaultTopK,
});

يتضمّن عنصر الخيارات الاختيارية للدالة create() أيضًا الحقل signal، الذي يتيح لك تمرير AbortSignal لإيقاف الجلسة.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const session = await LanguageModel.create({
  signal: controller.signal,
});

إضافة سياق باستخدام الطلبات الأولية

باستخدام الطلبات الأولية، يمكنك تزويد النموذج اللغوي بسياق حول التفاعلات السابقة، مثلاً، للسماح للمستخدم باستئناف جلسة محفوظة بعد إعادة تشغيل المتصفح.

const session = await LanguageModel.create({
  initialPrompts: [
    { role: 'system', content: 'You are a helpful and friendly assistant.' },
    { role: 'user', content: 'What is the capital of Italy?' },
    { role: 'assistant', content: 'The capital of Italy is Rome.' },
    { role: 'user', content: 'What language is spoken there?' },
    {
      role: 'assistant',
      content: 'The official language of Italy is Italian. [...]',
    },
  ],
});

فرض قيود على الردود باستخدام بادئة

يمكنك إضافة دور "assistant"، بالإضافة إلى الأدوار السابقة، لتوضيح الردود السابقة للنموذج. على سبيل المثال:

const followup = await session.prompt([
  {
    role: "user",
    content: "I'm nervous about my presentation tomorrow"
  },
  {
    role: "assistant",
    content: "Presentations are tough!"
  }
]);

في بعض الحالات، قد تحتاج إلى ملء جزء من رسالة الرد الخاصة بدور "assistant" مسبقًا بدلاً من طلب رد جديد. يمكن أن يكون ذلك مفيدًا لتوجيه النموذج اللغوي لاستخدام تنسيق ردّ محدّد. لإجراء ذلك، أضِف prefix: true إلى رسالة "assistant"-role اللاحقة. على سبيل المثال:

const characterSheet = await session.prompt([
  {
    role: 'user',
    content: 'Create a TOML character sheet for a gnome barbarian',
  },
  {
    role: 'assistant',
    content: '```toml\n',
    prefix: true,
  },
]);

إضافة الإدخال والإخراج المتوقّعَين

تتضمّن Prompt API إمكانات متعدّدة الوسائط وتتيح استخدام لغات متعدّدة. اضبط expectedInputs وexpectedOutputs طُرق التواصل واللغات عند إنشاء جلستك.

• ‫type: نوع الوسائط المتوقّع
  • بالنسبة إلى expectedInputs، يمكن أن يكون text أو image أو audio.
  • بالنسبة إلى expectedOutputs، تسمح Prompt API بـ text فقط.
• languages: مصفوفة لضبط اللغة أو اللغات المتوقّعة. تقبل Prompt API القيم "en" و"ja" و"es". ونحن نعمل حاليًا على إتاحة هذه الميزة بلغات إضافية.
  • بالنسبة إلى expectedInputs، اضبط لغة طلب النظام ولغة واحدة أو أكثر من لغات طلبات المستخدمين المتوقّعة.
  • اضبط لغة واحدة أو أكثر من expectedOutputs.

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en" /* system prompt */, "ja" /* user prompt */] }
  ],
  expectedOutputs: [
    { type: "text", languages: ["ja"] }
  ]
});

قد تتلقّى "NotSupportedError" DOMException إذا واجه النموذج إدخالاً أو إخراجًا غير متوافق.

الإمكانات المتعددة الوسائط

باستخدام هذه الإمكانات، يمكنك إجراء ما يلي:

• السماح للمستخدمين بنسخ الرسائل الصوتية المُرسَلة في تطبيق محادثة
• وصف صورة تم تحميلها إلى موقعك الإلكتروني لاستخدامها في تعليق توضيحي أو نص بديل

يمكنك الاطّلاع على العرض التوضيحي طلب Mediarecorder الصوتي لمعرفة كيفية استخدام Prompt API مع الإدخال الصوتي، والعرض التوضيحي طلب صورة Canvas لمعرفة كيفية استخدام Prompt API مع إدخال الصور.

إلحاق الرسائل

قد تستغرق عملية الاستنتاج بعض الوقت، خاصةً عند تقديم طلب باستخدام مدخلات متعدّدة الوسائط. قد يكون من المفيد إرسال طلبات محددة مسبقًا لتعبئة الجلسة، ليتمكّن النموذج من البدء في المعالجة.

في حين أنّ initialPrompts مفيدة عند إنشاء الجلسة، يمكن استخدام الطريقة append() بالإضافة إلى الطريقتين prompt() أو promptStreaming() لتقديم طلبات إضافية متعلقة بالسياق بعد إنشاء الجلسة.

على سبيل المثال:

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content:
        'You are a skilled analyst who correlates patterns across multiple images.',
    },
  ],
  expectedInputs: [{ type: 'image' }],
});

fileUpload.onchange = async () => {
  await session.append([
    {
      role: 'user',
      content: [
        {
          type: 'text',
          value: `Here's one image. Notes: ${fileNotesInput.value}`,
        },
        { type: 'image', value: fileUpload.files[0] },
      ],
    },
  ]);
};

analyzeButton.onclick = async (e) => {
  analysisResult.textContent = await session.prompt(userQuestionInput.value);
};

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

تمرير مخطط JSON

أضِف الحقل responseConstraint إلى الطريقتَين prompt() أو promptStreaming() لتمرير مخطط JSON كقيمة. يمكنك بعد ذلك استخدام الناتج المنظَّم مع Prompt API.

في المثال التالي، يضمن JSON Schema أنّ النموذج يستجيب بالرمز true أو false لتصنيف ما إذا كانت الرسالة المحدّدة تتعلّق بصناعة الفخار.

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended, but that
happens with reclaim. Glaze crawled the first time around, but pretty happy
with it after refiring.";

const result = await session.prompt(
  `Is this post about pottery?\n\n${post}`,
  {
    responseConstraint: schema,
  }
);
console.log(JSON.parse(result));
// true

يمكن أن يتضمّن التنفيذ مخطط JSON أو تعبيرًا عاديًا كجزء من الرسالة المرسَلة إلى النموذج. يؤدي ذلك إلى استخدام جزء من حصة الإدخال. يمكنك قياس مقدار حصة الإدخال التي سيتم استخدامها من خلال تمرير الخيار responseConstraint إلى session.measureInputUsage().

يمكنك تجنُّب هذا السلوك باستخدام الخيار omitResponseConstraintInput. في هذه الحالة، ننصحك بتضمين بعض الإرشادات في الطلب:

const result = await session.prompt(`
  Summarize this feedback into a rating between 0-5. Only output a JSON
  object { rating }, with a single property whose value is a number:
  The food was delicious, service was excellent, will recommend.
`, { responseConstraint: schema, omitResponseConstraintInput: true });

توجيه الطلبات للنموذج

يمكنك تقديم طلب إلى النموذج باستخدام الدالتَين prompt() أو promptStreaming().

الناتج غير المتدفّق

إذا كنت تتوقّع نتيجة قصيرة، يمكنك استخدام الدالة prompt() التي تعرض الردّ فور توفّره.

// Start by checking if it's possible to create a session based on the
// availability of the model, and the characteristics of the device.
const { defaultTemperature, maxTemperature, defaultTopK, maxTopK } =
  await LanguageModel.params();

const available = await LanguageModel.availability();

if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and wait for the whole result to come back.
  const result = await session.prompt('Write me a poem!');
  console.log(result);
}

الناتج الذي يتم بثه

إذا كنت تتوقّع الحصول على رد أطول، عليك استخدام الدالة promptStreaming() التي تتيح لك عرض نتائج جزئية أثناء ورودها من النموذج. تعرض الدالة promptStreaming() ReadableStream.

const { defaultTemperature, maxTemperature, defaultTopK, maxTopK } =
  await LanguageModel.params();

const available = await LanguageModel.availability();
if (available !== 'unavailable') {
  const session = await LanguageModel.create();

  // Prompt the model and stream the result:
  const stream = session.promptStreaming('Write me an extra-long poem!');
  for await (const chunk of stream) {
    console.log(chunk);
  }
}

إيقاف الطلبات

يقبل كلّ من prompt() وpromptStreaming() مَعلمة ثانية اختيارية تتضمّن الحقل signal، ما يتيح لك إيقاف تنفيذ الطلبات.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const result = await session.prompt('Write me a poem!', {
  signal: controller.signal,
});

إدارة الجلسة

تتتبّع كل جلسة سياق المحادثة. يتم أخذ التفاعلات السابقة في الاعتبار للتفاعلات المستقبلية إلى أن تمتلئ نافذة السياق الخاصة بالجلسة.

لكل جلسة حدّ أقصى لعدد الرموز المميّزة التي يمكنها معالجتها. يمكنك الاطّلاع على مدى تقدّمك نحو هذا الحد من خلال ما يلي:

console.log(`${session.inputUsage}/${session.inputQuota}`);

مزيد من المعلومات حول إدارة الجلسات

نسخ جلسة

للحفاظ على الموارد، يمكنك استنساخ جلسة حالية باستخدام الدالة clone(). تتم إعادة ضبط سياق المحادثة، ولكن تبقى المطالبة الأولية كما هي. تأخذ الدالة clone() عنصر خيارات اختياريًا مع حقل signal، ما يتيح لك تمرير AbortSignal لتدمير الجلسة المستنسخة.

const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const clonedSession = await session.clone({
  signal: controller.signal,
});

إنهاء جلسة

اتّصِل بالرقم destroy() لتحرير الموارد إذا لم تعُد بحاجة إلى جلسة. عند إيقاف جلسة، لن يعود بالإمكان استخدامها، وسيتم إيقاف أي عملية تنفيذ جارية. ننصحك بإبقاء الجلسة نشطة إذا كنت تنوي تقديم طلبات إلى النموذج بشكل متكرر، لأنّ إنشاء جلسة قد يستغرق بعض الوقت.

await session.prompt(
  "You are a friendly, helpful assistant specialized in clothing choices."
);

session.destroy();

// The promise is rejected with an error explaining that
// the session is destroyed.
await session.prompt(
  "What should I wear today? It is sunny, and I am choosing between a t-shirt
  and a polo."
);

العروض التوضيحية

لقد أنشأنا العديد من العروض التوضيحية لاستكشاف حالات الاستخدام العديدة لواجهة برمجة التطبيقات Prompt API. العروض التوضيحية التالية هي تطبيقات ويب:

• ساحة تجارب Prompt API
• طلب إذن الوصول إلى الصوت في Mediarecorder
• طلب صورة على لوحة قماشية

لاختبار Prompt API في إضافات Chrome، ثبِّت الإضافة التجريبية. يتوفّر رمز المصدر الخاص بالإضافة على GitHub.

استراتيجية الأداء

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

سياسة الأذونات وإطارات iframe وWeb Workers

تتوفّر واجهة برمجة التطبيقات Prompt API تلقائيًا للنوافذ ذات المستوى الأعلى ولإطارات iframe من المصدر نفسه. يمكن تفويض الوصول إلى واجهة برمجة التطبيقات إلى إطارات iframe من مصادر متعددة باستخدام السمة allow="" في Permission Policy:

<!--
  The hosting site at https://main.example.com can grant a cross-origin iframe
  at https://cross-origin.example.com/ access to the Prompt API by
  setting the `allow="language-model"` attribute.
-->
<iframe src="https://cross-origin.example.com/" allow="language-model"></iframe>

لا تتوفّر Prompt API حاليًا في Web Workers بسبب صعوبة تحديد مستند مسؤول لكل عامل من أجل التحقّق من حالة سياسة الأذونات.

المشاركة ومشاركة الملاحظات

يمكن أن يؤثّر إدخالك بشكل مباشر في طريقة إنشاء الإصدارات المستقبلية من واجهة برمجة التطبيقات هذه وجميع واجهات برمجة التطبيقات المضمّنة المستندة إلى الذكاء الاصطناعي وتنفيذها.

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