Firebase AI 端侧语言模型会话创建配置：LanguageModelCreateOptions 完全指南-平芜编程栈

开发工具
后端

【免费下载链接】firebase-js-sdk

Firebase Javascript SDK

项目地址：https://gitcode.com/gh_mirrors/fi/firebase-js-sdk

LanguageModelCreateOptions是 Firebase JavaScript SDK（@firebase/ai）中用于配置端侧（on-device）语言模型会话创建的核心接口，它定义了 Firebase AI 在调用 Chrome 内置 Prompt API 时应携带的模型创建参数。本文将以该接口为骨架，结合其继承关系、底层源码实现与真实测试用例，为你完整梳理initialPrompts、signal及继承自LanguageModelCreateCoreOptions的expectedInputs、expectedOutputs、monitor等全部配置项的含义、默认行为与最佳实践，帮助你准确配置 Firebase AI 的混合推理（Hybrid Inference）能力。

接口定义与继承关系

根据 API 参考文档，LanguageModelCreateOptions的类型签名如下：

export interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions

它继承自 LanguageModelCreateCoreOptions，并在其基础上追加了两个端侧会话创建专有的可选属性：initialPrompts与signal。在仓库源码 packages/ai/src/types/language-model.ts 中，接口定义与文档完全一致：

/** * Configures the creation of an on-device language model session. * @public */ export interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions { signal?: AbortSignal; initialPrompts?: LanguageModelMessage[]; }

该接口属于@firebase/ai包的公开 API（@public），并从 packages/ai/src/types/index.ts 统一导出，供上层GenerativeModel与ChromeAdapter使用。

属性一览

属性	类型	可选性	说明
`initialPrompts`	LanguageModelMessage[]	可选	创建会话时预置的初始消息序列
`signal`	`AbortSignal`	可选	用于取消会话创建（可能涉及模型下载）的信号
`expectedInputs`（继承）	LanguageModelExpected[]	可选	期望的输入类型与语言，默认图片输入 + 英文文本输入
`expectedOutputs`（继承）	LanguageModelExpected[]	可选	期望的输出类型与语言，默认英文文本输出
`monitor`（继承）	`(monitor: LanguageModelDownloadMonitor) => void`	可选	原生下载监视器，用于高级下载进度场景

initialPrompts：为端侧会话预置上下文

initialPrompts用于在创建端侧语言模型会话时，预先注入一段初始对话上下文，其类型为LanguageModelMessage[]。

LanguageModelMessage 结构

在 packages/ai/src/types/language-model.ts 中，消息结构定义如下：

export interface LanguageModelMessage { role: LanguageModelMessageRole; // 'system' | 'user' | 'assistant' content: LanguageModelMessageContent[]; } export interface LanguageModelMessageContent { type: LanguageModelMessageType; // 'text' | 'image' | 'audio' value: LanguageModelMessageContentValue; // ImageBitmapSource | AudioBuffer | BufferSource | string }

也就是说，每条消息由role（角色）和content（内容数组）组成：

role：取值'system'、'user'或'assistant'，对应系统指令、用户输入与模型回复三种角色；
content：每条内容对象包含type（'text'、'image'或'audio'）与value（文本字符串、ImageBitmapSource图片位图、AudioBuffer音频或BufferSource二进制缓冲区）。

一个典型的用法是预置system角色消息来设定模型行为，例如：

const createOptions = { initialPrompts: [ { role: 'system', content: [{ type: 'text', value: 'You are a helpful assistant.' }] } ] };

源码中的角色映射

值得注意的一个实现细节：在 Firebase AI 内部，LanguageModelMessage.role与 Firebase AI 自己的Role类型之间存在转换逻辑。查看 packages/ai/src/methods/chrome-adapter.ts：

private static toLanguageModelMessageRole( role: Role ): LanguageModelMessageRole { // Assumes 'function' rule has been filtered by isOnDeviceRequest return role === 'model' ? 'assistant' : 'user'; }

从源码结构看，当 Firebase AI 的Role为'model'时会被转换为'assistant'，其余情况（如'user'）保持不变；'system'角色则主要出现在通过initialPrompts等创建配置预置的上下文中。

signal：取消会话创建

signal?: AbortSignal允许你通过标准的 WebAbortSignal机制取消端侧模型会话的创建过程。由于创建会话可能触发模型下载（详见下文），这一参数对于需要“用户离开页面即取消下载/创建”的场景非常实用：

const controller = new AbortController(); const createOptions = { signal: controller.signal }; // 需要取消时： controller.abort();

从源码实现看，Firebase AI 的请求层对AbortSignal有成熟的处理机制。在 packages/ai/src/requests/request.ts 中，SDK 会将用户传入的外部信号与内部超时信号合并：

// Used to abort the fetch if either the user-defined `externalSignal` is aborted, or if the // internal signal (triggered by timeouts) is aborted. const combinedSignal = AbortSignal.any( externalSignal ? [externalSignal, internalAbortController.signal] : [internalAbortController.signal] );

对应的单元测试 packages/ai/src/requests/request.test.ts 验证了请求信号确实是AbortSignal实例，这印证了 SDK 对取消机制的完整支持。

继承属性：expectedInputs / expectedOutputs / monitor

LanguageModelCreateOptions从LanguageModelCreateCoreOptions继承的三个属性同样在会话创建时生效，它们在文档 ai.languagemodelcreatecoreoptions.md 中有完整说明。

expectedInputs 与 expectedOutputs

expectedInputs：期望的输入类型与语言。不设置时，默认值为图片输入 + 英文文本输入；
expectedOutputs：期望的输出类型与语言。不设置时，默认值为英文文本输出。

两者的元素类型均为 LanguageModelExpected，包含type（必填，LanguageModelMessageType，即'text'|'image'|'audio'）和可选的languages（字符串数组，如['en']、['zh']）。

默认值填充的源码证据

Chrome 适配器会在构造阶段自动为缺失的expectedInputs/expectedOutputs填充默认值。查看 packages/ai/src/methods/chrome-adapter.ts：

onDeviceParams: OnDeviceParams = { createOptions: { expectedInputs: defaultExpectedInputs, expectedOutputs: defaultExpectedOutputs } }; constructor( public languageModelProvider: LanguageModel, public mode: InferenceMode, onDeviceParams?: OnDeviceParams ) { if (onDeviceParams) { this.onDeviceParams = onDeviceParams; if (!this.onDeviceParams.createOptions) { this.onDeviceParams.createOptions = { expectedInputs: defaultExpectedInputs, expectedOutputs: defaultExpectedOutputs }; } else { if (!this.onDeviceParams.createOptions.expectedInputs) { this.onDeviceParams.createOptions.expectedInputs = defaultExpectedInputs; } if (!this.onDeviceParams.createOptions.expectedOutputs) { this.onDeviceParams.createOptions.expectedOutputs = defaultExpectedOutputs; } } } }

也就是说，即使你没有显式提供createOptions，SDK 也会以默认值调用 Chrome 的availability()与create()。测试用例 packages/ai/src/methods/chrome-adapter-browser.test.ts 专门验证了“即使设置了其他 onDeviceParams 参数，也会填充默认 expectedInputs/expectedOutputs”这一行为。

monitor：原生下载监视器

monitor?: (monitor: LanguageModelDownloadMonitor) => void是 Chrome Prompt API 提供的原生下载监视器入口，仅在高级场景下需要。其接收的 LanguageModelDownloadMonitor 对象暴露addEventListener与removeEventListener两个方法，事件类型为'downloadprogress'，回调参数为{ loaded: number }：

export interface LanguageModelDownloadMonitor { addEventListener: ( eventType: 'downloadprogress', eventListener: (e: { loaded: number }) => void ) => void; removeEventListener: ( eventType: 'downloadprogress', eventListener: (e: { loaded: number }) => void ) => void; }

注意优先级：在 ai.generativemodel.md 的initializeDeviceModel()说明中明确指出，如果LanguageModelCreateOptions中已填充monitor，则传入initializeDeviceModel(onDownloadProgress)的简单回调将被忽略。从源码看，这一优先级逻辑实现在download()方法中——仅当options.monitor为空且传入了onDownloadProgress时，SDK 才会用回调包装monitor：

// packages/ai/src/methods/chrome-adapter.ts#L293-L310 private download(onDownloadProgress?: (progressValue: number) => void): void { if (this.downloadPromise) { return; } const options = { ...this.onDeviceParams.createOptions }; if (options && !options.monitor && onDownloadProgress) { options.monitor = m => { m.addEventListener('downloadprogress', e => { onDownloadProgress(e.loaded); }); }; } this.downloadPromise = this.languageModelProvider ?.create(options) .finally(() => { this.downloadPromise = null; }); }

端侧会话创建在混合推理中的位置

LanguageModelCreateOptions并非孤立存在，它通过OnDeviceParams接入 Firebase AI 的混合推理体系。在 packages/ai/src/types/requests.ts 中定义：

export interface OnDeviceParams { createOptions?: LanguageModelCreateOptions; promptOptions?: LanguageModelPromptOptions; } export interface HybridParams { mode: InferenceMode; // 默认 prefer_on_device onDeviceParams?: OnDeviceParams; inCloudParams?: ModelParams; }

调用链如下：

开发者通过HybridParams.onDeviceParams.createOptions传入LanguageModelCreateOptions；
packages/ai/src/api.ts 中chromeAdapterFactory()读取hybridParams.onDeviceParams，在检测到全局存在LanguageModel（Chrome Prompt API）时创建ChromeAdapterImpl；
ChromeAdapterImpl.createSession()调用 Chrome 原生languageModelProvider.create(this.onDeviceParams.createOptions)创建会话（见 packages/ai/src/methods/chrome-adapter.ts）。

关于InferenceMode的取值，见 packages/ai/src/types/enums.ts：'prefer_on_device'、'only_on_device'、'only_in_cloud'、'prefer_in_cloud'。

与 initializeDeviceModel 的配合

LanguageModelCreateOptions中涉及的下载行为与GenerativeModel.initializeDeviceModel()紧密相关。在 packages/ai/src/models/generative-model.ts 中：

该方法会触发downloadIfAvailable()并在必要时下载模型；
若mode为'only_in_cloud'则直接返回（不做端侧处理）；
若模型不可用（Availability.UNAVAILABLE）且模式为'only_on_device'，会抛出AIErrorCode.API_NOT_ENABLED错误；其他模式下仅记录调试日志；
文档特别强调：initializeDeviceModel()必须在用户与页面交互之后（如按钮点击、按键）调用，否则在需要下载时会报错。

配置示例与最佳实践

基础配置：仅指定期望输入输出

import { getGenerativeModel, InferenceMode } from '@firebase/ai'; const model = getGenerativeModel(ai, { model: 'gemini-1.5-flash', mode: InferenceMode.PREFER_ON_DEVICE, onDeviceParams: { createOptions: { expectedInputs: [{ type: 'text', languages: ['en'] }], expectedOutputs: [{ type: 'text', languages: ['zh'] }] } } });

高级配置：预置系统上下文 + 取消信号

const controller = new AbortController(); const model = getGenerativeModel(ai, { model: 'gemini-1.5-flash', mode: InferenceMode.PREFER_ON_DEVICE, onDeviceParams: { createOptions: { signal: controller.signal, initialPrompts: [ { role: 'system', content: [{ type: 'text', value: '回答用户问题时始终使用简体中文。' }] } ], expectedInputs: [{ type: 'text', languages: ['en', 'zh'] }], expectedOutputs: [{ type: 'text', languages: ['zh'] }] } } }); // 首次使用前初始化（必须在用户交互之后调用） await model.initializeDeviceModel(progress => { console.log(`模型下载进度：${Math.round(progress * 100)}%`); }); // 需要取消会话创建时 controller.abort();

实践要点总结

要点	说明
默认能力	不设置`expectedInputs`/`expectedOutputs`时，SDK 自动补全“图片输入 + 英文文本输入 / 英文文本输出”
进度监控二选一	`monitor`与`onDownloadProgress`同时存在时，`monitor`优先，简单回调被忽略
取消时机	`signal`可中止下载/创建流程，适用于离开页面、切换任务的场景
交互前置条件	需要下载模型时，`initializeDeviceModel()`必须在用户手势之后调用
角色取值	`initialPrompts`中的`role`可取`'system'`、`'user'`、`'assistant'`；Firebase AI 的`model`角色在内部被映射为`'assistant'`

进一步阅读

基类接口：LanguageModelCreateCoreOptions
消息结构：LanguageModelMessage
期望输入输出：LanguageModelExpected
下载监视器：LanguageModelDownloadMonitor
初始化入口：GenerativeModel.initializeDeviceModel()
源码实现：packages/ai/src/types/language-model.ts、packages/ai/src/methods/chrome-adapter.ts、packages/ai/src/models/generative-model.ts
测试验证：packages/ai/src/methods/chrome-adapter-browser.test.ts