EN

The Prompt API

科技 阅读 0
  • 首页
  • Docs
  • AI on Chrome
  • 内置 AI

Prompt API 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Thomas Steiner Thomas Steiner GitHub LinkedIn Mastodon Bluesky 首页 Alexandra Klepper Alexandra Klepper GitHub Bluesky

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

说明类视频 Web 扩展程序 Chrome 状态 目的
GitHub 源试用 源试用 The Prompt API Chrome 138 查看 实验目的
GitHub 源试用 采样参数源试用 The Prompt API Chrome 148 查看 实验目的

借助 Prompt API，您可以在浏览器中向 Gemini Nano发送自然语言请求。

您可以通过多种方式使用 Prompt API。例如，您可以构建：

  • AI 驱动的搜索：根据网页内容回答问题。
  • 个性化新闻 Feed：构建一个 Feed，该 Feed 可以动态地将文章分类 ，并允许用户过滤该内容。
  • 自定义内容过滤器 。分析新闻文章，并根据用户定义的主题自动模糊或隐藏内容。
  • 日历活动创建 。开发一个 Chrome 扩展程序，该扩展程序可以自动从网页中提取活动详情，以便用户只需几个步骤即可创建日历条目。
  • 无缝联系人提取 。构建一个扩展程序，该扩展程序可以从网站中提取联系信息，让用户更轻松地联系企业或向联系人列表中添加详细信息。

以上仅列举了几个示例，我们期待看到您的创作成果。

重要提示：Gemini Nano 是一种生成式 AI 模型。在使用采用 Gemini Nano 的 API 进行构建之前，您应查看 《People + AI Guidebook》，了解使用 AI 进行设计的最佳实践、方法和示例。

查看硬件要求

开发者和在 Chrome 中使用这些 API 运行功能的用户需要满足以下要求。其他浏览器可能有不同的运行要求。

Language Detector 和 Translator APIs 可在桌面版 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 及更高版本）。 Chromebook Plus 设备。 采用 Gemini Nano 的 API 尚不支持 Android 版 Chrome、iOS 版 Chrome 和非 Chromebook Plus 设备上的 ChromeOS 。
  • 存储空间：包含 Chrome 配置文件的卷上至少有 22 GB 的可用空间。 内置模型应明显更小。确切大小可能会 因更新而略有不同。
  • GPU 或 CPU：内置模型可以使用 GPU 或 CPU 运行。
    • GPU：VRAM 严格超过 4 GB。
    • CPU：16 GB 或更多 RAM，以及 4 个或更多 CPU 核心。
    • 注意：采用音频输入的 Prompt API 需要 GPU。
  • 网络：无限数据或不按流量计费的连接。 关键术语：按流量计费的连接是指数据有限的互联网连接。Wi-Fi 和以太网连接默认情况下往往不按流量计费 ，而移动网络连接通常按流量计费 。 注意：网络要求仅适用于模型的初始下载。 后续使用模型不需要网络连接。使用模型时，不会向 Google 或任何第三方发送任何数据。

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

注意：如果下载后可用存储空间降至 10 GB 以下，该模型将从您的设备中移除。满足要求后，该模型会重新下载 。

使用 Prompt API

Prompt API 在 Chrome 中使用 Gemini Nano 模型。虽然该 API 内置于 Chrome 中，但模型会在来源首次使用该 API 时单独下载。在使用此 API 之前，请确认您已了解 Google 的《生成式 AI 使用限制政策》。

提示： 使用 @types/dom-chromium-ai npm 软件包获取 Prompt API 和其他内置 AI API 的 TypeScript 类型。注意： 扩展程序开发者应移除已过期的源试用权限： "permissions": ["aiLanguageModelOriginTrial"].

如需确定模型是否已准备就绪，请调用 LanguageModel.availability()。

const availability = await LanguageModel.availability({
  // The same options in `prompt()` or `promptStreaming()`
});
注意： 始终将您在 prompt() 或 promptStreaming() 中使用的相同选项传递给 availability() 函数。这一点至关重要，因为某些模型可能不支持某些模态或语言。

如需触发下载并实例化语言模型，请检查 用户激活情况。然后，调用 create() 函数。

const session = await LanguageModel.create({
  monitor(m) {
    m.addEventListener('downloadprogress', (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
});

如果对 availability() 的响应为 downloading，请监听 下载进度并 通知用户， 因为下载可能需要一些时间。

在 localhost 上使用

所有内置 AI API 都可在 Chrome 中的 localhost 上使用。将以下标志设置为 Enabled：

  • chrome://flags/#optimization-guide-on-device-model
  • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

然后，点击 Relaunch 或重启 Chrome。如果您遇到错误， 请对 localhost 进行问题排查。

模型参数

**注意：** 本部分中的参数仅适用于 Chrome 扩展程序的 Prompt API，或者您在使用 Prompt API 时启用了 来源 试用。

params() 函数会告知您语言模型的参数。该对象具有以下字段：

  • defaultTopK：默认 top-K 值。
  • maxTopK：最大 top-K 值。
  • defaultTemperature：默认 温度。
  • maxTemperature：最大温度。
// Only available when using the Prompt API for Chrome Extensions.
await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2}

创建会话

Prompt API 可以运行后，您可以使用 create() 函数创建会话。

const session = await LanguageModel.create();

使用 Chrome 扩展程序的 Prompt API 创建会话

当您使用 Chrome 扩展程序的 Prompt API 时，可以使用可选的选项对象通过 topK 和 temperature 自定义每个会话。这些参数的默认值从 LanguageModel.params() 返回。

// Only available when using the Prompt API for Chrome Extensions.
const params = await LanguageModel.params();
// Initializing a new session must either specify both `topK` and
// `temperature` or neither of them.
// Only available when using the Prompt API for Chrome Extensions.
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"-角色消息中。例如：

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"。对其他语言的支持正在开发中。
    • 对于 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 支持以下输入类型：

  • 音频：
    • AudioBuffer
    • ArrayBufferView
    • ArrayBuffer
    • Blob
  • 视觉：
    • 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,
});

会话管理

每个会话都会跟踪对话的上下文。在会话的上下文窗口已满之前，系统会在未来的互动中考虑之前的互动。

每个会话可以处理的 token 数都有上限。您可以使用以下方法查看距离此限制的进度：

console.log(`${session.contextUsage}/${session.contextWindow}`);

您可以发送导致上下文窗口溢出的提示。在这种情况下，系统会一次移除一个提示和响应对，直到有足够的 token 可用于处理新提示为止。系统提示除外，系统永远不会移除系统提示。

您可以通过监听会话中的 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：可用的 token 数

详细了解会话管理。

克隆会话

为了保留资源，您可以使用 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 应用：

  • Prompt API 游乐场
  • Mediarecorder Audio Prompt
  • Canvas Image Prompt

如需在 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>

由于需要为每个 Worker 建立负责任的文档以检查权限政策状态，因此 Prompt API 目前无法在 Web Worker 中使用。

参与并分享反馈

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

  • 如需提供有关 Chrome 实现的反馈，请提交 bug 报告 或 功能请求。
  • 如需分享有关 API 形状的反馈，请在 Prompt API GitHub 代码库中评论现有问题或 打开新问题 。
  • 加入抢先试用计划。

如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。

最后更新时间 (UTC)：2025-09-21。

[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-09-21。"],[],[]]
推荐阅读：权威网络骗子查询网 | 星辰云IDC