Prompt API

Thomas Steiner

Alexandra Klepper

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

الشارح	الويب	الإضافات	حالة Chrome	النيّة بالشراء
GitHub	‫ Chrome 148	Chrome 138	العرض	النيّة بالتجربة
GitHub	مرحلة التجربة والتقييم لمَعلَمات اختيار العيّنات	‫ Chrome 148	العرض	النيّة بالتجربة

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

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

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

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

استخدام Prompt API

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

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

const availability = await LanguageModel.availability({
  // The same options in `prompt()` or `promptStreaming()`
});

لتشغيل التنزيل وإنشاء نموذج لغوي، تحقَّق من تفعيل المستخدم. بعد ذلك، استخدِم الدالة create().

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

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

الاستخدام على localhost

تتوفّر جميع واجهات برمجة التطبيقات المدمجة المستندة إلى الذكاء الاصطناعي على localhost في Chrome. اضبط الإشارات التالية على مفعَّلة:

• chrome://flags/#optimization-guide-on-device-model
• chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

بعد ذلك، انقر على إعادة التشغيل أو أعِد تشغيل Chrome. إذا واجهت أخطاء، حدِّد المشاكل وحلّها في localhost.

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

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

• defaultTopK: القيمة التلقائية لـ top-K
• maxTopK: الحد الأقصى لقيمة top-K
• defaultTemperature: درجة الحرارة التلقائية .
• maxTemperature: الحد الأقصى لدرجة الحرارة

// Only available when using the Prompt API for Chrome Extensions.
await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

إنشاء جلسة

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

const session = await LanguageModel.create();

إنشاء جلسة باستخدام Prompt API لإضافات Chrome

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

// Only available when using the Prompt API for Chrome Extensions.
const params = await LanguageModel.params();
// Initializing a new session must either specify both `topK` and
// `temperature` or neither of them.
// Only available when using the Prompt API for Chrome Extensions.
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". على سبيل المثال:

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 Audio Prompt لاستخدام Prompt API مع إدخال الصوت، والعرض التوضيحي Canvas Image Prompt لاستخدام Prompt API مع إدخال الصورة.

تتوافق Prompt API مع أنواع الإدخال التالية:

• الصوت:
  • AudioBuffer
  • ArrayBufferView
  • ArrayBuffer
  • Blob
• المرئيات:
  • HTMLImageElement
  • SVGImageElement
  • HTMLVideoElement (يستخدم إطار الفيديو في موضع الفيديو الحالي)
  • HTMLCanvasElement
  • ImageBitmap
  • OffscreenCanvas
  • VideoFrame
  • Blob
  • ImageData

يعرض هذا المقتطف جلسة متعدّدة الوسائط تعالج أولاً صورتَين (إحداهما Blob والأخرى HTMLCanvasElement) وتطلب من الذكاء الاصطناعي مقارنتهما، ثم تسمح للمستخدم بالردّ باستخدام تسجيل صوتي (بتنسيق AudioBuffer).

const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en"] },
    { type: "audio" },
    { type: "image" },
  ],
  expectedOutputs: [{ type: "text", languages: ["en"] }],
});

const referenceImage = await (await fetch("reference-image.jpeg")).blob();
const userDrawnImage = document.querySelector("canvas");

const response1 = await session.prompt([
  {
    role: "user",
    content: [
      {
        type: "text",
        value:
          "Give a helpful artistic critique of how well the second image matches the first:",
      },
      { type: "image", value: referenceImage },
      { type: "image", value: userDrawnImage },
    ],
  },
]);
console.log(response1);

const audioBuffer = await captureMicrophoneInput({ seconds: 10 });

const response2 = await session.prompt([
  {
    role: "user",
    content: [
      { type: "text", value: "My response to your critique:" },
      { type: "audio", value: audioBuffer },
    ],
  },
]);
console.log(response2);

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

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

في حين أنّ 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 Schema

أضِف الحقل responseConstraint إلى الطريقتَين prompt() أو promptStreaming() لتمرير JSON Schema كقيمة. يمكنك بعد ذلك استخدام الإخراج المنظَّم مع الـ 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 Schema أو تعبيرًا عاديًا كجزء من الرسالة المُرسَلة إلى النموذج. يستخدم ذلك جزءًا من قدرة الاستيعاب. يمكنك قياس مقدار قدرة الاستيعاب التي سيتم استخدامها من خلال تمرير الخيار responseConstraint إلى session.measureContextUsage().

يمكنك تجنُّب هذا السلوك باستخدام الخيار 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 available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});

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 available = await LanguageModel.availability({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
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.contextUsage}/${session.contextWindow}`);

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

يمكن رصد حالات التجاوز هذه من خلال الاستماع إلى حدث contextoverflow في الجلسة:

session.addEventListener("contextoverflow", () => {
  console.log("We've gone past the context window, and some inputs will be dropped!");
});

إذا تعذّر إزالة رموز مميّزة كافية من سجلّ المحادثة لمعالجة الطلب الجديد، سيتعذّر تنفيذ استدعاء prompt() أو promptStreaming() وسيظهر استثناء QuotaExceededError ولن تتم إزالة أي بيانات. يحتوي QuotaExceededError على السمات التالية:

• requested: عدد الرموز المميّزة التي يتكوّن منها الإدخال
• contextWindow: عدد الرموز المميّزة المتاحة

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

استنساخ جلسة

للحفاظ على الموارد، يمكنك نسخ جلسة حالية باستخدام الدالة 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 Audio Prompt
• Canvas Image Prompt

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

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

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

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

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

<!--
  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، يمكنك الإبلاغ عن خطأ أو إرسال طلب ميزة.
• يمكنك مشاركة ملاحظاتك حول شكل واجهة برمجة التطبيقات من خلال التعليق على مشكلة حالية أو بـ فتح مشكلة جديدة في مستودع Prompt API على GitHub.
• يمكنك الانضمام إلى برنامج الاستخدام المبكر.