用 Vercel AI SDK 玩轉 Chrome Built-in AI

#chrome #ai #webdev #vercel

Google 官方關於 Chrome Built-in AI 與 Vercel AI SDK 的文件寫了一大堆，但看完會發現官方範例只教你怎麼印出 Hello World，好多坑都沒有交代。

如果模型還沒下載完該怎麼辦？瀏覽器不支援時怎麼辦？Tool Calling 的介面要怎麼安全的接上？附上在 Chrome上的一些踩坑小筆記，幫你想在前端加上本地 LLM 時少走彎路（雖然彎路的都記得比較久ＸＤ）！

官方範例

Google 官方有兩篇基礎教學，繁體中文版都寫得清楚：

看完你大概可以了解，可以用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，目前在「瀏覽器本地推理」這個領域已經是最主要的Tool。

作者是 jakobhoeg/browser-ai的 Jakob Hoeg Mørk，2025 年開始維護，進過 Chrome for Developers 的贊助名單，現在掛在 Vercel OSS Program 底下。

import { generateText } from "ai";
import { browserAI } from "@browser-ai/core";

const result = await 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）也在ＵＩ上做了下拉選單可以即時切換，讓使用者可以同一份 streamText 程式碼，本地模型、WebGPU 模型、雲端模型切換成整合或是測試。

有兩個實作細節滿值得整合前端應用的參考的：

自訂 ChatTransport 接 useChat
用 ClientSideChatTransport 把 React 的 useChat 綁到本地模型來讓整個聊天流程跑在客戶端，連 server 都不用起，萬一有一天你不想用本地模型了，換回 DefaultChatTransport 就切到 server API，前端程式碼一行不用改。
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 的優勢！

DEV Community