一个运行时,多个接口
构建并运行一个七接口的 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 控制。校对器不应被提示去发明一个新的冠词。摘要器可以直接描述摘要类型,而不必让每个应用都一致地措辞。
窄换来三个属性:
- 可发现性 —— 受支持的选项是接口的一部分。
- 可检视性 —— 调试器可以显示语义配置,而无需解读散文。
- 可替换性 —— 浏览器可以选择适配所声明任务的实现。
代价是自由度降低。如果应用需要任务契约之外的不寻常操作,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 章体验把同一个注册表暴露为一张实时能力矩阵,读者可以看到他们的浏览器实际提供哪些接口,并检视每个结果背后的选项。接下来三章使用这个底座,而不是发明孤立的例子。
我们从摘要开始,因为它几乎一次暴露了所有张力:抽取与生成、结构与含义、速度与能力,以及一个看起来极好、却恰好漏掉读者所需那一项事实的结果。
参考与延伸阅读
- Chrome for Developers, Built-in AI.
- Chrome for Developers, The Prompt API.
- Chrome for Developers, Summarize with built-in AI.
- Chrome for Developers, Writer API.
- Chrome for Developers, Rewriter API.
- Chrome for Developers, Proofreader API.
- Chrome for Developers, Translation with built-in AI.
- Chrome for Developers, Language detection with built-in AI.