Prompt API

发布时间:2025 年 5 月 20 日

说明类视频 Web 扩展程序 Chrome 状态 意向
GitHub 源试用Origin 试用 Chrome 138 视图 实验意向

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

您可以通过多种方式使用 Prompt API。在 Web 应用或网站中,您可以创建:

  • AI 赋能的搜索:根据网页内容回答问题。
  • 个性化新闻 Feed:构建一个可动态对文章进行分类的 Feed,并允许用户过滤相应内容。

以上只是几个示例,我们期待看到您的创作成果。

查看硬件要求

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

语言检测器和翻译器 API 可在桌面版 Chrome 中使用。这些 API 不适用于移动设备。当满足以下条件时,Prompt API、Summarizer API、Writer API 和 Rewriter API 可在 Chrome 中正常运行:

  • 操作系统:Windows 10 或 11;macOS 13 及更高版本(Ventura 及更高版本);或 Linux。使用 Gemini Nano 的 API 尚不支持 Android 版 Chrome、iOS 版 Chrome 和 ChromeOS 版 Chrome。
  • 存储空间:包含 Chrome 个人资料的卷上至少有 22 GB 的可用空间。
  • GPU:VRAM 严格大于 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:默认的 top-K 值(默认值:3)。
  • maxTopK最大 Top-K 值 (8)。
  • defaultTemperature:默认温度 (1.0)。温度值必须介于 0.02.0 之间。
  • maxTemperature:最高温度。
await LanguageModel.params();
// {defaultTopK: 3, maxTopK: 8, defaultTemperature: 1, maxTemperature: 2}

创建会话

Prompt API 可以运行后,您可以使用 create() 函数创建会话。您可以使用 prompt()promptStreaming() 函数提示模型。

自定义会话

您可以使用可选的 options 对象,通过 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" 角色响应消息,而不是请求新的响应。这有助于引导语言模型使用特定的回答格式。为此,请将 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,
  },
]);
在不提示的情况下附加消息

推理可能需要一些时间,尤其是在使用多模态输入进行提示时。 预先发送预定的提示来填充会话可能很有用,这样模型就可以提前开始处理。

虽然 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);

克隆会话

如需保留资源,您可以使用 clone() 函数克隆现有会话。对话上下文会重置,但初始提示会保持不变。clone() 函数接受一个包含 signal 字段的可选 options 对象,该字段可让您传递 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 版开始,Prompt 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 音频提示演示;如需了解如何将 Prompt API 与图片输入搭配使用,请参阅 Canvas 图片提示演示。

效果策略

适用于 Web 的 Prompt API 仍在开发中。在构建此 API 期间,请参阅我们有关会话管理的最佳实践,以获得最佳性能。

反馈

您的反馈有助于我们了解此 API 的未来发展方向以及 Gemini Nano 的改进方向。我们甚至可能会推出专门的任务 API(例如用于音频转写或图片描述的 API),以便满足您和用户的需求。

参与并分享反馈

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