Firebase JavaScript SDK 的 AIModel 抽象基类:模型资源名规范、后端绑定与子类体系全解析

原创2026-10-14 13:22:251,385 阅读
文章标签:开发工具后端

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),这意味着它不能直接被实例化,只能被继承。它的核心职责可以概括为两点:

  1. 绑定后端:每个 AIModel 实例都与一个特定的 Firebase AI Backend(即 Backend 抽象类,见 packages/ai/src/backend.ts)相关联,该后端决定了 SDK 最终与哪套生成式模型服务通信。
  2. 提供模型交互入口:子类通过继承 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
  );
}

构造函数只做两件事:

  1. 初始化 API 设置:调用 initApiSettings(ai),从传入的 AI 实例中提取 apiKey、projectId、appId、后端配置、App Check 令牌获取函数与 Auth 令牌获取函数,组装成内部的 ApiSettings 对象。
  2. 归一化模型名:调用静态方法 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-model
  • new TestModel(fakeAI, 'models/my-model') → publishers/google/models/my-model
  • new 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}。

注意两个细节:

  1. 归一化出的模型名会直接嵌入后端路径模板。例如在 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')。
  2. 归一化规则与路径模板的分工不同:归一化只处理“模型资源名”本身(补全 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 及其子类时有几点值得注意:

  1. 永远不要直接实例化或继承 AIModel:构造函数是 protected 且被标记为 @internal,应始终通过 getAI / getGenerativeModel / getLiveGenerativeModel 等公开工厂方法获取模型实例。
  2. 模型名写法取决于后端:Google AI 后端下归一化为 models/{name};Agent Platform 后端下普通短名会被补全为 publishers/google/models/{name},而 models/{name} 半限定名也会被补全 publisher。若使用微调模型等自定义路径(如 tunedModels/...),在 Agent Platform 后端下必须自行传入完整正确路径,SDK 会原样保留。
  3. Firebase 配置校验是硬性的:apiKey、projectId、appId 任一缺失,模型实例化即失败并抛出对应的 AIError,错误码分别为 no-api-key、no-project-id、no-app-id。
  4. 模型名一经创建即不可变:readonly model 保证实例生命周期内模型资源名固定,如需切换模型应创建新的模型实例。

通过理解 AIModel 这一抽象基类,你就掌握了 Firebase JavaScript SDK AI 模块中“模型资源名解析”与“后端绑定”这两条最核心的基础链路,后续阅读 GenerativeModel 的推理方法或 Live API 的 WebSocket 会话实现都会更加顺畅。

延伸阅读

登录后查看全文
firebase-js-sdk