Prompt API

تاریخ انتشار: 20 می 2025، آخرین به روز رسانی: 21 جولای 2025

توضیح دهنده وب برنامه های افزودنی وضعیت کروم قصد
GitHub آزمایش مبدا در نسخه آزمایشی Origin کروم 138 مشاهده کنید قصد آزمایش

با Prompt API می‌توانید درخواست‌های زبان طبیعی را به Gemini Nano در مرورگر ارسال کنید.

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

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

اینها فقط چند احتمال هستند و ما از دیدن آنچه شما ایجاد می کنید هیجان زده هستیم.

الزامات سخت افزاری را بررسی کنید

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

زبان شناساگر و API های مترجم در کروم روی دسکتاپ کار می کنند. این API ها روی دستگاه های تلفن همراه کار نمی کنند. Prompt API، Summarizer API، Writer API، و Rewriter API در Chrome کار می‌کنند که شرایط زیر رعایت شود:

  • سیستم عامل : ویندوز 10 یا 11؛ macOS 13+ (ونتورا و به بعد)؛ لینوکس؛ یا ChromeOS (از پلتفرم 16389.0.0 و به بعد) در دستگاه‌های [Chromebook Plus](https://www.google.com/chromebook/chromebookplus/). Chrome for Android، iOS و ChromeOS در دستگاه‌های غیرChromebook Plus هنوز توسط APIهایی که از Gemini Nano استفاده می‌کنند پشتیبانی نمی‌شوند.
  • فضای ذخیره سازی : حداقل 22 گیگابایت فضای خالی در حجمی که نمایه Chrome شما را در بر می گیرد.
  • GPU : به طور دقیق بیش از 4 گیگابایت VRAM.
  • شبکه : داده های نامحدود یا اتصال نامحدود.

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

از Prompt API استفاده کنید

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

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

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 Schema را به عنوان مقدار ارسال کنید. سپس می توانید از خروجی ساخت یافته با 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.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 از ورودی های صوتی و تصویری پشتیبانی می کند. 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 برای وب هنوز در حال توسعه است. در حالی که ما این API را می سازیم، برای عملکرد بهینه به بهترین شیوه های مدیریت جلسه مراجعه کنید.

خط مشی مجوز، iframes، و کارگران وب

به‌طور پیش‌فرض، Prompt API فقط برای پنجره‌های سطح بالا و iframe‌های همان مبدا در دسترس است. دسترسی به API را می توان با استفاده از ویژگی Permission Policy 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 در دسترس نیست.

شرکت کنید و بازخورد خود را به اشتراک بگذارید

ورودی شما می‌تواند مستقیماً بر نحوه ساخت و اجرای نسخه‌های آینده این API و همه APIهای AI داخلی تأثیر بگذارد.