تاريخ النشر: 20 مايو 2025، تاريخ آخر تعديل: 21 يوليو 2025
شرح | الويب | الإضافات | حالة Chrome | النيّة |
---|---|---|---|---|
Github | العرض | نية إجراء تجربة |
باستخدام Prompt API، يمكنك إرسال طلبات باللغة الطبيعية إلى Gemini Nano في المتصفّح.
هناك العديد من الطرق التي يمكنك من خلالها استخدام Prompt API في تطبيق ويب أو موقع إلكتروني. على سبيل المثال، يمكنك إنشاء ما يلي:
- البحث المستند إلى الذكاء الاصطناعي: الإجابة عن الأسئلة استنادًا إلى محتوى صفحة ويب
- خلاصات الأخبار المخصّصة: يمكنك إنشاء خلاصة تصنّف المقالات ديناميكيًا حسب الفئات وتتيح للمستخدمين فلترة المحتوى.
هذه مجرد بعض الاحتمالات، ونحن متحمّسون لرؤية ابتكاراتك.
مراجعة متطلبات الأجهزة
تتوفّر المتطلبات التالية للمطوّرين والمستخدمين الذين يشغّلون الميزات باستخدام واجهات برمجة التطبيقات هذه في Chrome. قد تتطلّب المتصفّحات الأخرى متطلبات تشغيل مختلفة.
تعمل واجهتا برمجة التطبيقات Language Detector وTranslator في متصفّح Chrome على أجهزة الكمبيوتر المكتبي. ولا تعمل واجهات برمجة التطبيقات هذه على الأجهزة الجوّالة. تعمل واجهات برمجة التطبيقات Prompt API وSummarizer API وWriter API وRewriter API في Chrome عند استيفاء الشروط التالية:
- نظام التشغيل: Windows 10 أو 11 أو macOS 13 (Ventura والإصدارات الأحدث) أو Linux أو ChromeOS (الإصدار 16389.0.0 والإصدارات الأحدث) على أجهزة [Chromebook Plus](https://www.google.com/chromebook/chromebookplus/) لا تتوافق واجهات برمجة التطبيقات التي تستخدم Gemini Nano بعد مع Chrome على أجهزة Android وiOS وChromeOS غير Chromebook Plus.
- مساحة التخزين: يجب توفّر مساحة خالية لا تقل عن 22 غيغابايت على وحدة التخزين التي تحتوي على ملفك الشخصي على Chrome.
- وحدة معالجة الرسومات (GPU): يجب أن تكون ذاكرة الوصول العشوائي للفيديو (VRAM) أكبر من 4 غيغابايت.
- الشبكة: بيانات غير محدودة أو اتصال غير محدود.
قد يختلف حجم Gemini Nano الدقيق مع تحديث المتصفّح للنموذج. لتحديد الحجم الحالي، انتقِل إلى chrome://on-device-internals
ثم إلى حالة النموذج. افتح مسار الملف المُدرَج لتحديد حجم النموذج.
استخدام Prompt API
تستخدم واجهة برمجة التطبيقات Prompt API نموذج Gemini Nano في Chrome. مع أنّ واجهة برمجة التطبيقات مدمجة في Chrome، يتم تنزيل النموذج بشكل منفصل في المرة الأولى التي يستخدم فيها مصدر واجهة برمجة التطبيقات.
لتحديد ما إذا كان النموذج جاهزًا للاستخدام، استدعِ الدالة
LanguageModel.availability()
.
إذا كان الردّ على availability()
هو downloadable
، استمع إلى مستوى التقدّم في عملية التنزيل وأبلِغ المستخدم بذلك، لأنّ عملية التنزيل قد تستغرق بعض الوقت.
const availability = await LanguageModel.availability();
لتفعيل التنزيل وإنشاء نموذج اللغة، تحقَّق من تفاعل المستخدم. بعد ذلك، استدعِ الدالة غير المتزامنة LanguageModel.create()
.
const session = await LanguageModel.create({
monitor(m) {
m.addEventListener('downloadprogress', (e) => {
console.log(`Downloaded ${e.loaded * 100}%`);
});
},
});
مَعلمات النموذج
تُعلمك الدالة params()
بمعلَمات النموذج اللغوي. يحتوي العنصر على الحقول التالية:
defaultTopK
: القيمة التلقائية لأعلى K.maxTopK
: تمثّل الحد الأقصى لقيمة top-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,
},
]);
إلحاق الرسائل
قد تستغرق عملية الاستنتاج بعض الوقت، خاصةً عند تقديم طلب باستخدام مدخلات متعددة الوسائط. قد يكون من المفيد إرسال طلبات محددة مسبقًا لتعبئة الجلسة، ما يتيح للنموذج البدء في المعالجة.
في حين أنّ 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()
بعد التحقّق من صحة الطلب ومعالجته وإضافته إلى الجلسة. يتم رفض الوعد إذا تعذّر إلحاق النص.
استمرار الجلسة وحدودها
تتتبّع كل جلسة سياق المحادثة. يتم أخذ التفاعلات السابقة في الاعتبار للتفاعلات المستقبلية إلى أن تمتلئ نافذة السياق الخاصة بالجلسة.
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);
لكل جلسة حدّ أقصى لعدد الرموز المميّزة التي يمكنها معالجتها. يمكنك الاطّلاع على مدى تقدّمك نحو هذا الحد من خلال ما يلي:
console.log(`${session.inputUsage}/${session.inputQuota}`);
تمرير مخطط 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 });
نسخ جلسة
للحفاظ على الموارد، يمكنك استنساخ جلسة حالية باستخدام الدالة 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 choosing between a t-shirt
and a polo."
);
الإمكانات المتعددة الوسائط
تتيح مرحلة التجربة والتقييم لواجهة برمجة التطبيقات Prompt API إدخال بيانات صوتية وصور. تعرض واجهة برمجة التطبيقات ناتجًا نصيًا.
باستخدام هذه الإمكانات، يمكنك إجراء ما يلي:
- السماح للمستخدمين بنسخ الرسائل الصوتية التي يتم إرسالها في تطبيق محادثة
- وصف صورة تم تحميلها إلى موقعك الإلكتروني لاستخدامها في تعليق توضيحي أو نص بديل
const session = await LanguageModel.create({
// { type: 'text' } only required when including expected input languages.
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 an 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 للويب. أثناء إنشاء واجهة برمجة التطبيقات هذه، يمكنك الرجوع إلى أفضل الممارسات المتعلّقة بإدارة الجلسات لتحقيق أفضل أداء.
سياسة الأذونات وإطارات 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 لهذه الميزة، يمكنك تقديم تقرير خطأ أو طلب ميزة.
- يمكنك مشاركة ملاحظاتك حول شكل واجهة برمجة التطبيقات من خلال إضافة تعليق على مشكلة حالية أو فتح مشكلة جديدة في مستودع Prompt API GitHub.
- الانضمام إلى برنامج الاستخدام المبكر