← Browser AI From First Principles

内置到底意味着什么?

把 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. 流式传输改变了我们能测量什么

一次非流式调用产生两个显而易见的时间戳:

请求开始 ───────────────── 响应完成

一次流式调用暴露了更有用的结构:

请求开始
      ↓
首个分片
      ↓
分片节奏
      ↓
最后分片
      ↓
流完成

从这些事件我们可以推导:

$$ T_{first} = t_{first\ chunk} - t_{request} $$
以及:
$$ T_{generation} = t_{complete} - t_{first\ chunk} $$
如果 token 计数可得或被一致地估算,我们可以近似吞吐:
$$ R = \frac{N_{output}}{T_{generation}} $$
这个估计必须被诚实地标注。JavaScript 字符串长度不是 token 数。用错模型的 tokenizer 也不精确。对于第一个观测站版本,我们将存储字节、Unicode 码点与耗时,之后只在具名估算器背后加入 token 估计。

这个区分防止一个精致的仪表盘报告虚构的精度。


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 扩展。


参考与延伸阅读

  1. Chrome for Developers, Get started with built-in AI.
  2. Chrome for Developers, The Prompt API.
  3. Chrome for Developers, Inform users of model download.
  4. Chrome for Developers, Understand built-in model management in Chrome.
  5. Chrome for Developers, Built-in AI.