从 Google AI 客户端 SDK 迁移到 Firebase AI Logic SDK

Swift

使用 Swift Package Manager 安装和管理 Firebase 依赖项。

Firebase AI Logic 库提供了用于与 Gemini 和 Imagen 模型交互的 API。该库包含在适用于 Apple 平台的 Firebase SDK (firebase-ios-sdk) 中。

如果您已在使用 Firebase，请确保您的 Firebase 软件包是 v11.13.0 或更高版本。

1. 在 Xcode 中打开您的应用项目，依次点击 File（文件）> Add Package Dependencies（添加软件包依赖项）。

2. 出现提示时，添加 Firebase Apple 平台 SDK 代码库：

   https://github.com/firebase/firebase-ios-sdk
   

3. 选择最新的 SDK 版本。

4. 选择 FirebaseAI 库。

完成之后，Xcode 将会自动开始在后台解析和下载您的依赖项。

Kotlin

Firebase AI Logic SDK for Android (firebase-ai) 提供对 API 的访问权限，以便与 Gemini 和 Imagen 模型交互。

在您的模块（应用级）Gradle 文件（例如 <project>/<app-module>/build.gradle.kts）中，添加适用于 Android 的 Firebase AI Logic 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

dependencies {
  // ... other androidx dependencies

  // Import the BoM for the Firebase platform
  implementation(platform("com.google.firebase:firebase-bom:33.14.0"))

  // Add the dependency for the Firebase AI Logic library
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")
}

借助 Firebase Android BoM，可确保您的应用使用的始终是 Firebase Android 库的兼容版本。

dependencies {
  // Add the dependency for the Firebase AI Logic library
  // When NOT using the BoM, you must specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai:16.0.0")
}

Java

Firebase AI Logic SDK for Android (firebase-ai) 提供对 API 的访问权限，以便与 Gemini 和 Imagen 模型交互。

在您的模块（应用级）Gradle 文件（例如 <project>/<app-module>/build.gradle.kts）中，添加适用于 Android 的 Firebase AI Logic 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

对于 Java，您需要额外添加两个库。

dependencies {
  // ... other androidx dependencies

  // Import the BoM for the Firebase platform
  implementation(platform("com.google.firebase:firebase-bom:33.14.0"))

  // Add the dependency for the Firebase AI Logic library
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")

  // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

借助 Firebase Android BoM，可确保您的应用使用的始终是 Firebase Android 库的兼容版本。

dependencies {
  // Add the dependency for the Firebase AI Logic library
  // When NOT using the BoM, you must specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai:16.0.0")
}

Web

Firebase AI Logic 库提供了用于与 Gemini 和 Imagen 模型交互的 API。该库包含在 Firebase JavaScript SDK for Web 中。

1. 使用 npm 安装 Firebase JS SDK for Web：

   npm install firebase
   

2. 在您的应用中初始化 Firebase：

   import { initializeApp } from "firebase/app";
   
   // TODO(developer) Replace the following with your app's Firebase configuration
   // See: https://firebase.google.com/docs/web/learn-more#config-object
   const firebaseConfig = {
     // ...
   };
   
   // Initialize FirebaseApp
   const firebaseApp = initializeApp(firebaseConfig);
   

Dart

适用于 Flutter 的 Firebase AI Logic 插件 (firebase_ai) 提供对 API 的访问权限，以便与 Gemini 和 Imagen 模型交互。

1. 在您的 Flutter 项目目录中，运行以下命令以安装核心插件和 Firebase AI Logic 插件：

   flutter pub add firebase_core && flutter pub add firebase_ai
   

2. 在 lib/main.dart 文件中，导入您之前生成的 Firebase 核心插件、Firebase AI Logic 插件和配置文件：

   import 'package:firebase_core/firebase_core.dart';
   import 'package:firebase_ai/firebase_ai.dart';
   import 'firebase_options.dart';
   

3. 同样在 lib/main.dart 文件中，使用配置文件导出的 DefaultFirebaseOptions 对象初始化 Firebase：

   await Firebase.initializeApp(
     options: DefaultFirebaseOptions.currentPlatform,
   );
   

4. 重新构建 Flutter 应用：

   flutter run
   

Unity

Google AI 客户端 SDK 不支持 Unity。

了解如何开始使用适用于 Unity 的 Firebase AI Logic SDK。

Swift

移除旧库：

1. 在 Xcode 中打开您的应用项目，前往 Packages Dependencies 窗格。

2. 从软件包依赖项列表中选择 generative-ai-swift 软件包。

3. 点击列表底部的 - 按钮，然后点击移除进行确认。

Kotlin

dependencies {
    implementation("com.google.ai.client.generativeai:generativeai:VERSION")
}

Java

dependencies {
    implementation("com.google.ai.client.generativeai:generativeai:VERSION")
}

Web

// BEFORE
import { initializeApp } from "firebase/app";
import { GoogleGenerativeAI } from "@google/generative-ai";

Dart

删除旧软件包：
flutter pub remove google_generative_ai

Unity

Google AI 客户端 SDK 不支持 Unity。

了解如何开始使用适用于 Unity 的 Firebase AI Logic SDK。

Swift

// BEFORE
import GoogleGenerativeAI

let model = GenerativeModel(name: "MODEL_NAME", apiKey: APIKey.default)

// AFTER
import FirebaseAI

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(modelName: "gemini-2.0-flash")

Kotlin

// BEFORE
import com.google.ai.client.generativeai.Chat
import com.google.ai.client.generativeai.type.Content
import com.google.ai.client.generativeai.java.GenerativeModuleFutures

...

val generativeModel = GenerativeModel(modelName = "MODEL_NAME",
  // Access your API key as a Build Configuration variable
  apiKey = BuildConfig.apiKey
)

// AFTER
import com.google.firebase.Firebase
import com.google.firebase.ai.ai
import com.google.firebase.ai.type.GenerativeBackend

...

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
                        .generativeModel("gemini-2.0-flash")

Java

// BEFORE
import com.google.ai.client.generativeai.Chat;
import com.google.ai.client.generativeai.type.Content;
import com.google.ai.client.generativeai.java.GenerativeModuleFutures;

...

GenerativeModel gm = new GenerativeModel("MODEL_NAME",
  // Access your API key as a Build Configuration variable
  BuildConfig.apiKey
);

GenerativeModelFutures model = GenerativeModelFutures.from(gm);

// AFTER
import com.google.firebase.ai.FirebaseAI;
import com.google.firebase.ai.GenerativeModel;
import com.google.firebase.ai.java.GenerativeModelFutures;
import com.google.firebase.ai.type.GenerativeBackend;

...

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel("gemini-2.0-flash");

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

Web

// BEFORE
import { GoogleGenerativeAI } from "@google/generative-ai";

// Fetch your API_KEY and access your API
const API_KEY = "...";
const genAI = new GoogleGenerativeAI(API_KEY);

...

const model = genAI.getGenerativeModel({ model: "MODEL_NAME"});

// AFTER
import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(ai, { model: "gemini-2.0-flash" });

Dart

// BEFORE
import 'package:google_generative_ai/google_generative_ai.dart';

final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
print('No \$API_KEY environment variable');
exit(1);
}

final model = GenerativeModel(model: 'MODEL_NAME', apiKey: apiKey);

// AFTER
import 'package:firebase_ai/firebase_ai.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model =
      FirebaseAI.googleAI().generativeModel(model: 'gemini-2.0-flash');

Unity

Google AI 客户端 SDK 不支持 Unity。

了解如何开始使用适用于 Unity 的 Firebase AI Logic SDK。

Swift

• 枚举

  • 将大多数 enum 类型替换成了包含静态变量的 struct。此更改让您能够更灵活地以向后兼容的方式改进 API。现在，使用 switch 语句时，您必须添加 default: 情况来涵盖未知或未处理的值，包括将来添加到 SDK 中的新值。

  • 将 BlockThreshold 枚举重命名为 HarmBlockThreshold；此类型现在是 struct。

  • 从以下枚举（现在是 struct）中移除了 unknown 和 unspecified 情况：HarmCategory、HarmBlockThreshold、HarmProbability、BlockReason 和 FinishReason。

  • 将枚举 ModelContent.Part 替换为名为 Part 的协议，以允许以向后兼容的方式添加新类型。内容部分部分对此变更进行了更详细的介绍。

• 内容部分

  • 移除了 ThrowingPartsRepresentable 协议，并简化了 ModelContent 的初始化程序，以避免偶尔出现编译器错误。未正确编码的图片在 generateContent 中使用时仍会抛出错误。

  • 将 ModelContent.Part 情况替换为符合 Part 协议的以下 struct 类型：

    • .text 到 TextPart
    • .data 至 InlineDataPart
    • .fileData 至 FileDataPart
    • .functionCall 至 FunctionCallPart
    • .functionResponse 到 FunctionResponsePart

• 危害类别

  • 更改了 HarmCategory，使其不再嵌套在 SafetySetting 类型中。如果您将其称为 SafetySetting.HarmCategory，则可以将其替换为 HarmCategory。

• 安全反馈

  • 移除了 SafetyFeedback 类型，因为它未在任何响应中使用。

• 引用元数据

  • 将 CitationMetadata 中的 citationSources 属性重命名为 citations。

• 应计费字符总数

  • 将 CountTokensResponse 中的 totalBillableCharacters 属性更改为可选属性，以反映未发送任何字符的情况。

• 候选回答

  • 将 CandidateResponse 重命名为 Candidate，以与其他平台保持一致。

• 生成配置

  • 将 GenerationConfig 的公开属性更改为 internal。它们仍然可以在初始化程序中进行配置。

Kotlin

• 枚举

  • 将 enum 类和 sealed 类替换为常规类。此更改让您能够更灵活地以向后兼容的方式改进 API。

  • 将 BlockThreshold 枚举重命名为 HarmBlockThreshold。

  • 从以下枚举中移除了值：HarmBlockThreshold、HarmProbability、HarmSeverity、BlockReason 和 FinishReason。

• Blob 方法

  • 重命名了名称中包含 Blob 的所有方法，改为使用 InlineData。

• 安全设置

  • 将 method 字段更改为了可为空字段。

• 时长类

  • 移除了 Kotlin 的 Duration 类的所有用法，并将其替换为 long。此变更可提高与 Java 的互操作性。

• 引用元数据

  • 将之前在 CitationMetadata 中声明的所有字段封装到名为 Citation 的新类中。您可以在 CitationMetadata 中名为 citations 的列表中找到引文。此变更有助于更好地在各个平台上对齐类型。

• 统计词元数

  • 将 totalBillableCharacters 字段更改为了可为空字段。

• 应计费字符总数

  • 将 CountTokensResponse 中的 totalBillableCharacters 属性更改为可选属性，以反映未发送任何字符的情况。

• 实例化模型

  • 将 requestOptions 参数移到了参数列表的末尾，以与其他平台保持一致。

Java

• 枚举

  • 将 enum 类和 sealed 类替换为常规类。此更改让您能够更灵活地以向后兼容的方式改进 API。

  • 将 BlockThreshold 枚举重命名为 HarmBlockThreshold。

  • 从以下枚举中移除了值：HarmBlockThreshold、HarmProbability、HarmSeverity、BlockReason 和 FinishReason。

• Blob 方法

  • 重命名了名称中包含 Blob 的所有方法，改为使用 InlineData。

• 安全设置

  • 将 method 字段更改为了可为空字段。

• 时长类

  • 移除了 Kotlin 的 Duration 类的所有用法，并将其替换为 long。此变更可提高与 Java 的互操作性。

• 引用元数据

  • 将之前在 CitationMetadata 中声明的所有字段封装到名为 Citation 的新类中。您可以在 CitationMetadata 中名为 citations 的列表中找到引文。此变更有助于更好地在各个平台上对齐类型。

• 统计词元数

  • 将 totalBillableCharacters 字段更改为了可为空字段。

• 应计费字符总数

  • 将 CountTokensResponse 中的 totalBillableCharacters 属性更改为可选属性，以反映未发送任何字符的情况。

• 实例化模型

  • 将 requestOptions 参数移到了参数列表的末尾，以与其他平台保持一致。

Web

请注意，自 Firebase AI Logic 客户端 SDK 从 Google AI 客户端 SDK 分支以来，Google AI 客户端 SDK 发生了许多变化。以下列出了您在迁移到 Firebase AI Logic 客户端 SDK 时可能需要考虑的一些潜在更改。

• 枚举

  • 从以下枚举中移除了值：HarmCategory、BlockThreshold、HarmProbability、HarmSeverity、BlockReason 和 FinishReason。

• 屏蔽原因

  • 将 PromptFeedback 中的 blockReason 更改为可选。

• 搜索依据

  • 移除了此功能的所有用法，因为 Firebase AI Logic SDK 尚不支持此功能。

• 错误

  • 移除了 GoogleGenerativeAIError 的所有用法，并可选择性地改用 AIError。

Dart

• 枚举

  • 从以下枚举中移除了值：HarmCategory、HarmProbability、BlockReason 和 FinishReason。

• 数据部分

  • 将 DataPart 重命名为 InlineDataPart，并将 static data 函数重命名为 inlineData，以便与其他平台保持一致。

• 请求选项

  • 移除了 RequestOptions，因为 timeout 无法正常运行。我们将在不久的将来重新添加此类型，但会将其移至 GenerativeModel 类型，以与其他平台保持一致。

• 停止序列

  • 将 GenerationConfig 中的 stopSequences 参数更改为可选参数，并将其默认值更改为 null（而非空数组）。

• 引用

  • 将 CitationMetadata 中的 citationSources 属性重命名为 citations。CitationSource 类型已重命名为 Citation，以与其他平台保持一致。

• 不必要的公共类型、方法和属性

  • 移除了以下无意中公开的类型、方法和属性：defaultTimeout、CountTokensResponseFields、parseCountTokensResponse、parseEmbedContentResponse、parseGenerateContentResponse、parseContent、BatchEmbedContentsResponse、ContentEmbedding、EmbedContentRequest 和 EmbedContentResponse。

• 统计词元数

  • 从 countTokens 函数中移除了不再需要的额外字段。只需 contents 即可。

• 实例化模型

  • 将 systemInstruction 参数移到了参数列表的末尾，以与其他平台保持一致。

• 嵌入功能

  • 从模型中移除了不受支持的嵌入功能 (embedContent 和 batchEmbedContents)。

Unity

Google AI 客户端 SDK 不支持 Unity。

了解如何开始使用适用于 Unity 的 Firebase AI Logic SDK。