我如何构建了一个在本地和云端 AI 之间切换的 Chrome 扩展

Source: Dev.to

Chrome 静悄悄地发布了一项巨大的功能：内置 AI 完全在设备上运行（Gemini Nano）。它直接嵌入浏览器，无需额外安装，也不进行网络请求。

我想看看在真实产品中能把它推到什么程度，于是我构建了 DocuMentor AI，这是一款 Chrome 扩展，帮助开发者从技术内容中学习：智能摘要、“我该阅读吗？”提示以及精选学习资源。

在生产环境中，这个扩展同时运行在 两种 环境下：

• Chrome 的 本地 Gemini Nano（以隐私为先，绑定设备）
• 云端 AI 后端（更快、更强大）

它会自动选择合适的路径。本文是 混合架构如何工作 的简要版。

问题：两种截然不同的 AI

大多数云端大模型只提供一个通用的聊天接口，要求你通过提示工程和工具来解决所有问题。

Chrome 的内置 AI 则不同。它提供 专用 API：

// Chrome AI APIs
Summarizer   // 用于 TL;DR 和要点提取
Writer       // 用于生成内容
LanguageModel // 用于通用提示和聊天

如果你把所有这些都隐藏在一个 generate() 函数后面，无论是本地还是云端都会感觉不对劲。
所以我没有按“模型”抽象，而是按 功能 抽象。

第一步：围绕功能设计接口

在扩展内部，有一个小接口描述系统能做 什么，而不是任何提供者是 如何 工作的：

• summarize(text, options)
• executePrompt(messages, options)
• write(content, options)
• isAvailable() / initialize()

提供者

• GeminiNanoProvider 包装了 Chrome 的 Summarizer、LanguageModel 和 Writer API。
• DocumentorAIProvider 与后端通信，后端使用单一云端大模型并通过提示工程模拟相同的能力。

提供者的选择非常简单：

• 已登录用户 → 云端提供者（速度快 + 推理更强）
• 未登录用户 → 本地提供者（隐私 + 离线化）

不会在会话中途切换。认证状态决定提供者，使扩展逻辑保持可预测。

第二步：本地与云端 AI 的不同策略

当两个提供者都实现了相同接口后，出现了新的问题：能力和可靠性。

云模型可以在 一次 调用中完成多步骤工作流并使用工具。
Chrome 本地的 Gemini Nano 在 CPU 机器上往往无法可靠完成，表现为：

• 难以在多步骤中保持上下文
• 工具调用不稳定
• 结构化 JSON 输出不一致

于是我采用了 两套编排策略。

本地 AI：顺序、由应用驱动的编排

以 YouTube 视频推荐为例，纯 Chrome 路径的流程如下：

1. 让 Gemini Nano 生成一个 搜索查询。
2. 在代码中 直接调用 YouTube API。
3. 再让 Gemini Nano 对结果进行排序和改写。
4. 防御性地解析并修复 JSON，必要时重试。

模型只负责 小而专注的推理任务，其余全部由扩展编排。

云端 AI：一次工具增强调用

对于云端提供者，同一功能可以写成一次带工具调用的提示：

“分析此页面，调用 search_youtube，评分相关性，并以 JSON 返回前 3 条视频。”

云模型充当 规划者 + 执行者。扩展只需要调用一次并渲染结果。

相同的用户体验，两种内部策略

• 本地 = 顺序分解
• 云端 = 单次工具增强调用

第三步：尊重设备端限制

在浏览器内部运行 AI 必须考虑云端通常隐藏的约束：

• 令牌配额：使用 measureInputUsage() 和 inputQuota 在提示前检查输入是否符合配额。若超出则截断，而不是盲目尝试。
• 内容提取：使用类似 Mozilla Readability 的库去除噪声（导航、广告、页脚），并限制内容大小（约 15 K 字符效果良好）后再发送给 AI。
• 顺序而非并行：多个 Chrome AI 调用并行往往 更慢 且更脆弱。

UX 收获：先快速返回 TL;DR，再让更重的结果流式返回。

第四步：用户无需感知的回退机制

扩展使用了一个简单、静默的回退链：

1. 尝试 云端 AI（快速路径）。
2. 若出现任何错误或配额耗尽，回退到 本地 AI。
3. 只有在两者都失败时才显示错误。

界面从不显示 “正在切换提供者”。用户感受到的只是：

• 大多数情况下 → 快速响应（云端）。
• 有时会稍慢，但仍能工作（本地）。

给你自己的 Chrome AI 项目的几点建议

• 围绕功能而非模型设计。
• 让 云模型 处理复杂、工具密集的工作流，一次调用完成。
• 让 扩展 在本地 AI 上编排并保持提示简短。
• 将设备端约束（令牌、内容大小、并行度）视为 一等设计输入。
• 构建回退机制，让用户得到 性能降级 而不是 硬错误。

这就是我如何构建一个在本地和云端 AI 之间悄然切换、且对用户透明的 Chrome 扩展的要点。