Prompt API

發布日期:2025 年 5 月 20 日,上次更新日期:2025 年 7 月 21 日

說明 網頁 額外資訊 Chrome 狀態 Intent
GitHub 來源試用 原始試用 Chrome 138 查看 實驗意圖

透過 Prompt API,您可以將自然語言要求傳送至瀏覽器中的 Gemini Nano

您可以在網頁應用程式或網站中,以多種方式使用 Prompt API。舉例來說,您可以建構:

  • AI 輔助搜尋:根據網頁內容回答問題。
  • 個人化新聞動態消息:建立動態消息,動態分類文章,並允許使用者篩選該內容。

以上僅列舉幾個例子,我們很期待看到你的創作。

查看硬體需求

開發人員和使用者在 Chrome 中使用這些 API 運作功能時,必須遵守下列規定。其他瀏覽器的操作規定可能不同。

語言偵測器和翻譯器 API 適用於電腦版 Chrome。這些 API 不適用於行動裝置。在 Chrome 中使用 Prompt API、Summarizer API、Writer API 和 Rewriter API 時,須符合下列條件:

  • 作業系統:Windows 10 或 11;macOS 13 以上版本 (Ventura 和後續版本);或 Linux。目前 Android 版、iOS 版和 ChromeOS 版 Chrome 尚未支援使用 Gemini Nano 的 API。
  • 儲存空間:包含 Chrome 設定檔的磁碟區至少要有 22 GB 的可用空間。
  • GPU:視訊記憶體必須超過 4 GB。
  • 網路:無限量數據或不計量的連線。

瀏覽器更新模型時,Gemini Nano 的確切大小可能會有所不同。如要判斷目前大小,請前往 chrome://on-device-internals 並前往「模型狀態」。開啟列出的「檔案路徑」,判斷模型大小。

使用 Prompt API

使用這項 API 前,請先詳閱並同意《Google 生成式 AI 使用限制政策》

LanguageModel 命名空間提供以下兩個函式:

  • availability(),瞭解模型的功能和適用情形。
  • create() 即可開始語言模型工作階段。

下載模型

Prompt API 會使用 Chrome 中的 Gemini Nano 模型。雖然 API 已內建於 Chrome,但來源首次使用 API 時,模型會另外下載。

如要判斷模型是否已可使用,請呼叫非同步 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.02.0 之間。
  • maxTemperature:最高溫度。
await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 8, defaultTemperature: 1, maxTemperature: 2}

建立工作階段

提示 API 執行後,您可以使用 create() 函式建立工作階段。您可以使用 prompt()promptStreaming() 函式提示模型。

自訂工作階段

您可以使用選用的選項物件,透過 topKtemperature 自訂每個工作階段。這些參數的預設值會從 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" 角色回覆訊息。這有助於引導語言模型使用特定回覆格式。如要這麼做,請在結尾的 "assistant" 角色訊息中加入 prefix: true。例如:

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 在建立工作階段時很有用,但除了 prompt()promptStreaming() 方法外,您也可以使用 append() 方法,在工作階段建立後提供額外的背景提示。

例如:

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() 傳回的 Promise 就會完成。如果無法附加提示,系統會拒絕 Promise。

工作階段相關限制

特定語言模型工作階段可處理的權杖數量有上限。 您可以在工作階段物件中使用下列屬性,查看用量和進度:

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);
傳遞 JSON 結構定義

如要確保模型遵守要求的 JSON 結構定義,您需要將 JSON 結構定義做為引數,傳遞至 prompt()promptStreaming() 方法的選項物件,做為 responseConstraint 欄位的值。

以下是 JSON 結構定義的基本範例,可確保模型回覆 truefalse,判斷指定訊息 (例如這則 Mastodon 貼文) 是否與陶藝相關。

const session = await LanguageModel.create();

const schema = {
  "type": "boolean"
};

const post = "Mugs and ramen bowls, both a bit smaller than intended- but that's
how it goes 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

根據預設,實作方式可能會將結構定義或規則運算式納入傳送至基礎語言模型的訊息中。這會使用部分輸入配額。您可以將 responseConstraint 選項傳遞至 session.measureInputUsage(),測量這項作業會用掉多少輸入配額。

如要避免這種情況,請使用 omitResponseConstraintInput 選項。在這種情況下,建議您在提示中加入一些指引:

const result = await session.prompt(`
  Summarize this feedback into a rating between 0-5, only outputting 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 unsure between a
  t-shirt and a polo."
);

多模態功能

從 Chrome 138 Canary 版起,提示 API 支援音訊和圖片輸入,方便您在本機進行實驗。API 會傳回文字輸出內容。

有了這些功能,您就能:

  • 允許使用者轉錄在即時通訊應用程式中傳送的語音訊息。
  • 描述上傳至網站的圖片,以用於說明文字或替代文字。
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 },
    ],
  },
]);

多模態示範

如要瞭解如何搭配音訊輸入使用 Prompt API,請參閱 Mediarecorder Audio Prompt 示範;如要瞭解如何搭配圖片輸入使用 Prompt API,請參閱 Canvas Image Prompt 示範。

成效策略

網頁版提示 API 仍在開發中,在我們建構這項 API 時,請參閱工作階段管理最佳做法,以獲得最佳成效。

意見回饋

您的意見有助於我們決定這項 API 的未來發展方向,並改善 Gemini Nano。甚至可能推出專屬的 Task API (例如音訊轉錄或圖片說明 API),滿足您和使用者的需求。

參與並分享意見

您的意見將直接影響我們建構及實作這個 API 和所有內建 AI API 的後續版本。