發布日期:2025 年 5 月 20 日,上次更新日期:2025 年 9 月 21 日
說明 | 網頁 | 擴充功能 | Chrome 狀態 | 意圖 |
---|---|---|---|---|
GitHub | 查看 | 實驗意圖 |
透過 Prompt API,您可以將自然語言要求傳送至瀏覽器中的 Gemini Nano。
提示 API 的用途非常廣泛,舉例來說,您可以建構:
- AI 輔助搜尋:根據網頁內容回答問題。
- 個人化新聞動態消息:建立動態消息,根據類別動態分類文章,並允許使用者篩選該內容。
- 自訂內容篩選器:分析新聞報導,並根據使用者定義的主題自動模糊處理或隱藏內容。
- 建立日曆活動。開發 Chrome 擴充功能,自動從網頁擷取活動詳細資料,讓使用者只需幾個步驟就能建立日曆項目。
- 輕鬆擷取聯絡人資訊:建立擴充功能,從網站擷取聯絡資訊,方便使用者與商家聯絡,或將詳細資料新增至聯絡人清單。
以上僅列舉幾個例子,我們很期待看到你的創作。
查看硬體需求
開發人員和在 Chrome 中使用這些 API 操作功能的使用者,都必須遵守下列規定。其他瀏覽器的操作規定可能不同。
語言偵測器和翻譯工具 API 適用於 Chrome 電腦版。這些 API 不適用於行動裝置。在 Chrome 中,只要符合下列條件,即可使用 Prompt API、Summarizer API、Writer API、Rewriter API 和 Proofreader API:
- 作業系統:Windows 10 或 11;macOS 13 以上版本 (Ventura 以上版本); Linux;或 Chromebook Plus 裝置上的 ChromeOS (自 Platform 16389.0.0 以上版本)。 使用 Gemini Nano 的 API 目前不支援 Android 版、iOS 版 Chrome,以及非 Chromebook Plus 裝置上的 ChromeOS。
- 儲存空間:包含 Chrome 設定檔的磁碟區至少要有 22 GB 的可用空間。
- GPU:視訊記憶體必須超過 4 GB。
- 網路:無限量數據或不計量的連線。
瀏覽器更新模型時,Gemini Nano 的確切大小可能會有所不同。如要瞭解目前的容量,請前往 chrome://on-device-internals
。
使用 Prompt API
提示 API 會使用 Chrome 中的 Gemini Nano 模型。雖然 API 已內建於 Chrome,但來源首次使用 API 時,模型會另外下載。使用這項 API 前,請先詳閱並同意Google 的生成式 AI 使用限制政策。
如要判斷模型是否已可使用,請呼叫 LanguageModel.availability()
。
const availability = await LanguageModel.availability();
必須先有使用者互動 (例如點選、輕觸或按下按鍵),才能下載模型。
如果回應為 downloadable
或 downloading
,表示模型和 API 可供使用,但必須先下載才能使用相關功能。使用者必須與網頁互動 (例如點選、輕觸或按下按鍵),才能下載檔案。
如要下載及例項化模型,請呼叫 create()
函式。
const session = await LanguageModel.create({
monitor(m) {
m.addEventListener('downloadprogress', (e) => {
console.log(`Downloaded ${e.loaded * 100}%`);
});
},
});
如果對 availability()
的回應是 downloading
,請監聽下載進度並告知使用者,因為下載可能需要一段時間。
模型參數
params()
函式會告知語言模型的參數。物件包含下列欄位:
await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}
建立工作階段
提示 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"
角色回覆訊息。這有助於引導語言模型使用特定回覆格式。如要這麼做,請在結尾的 "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,
},
]);
新增預期輸入和輸出內容
Prompt API 具有多模態功能,並支援多種語言。建立工作階段時,請設定 expectedInputs
和 expectedOutputs
模態和語言。
type
:預期模態。- 如果是
expectedInputs
,則可以是text
、image
或audio
。 - 對於
expectedOutputs
,只有text
允許使用 Prompt API。
- 如果是
languages
:用於設定預期語言的陣列。Prompt API 接受"en"
、"ja"
和"es"
。我們正在開發更多語言的支援功能。- 如要設定
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 示範。
附加訊息
推論作業可能需要一些時間,尤其是使用多模態輸入內容提示時。 預先傳送預先決定的提示來填入工作階段,模型就能搶先開始處理。
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。
傳遞 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.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 });
提示模型
您可以使用 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,
});
工作階段管理
每個工作階段都會追蹤對話情境。在工作階段的內容視窗填滿之前,系統會將先前的互動納入考量,以利後續互動。
每個工作階段可處理的權杖數量有上限。如要查看進度,請使用下列方法:
console.log(`${session.inputUsage}/${session.inputQuota}`);
進一步瞭解工作階段管理。
複製課程
如要保留資源,可以使用 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 的多種用途。 下列是網頁應用程式的試用版:
如要在 Chrome 擴充功能中測試 Prompt API,請安裝示範擴充功能。您可以在 GitHub 上找到擴充功能原始碼。
成效策略
網頁版 Prompt API 仍在開發中。在我們建構這項 API 時,請參閱工作階段管理最佳做法,以獲得最佳成效。
權限政策、iframe 和 Web Worker
根據預設,Prompt API 僅適用於頂層視窗和同源 iframe。您可以使用 Permission Policy allow=""
屬性,將 API 存取權委派給跨來源 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>
由於要為每個 Worker 建立負責的文件,以檢查權限政策狀態,因此目前 Web Worker 無法使用 Prompt API。
參與並分享意見
您的意見將直接影響我們建構及實作這個 API 和所有內建 AI API 的後續版本。
- 如要提供 Chrome 實作方面的意見,請提出錯誤報告或功能要求。
- 如要分享對 API 形式的意見,請在現有問題中留言,或在 Prompt API GitHub 存放區中開啟新問題。
- 加入搶先體驗計畫。