← Browser AI From First Principles

一个运行时,多个接口

构建并运行一个七接口的 Browser AI 交换台:共享生命周期插桩,同时保留每个 API 的标识、选项、操作与输出契约。

第一个 Browser AI Observatory 只认识一个全局对象:LanguageModel。

这足以暴露通用生命周期。我们可以检视可用性、创建会话、监视模型获取、流式输出、取消请求并记录发生了什么。

Chrome 还暴露更窄的内置 AI 能力。应用不必让一个通用语言模型会话去执行任意任务,它可以创建一个摘要器、写作器、改写器、校对器、翻译器或语言检测器。

起初这看起来像便利语法:

await session.prompt("Summarize this text: ...");

变成:

await summarizer.summarize(text);

如果变化仅止于此,我们可以保留一章 Prompt API,把其余当作包装器。

但任务专用 API 在架构上做了一件重要的事:它把部分任务契约从提示词散文移进了软件结构。

通用提示

任务 + 选项 + 输入编码为语言
                    ↓
             LanguageModel

任务 API

任务由接口选择
选项由字段选择
输入作为数据提供
            ↓
        Summarizer

这改变了浏览器知道什么、开发者能验证什么,以及我们的调试器该显示什么。

本章把当前全部七个表面加入 Browser AI Observatory,而不假装它们是同一回事。


1. 共同的形状

内置 AI API 共享一个可辨认的生命周期:

功能检测
      ↓
availability(options)
      ↓
create(options + monitor)
      ↓
任务操作(input)
      ↓
结果或流

这个共同的形状配得上一个共享适配器。

它让观测站把能力检视、下载进度、计时、取消、轨迹标识与导出只实现一次。如果每个面板标签页都重新实现这些机制,调试器里的差异就会被误认为 API 之间的差异。

但共享的生命周期止于任务含义之前。

API 创建的对象 主要操作 输出形状
Prompt 语言模型会话 prompt() 文本
Summarizer 摘要器 summarize() 文本
Writer 写作器 write() 文本
Rewriter 改写器 rewrite() 文本
Proofreader 校对器 proofread() 更正后的文本加更正项
Language Detector 检测器 detect() 带排序的语言候选项
Translator 翻译器 translate() 译文

前四个可以流式生成文本。翻译也可以流式。校对与语言检测返回结构化结果,而不是假装每个有用的答案都是散文。

适配器应当在保留含义的同时规范化机制。


2. Prompt API 留给我们的东西

一个通用提示几乎可以表达任何文本任务:

const result = await session.prompt(`
Summarize the following passage as three Markdown bullet points.
Preserve the distinction between browser responsibility and application responsibility.

${text}
`);

浏览器看到的是一串指令与数据。应用必须确保:

  • 输入与指令被安全地分开;
  • 所请求的格式被理解;
  • 条数被遵守;
  • 重要含义被保留;
  • 不引入无关文本;
  • 结果可以被安全地解析或渲染。

其中一些义务依然留在任务 API 一侧。摘要仍可能遗漏或歪曲信息。生成的 Markdown 仍需要安全渲染。更窄的接口不会把概率性行为变成确定性函数。

不过它确实让重要的意图变得显式:

const summarizer = await Summarizer.create({
  type: "key-points",
  format: "markdown",
  length: "short",
  preference: "auto",
  expectedInputLanguages: ["en"],
  expectedContextLanguages: ["en"],
  outputLanguage: "en"
});

任务、输出形式、大致长度、执行偏好与语言契约都是字段。它们可以在执行前被检视,也可以在不解析提示字符串的情况下被记录。

这是任务 API 的第一个优势:

任务 API 把部分行为意图变成类型化配置。


3. 窄接口造就有用的约束

Writer API 提供语气、格式、长度与共享上下文。Rewriter API 提供相关但不同的值,因为改写从既有文本出发。Translator API 要求源语言与目标语言。Language Detector 返回一个排序,而不是一个孤立的确定性主张。

这些区分告诉我们平台认为该操作是什么。

它们还阻止无意义的组合变成惯用法。翻译器不需要 temperature 控制。校对器不应被提示去发明一个新的冠词。摘要器可以直接描述摘要类型,而不必让每个应用都一致地措辞。

窄换来三个属性:

  1. 可发现性 —— 受支持的选项是接口的一部分。
  2. 可检视性 —— 调试器可以显示语义配置,而无需解读散文。
  3. 可替换性 —— 浏览器可以选择适配所声明任务的实现。

代价是自由度降低。如果应用需要任务契约之外的不寻常操作,Prompt API 仍是那个逃生门。


4. 不要假设只有一个物理模型

本章标题说的是一个运行时,不是一组权重。

Chrome 把内置 AI 描述为浏览器管理的基础模型与专家模型。某些能力可能共享一个基础模型。翻译与语言检测可以使用任务专用模型。实现可以随浏览器演进而改变。

我们的应用可以安全地依赖所暴露的能力契约。

它不能安全地推断所有 API 全局对象:

  • 下载同一份资源;
  • 有相同的硬件要求;
  • 支持相同的语言;
  • 共享同一个上下文窗口;
  • 有相同的延迟;
  • 在更新后一同改变。

因此观测站在每个事件上记录 apiId。一个名为 session.create.finished 的通用事件,只有在我们仍能分辨创建了哪种能力时才有用。

{
  "type": "session.create.finished",
  "data": {
    "apiId": "summarizer",
    "durationMs": 842.4
  }
}

共享插桩应当消除意外的差异,而不是有意义的差异。


5. 构建能力注册表

可运行的扩展现在把 API 专属的事实放进一个注册表:

const DEFINITIONS = {
  prompt: {
    globalName: "LanguageModel",
    method: "prompt",
    streamingMethod: "promptStreaming",
    defaultOptions: {
      samplingMode: "most-predictable",
      expectedInputs: [{ type: "text", languages: ["en"] }],
      expectedOutputs: [{ type: "text", languages: ["en"] }]
    }
  },
  summarizer: {
    globalName: "Summarizer",
    method: "summarize",
    streamingMethod: "summarizeStreaming",
    defaultOptions: {
      type: "key-points",
      format: "markdown",
      length: "medium",
      preference: "auto",
      expectedInputLanguages: ["en"],
      expectedContextLanguages: ["en"],
      outputLanguage: "en"
    }
  }
};

完整实现把 Writer、Rewriter、Proofreader、Language Detector 与 Translator 的定义放进 core/adapters.js。

注册表是数据,而不是七个类的继承体系。这些 API 主要按全局名、创建选项与操作名区分。在这里引入继承只会增加代码,不会揭示更多架构。

适配器执行共同的机制:

export function createAPIAdapter(apiId, environment = globalThis) {
  const definition = getAPIDefinition(apiId);

  return {
    ...definition,
    id: apiId,

    exposed() {
      return Boolean(environment[definition.globalName]);
    },

    async availability(options = definition.defaultOptions) {
      const api = environment[definition.globalName];
      if (!api) return "unavailable";
      return api.availability(options);
    },

    async create(options, onProgress) {
      const api = environment[definition.globalName];
      return api.create({
        ...options,
        monitor(monitor) {
          monitor.addEventListener("downloadprogress", onProgress);
        }
      });
    }
  };
}

传入 environment 使边界可测试。生产使用 globalThis。测试提供假 API 并验证生命周期行为,而声称自己并不仿真模型。


6. 运行七接口交换台

从第 05 章选择 Run with Browser AI 以打开:

/tools/ai/browser-ai-from-first-principles/05-chapter/

新交换台提出七个分开的能力问题:

接口 全局对象 契约重点
Prompt LanguageModel 采样、预期输入与预期输出
Summarizer Summarizer 类型、格式、长度与语言期望
Writer Writer 语气、格式、长度与语言期望
Rewriter Rewriter 与既有文本的关系加输出约束
Proofreader Proofreader 面向更正的结构化结果
Translator Translator 显式的源语言与目标语言
Language Detector LanguageDetector 带排序的语言假设

点击 Inspect all interfaces。对每一行,该体验先检查具名全局对象是否暴露。如果暴露,页面就用最后一列显示的确切选项对象调用该接口的 availability(options) 方法。

该矩阵刻意把 Exposed 与 Availability 分开。一个全局对象可以存在,而所请求的语言或任务配置不可用。反过来,此页面上缺失的接口会被报告为未暴露,而不是被折叠成一个含糊的浏览器级"AI 已禁用"状态。

每次检视也会进入共享的 Observatory 轨迹:

capability.inspect.started  { apiId: "summarizer" }
capability.inspect.finished {
  apiId: "summarizer",
  globalName: "Summarizer",
  exposed: true,
  availability: "available"
}

这产生了一种有用的证据形式,而无需创建七个会话或触发七次获取。交换台是一件预检仪器。模型准备仍留在其后一个显式的用户动作之后,由读者选择运行的任务触发。

接口定义位于本章的 experiment.json。它们与扩展使用的注册表一致,包括在 Prompt API 采样需要与投机解码构建兼容、实验室配置档已注册之处的 samplingMode: "most-predictable"。把选项放进可检视的数据,意味着矩阵可以展示它问了什么,而不是把可用性当作脱离上下文的真相呈现。

回放模式保持同一条规则。那份已评审的 9 月 2 日轨迹包含一个 Prompt API 能力结果。交换台填上那一行,把其余六个接口标注为 unobserved。它不会把"该轨迹中不存在"转换成"不可用"。

这个交换台成为接下来三章的可复用底座。第 06 章可以选择 Summarizer,第 07 章可以比较 Writer、Rewriter 与 Proofreader,第 08 章可以把 Language Detector 与 Translator 配对。共享生命周期保持稳定,而实验契约在变。


7. 保留输出形状

文本操作适合同一条流式路径:

const stream = instance[streamingMethod](input, operationOptions);
let output = "";

for await (const chunk of stream) {
  output += chunk;
  onChunk(chunk);
}

结构化操作需要一个决定。UI 需要可显示的文本,而评估可能需要原始结构。

第一个实现把非字符串结果序列化为带格式的 JSON:

function formatResult(value) {
  return typeof value === "string"
    ? value
    : JSON.stringify(value, null, 2);
}

对一个实验控制台来说这是可接受的,因为它保留字段并使导出直接。之后的类型化结果层应当把原始值与渲染表示并排保留。否则调试器可能不小心把一个数值型置信度变成字符串,让下游分析更难。

重要的规则是:

规范化不得抹掉评估该任务所需的证据。


8. 一个面板,不同的实验

面板现在包含:

  • 一个 API 选择器;
  • 可编辑的创建选项;
  • 上下文与输入字段;
  • 能力检视;
  • 会话创建与下载进度;
  • 运行与停止控件;
  • 流式或结构化输出;
  • fixture 评估;
  • 统一的事件轨迹;
  • JSON 导出。

更换所选 API 会销毁当前适配器引用并要求新会话。这反映了平台契约:创建期参数不是附着在一个通用对象上的可变偏好。

function selectAPI(apiId) {
  const adapter = runtime.select(apiId);
  options.value = JSON.stringify(adapter.defaultOptions, null, 2);
  availability.textContent = "Unknown";
  sessionState.textContent = "None";
  run.disabled = true;
}

开发者选择 Rewriter 之后,面板不会悄悄复用一个 Writer。可见状态阻止了一种出人意料的常见实验错误:以为改了某个选项,程序实际仍在使用更早配置的旧实例。


9. fixture 让比较成为可能

一个空白文本框邀请探索。它不产生可比的证据。

观测站为每个任务族包含一个 fixture。fixture 冻结:

API 标识
创建选项
上下文
输入
自动断言
人工评审细则

例如,摘要 fixture 要求至少三个要点,且同时包含 “browser” 与 “application”。人工检查会问输出是否避免声称本地执行天然更私密或更快。

{
  id: "summarizer-browser-runtime",
  apiId: "summarizer",
  options: {
    type: "key-points",
    format: "markdown",
    length: "short"
  },
  assertions: [
    { kind: "min-bullets", value: 3 },
    { kind: "contains", value: "browser" },
    { kind: "contains", value: "application" },
    {
      kind: "custom",
      rubric: "No claim that local execution is automatically private or faster."
    }
  ]
}

结构化断言刻意保持克制。词面出现不证明含义被保留。人工细则不会被悄悄转换成一个假的数值检查。

这给每次运行三个独立的结果:

结果 问题
运行时 API 操作完成了吗?
自动 fixture 输出满足机器可检查的约束吗?
人工评审 它保留了预期的含义与质量吗?

一个绿色结果永远不应代替全部三个。


10. 比较契约,而不只是散文

我们现在可以运行一次受控比较:

路线 A:Prompt API

在提示中编码任务、格式、长度与源文本。

路线 B:Summarizer API

在 Summarizer.create() 中编码任务选项,把源文本传给 summarize()。

记录:

  • 暴露与可用性;
  • 冷与热的创建时间;
  • 下载事件;
  • 首个分片时间;
  • 总时长;
  • 输出尺寸;
  • 结构化检查;
  • 人工细则;
  • 配置复杂度;
  • 失败模式。

问题不是"哪一段读起来单次更好"。

而是:

哪份契约能产出一个在重复用例中更易指定、观察、验证与维护的功能?

通用提示可能在专门任务上取胜。任务 API 可能在可预测的语义与配置上取胜。应当允许实验来告诉我们。


11. 确定性测试证明了什么

扩展包含使用假浏览器 API 的 Node 测试。

它们验证:

  • 全部七个能力定义都已注册;
  • 缺失的全局对象变为操作性不可用;
  • 进度事件穿过适配器;
  • 流式分片按序拼接;
  • 结构化校对结果保持可检视;
  • 运行时事件按生命周期顺序出现;
  • metrics-only 模式不保留提示或响应内容;
  • content 模式只在显式选中时保留文本;
  • fixture 指向已知 API;
  • 自动检查不会把人工细则默默标为通过。

它们不验证摘要质量、语言覆盖,或 Chrome 的真实模型行为。

这个分工是有意的:

Node 测试
  → 我们确定性的插桩与评估机制

Chrome fixture 运行
  → 浏览器可用性、性能与模型行为

测试一个假模型只会给我们一套绿色测试,以及关于本书所研究系统的一份零证据。


结论

内置 AI API 共享一个生命周期,但它们不共享同一种含义。

通用适配器可以规范化暴露、可用性、创建、下载监视、流式、取消与轨迹事件。注册表仍必须保留 API 标识、创建选项、操作名与输出形状。

任务 API 之所以重要,是因为它们把部分意图移出提示词散文、移进可检视的软件契约。这能让功能更易配置与调试。它不会让模型变成确定性的,也不会让输出自动正确。

Browser AI Observatory 现在可以通过一个面板运行完整的第二部分实验组。第 05 章体验把同一个注册表暴露为一张实时能力矩阵,读者可以看到他们的浏览器实际提供哪些接口,并检视每个结果背后的选项。接下来三章使用这个底座,而不是发明孤立的例子。

我们从摘要开始,因为它几乎一次暴露了所有张力:抽取与生成、结构与含义、速度与能力,以及一个看起来极好、却恰好漏掉读者所需那一项事实的结果。


参考与延伸阅读

  1. Chrome for Developers, Built-in AI.
  2. Chrome for Developers, The Prompt API.
  3. Chrome for Developers, Summarize with built-in AI.
  4. Chrome for Developers, Writer API.
  5. Chrome for Developers, Rewriter API.
  6. Chrome for Developers, Proofreader API.
  7. Chrome for Developers, Translation with built-in AI.
  8. Chrome for Developers, Language detection with built-in AI.