Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

Prompt API

Thomas Steiner

Alexandra Klepper

发布时间：2025 年 5 月 20 日，上次更新时间：2026 年 10 月 21 日

说明类视频	Web	扩展程序	Chrome 状态	目的
GitHub	Chrome 148	Chrome 138	查看	发货意向
GitHub	采样参数源试用	Chrome 148	查看	Intent to Experiment

借助 Prompt API，您可以向 Chrome 中的基础模型发送自然语言请求。

Prompt API 有多种用途。例如，您可以构建：

AI 赋能的搜索：根据网页内容回答问题。
个性化新闻信息流：构建一个信息流，以便按类别动态分类文章，并允许用户过滤这些内容。
自定义内容过滤器。分析新闻报道，并根据用户定义的主题自动模糊处理或隐藏内容。
创建日历活动。开发一个 Chrome 扩展程序，用于自动从网页中提取活动详细信息，以便用户只需几步即可创建日历条目。
顺畅提取联系人信息。构建一个扩展程序，用于从网站中提取联系信息，让用户能够更轻松地联系商家或将详细信息添加到其联系人列表中。

这些只是部分可能性，我们期待看到您的创作成果。

查看硬件要求

对于开发者以及在 Chrome 中使用这些 API 操作功能的用户，存在以下要求。其他浏览器可能有不同的操作要求。

Language Detector 和 Translator API 适用于桌面版 Chrome。这些 API 无法在移动设备上运行。

Prompt API、Summarizer API、Writer API、Rewriter API 和 Proofreader API 在满足以下条件时可在 Chrome 中运行：

操作系统：Windows 10 或 11；macOS 13 或更高版本（Ventura 及更高版本）；Linux；或 Chromebook Plus 设备上的 ChromeOS（平台 16389.0.0 及更高版本）。使用基础模型的 API 尚不支持 Android 版 Chrome、iOS 版 Chrome 以及非 Chromebook Plus 设备上的 ChromeOS。
存储空间：包含 Chrome 个人资料的卷上至少有 22 GB 的可用空间。
内置模型应该要小得多。确切大小可能会因更新而略有不同。
GPU 或 CPU：内置模型可以使用 GPU 或 CPU 运行。
- GPU：严格大于 4 GB 的 VRAM。
- CPU：16 GB 或更多 RAM，以及 4 个或更多 CPU 核心。
- 注意：支持音频输入的 Prompt API 需要 GPU。
网络：无限流量或不按流量计费的连接。
关键术语：按流量计费的网络是指流量受限的网络连接。默认情况下，Wi-Fi 和以太网连接往往不按流量计费，而移动网络连接通常按流量计费。

注意：网络要求仅适用于模型的初始下载。后续使用该模型时无需网络连接。使用该模型时，不会向 Google 或任何第三方发送任何数据。

Gemini Nano 的确切大小可能会因浏览器更新模型而有所不同。如需确定当前大小，请访问 chrome://on-device-internals。

使用 Prompt API

Prompt API 使用 Chrome 中的 Gemini Nano 模型。虽然该 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() 函数的可选 options 对象接受 signal 字段，该字段可让您传递 AbortSignal 以销毁会话。

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

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

采样参数

通过控制采样，您可以调整模型回答的可预测性（确定性）或创造性（多样性）。Web 平台和 Chrome 扩展程序之间的采样参数可用性有所不同：

Web：使用 samplingMode 选项，该选项使用描述性枚举值（而非原始数字）来调整输出可预测性。
Chrome 扩展程序：支持旧版数字参数（topK、temperature）和 LanguageModel.params() 方法。

Web 采样模式

将 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 扩展程序的采样参数

在 Chrome 扩展程序中使用 Prompt API 时，仍可以使用选项对象通过 topK 和 temperature 自定义每个会话。

静态 LanguageModel.params() 函数会告知您语言模型的默认和最大参数限制：

defaultTopK：默认 top-K 值。
maxTopK：Top-K 上限值。
defaultTemperature：默认温度。
maxTemperature：最高温度。

// 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 支持以下输入类型：

音频：
视觉：
- HTMLImageElement
- SVGImageElement
- HTMLVideoElement（使用当前视频位置处的视频帧）
- HTMLCanvasElement
- ImageBitmap
- OffscreenCanvas
- VideoFrame
- Blob
- ImageData

此代码段展示了一个多模态会话，该会话首先处理两个视觉内容（一张图片 Blob 和一个 HTMLCanvasElement），并让 AI 对其进行比较，然后让用户使用录音（作为 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 在创建会话时很有用，但除了 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.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!");
});

如果无法从对话记录中移除足够的 token 来处理新提示，则 prompt() 或 promptStreaming() 调用将失败并抛出 QuotaExceededError 异常，并且不会移除任何内容。QuotaExceededError 具有以下属性：

requested：输入包含多少个 token
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 的众多应用场景。以下演示是 Web 应用：

如需在 Chrome 扩展程序中测试 Prompt API，请安装演示版扩展程序。扩展程序源代码可在 GitHub 上找到。

效果策略

适用于 Web 的 Prompt API 仍在开发中。在我们构建此 API 的过程中，请参阅会话管理方面的最佳实践，以获得最佳性能。

权限政策、iframe 和 Web Worker

默认情况下，Prompt API 仅适用于顶级窗口及其同源 iframe。您可以使用权限政策 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>

目前，Prompt API 无法在 Web Worker 中使用，因为为每个 Worker 建立负责任的文档以检查权限政策状态非常复杂。

您的反馈将直接影响我们如何构建和实现此 API 以及所有内置 AI API 的未来版本。

如需针对 Chrome 的实现提供反馈，请提交错误报告或功能请求。
如需分享您对 API 形式的反馈，请在 Prompt API GitHub 代码库中对现有问题发表评论或提出新问题。
加入抢先试用计划。