Firebase JavaScript SDK 的 AIModel 抽象基类:模型资源名规范、后端绑定与子类体系全解析
Firebase JavaScript SDK 的 AIModel 抽象基类:模型资源名规范、后端绑定与子类体系全解析
导读
AIModel 是 Firebase JavaScript SDK 中 AI 服务(@firebase/ai)的模型 API 抽象基类,它为 GenerativeModel、LiveGenerativeModel 等具体模型类提供了统一的“模型资源名(model resource name)”规范能力与后端绑定机制。本文基于 SDK 的 API 参考文档 ai.aimodel.md,并结合 packages/ai/src/models/ai-model.ts 源码与测试用例,深入讲解 AIModel 的类签名、model 属性、模型名归一化规则、后端差异以及各子类如何复用这套基础设施。读完本文,你将能准确理解 Firebase AI 中“模型名”在不同后端(Gemini Developer API 与 Agent Platform Gemini API)下的解析规则,并掌握 getGenerativeModel 等工厂方法的底层调用链。
AIModel 类概览:Firebase AI 模型 API 的公共基类
根据官方 API 参考文档,AIModel 被定义为:
Base class for Firebase AI model APIs.
其类签名如下:
export declare abstract class AIModel
AIModel 是一个抽象类(abstract class),这意味着它不能直接被实例化,只能被继承。它的核心职责可以概括为两点:
- 绑定后端:每个
AIModel实例都与一个特定的 Firebase AI Backend(即Backend抽象类,见 packages/ai/src/backend.ts)相关联,该后端决定了 SDK 最终与哪套生成式模型服务通信。 - 提供模型交互入口:子类通过继承
AIModel获得统一的模型资源名与 API 设置(ApiSettings)基础设施,并在此基础上对外提供generateContent、connect等具体推理方法。
文档特别强调:该类的构造函数被标记为 internal,第三方代码不应直接调用构造函数,也不应创建继承 AIModel 的类。这一点在源码中体现为受保护的构造函数:
// packages/ai/src/models/ai-model.ts 第 59 行
protected constructor(ai: AI, modelName: string) { ... }
使用 protected 修饰符后,外部代码无法 new AIModel(...),只有子类(如 GenerativeModel、LiveGenerativeModel)能在内部通过 super(ai, modelName) 调用它。
model 属性:全限定模型资源名
AIModel 只公开一个属性:
readonly model: string;
文档给出的解释是:
The fully qualified model resource name (for example,
publishers/google/models/gemini-3.6-flash).
也就是说,model 保存的是全限定的模型资源名(fully qualified model resource name)。它并不是用户传入的原始字符串,而是经过构造函数内部归一化(normalize)之后的结果。以文档中的示例 publishers/google/models/gemini-3.6-flash 为例,其结构为 publishers/{publisher}/models/{model-name},这种格式可以直接用于构造面向 Agent Platform(Vertex AI)的 REST API 路径。
由于属性声明为 readonly,它在实例化之后不可再被修改,这保证了模型资源名在整个实例生命周期内的不可变性,避免推理请求中途更换模型导致状态不一致。
构造函数内部逻辑:配置校验与模型名归一化
虽然构造函数对外不可直接调用,但理解它的内部逻辑是掌握 AIModel 的关键。源码实现如下:
// packages/ai/src/models/ai-model.ts 第 59-65 行
protected constructor(ai: AI, modelName: string) {
this._apiSettings = initApiSettings(ai);
this.model = AIModel.normalizeModelName(
modelName,
this._apiSettings.backend.backendType
);
}
构造函数只做两件事:
- 初始化 API 设置:调用
initApiSettings(ai),从传入的AI实例中提取apiKey、projectId、appId、后端配置、App Check 令牌获取函数与 Auth 令牌获取函数,组装成内部的ApiSettings对象。 - 归一化模型名:调用静态方法
normalizeModelName(modelName, backendType),根据当前后端的类型把用户传入的模型名转换成全限定格式,并赋值给只读的model属性。
initApiSettings 的配置校验
initApiSettings 定义在 packages/ai/src/models/utils.ts。它首先对 Firebase 配置做严格的字段校验,缺少任一字段都会抛出 AIError:
| 缺失字段 | 错误码(packages/ai/src/types/error.ts) | 说明 |
|---|---|---|
apiKey |
AIErrorCode.NO_API_KEY('no-api-key') |
“Firebase AI requires this field to contain a valid API key.” |
projectId |
AIErrorCode.NO_PROJECT_ID('no-project-id') |
缺少有效项目 ID |
appId |
AIErrorCode.NO_APP_ID('no-app-id') |
缺少有效应用 ID |
因此,文档中“构造函数会因 Firebase 配置缺少 apiKey 或 projectId 而抛出异常”的描述,其具体实现就是对上述三个字段的逐一校验。该校验逻辑意味着:任何继承 AIModel 的模型类在创建时,都会强制要求宿主 Firebase 应用配置了完整的 API Key、Project ID 与 App ID。
此外,initApiSettings 还处理了认证相关的可选注入:当使用的是 Firebase Server App 且配置了 appCheckToken 时,会直接用它作为 App Check 令牌来源;否则在存在 App Check 实例时使用 getToken()(若设置了 useLimitedUseAppCheckTokens 则改用 getLimitedUseToken());存在 Auth 实例时注入 getAuthToken()。
normalizeModelName:按后端类型差异化归一化
归一化逻辑(packages/ai/src/models/ai-model.ts 第 75-112 行)会根据 backendType 分派到两条不同的路径:
static normalizeModelName(modelName: string, backendType: BackendType): string {
if (backendType === BackendType.GOOGLE_AI) {
return AIModel.normalizeGoogleAIModelName(modelName);
} else {
return AIModel.normalizeVertexAIModelName(modelName);
}
}
其中 BackendType 定义在 packages/ai/src/public-types.ts,取值仅有两种字符串字面量:'AGENT_PLATFORM' 与 'GOOGLE_AI'。
**Google AI 后端(Gemini Developer API)**的归一化非常简单:
// 第 89-91 行
private static normalizeGoogleAIModelName(modelName: string): string {
return `models/${modelName}`;
}
即统一加上 models/ 前缀,最终形态形如 models/gemini-3.6-flash。
**Agent Platform 后端(Agent Platform Gemini API,即原 Vertex AI Gemini API)**的归一化则要复杂得多,因为它需要支持普通模型、models/ 前缀模型与自定义模型(如微调模型)三种形态:
// 第 96-112 行
private static normalizeVertexAIModelName(modelName: string): string {
let model: string;
if (modelName.includes('/')) {
if (modelName.startsWith('models/')) {
// Add 'publishers/google' if the user is only passing in 'models/model-name'.
model = `publishers/google/${modelName}`;
} else {
// Any other custom format (e.g. tuned models) must be passed in correctly.
model = modelName;
}
} else {
// If path is not included, assume it's a non-tuned model.
model = `publishers/google/models/${modelName}`;
}
return model;
}
上述规则可用一张表完整概括:
| 用户传入的模型名 | 归一化结果(Agent Platform 后端) | 说明 |
|---|---|---|
my-model |
publishers/google/models/my-model |
短名,自动补全前缀 |
models/my-model |
publishers/google/models/my-model |
半限定名,自动补全 publisher |
publishers/google/models/my-model |
publishers/google/models/my-model |
已是全限定名,原样保留 |
tunedModels/my-model(或其他含 / 的自定义路径) |
tunedModels/my-model(原样保留) |
自定义/微调模型,要求用户传入完整正确路径 |
构造函数 JSDoc 中对 modelName 三种合法格式的描述(my-model、models/my-model、publishers/my-publisher/models/my-model)正是对这套规则的用户侧抽象。
测试用例验证
packages/ai/src/models/ai-model.test.ts 用一个继承 AIModel 的 TestModel 类系统验证了上述所有分支:
new TestModel(fakeAI, 'my-model')→publishers/google/models/my-modelnew TestModel(fakeAI, 'models/my-model')→publishers/google/models/my-modelnew TestModel(fakeAI, 'publishers/google/models/my-model')→ 保持不变new TestModel(fakeAI, 'tunedModels/my-model')→ 保持不变(自定义微调模型路径原样传递)
这些断言与源码逻辑一一对应,可作为理解模型名解析行为的最直接证据。
后端(Backend)如何参与模型资源名解析
AIModel 之所以能感知“当前使用哪个后端”,是因为构造时从 initApiSettings(ai) 返回的 ApiSettings 中读取了 backend.backendType。而 Backend 抽象类及其两个子类定义在 packages/ai/src/backend.ts:
GoogleAIBackend:backendType为GOOGLE_AI,对应 Gemini Developer API(通过 Google AI 提供)。其模型路径模板为/${DEFAULT_API_VERSION}/projects/${project}/${model}。AgentPlatformBackend:backendType为AGENT_PLATFORM,对应 Agent Platform Gemini API(原 Vertex AI Gemini API)。构造函数可接收可选的location参数(默认'global',见 packages/ai/src/constants.ts 中的DEFAULT_LOCATION),模型路径模板为/${DEFAULT_API_VERSION}/projects/${project}/locations/${location}/${model}。
注意两个细节:
- 归一化出的模型名会直接嵌入后端路径模板。例如在 Agent Platform 后端下,
model为publishers/google/models/gemini-3.6-flash,最终 REST 路径即为/v1beta/projects/{project}/locations/{location}/publishers/google/models/gemini-3.6-flash(DEFAULT_API_VERSION为'v1beta')。 - 归一化规则与路径模板的分工不同:归一化只处理“模型资源名”本身(补全
publishers/google/models/前缀),而项目、区域等信息由Backend._getModelPath()在构造完整请求路径时补上。
后端的选择发生在 getAI() 阶段。根据 packages/ai/src/api.ts 的实现,getAI(app, options) 默认使用 new GoogleAIBackend(),也可通过 options.backend 显式指定:
// 使用 Gemini Developer API(Google AI)
const ai = getAI(app, { backend: new GoogleAIBackend() });
// 使用 Agent Platform Gemini API(默认区域 global)
const ai = getAI(app, { backend: new AgentPlatformBackend() });
// 指定区域的 Agent Platform
const ai = getAI(app, { backend: new AgentPlatformBackend('us-central1') });
在 Live API 场景中,后端类型同样直接决定 WebSocket 会话使用的模型路径:packages/ai/src/models/live-generative-model.ts 第 81-85 行会根据 _apiSettings.backend instanceof AgentPlatformBackend 来拼接 projects/{project}/locations/{location}/{model} 或 projects/{project}/{model}。
子类体系:谁继承了 AIModel
AIModel 是 SDK 中生成式模型类的公共底座,其直接子类包括:
| 子类 | 定义位置 | 公开入口(工厂方法) | 说明 |
|---|---|---|---|
GenerativeModel |
packages/ai/src/models/generative-model.ts | getGenerativeModel(ai, modelParams) |
常规生成式模型,支持 generateContent / generateContentStream / 聊天会话 / 工具调用 / 设备端混合推理 |
LiveGenerativeModel |
packages/ai/src/models/live-generative-model.ts | getLiveGenerativeModel(ai, modelParams) |
低延迟、双向多模态交互的 Live API 模型(Beta) |
这两个子类都在构造函数中调用 super(ai, modelParams.model),把用户传入的 ModelParams.model / LiveModelParams.model 交给 AIModel 完成归一化。GenerativeModel 还额外持有 generationConfig、safetySettings、tools、toolConfig、systemInstruction 等配置,并支持通过 Chrome 内置 Prompt API 进行设备端推理(initializeDeviceModel)。
需要特别指出的是,TemplateGenerativeModel(服务器提示词模板模型)并不继承 AIModel,它直接在 packages/ai/src/models/template-generative-model.ts 中自行调用 initApiSettings(ai) 并维护 _apiSettings,因为它面向的是服务端模板(templateId)而非独立的模型资源名。这与 AIModel 的定位形成互补:AIModel 家族负责“以模型名为主语”的推理,而模板模型以“模板 ID 为主语”。
所有工厂方法统一收敛在 packages/ai/src/api.ts:
// 常规生成式模型
const model = getGenerativeModel(ai, { model: 'gemini-3.6-flash' });
// Live 模型(仅支持现代浏览器窗口与 Node >= 22)
const liveModel = getLiveGenerativeModel(ai, { model: 'gemini-live-3.6' });
// 服务端提示词模板模型
const templateModel = getTemplateGenerativeModel(ai);
其中 getGenerativeModel 在未提供模型名时会抛出 AIErrorCode.NO_MODEL('no-model')错误,错误信息示例为 “Must provide a model name. Example: getGenerativeModel({ model: 'my-model-name' })”。
实战要点小结
结合 API 文档与源码,使用 AIModel 及其子类时有几点值得注意:
- 永远不要直接实例化或继承
AIModel:构造函数是protected且被标记为@internal,应始终通过getAI/getGenerativeModel/getLiveGenerativeModel等公开工厂方法获取模型实例。 - 模型名写法取决于后端:Google AI 后端下归一化为
models/{name};Agent Platform 后端下普通短名会被补全为publishers/google/models/{name},而models/{name}半限定名也会被补全 publisher。若使用微调模型等自定义路径(如tunedModels/...),在 Agent Platform 后端下必须自行传入完整正确路径,SDK 会原样保留。 - Firebase 配置校验是硬性的:
apiKey、projectId、appId任一缺失,模型实例化即失败并抛出对应的AIError,错误码分别为no-api-key、no-project-id、no-app-id。 - 模型名一经创建即不可变:
readonly model保证实例生命周期内模型资源名固定,如需切换模型应创建新的模型实例。
通过理解 AIModel 这一抽象基类,你就掌握了 Firebase JavaScript SDK AI 模块中“模型资源名解析”与“后端绑定”这两条最核心的基础链路,后续阅读 GenerativeModel 的推理方法或 Live API 的 WebSocket 会话实现都会更加顺畅。
延伸阅读
- 类参考文档:ai.aimodel.md
- 核心实现:packages/ai/src/models/ai-model.ts
- 单元测试:packages/ai/src/models/ai-model.test.ts
- 后端配置:packages/ai/src/backend.ts 及其测试 packages/ai/src/backend.test.ts
- 公共入口与工厂方法:packages/ai/src/api.ts
- API 设置初始化与校验:packages/ai/src/models/utils.ts
- 公共类型(
BackendType、AI、AIOptions):packages/ai/src/public-types.ts - 错误码定义:packages/ai/src/types/error.ts