Prompt API

Thomas Steiner
Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

تاریخ انتشار: ۲۰ مه ۲۰۲۵، آخرین به‌روزرسانی: ۲۱ اکتبر ۲۰۲۶

راهنمای توضیحی وب برنامه‌های افزودنی Chrome Status هدف
GitHub Chrome 148 Chrome 138 مشاهده قصد ارسال
GitHub آزمایش معرفی ویژگی جدید آزمایش معرفی ویژگی جدید برای پارامترهای نمونه‌گیری Chrome 148 مشاهده Intent to Experiment
برای افزونه‌های Chrome، پارامترهای نمونه‌برداری قدیمی (topK، temperature) و LanguageModel.params() هنوز وجود دارند.

با Prompt API، می‌توانید درخواست‌های زبان طبیعی را به مدل پایه در Chrome ارسال کنید.

روش‌های زیادی برای استفاده از Prompt API وجود دارد. برای مثال، می‌توانید این موارد را بسازید:

  • جستجوی هوشواره‌ای: به سؤالات براساس محتوای صفحه وب پاسخ دهید.
  • فیدهای خبری شخصی‌سازی‌شده: فیدی بسازید که مقاله‌ها را به‌طور پویا با دسته‌ها طبقه‌بندی کند و به کاربران اجازه دهد آن محتوا را فیلتر کنند.
  • فیلترهای محتوای سفارشی. مقاله‌های خبری را تجزیه‌وتحلیل کنید و محتوا را براساس موضوعات تعریف‌شده توسط کاربر به‌طور خودکار محو یا پنهان کنید.
  • ایجاد رویداد تقویم. افزونه Chrome توسعه دهید که به‌طور خودکار جزئیات رویداد را از صفحه‌های وب استخراج کند تا کاربران بتوانند فقط با چند مرحله ورودی‌های تقویم ایجاد کنند.
  • استخراج یکپارچه مخاطب. افزونه‌ای بسازید که اطلاعات تماس را از وب‌سایت‌ها استخراج کند و تماس با کسب‌وکار یا افزودن جزئیات به فهرست مخاطبین را برای کاربران آسان‌تر کند.

این‌ها فقط چند مورد از امکانات هستند و ما مشتاقیم ببینیم شما چه چیزی خلق می‌کنید.

بررسی الزامات سخت‌افزاری

الزامات زیر برای توسعه‌دهندگان و کاربرانی که ویژگی‌ها را بااستفاده از این میاناهای برنامه‌سازی کاربردی در Chrome اجرا می‌کنند وجود دارد. مرورگرهای دیگر ممکن است الزامات عملیاتی متفاوتی داشته باشند.

Language Detector و Translator APIs در Chrome در رایانه کار می‌کنند. این میاناهای برنامه‌سازی کاربردی در دستگاه‌های همراه کار نمی‌کنند.

Prompt API، Summarizer API، Writer API، Rewriter API، و Proofreader API در Chrome کار می‌کنند اگر شرایط زیر برآورده شود:

  • سیستم‌عامل: Windows 10 یا 11؛ macOS 13+‎ (Ventura و نسخه‌های جدیدتر)؛ Linux؛ یا ChromeOS (از پلاتفرم 16389.0.0 و نسخه‌های جدیدتر) در دستگاه‌های Chromebook Plus. Chrome ویژه Android،‏ iOS، و ChromeOS در دستگاه‌های غیر Chromebook Plus هنوز توسط میاناهای برنامه‌سازی کاربردی که از مدل‌های پایه استفاده می‌کنند پشتیبانی نمی‌شوند.
  • فضای ذخیره‌سازی: حداقل ۲۲ گیگابایت فضای آزاد در درایوی که حاوی نمایه Chrome شما است.
  • واحد پردازش گرافیکی یا واحد پردازش مرکزی: مدل‌های داخلی می‌توانند با واحد پردازش گرافیکی یا واحد پردازش مرکزی اجرا شوند.
    • واحد پردازش گرافیکی: دقیقاً بیشتر از ۴ گیگابایت VRAM.
    • واحد پردازش مرکزی: ۱۶ گیگابایت حافظه دسترسی تصادفی یا بیشتر و ۴ هسته واحد پردازش مرکزی یا بیشتر.
    • توجه: Prompt API با ورودی صوتی به GPU نیاز دارد.
  • شبکه: داده نامحدود یا اتصال نامحدود.

اندازه دقیق Gemini Nano ممکن است با به‌روزرسانی مدل توسط مرورگر تغییر کند. برای تعیین اندازه فعلی، به chrome://on-device-internals بروید.

استفاده از Prompt API

Prompt API از مدل Gemini Nano در Chrome استفاده می‌کند. درحالی‌که API در Chrome تعبیه شده است، مدل به‌طور جداگانه در اولین‌باری که یک مبدأ از API استفاده می‌کند بارگیری می‌شود.

برای تعیین اینکه مدل آماده استفاده است یا نه، 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 بود، به پیشرفت بارگیری گوش دهید و به کاربر اطلاع دهید، زیرا بارگیری ممکن است طول بکشد.

ایجاد جلسه

وقتی Prompt API بتواند اجرا شود، با تابع create() جلسه‌ای ایجاد می‌کنید.

const session = await LanguageModel.create();

شیء گزینه‌های اختیاری تابع create() فیلد signal را می‌گیرد که به شما امکان می‌دهد AbortSignal را برای ازبین بردن جلسه ارسال کنید.

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

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

پارامترهای نمونه‌گیری

کنترل کردن نمونه‌برداری به شما امکان می‌دهد میزان قابل‌پیش‌بینی بودن (قطعی بودن) یا خلاقانه بودن (متنوع بودن) پاسخ‌های مدل را تنظیم کنید. دردسترس بودن پارامترهای نمونه‌برداری بین پلاتفرم وب و «افزونه‌های Chrome» متفاوت است:

  • وب: از گزینه samplingMode استفاده کنید که به‌جای اعداد خام از مقادیر شمارشی توصیفی برای تنظیم پیش‌بینی‌پذیری برونداد استفاده می‌کند.
  • افزونه‌های Chrome: پارامترهای عددی قدیمی (topK، temperature) و روش LanguageModel.params() پشتیبانی می‌شوند.

حالت نمونه‌گیری وب

گزینه samplingMode را به LanguageModel.create() (یا LanguageModel.availability()) ارسال کنید.

مقادیر شمارشی samplingMode پشتیبانی‌شده عبارت‌اند از:

  • "most-predictable": بالاترین قطعیت و پیش‌بینی‌پذیری.
  • ‫"predictable": برونداد قابل‌پیش‌بینی‌تر با حداقل تنوع.
  • ‫"slightly-predictable": برونداد تاحدی قابل‌پیش‌بینی.
  • ‫"balanced": تعادل بین قابل‌پیش‌بینی بودن و خلاقیت (رفتار پیش‌فرض معمول).
  • "slightly-creative": خروجی کمی متنوع و خلاقانه.
  • "creative": خروجی خلاقانه و متنوع.
  • ‫"most-creative": حداکثر تنوع و خلاقیت.
// Available on the web with the Sampling Parameters Origin Trial enabled
const session = await LanguageModel.create({
  samplingMode: 'creative',
});

// The configured sampling mode is exposed on the session instance
console.log(session.samplingMode);
// "creative"

پارامترهای نمونه‌گیری برای افزونه‌های Chrome

هنگام استفاده از Prompt API در «افزونه‌های Chrome»، هر جلسه همچنان می‌تواند بااستفاده از شیء گزینه‌ها با topK و temperature سفارشی‌سازی شود.

تابع ایستا LanguageModel.params() شما را از محدودیت‌های پارامتر پیش‌فرض و حداکثر مدل زبانی مطلع می‌کند:

// Only available in Chrome Extensions
const params = await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

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

console.log(slightlyHighTemperatureSession.temperature);
console.log(slightlyHighTemperatureSession.topK);

افزودن زمینه با پیام‌واره‌های اولیه

با پیام‌واره‌های اولیه، می‌توانید برای مدل زبانی زمینه‌ای درباره تعاملات قبلی ارائه دهید، برای مثال، به کاربر اجازه دهید پس‌از بازراه‌اندازی مرورگر، جلسه ذخیره‌شده را ازسر بگیرد.

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"، "de"، و "fr" را می‌پذیرد. پشتیبانی از زبان‌های دیگر درحال توسعه است.
    • برای expectedInputs، زبان پیام‌واره سیستم و یک یا چند زبان پیام‌واره موردانتظار کاربر را تنظیم کنید.
    • یک یا چند زبان expectedOutputs را تنظیم کنید.
const session = await LanguageModel.create({
  expectedInputs: [
    { type: "text", languages: ["en" /* system prompt */, "ja" /* user prompt */] }
  ],
  expectedOutputs: [
    { type: "text", languages: ["ja"] }
  ]
});

اگر مدل با ورودی یا خروجی پشتیبانی‌نشده‌ای مواجه شود، ممکن است "NotSupportedError" DOMException دریافت کنید.

قابلیت‌های چندحالته

با این قابلیت‌ها می‌توانید:

  • به کاربران اجازه می‌دهد پیام‌های صوتی ارسال‌شده در برنامه گپ را ترانویسی کنند.
  • تصویری را که در وب‌سایتتان بارگذاری شده است برای استفاده در زیرنویس یا نوشتار جایگزین توصیف کنید.

برای استفاده از Prompt API با ورودی صوتی، به نسخه نمایشی Mediarecorder Audio Prompt و برای استفاده از Prompt API با ورودی تصویری، به نسخه نمایشی Canvas Image Prompt مراجعه کنید.

‫Prompt API از انواع ورودی زیر پشتیبانی می‌کند:

این قطعه کد یک جلسه چندحالتی را نشان می‌دهد که ابتدا دو عنصر بصری (یک تصویر 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

فیلد responseConstraint را به روش prompt() یا promptStreaming() اضافه کنید تا «طرح JSON» را به‌عنوان مقدار ارسال کنید. سپس می‌توانید از برونداد ساختاریافته با Prompt API استفاده کنید.

در مثال زیر، «طرح JSON» مطمئن می‌شود که مدل با 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.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 در «افزونه‌های Chrome»، افزونه نمایشی را نصب کنید. کد منبع افزونه در GitHub دردسترس است.

راهبرد عملکرد

Prompt API برای وب هنوز درحال توسعه است. درحالی‌که این میانای برنامه‌سازی کاربردی را می‌سازیم، برای عملکرد بهینه به روال‌های مطلوب ما درباره مدیریت جلسه مراجعه کنید.

خط‌مشی اجازه، iframe، و Web Workers

به‌طور پیش‌فرض، Prompt API فقط برای پنجره‌های سطح بالا و iframeهای هم‌مبدأ آن‌ها دردسترس است. دسترسی به میانای برنامه‌سازی کاربردی را می‌توان بااستفاده از مشخصه allow="" «خط‌مشی اجازه» به iframe میان‌مبدئی واگذار کرد:

<!--
  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 دردسترس نیست، زیرا ایجاد یک سند مسئول برای هر کارگر به‌منظور بررسی وضعیت خط‌مشی اجازه‌ها پیچیده است.

مشارکت و هم‌رسانی بازخورد

بازخورد شما می‌تواند مستقیماً بر نحوه ساخت و پیاده‌سازی نسخه‌های آینده این میانای برنامه‌سازی کاربردی و همه میاناهای برنامه‌سازی کاربردی هوش مصنوعی داخلی تأثیر بگذارد.