Prompt API

Thomas Steiner

Alexandra Klepper

تاريخ النشر: 20 مايو 2025

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

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

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

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

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

استخدام Prompt API

قبل استخدام واجهة برمجة التطبيقات هذه، يجب الإقرار بسياسة الاستخدام المحظور للذكاء الاصطناعي التوليدي من Google.

تتوفّر لك وظيفتان في مساحة الاسم LanguageModel:

• availability() لمعرفة إمكانات النموذج وما إذا كان متاحًا.
• create() لبدء جلسة نموذج لغوي

تنزيل النموذج

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

لتحديد ما إذا كان النموذج جاهزًا للاستخدام، استدعِ الدالة غير المتزامنة LanguageModel.availability(). من المفترض أن يعرض هذا الأمر إحدى الاستجابات التالية:

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

لتفعيل تنزيل النموذج وإنشاء جلسة النموذج اللغوي، استدعِ الدالة غير المتزامنة LanguageModel.create(). إذا كان الردّ على availability() هو 'downloadable'، من أفضل الممارسات الاستماع إلى تقدّم التنزيل. بهذه الطريقة، يمكنك إبلاغ المستخدم في حال استغرق التنزيل وقتًا طويلاً.

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

إمكانات النموذج

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

• defaultTopK: القيمة التلقائية لأفضل K (القيمة التلقائية: 3).
• maxTopK: قيمة أعلى K (8).
• defaultTemperature: درجة الحرارة التلقائية (1.0). يجب أن تتراوح قيمة درجة الحرارة بين 0.0 و2.0.
• ‫maxTemperature: تمثّل هذه السمة الحدّ الأقصى لدرجة الحرارة.

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

إنشاء جلسة

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

تخصيص جلستك

يمكن تخصيص كل جلسة باستخدام 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,
  },
]);

إضافة رسائل بدون طلب تأكيد

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

في حين أنّ 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() بعد التحقّق من صحة الطلب ومعالجته وإضافته إلى الجلسة. يتم رفض الوعد إذا تعذّر إلحاق الطلب.

حدود الجلسات

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

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

استمرار الجلسة

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

const session = await LanguageModel.create({
  initialPrompts: [
    {
      role: 'system',
      content:
        'You are a friendly, helpful assistant specialized in clothing choices.',
    },
  ],
});

const result1 = await session.prompt(
  'What should I wear today? It is sunny. I am unsure between a t-shirt and a polo.',
);
console.log(result1);

const result2 = await session.prompt(
  'That sounds great, but oh no, it is actually going to rain! New advice?',
);
console.log(result2);

نسخ جلسة

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

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

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

تقديم طلب إلى النموذج

يمكنك تقديم طلب إلى النموذج باستخدام الدالتَين 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,
});

إنهاء جلسة

اتّصِل بالرقم 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 unsure between a
  t-shirt and a polo."
);

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

تتيح واجهة برمجة التطبيقات Prompt API إدخال الصوت والصور من الإصدار 138 من Chrome Canary، وذلك لإجراء تجارب محلية. تعرض واجهة برمجة التطبيقات نصًا.

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

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

const session = await LanguageModel.create({
  // { type: "text" } is not necessary to include explicitly, unless
  // you also want to include expected input languages for text.
  expectedInputs: [{ type: 'audio' }, { type: 'image' }],
});

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 audioBlob = await captureMicrophoneInput({ seconds: 10 });

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

عروض توضيحية متعددة الوسائط

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

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

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

الملاحظات

تساعدنا ملاحظاتك في تحديد مستقبل واجهة برمجة التطبيقات هذه وإجراء تحسينات على Gemini Nano. وقد يؤدي ذلك إلى توفير واجهات برمجة تطبيقات مخصّصة للمهام (مثل واجهات برمجة التطبيقات الخاصة بنسخ الصوت أو وصف الصور)، ما يتيح لنا تلبية احتياجاتك واحتياجات المستخدمين.

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

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

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