内置到底意味着什么?
把 Chrome 的内置 AI API 变成一台可观测的状态机:直接在本章内检视能力暴露、可用性、模型获取、会话就绪、执行与失败。
built-in(内置)这个词暗示着恒常。
内置函数在程序启动时就存在。内置的浏览器功能被认为无需安装器、账号或部署即可工作。如果一个 Web 开发者听说 AI 被内置进了浏览器,显而易见的心智模型就是一个等待被调用的全局函数。
const answer = await browserAI.prompt("Explain this page");
那并不是我们实际拥有的系统。
API 可能缺失。设备可能不具备资格。所请求的语言或模态可能不受支持。模型可能需要下载。下载可能需要用户动作。字节可能在抽取与加载完成之前就到达。会话可能被创建、随后耗尽其上下文。同一条接口在浏览器更新之后可能由一个已变更的实现支撑。
因此"内置"描述的是管理,而不是瞬时就绪。
浏览器管理这项能力。应用仍然必须为其状态建模。
本章把这种状态变成一份显式契约。本章结束时,我们将拥有一个小的适配器:后续每个实验都能使用它,Browser AI Observatory 中的每个事件都能理解它。
1. 一个运行时,几种 API
Chrome 的内置 AI 工作包括一个通用 Prompt API 和一组任务 API。
这个区分是架构性的。
通用能力
Prompt API 暴露一个语言模型会话。应用提供指令与输入,接收生成的输出,并拥有任务定义。
应用定义任务
↓
通用语言模型会话
↓
生成的响应
这很灵活。同一机制可以分类、抽取、解释、转换或起草。灵活性也意味着应用必须设计提示词、约束输出、评估行为并处理变化。
任务能力
任务 API 暴露更窄的操作,例如摘要、写作、改写、校对、翻译与语言检测。
应用选择任务与选项
↓
任务专用的浏览器 API
↓
任务形状的结果
浏览器拥有更多语义信息。它知道应用想要的是摘要而不是任意的补全。它可以暴露贴合该任务的选项,并可能使用专门的模型或适配器。
两类能力没有哪一类普遍更好。
| 需求 | 可用时优先任务 API | 优先 Prompt API |
|---|---|---|
| 标准摘要或翻译 | 是 | 有时 |
| 带自定义指令的新颖任务 | 否 | 是 |
| 窄而可预测的选项 | 是 | 否 |
| 最大行为灵活性 | 否 | 是 |
| 减少提示词设计 | 是 | 否 |
| 为许多实验共用一个抽象 | 否 | 是 |
我们从 Prompt API 开始,因为它最清楚地暴露通用生命周期。之后我们会把专用 API 与等价的提示词做比较,而不是先验地假定某条路线更优。
2. 能力检测有两个层次
“这个浏览器支持 Prompt API 吗?“这句话里藏着两个不同的问题。
第一个是结构性的:
const exposed = "LanguageModel" in globalThis;
它问的是:当前 JavaScript 上下文是否暴露了该接口。
第二个是运行性的:
const options = {
expectedInputs: [{ type: "text", languages: ["en"] }],
expectedOutputs: [{ type: "text", languages: ["en"] }],
};
const availability = await LanguageModel.availability(options);
它问的是:浏览器能否创建一个与特定请求兼容的会话。
这两种检查不可互换。
API 可以存在而所请求的能力不可用。浏览器可以支持英文文本提示而拒绝另一种语言或模态。在没有使用预期选项的情况下执行的测试,可能报告一个并不适用于应用随后创建的会话的状态。
因此 Chrome 的指引很重要:把相应的能力选项传给 availability() 和 create()。可用性检查是针对特定会话形状的预检(preflight),不是贴在浏览器上的一枚全局徽章。
我们可以用一个共享常量来编码这一点:
export const ENGLISH_TEXT_SESSION = Object.freeze({
expectedInputs: [{ type: "text", languages: ["en"] }],
expectedOutputs: [{ type: "text", languages: ["en"] }],
});
每次调用都使用同一个对象:
const state = await LanguageModel.availability(ENGLISH_TEXT_SESSION);
const session = await LanguageModel.create({
...ENGLISH_TEXT_SESSION,
monitor(monitor) {
monitor.addEventListener("downloadprogress", onProgress);
},
});
这看起来像是一个小的代码质量选择。它其实是一条正确性约束。如果预检与创建的选项各自漂移,接口可能承诺一种能力、却尝试另一种。
3. 可用性是一台状态机
在写作之时,通用的内置 AI 生命周期使用四个可用性值:
| 状态 | 对应用的含义 | 恰当的响应 |
|---|---|---|
unavailable |
所请求的能力在该环境中无法创建 | 解释、禁用,或提供显式回退 |
downloadable |
浏览器在下载所需资源后可以支持它 | 请用户开始;显示预期的状态转换 |
downloading |
某个必需的下载已在进行中 | 显示进度或等待状态 |
available |
无需再次下载模型即可创建兼容会话 | 启用创建或提示流程 |
注意这些值没有说什么。
available 不表示会话已经存在。downloadable 不表示应用应当悄悄开始一次大下载。downloading 也不必然表示当进度事件到达其最终数值时功能就已就绪;模型可能仍需准备与加载。
unavailable 并不指向一个单一的普遍原因。不支持的硬件、存储不足、不受支持的选项、浏览器配置或灰度状态,都可能收敛到同一个应用可见的结果。
我们应当保留原始状态,并从它派生 UI 状态:
function availabilityView(state) {
switch (state) {
case "available":
return { level: "ready", action: "Create session" };
case "downloadable":
return { level: "setup", action: "Download and enable" };
case "downloading":
return { level: "waiting", action: null };
case "unavailable":
return { level: "blocked", action: null };
default:
return { level: "error", action: null };
}
}
不要把这些值直接转成布尔值。布尔值恰好抹掉了接口所需的生命周期信息。
4. 在本章中运行这台状态机
只有当我们能把状态表与浏览器的实际路径作比较时,它才变得有用。
本章的 Run with Browser AI 动作会打开一个章节专属体验:
/tools/ai/browser-ai-from-first-principles/02-chapter/
该页面使用与第 01 章相同的共享 Browser AI 运行时,但第 02 章提供了一份不同的实验契约。它要求运行时暴露一个生命周期视图,并声明检视与创建时都必须使用的会话选项。
{
"view": "capability-lifecycle",
"options": {
"samplingMode": "most-predictable",
"expectedInputs": [{ "type": "text", "languages": ["en"] }],
"expectedOutputs": [{ "type": "text", "languages": ["en"] }]
}
}
确定性采样模式是刻意的。它与使用投机解码和 Multi-Token Prediction 的浏览器构建兼容。更重要的是,完全相同的选项会到达 LanguageModel.availability() 和 LanguageModel.create()。该接口不会预检一个会话、却尝试创建另一个。
截至 2026 年 9 月 6 日的出版快照,samplingMode 并不是每个普通网页的默认假设。在本书中,它是实验室轨迹所用的已注册实验配置档的一部分。托管在扩展中的实验还可能遇到 topK、temperature 和 LanguageModel.params() 等遗留兼容表面。这条不变式比任何一个选项名都简单:检视与创建必须使用同一份已声明的配置档,且该配置档必须随证据一起被记录。
该体验从 not-inspected 开始。点击 Inspect this browser 执行结构性与运行性检查。随后它只标记该浏览器返回的状态:
not-inspected
├── unsupported
└── unavailable | downloadable | downloading | available
↓
session-ready
↓
running
┌──────┴──────┐
completed failed
这不是一个装饰性的进度指示器。没有任何规则说每次运行都必须经过每个状态。报告 available 的浏览器可以直接进入会话创建。没有暴露 LanguageModel 的浏览器停在 unsupported。一个下载进度事件会把 downloading 加进观测到的路径。这条状态带是关于发生了什么的证据,而不是应用希望发生之事的动画。
本章的 bundle 包含三种不同形态的知识:
02-chapter/context.md 章节专属概念
02-chapter/experiment.json 可执行的选项与提示词
02-chapter/recorded-trace.json 来自早先一次运行的已评审证据
上下文只在用户运行提示词时才提供。它不会被夹带进能力检测。实验配置定义行为。轨迹则保有其原始来源,仍是证据。
如果实时执行不可用,Replay captured trace 会从那次已评审的 Chrome 运行的事件中重建生命周期。回放可能显示 available、下载进度事件与 session-ready,因为那些是浏览器实际发出的事件。它绝不应仅仅为了让画面看起来整齐而补上 downloadable。录制模式全程带有标注,以免另一台机器的证据被误认为当前浏览器的状态。
这改变了本章的角色。散文定义契约;实时页面让读者检视它的一个实现;导出的轨迹使观察可携带。现在我们可以通过运行系统来质疑一张图。
5. 下载是产品的一部分
当能力处于 downloadable 时,第一次 create() 调用会触发模型获取。Chrome 执行准入检查、下载所需模型资源、准备它们,并使它们为共享该模型的内置 AI API 可用。
这有几个后果。
下载属于一个用户可见的动作
网页不应让用户疑惑为什么一个浏览器进程突然占用带宽与磁盘。当需要用户激活动作时,应用也无法可靠地从任意后台回调发起该过程。
一个有用的交互是显式的:
本地 AI 受支持但尚未安装。
下载浏览器管理的模型以启用此功能。
浏览器控制存储与日后的更新。
[启用本地 AI]
确切的文案取决于产品,但这个动作应当传达"正在进行设置”。
进度不只是装饰
创建 API 接受一个 monitor 回调。monitor 发出 downloadprogress 事件,其 loaded 值向 1 移动。
const session = await LanguageModel.create({
...ENGLISH_TEXT_SESSION,
monitor(monitor) {
monitor.addEventListener("downloadprogress", (event) => {
renderProgress(Math.round(event.loaded * 100));
});
},
});
我们会记录这些事件,而不只是画一条进度条。事件序列让我们得以测量:
- 从用户动作到首个进度的时间;
- 下载时长;
- 从最后进度到会话创建 resolve 的时间;
- 失败与停滞;
- 冷创建与热创建之间的差异。
应用不拥有持久性
浏览器管理的模型可以被更新或清除。Chrome 的管理规则包括设备准入资格与可用存储。应用不应把周一的一次成功会话当作模型周五仍将就绪的证明。
能力检查属于使用点,只有在平台契约认为安全之处才做合理的缓存。
6. 会话是有状态的资源
创建之后,Prompt API 返回一个会话。会话可以接受一个完整提示词,或产生一个流。
const response = await session.prompt("Explain event delegation.");
或者:
const stream = session.promptStreaming(
"Explain event delegation with one minimal example."
);
for await (const chunk of stream) {
appendOutput(chunk);
}
第二种形式对交互式软件很重要。它减少感知等待时间,并暴露首个输出时间、流式节奏与中断行为。
会话还拥有对话上下文。后续提示词会受到先前轮次的影响,直到上下文容量耗尽。这使会话不止是一个函数引用。
它是一个拥有以下属性的资源:
- 标识;
- 创建选项;
- 创建时间;
- 累积的上下文;
- 活动请求;
- 取消行为;
- 终结性的销毁或失败。
观测站会分配它自己的会话标识,因为平台对象不是持久的轨迹键:
function createSessionRecord(apiSession, options) {
return {
id: crypto.randomUUID(),
apiSession,
options,
createdAt: performance.timeOrigin + performance.now(),
prompts: 0,
status: "ready",
};
}
我们把运行时对象与可序列化记录分开。不能假定 apiSession 能挺过扩展消息传递或存储。记录可以。
7. 流式传输改变了我们能测量什么
一次非流式调用产生两个显而易见的时间戳:
请求开始 ───────────────── 响应完成
一次流式调用暴露了更有用的结构:
请求开始
↓
首个分片
↓
分片节奏
↓
最后分片
↓
流完成
从这些事件我们可以推导:
这个区分防止一个精致的仪表盘报告虚构的精度。
8. 取消是正确性的一部分
生成可能很慢,用户可能改变主意,页面可能跳转离开。完整与流式两种提示操作都可以接受一个 abort 信号。
const controller = new AbortController();
stopButton.addEventListener("click", () => controller.abort());
try {
const stream = session.promptStreaming(prompt, {
signal: controller.signal,
});
for await (const chunk of stream) {
appendOutput(chunk);
}
} catch (error) {
if (error.name === "AbortError") {
showStatus("Stopped");
} else {
throw error;
}
}
中止与模型失败不是一回事。观测站事件必须保留这个区分:
{
"type": "prompt.finished",
"outcome": "aborted",
"error": null
}
如果取消被折叠进一个笼统的错误计数,仪表盘会把一个响应式的用户控件渲染成一次可靠性回归。
9. 生命周期只建模一次
我们现在有足够的行为了,可以定义一个可复用的适配器。
export class BrowserLanguageModel {
constructor(options, emit = () => {}) {
this.options = options;
this.emit = emit;
this.session = null;
this.sessionId = null;
}
async inspect() {
if (!("LanguageModel" in globalThis)) {
return { exposed: false, availability: "unavailable" };
}
const availability = await LanguageModel.availability(this.options);
return { exposed: true, availability };
}
async create() {
const startedAt = performance.now();
this.emit({ type: "session.create.started", startedAt });
this.session = await LanguageModel.create({
...this.options,
monitor: (monitor) => {
monitor.addEventListener("downloadprogress", (event) => {
this.emit({
type: "model.download.progress",
loaded: event.loaded,
at: performance.now(),
});
});
},
});
this.sessionId = crypto.randomUUID();
this.emit({
type: "session.create.finished",
sessionId: this.sessionId,
durationMs: performance.now() - startedAt,
});
return this.session;
}
async *stream(prompt, signal) {
if (!this.session) {
throw new Error("Create a session before prompting.");
}
const traceId = crypto.randomUUID();
const startedAt = performance.now();
let firstChunkAt = null;
let outputChars = 0;
this.emit({
type: "prompt.started",
traceId,
sessionId: this.sessionId,
inputChars: [...prompt].length,
startedAt,
});
try {
const response = this.session.promptStreaming(prompt, { signal });
for await (const chunk of response) {
const at = performance.now();
firstChunkAt ??= at;
outputChars += [...chunk].length;
this.emit({ type: "prompt.chunk", traceId, at, chars: [...chunk].length });
yield chunk;
}
this.emit({
type: "prompt.finished",
traceId,
outcome: "completed",
totalMs: performance.now() - startedAt,
timeToFirstChunkMs:
firstChunkAt === null ? null : firstChunkAt - startedAt,
outputChars,
});
} catch (error) {
this.emit({
type: "prompt.finished",
traceId,
outcome: error.name === "AbortError" ? "aborted" : "failed",
totalMs: performance.now() - startedAt,
errorName: error.name,
});
throw error;
}
}
}
这还不是一个生产级包装器。对当前阶段而言,它做了一件更重要的事:让我们的假设变得可见。
它把能力检视与会话创建分开,使用同一份选项契约,并把下载进度当作事件。它指派会话与轨迹标识,区分完成、中止与失败,并在不假装它们是 token 的情况下记录尺寸。它流式输出,默认不在事件中保留提示词内容。
这足以成为第一个扩展的核心。
10. 失败必须先分类,再处理
浏览器 AI 功能可能在若干层失败:
| 层 | 例子 | 响应 |
|---|---|---|
| 暴露 | LanguageModel 缺失 |
解释浏览器要求或选择回退 |
| 能力 | 所请求的语言不可用 | 更改选项或禁用该路线 |
| 获取 | 下载无法开始或完成 | 显示可操作的设置状态 |
| 会话 | 创建失败 | 记录环境与错误;在安全处允许重试 |
| 请求 | 提示被拒绝或上下文耗尽 | 修订输入、轮换会话,或压缩上下文 |
| 用户控制 | 请求被中止 | 干净地停止;不要上报为系统失败 |
| 行为 | 流畅但错误的输出 | 评估并拒绝;API 成功不是任务成功 |
最后一行最重要。
一个 resolve 的 promise 证明推理完成了。它不证明结果是正确、有用、安全,或与功能契约兼容的。
操作可观测性与行为评估必须相遇,但不应被混为一谈。
结论
“内置"不是一个二元属性。它是一段部分由浏览器控制、通过应用被体验的生命周期。
应用必须区分接口暴露、能力可用性、模型获取、会话就绪、进行中的生成、取消、操作性失败与行为性失败。把这些状态压平成 supported: true,会造出一个脆弱的功能和一个帮不上忙的调试器。
第 02 章现在让这个区分变得可执行。实时体验只显示在当前浏览器中观测到的路径;回放模式只显示被录制事件保留下来的路径。二者喂给同一套事件词汇表,因此概念模型、读者界面与 Observatory 可以一同演进。
我们现在拥有了开篇组其余部分所需的契约:
检视能力
↓
解释或发起获取
↓
创建并标识会话
↓
带取消的提示
↓
流式传输与测量
↓
分类结果
下一章把这份契约放进 Chrome DevTools。我们将构建最小的 Browser AI Observatory:一个带自有面板、能力探针、下载显示、流式提示运行器与事件轨迹的 Manifest V3 扩展。
参考与延伸阅读
- Chrome for Developers, Get started with built-in AI.
- Chrome for Developers, The Prompt API.
- Chrome for Developers, Inform users of model download.
- Chrome for Developers, Understand built-in model management in Chrome.
- Chrome for Developers, Built-in AI.