⚡

Chrome本地AI提示API开发指南Skill web-ai-prompt-api

Chrome本地AI提示API开发指南，详细介绍如何在浏览器中利用Gemini Nano模型实现AI功能，包括会话管理、多模态输入处理、结构化JSON输出、流式响应和Chrome扩展集成。该技能专注于前端AI应用开发，提供完整的本地化AI解决方案，无需依赖云端服务，保障数据隐私和安全。关键词：Chrome AI API，Gemini Nano，本地AI，浏览器AI，多模态输入，结构化输出，会话管理，前端AI开发，隐私保护AI

前端开发 0 次安装 2 次浏览 更新于 3/1/2026

名称: web-ai-prompt-api 描述: Chrome内置Prompt API实现指南。在浏览器本地使用Gemini Nano实现AI功能 - 会话管理、多模态输入、结构化输出、流式传输、Chrome扩展。所有Prompt API开发的参考文档。

Chrome Prompt API 参考文档

使用Gemini Nano实现Chrome内置Prompt API的完整实施指南。

硬件与操作系统要求

操作系统: Windows 10/11, macOS 13+ (Ventura及以上), Linux, ChromeOS (平台版本16389.0.0+) 在Chromebook Plus上 存储空间: 22 GB可用空间（模型单独下载） GPU: >4 GB显存 或 CPU: 16 GB内存 + 4核心 网络: 无限流量连接用于下载 Chrome版本: 138+（扩展功能在稳定版中，Web功能在原始试用中）

不支持: 移动设备（Android, iOS），非Chromebook Plus的ChromeOS

检查模型大小: chrome://on-device-internals 如果下载后存储空间<10 GB，模型将被移除。

语言支持

从Chrome 140开始: 英语、西班牙语、日语（输入/输出）

可用性检查

const availability = await LanguageModel.availability();
// 返回: "unavailable" | "downloadable" | "downloading" | "available"

关键: 始终将相同的选项传递给availability()和create()。某些模型不支持特定的模态/语言。

模型参数

await LanguageModel.params();
// { defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2 }

会话创建

基础会话

const session = await LanguageModel.create();

使用自定义参数

const params = await LanguageModel.params();
const session = await LanguageModel.create({
  temperature: Math.min(params.defaultTemperature * 1.2, 2.0),
  topK: params.defaultTopK
});

使用下载监控

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

使用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: '你是一个乐于助人的助手。' },
    { role: 'user', content: '意大利的首都是什么？' },
    { role: 'assistant', content: '意大利的首都是罗马。' },
    { role: 'user', content: '那里说什么语言？' },
    { role: 'assistant', content: '官方语言是意大利语。' }
  ]
});

使用场景:

  • 浏览器重启后恢复存储的会话
  • N-shot提示
  • 设置助手个性/语气
  • 提供对话历史

多模态输入（原始试用）

expectedInputs & expectedOutputs

const session = await LanguageModel.create({
  expectedInputs: [
    {
      type: "text",  // 或 "image", "audio"
      languages: ["en" /* 系统 */, "ja" /* 用户提示 */]
    }
  ],
  expectedOutputs: [
    { type: "text", languages: ["ja"] }
  ]
});

输入类型: 文本、图像、音频 输出类型: 仅文本

如果模态不支持，抛出NotSupportedError。

使用图像/音频

const session = await LanguageModel.create({
  initialPrompts: [{
    role: 'system',
    content: '分析图像中的模式。'
  }],
  expectedInputs: [{ type: 'image' }]
});

// 附加图像
await session.append([{
  role: 'user',
  content: [
    { type: 'text', value: '分析这张图像' },
    { type: 'image', value: fileInput.files[0] }
  ]
}]);

提示方法

非流式（短响应）

const result = await session.prompt('给我写一首俳句！');
console.log(result);

流式（长响应）

const stream = session.promptStreaming('给我写一首长诗！');
for await (const chunk of stream) {
  console.log(chunk);  // 部分结果实时到达
}

使用AbortSignal

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

const result = await session.prompt('写一首诗', {
  signal: controller.signal
});

响应约束（结构化输出）

传递JSON Schema以获得可预测的JSON响应：

const schema = {
  type: "object",
  properties: {
    hashtags: {
      type: "array",
      maxItems: 3,
      items: {
        type: "string",
        pattern: "^#[^\\s#]+$"
      }
    }
  },
  required: ["hashtags"],
  additionalProperties: false
};

const result = await session.prompt(
  `为以下内容生成标签: ${post}`,
  { responseConstraint: schema }
);

const data = JSON.parse(result);  // 保证有效的JSON

简单布尔值示例:

const schema = { "type": "boolean" };
const result = await session.prompt(
  `这是关于陶器的吗？

${text}`,
  { responseConstraint: schema }
);
console.log(JSON.parse(result));  // true 或 false

测量输入配额使用情况:

const usage = session.measureInputUsage({ responseConstraint: schema });

从输入配额中省略schema:

const result = await session.prompt(
  `以JSON { rating } 格式总结，使用0-5数字:`,
  {
    responseConstraint: schema,
    omitResponseConstraintInput: true
  }
);

响应前缀

通过预填充助手响应来指导模型输出格式：

const result = await session.prompt([
  { role: 'user', content: '创建一个TOML角色表' },
  { role: 'assistant', content: '```toml
', prefix: true }
]);
// 模型从"```toml
"继续

append() 方法

向会话添加消息而不立即响应（对多模态有用）：

await session.append([
  {
    role: 'user',
    content: [
      { type: 'text', value: '第一个上下文消息' },
      { type: 'image', value: imageFile }
    ]
  }
]);

// 稍后，使用累积的上下文进行提示
const result = await session.prompt('分析这些图像');

Promise在验证和附加完成后履行。

会话管理

检查配额

console.log(`${session.inputUsage}/${session.inputQuota}`);
const remaining = session.inputQuota - session.inputUsage;

当配额超出时，最旧的消息将从上下文中丢失。

克隆会话

克隆继承参数、初始提示和历史记录：

const mainSession = await LanguageModel.create({
  initialPrompts: [{ role: 'system', content: '像海盗一样说话' }]
});

const clone1 = await mainSession.clone();
const clone2 = await mainSession.clone({ signal: controller.signal });

// 具有相同设置的独立对话
await clone1.prompt('给我讲一个关于鹦鹉的笑话');
await clone2.prompt('给我讲一个关于宝藏的笑话');

用于: 并行对话、"假设"场景、资源效率

从localStorage恢复会话

let sessionData = getFromLocalStorage(uuid) || {
  initialPrompts: [],
  topK: (await LanguageModel.params()).defaultTopK,
  temperature: (await LanguageModel.params()).defaultTemperature
};

const session = await LanguageModel.create(sessionData);

// 跟踪对话
const stream = session.promptStreaming(prompt);
let result = '';
for await (const chunk of stream) {
  result = chunk;
}

sessionData.initialPrompts.push(
  { role: 'user', content: prompt },
  { role: 'assistant', content: result }
);

localStorage.setItem(uuid, JSON.stringify(sessionData));

销毁会话

session.destroy();
// 释放资源，中止正在进行的执行
// 销毁后会话不可用

最佳实践: 保持一个空会话活动以保持模型加载。仅在真正完成时销毁。

用户激活要求

模型下载需要用户交互：

if (navigator.userActivation.isActive) {
  const session = await LanguageModel.create();
}

粘性激活事件: 点击、轻触、按键按下、鼠标按下

权限策略与iframe

默认: 仅顶级窗口 + 同源iframe

授予跨源iframe访问权限:

<iframe src="https://cross-origin.example.com/"
        allow="language-model">
</iframe>

Web Workers中不可用（权限策略复杂性）

本地开发（localhost）

  1. 前往 chrome://flags/#prompt-api-for-gemini-nano-multimodal-input
  2. 选择 已启用
  3. 重新启动Chrome
  4. 打开开发者工具，输入: await LanguageModel.availability();
  5. 应返回 "available"

故障排除:

  • 重启Chrome
  • 检查 chrome://on-device-internals → 模型状态标签页
  • 等待模型下载完成

Chrome扩展

在Chrome 138+稳定版中可用于扩展。

移除过期的原始试用权限:

{
  "permissions": ["aiLanguageModelOriginTrial"]  // 移除此行
}

如果需要，注册当前原始试用。

最佳实践

会话管理:

  • 克隆会话以保留初始提示
  • 使用AbortController让用户停止响应
  • 跟踪inputUsage以在配额超出前警告
  • 销毁未使用的会话以释放内存
  • 保持一个空会话活动以保持模型就绪

性能:

  • 对长响应使用流式传输
  • 为多模态提前append()消息
  • 监控下载进度，通知用户
  • 在创建会话前检查可用性

结构化输出:

  • 使用JSON Schema获得可预测的响应
  • LLM擅长从描述生成schema
  • 使用JSON Schema验证器验证
  • 使用前缀进行格式指导

上下文保留:

  • 将会话存储在localStorage中以供恢复
  • 使用initialPrompts设置会话上下文
  • 克隆以实现具有相同上下文的并行对话

错误处理

try {
  const session = await LanguageModel.create();
  const result = await session.prompt('你好');
} catch (err) {
  if (err.name === 'AbortError') {
    // 用户停止生成
  } else if (err.name === 'NotSupportedError') {
    // 不支持的模态/语言
  } else {
    console.error(err.name, err.message);
  }
}

关键限制

  • 仅限桌面（无移动设备）
  • 需要22 GB存储空间
  • 下载需要无限流量网络
  • 不支持Web Workers
  • 输出仅为文本（输入可以是多模态）
  • 上下文窗口有令牌限制
  • 如果下载后存储空间<10 GB，模型将被移除

使用场景

  • 基于AI的页面内容搜索
  • 内容分类/过滤
  • 从页面提取事件
  • 联系信息提取
  • 具有对话记忆的聊天机器人
  • 离线AI功能
  • 隐私敏感数据处理
  • 内容摘要
  • 翻译辅助
  • 图像/音频分析（多模态）