Chrome 本地 AI 接入 Vercel AI SDK：官方没写的三个坑，实测帮你踩平

Google 官方关于 Chrome Built-in AI 与 Vercel AI SDK 的文档写了一堆，但看完会发现，官方范例只教你印出 Hello World，很多坑都没有交代。模型还没下载完怎么办？浏览器不支持时怎么办？Tool Calling 的接口要怎么安全接上？这里附上在 Chrome 上的一些踩坑小笔记，帮你在前端加上本地 LLM 时少走弯路。

官方范例只讲 API 长什么样

Google 官方有两篇基础教学，繁体中文版都写得清楚：Prompt API 搭配 Vercel AI SDK、使用 AI Elements 打造 UI（含 demo）。看完大概可以了解，可以用 browserAI() 把 model 丢进 generateText、streamText、Output.object，大概 30 行就能跑。但官方范例大多着重在“API 长什么样”，实际工程里会撞上的问题，反而没怎么提。

@browser-ai/core 是当前主要工具

@browser-ai/core 是 Chrome Built-in AI 接到 AI SDK 的 provider，特点是同时支持 AI SDK v5-7，且跨三个本地引擎（Prompt API、Transformers.js、WebLLM）共用同一套 API，目前在“浏览器本地推理”这个领域已经是最主要的工具。作者是 jakobhoeg/browser-ai 的 Jakob Hoeg Mørk，2025 年开始维护，进过 Chrome for Developers 的赞助名单，现在挂在 Vercel OSS Program 底下。

基本用法很直接：

• 从 ai 导入 generateText
• 从 @browser-ai/core 导入 browserAI
• 调用 generateText，model 传 browserAI()，prompt 写“Invent a new holiday.”

当“模型还没下载”的状况发生时，availability() 会回 unavailable（浏览器不支持）或 downloadable（可以下载）。配合 createSessionWithProgress 就能拿到下载百分比，这对前端无论开发什么样的应用，都是给使用者第一层的 UX。大部分首次下载要吞好几 GB 的等待时间，没有进度反馈，用户只会以为页面卡死。

next-hybrid 比官方范例完整太多

在 jakobhoeg/browser-ai 同一个 repo 底下的 examples/next-hybrid 也满值得一看。它比官方范例完整太多，而且目前都是完整的可 demo 范例，建议可以直接当 template 复制。它也像之前测试 transformer/webgpu 一样，同时接了三種引擎（browser / transformers-js / web-llm），并在 UI 上做了下拉菜单可以即时切换，让使用者可以用同一份 streamText 代码，在本地模型、WebGPU 模型、云端模型之间切换整合或测试。

有两个实作细节满值得整合前端应用时参考：

1. 自订 ChatTransport 接 useChat：用 ClientSideChatTransport 把 React 的 useChat 绑到本地模型，让整个聊天流程跑在客户端，连 server 都不用起。万一有一天你不想用本地模型了，换回 DefaultChatTransport 就切到 server API，前端代码一行不用改。
2. tool calling 的完整流程：它示范了 webSearch（用 Exa API）和 getCurrentTime 两个 tool，加上 toolApproval 的确认 UI。如果模型想动用外部 API 前，会先跳出一个确认框让使用者同意确认。这对安全敏感的医疗或金融企业场景，可以配合记录一些符合法规面需求的 Audit Log。

domainstack.io 是最接近生产的案例

jakejarvis/domainstack.io 是目前找得到最接近 production 的案例，而且是少数用 @browser-ai/core 的第三方专案。它做的是网域名称查询工具，虽然串接 AI 只是其中一小部分功能，但架构完整到可以拿来当作范本。

跟前面提到的场域类似，核心设计是三种模式自动切换：local（本机）、cloud（云端）、auto（本机不可用就 fallback）。useBrowserAI hook 会先查 availability()，如果浏览器不支持就默默切到云端 API，对使用者完全无感。另外它示范了让本地模型呼叫 tRPC 的 tool（WHOIS、DNS、SSL 查询），也证明本地 LLM 做 agentic workflow 是可行的，不是只能聊天。

实测踩坑：三个官方没写清楚的地方

第一，API 只能在安全环境（Secure Context）运行。如果你在 about:blank 测试，window.LanguageModel 会直接回传 undefined。改到 http://localhost 或 HTTPS 环境下，API 才会正常。

第二，模型下载必须由“真实使用者互动”触发。直接在代码初始化呼叫 LanguageModel.create() 会直接报错：NotAllowedError: Requires a user gesture。这代表不能在页面载入时自动背景下载，必须由使用者点击按钮等主动触发。因此，如果你用 Headless 测试，必须透过 CDP（Chrome DevTools Protocol）发送 Input.dispatchMouseEvent 来模拟真实的鼠标点击事件，才可以正常执行。

第三，硬件有硬性门槛。在 chrome://on-device-internals 的 Broker State 系统纪录中，明确标示需要 20480 MiB required。测试时我的 MBA 原本只剩 4.7GB，模型下载停住，直到清出 23GB 空间后，下载状态才顺利转绿开始执行。

总结与建议路线

Chrome Built-in AI 的核心优势不在于顶尖的算力或模型表现，而在于零 API Key 成本、零代管费用，以及资料绝对不出装置的隐私安全。再搭配 Vercel AI SDK 后，本地模型与云端 LLM 的切换只需要一行 Provider 设定就可以搞定。

如果你正准备试试，建议路线如下：

• 快速验证：用 browserAI() + generateText，30 行内快速跑通。
• 完整架构学习：直接 Fork next-hybrid 当专案骨架。
• 生产环境：参考 domainstack.io 的自动 Fallback 策略与 Tool Calling 设计。

目前整个浏览器本地 AI 生态还处于早期阶段，大部分开发者都还在摸索。趁现在掌握这些工具与解决方案，就能为你的前端专案抢先整合本地 AI 的优势。