從 Firebase SDK 中的 Vertex AI 預先發布版，遷移至 Firebase AI Logic SDK

本指南說明如何從「Vertex AI in Firebase」SDK 的預先發布 (或 Beta) 版本，遷移至 Firebase AI Logic 用戶端 SDK。
這些用戶端 SDK 適用於 Apple 平台的 Swift、Android 的 Kotlin 和 Java、Web 的 JavaScript、Flutter 的 Dart，以及 Unity。

如果您使用的是「Vertex AI in Firebase」SDK 的正式版，請參閱從 SDK 正式版遷移的指南。

和用戶端 SDK 先前稱為「Vertex AI in Firebase」。為更準確反映我們擴展的服務和功能 (例如，我們現在支援 Gemini Developer API！)，我們將服務重新命名並重新封裝為 Firebase AI Logic。Firebase AI Logic

如要直接從行動或網頁應用程式安全地存取 Google 的生成式 AI 模型，現在可以選擇「Gemini API」供應商，包括長期可用的 Vertex AI Gemini API 或現在的 Gemini Developer API。也就是說，您現在可以選擇使用 Gemini Developer API，這項服務提供免付費層級，並設有合理的速率限制和配額。

遷移至 Firebase AI Logic SDK 的步驟總覽

• 步驟 1：為應用程式和用途選擇最合適的「Gemini API」供應商。

• 步驟 2：啟用必要的 API。

• 步驟 3：更新應用程式中使用的程式庫。

• 步驟 4：更新應用程式中的初始化設定。

• 步驟 5：根據您使用的功能更新程式碼。

步驟 1：為應用程式選擇最合適的「Gemini API」供應商

遷移時，您可以選擇「Gemini API」供應商：

• 舊版「Vertex AI in Firebase」SDK 只能使用 Vertex AI Gemini API。

• 透過新的 Firebase AI Logic SDK，您可以選擇要從行動或網頁應用程式直接呼叫的「Gemini API」供應商，也就是 Gemini Developer API 或 Vertex AI Gemini API。

請查看使用這兩個Gemini API供應商的差異，特別是支援的功能、價格和速率限制。舉例來說，Gemini Developer API 不支援使用 Cloud Storage 網址提供檔案，但如果您想善用免付費方案和合理配額，這或許是不錯的選擇。

重要事項：如要使用 Gemini Developer API 的「免費層級」，請降級目前搭配用戶端 SDK 使用的 Firebase 專案，改用免付費的 Spark 定價方案 (也就是取消連結 Cloud Billing 帳戶)。降級前，請確認您沒有使用任何需要 Blaze 方案的其他服務或配額。

如果 Firebase 專案維持 Blaze 定價方案，則會採用 Gemini Developer API 的「付費層級」。

步驟 2：啟用必要的 API

請確認已在 Firebase 專案中啟用所有必要的 API，才能使用所選的「Gemini API」供應商。

請注意，您可以在專案中同時啟用這兩個 API 提供者。

1. 登入 Firebase 控制台，然後選取 Firebase 專案。

2. 前往 Firebase 控制台的「Firebase AI Logic」頁面。

3. 按一下「開始使用」，即可啟動導覽工作流程，協助您為專案設定必要 API 和資源。

4. 選取要搭配 Firebase AI Logic SDK 使用的「Gemini API」供應商。你之後隨時可以設定及使用其他 API 供應商。

   • Gemini Developer API - 計費為選用項目 (適用於免付費的 Spark 定價方案)
     控制台的工作流程會啟用必要的 API，並在專案中建立 Gemini API 金鑰。
     請勿將這個 Gemini API 金鑰加入應用程式的程式碼集。 瞭解詳情。

   • Vertex AI Gemini API - 需要帳單 (需要即付即用 Blaze 定價方案)
     控制台的工作流程會在專案中啟用必要的 API。

5. 請繼續閱讀本遷移指南，瞭解如何更新應用程式中的程式庫和初始化作業。

步驟 3：更新應用程式中使用的程式庫

更新應用程式的程式碼集，使用 Firebase AI Logic 程式庫。

Swift

1. 在 Xcode 中保持開啟應用程式專案，然後使用下列其中一種做法，將 Firebase 軟體包更新至 11.13.0 以上版本：

   • 選項 1：更新所有套件：依序前往「File」>「Packages」>「Update to Latest Package Versions」。

   • 方法 2：個別更新 Firebase：前往「Package Dependencies」(套件依附元件) 區段中的 Firebase 套件。在 Firebase 套件上按一下滑鼠右鍵，然後選取「Update Package」。

2. 確認 Firebase 套件現在顯示 11.13.0 以上版本。如果沒有，請確認您指定的套件需求允許更新至 11.13.0 以上版本。

3. 在專案編輯器中選取應用程式的目標，然後前往「Frameworks, Libraries, and Embedded Content」部分。

4. 新增程式庫：選取「+」按鈕，然後從 Firebase 套件新增「FirebaseAI」。

5. 完成應用程式遷移作業後 (請參閱本指南的其餘章節)，請務必移除舊程式庫：
   選取「FirebaseVertexAI-Preview」，然後按下「—」按鈕。

Kotlin

1. 在模組 (應用程式層級) Gradle 檔案 (通常為 <project>/<app-module>/build.gradle.kts或 <project>/<app-module>/build.gradle) 中，將舊版依附元件 (如適用) 替換為下列項目。

   請注意，刪除舊版依附元件前，遷移應用程式的程式碼集可能比較容易 (請參閱本指南的其餘章節)。

   // BEFORE
   dependencies {
     implementation("com.google.firebase:firebase-vertexai:16.0.0-betaXX")
   }
   
   
   // AFTER
   dependencies {
     // Import the BoM for the Firebase platform
     implementation(platform("com.google.firebase:firebase-bom:33.16.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")
   }

2. 將 Android 專案與 Gradle 檔案同步。

請注意，如果您選擇不使用 Firebase Android BoM，只要新增 firebase-ai 程式庫的依附元件，並接受 Android Studio 建議的最新版本即可。

Java

1. 在模組 (應用程式層級) Gradle 檔案 (通常為 <project>/<app-module>/build.gradle.kts或 <project>/<app-module>/build.gradle) 中，將舊版依附元件 (如適用) 替換為下列項目。

   請注意，刪除舊版依附元件前，遷移應用程式的程式碼集可能比較容易 (請參閱本指南的其餘章節)。

   // BEFORE
   dependencies {
     implementation("com.google.firebase:firebase-vertexai:16.0.0-betaXX")
   }
   
   
   // AFTER
   dependencies {
     // Import the BoM for the Firebase platform
     implementation(platform("com.google.firebase:firebase-bom:33.16.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")
   }

2. 將 Android 專案與 Gradle 檔案同步。

請注意，如果您選擇不使用 Firebase Android BoM，只要新增 firebase-ai 程式庫的依附元件，並接受 Android Studio 建議的最新版本即可。

Web

1. 使用 npm 取得最新版的 Firebase JS SDK for Web：

   npm i firebase@latest

   或

   yarn add firebase@latest

2. 請更新匯入程式庫的匯入陳述式，改為使用 firebase/ai。

   請注意，刪除舊匯入項目之前，可能先遷移應用程式的程式碼集會比較容易 (請參閱本指南的其餘章節)。

   // BEFORE
   import { initializeApp } from "firebase/app";
   import { getVertexAI, getGenerativeModel } from "firebase/vertexai-preview";
   
   
   // AFTER
   import { initializeApp } from "firebase/app";
   import { getAI, getGenerativeModel } from "firebase/ai";

Dart

1. 在 pubspec.yaml 檔案中更新為使用 firebase_ai 套件，方法是在 Flutter 專案目錄中執行下列指令：

   flutter pub add firebase_ai

2. 重建 Flutter 專案：

   flutter run

3. 完成應用程式遷移作業後 (請參閱本指南的其餘章節)，請務必刪除舊套件：

   flutter pub remove firebase_vertexai

Unity

「Vertex AI in Firebase」不支援 Unity。

瞭解如何開始使用 Unity 適用的 Firebase AI Logic SDK。

步驟 4：更新應用程式中的初始化設定

按一下 Gemini API 供應商，即可在這個頁面查看供應商專屬內容和程式碼。 Gemini Developer API Vertex AI Gemini API

更新所選 API 供應商的服務初始化方式，並建立 GenerativeModel 例項。

Swift

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.5-flash")

Kotlin

// 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.5-flash")

Java

// 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.5-flash");

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

Web

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.5-flash" });

Dart

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.5-flash');

Unity

「Vertex AI in Firebase」不支援 Unity。

瞭解如何開始使用 Firebase AI Logic SDK for Unity。

請注意，視您使用的功能而定，您可能不一定會建立 GenerativeModel 執行個體。

• 如要存取 Imagen 模型，請建立 ImagenModel 執行個體。

步驟 5：根據您使用的功能更新程式碼

本步驟說明您可能需要進行的變更，視您使用的功能而定。

• 如果您使用 Cloud Storage 網址並在這次遷移中改用 Gemini Developer API，則必須更新多模態要求，將檔案納入為內嵌資料 (或使用 YouTube 網址做為影片來源)。

• 「Vertex AI in Firebase」SDK 的正式版導入了多項變更，如要使用 Firebase AI Logic SDK，也必須進行這些變更。請查看下列清單，瞭解程式碼中可能需要進行哪些變更，才能採用 Firebase AI Logic SDK。

所有語言和平台都必須提供

• 函式呼叫
  如果您在正式發布前實作這項功能，則需要更新定義結構定義的方式。建議您詳閱更新後的函式呼叫指南，瞭解如何編寫函式宣告。

• 使用 responseSchema
  生成結構化輸出內容 (例如 JSON) 如果您在正式發布前導入這項功能，則需要更新結構定義方式。建議您參閱新的結構化輸出指南，瞭解如何編寫 JSON 結構定義。

• 逾時

  • 將要求的預設逾時時間變更為 180 秒。

視平台或語言而定

Swift

• 列舉

  • 將大部分 enum 型別換成具有靜態變數的 struct。這項變更可讓您更靈活地以回溯相容的方式演進 API。使用 switch 陳述式時，現在必須加入 default: 情況，涵蓋不明或未處理的值，包括日後新增至 SDK 的值。

  • 已將 BlockThreshold 列舉重新命名為 HarmBlockThreshold，這個型別現在是 struct。

  • 從下列列舉中移除 unknown 和 unspecified 案例 (現在為 struct)：HarmCategory、HarmBlockThreshold、HarmProbability、BlockReason 和 FinishReason。

  • 將列舉 ModelContent.Part 替換為名為 Part 的通訊協定，以便以回溯相容的方式新增類型。如要瞭解這項異動的詳細資訊，請參閱「內容部分」一節。

• 內容部分

  • 已移除 ThrowingPartsRepresentable 協定，並簡化 ModelContent 的初始值，避免偶爾發生編譯器錯誤。如果圖片編碼不正確，在 generateContent 中使用時仍會擲回錯誤。

  • 已將 ModelContent.Part 案例替換為以下 struct 型別， 並符合 Part 通訊協定：

    • .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 欄位變更為可為空值。

• Duration 類別

  • 移除 Kotlin 的 Duration 類別的所有用法，並替換為 long。這項變更可提升與 Java 的互通性。

• 引用中繼資料

  • 將先前在 CitationMetadata 中宣告的所有欄位，包裝到名為 Citation 的新類別中。您可以在 CitationMetadata 中找到名為「引文」citations的清單。這項異動可讓各平台上的型別更一致。

• 計算權杖數

  • 將 totalBillableCharacters 欄位變更為可為空值。

• 可計費字元總數

  • 變更 CountTokensResponse 中的 totalBillableCharacters 屬性，使其成為選用屬性，以反映未傳送任何字元的情況。

• 例項化模型

  • 將 requestOptions 參數移至參數清單結尾，與其他平台保持一致。

• Live API

  • 移除了列舉類別 ResponseModality 的 UNSPECIFIED 值。請改用 null。

  • 「LiveGenerationConfig.setResponseModalities」已重新命名為「LiveGenerationConfig.setResponseModality」。

  • 移除 LiveContentResponse.Status 類別，並將狀態欄位巢狀化為 LiveContentResponse 的屬性。

  • 已移除 LiveContentResponse 類別，並改為提供與模型回應相符的 LiveServerMessage 子類別。

  • 將 LiveModelFutures.connect 變更為回傳 ListenableFuture<LiveSessionFutures>，而不是 ListenableFuture<LiveSession>。

Java

• 列舉

  • 以一般類別取代 enum 類別和 sealed 類別。這項變更可讓 API 發展更具彈性，同時確保回溯相容性。

  • 將 BlockThreshold 列舉重新命名為 HarmBlockThreshold。

  • 從下列列舉中移除值：HarmBlockThreshold、HarmProbability、HarmSeverity、BlockReason 和 FinishReason。

• Blob 方法

  • 將名稱中包含 Blob 的所有方法重新命名，改為使用 InlineData。

• 安全設定

  • 將 method 欄位變更為可為空值。

• Duration 類別

  • 移除 Kotlin 的 Duration 類別的所有用法，並替換為 long。這項變更可提升與 Java 的互通性。

• 引用中繼資料

  • 將先前在 CitationMetadata 中宣告的所有欄位，包裝到名為 Citation 的新類別中。您可以在 CitationMetadata 中找到名為「引文」citations的清單。這項異動可讓各平台上的型別更一致。

• 計算權杖數

  • 將 totalBillableCharacters 欄位變更為可為空值。

• 可計費字元總數

  • 變更 CountTokensResponse 中的 totalBillableCharacters 屬性，使其成為選用屬性，以反映未傳送任何字元的情況。

• 例項化模型

  • 將 requestOptions 參數移至參數清單結尾，與其他平台保持一致。

• Live API

  • 移除了列舉類別 ResponseModality 的 UNSPECIFIED 值。請改用 null。

  • 「LiveGenerationConfig.setResponseModalities」已重新命名為「LiveGenerationConfig.setResponseModality」。

  • 移除 LiveContentResponse.Status 類別，並將狀態欄位巢狀化為 LiveContentResponse 的屬性。

  • 已移除 LiveContentResponse 類別，並改為提供與模型回應相符的 LiveServerMessage 子類別。

  • 將 LiveModelFutures.connect 變更為回傳 ListenableFuture<LiveSessionFutures>，而不是 ListenableFuture<LiveSession>。

• 變更各種 Java 建構工具方法，現在會正確傳回其類別的例項，而非 void。

Web

• 列舉

  • 已從下列列舉中移除值：HarmCategory、BlockThreshold、HarmProbability、HarmSeverity、BlockReason 和 FinishReason。

• 封鎖原因

  • 將 PromptFeedback 中的 blockReason 變更為選用。

只有在開始使用 Gemini Developer API (而非 Vertex AI Gemini API) 時，才需要進行變更：

• 安全設定

  • 移除不支援的 SafetySetting.method 用法。

• 內嵌資料

  • 移除不支援的 InlineDataPart.videoMetadata 用法。

Dart

• 列舉

  • 從下列列舉中移除值：HarmCategory、HarmProbability、BlockReason 和 FinishReason。

• 資料部分

  • 已將 DataPart 重新命名為 InlineDataPart，並將 static data 函式重新命名為 inlineData，與其他平台保持一致。

• 要求選項

  • 由於 timeout 無法運作，因此已移除 RequestOptions。我們會在不久的將來重新加入這項功能，但會移至 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

「Vertex AI in Firebase」不支援 Unity。

瞭解如何開始使用 Unity 適用的 Firebase AI Logic SDK。

遷移時可能發生的錯誤

由於您要遷移至 Firebase AI Logic 的正式版，如果未按照本遷移指南完成所有必要變更，可能會遇到錯誤。

403 錯誤：Requests to this API firebasevertexai.googleapis.com ... are blocked.

如果收到 403 錯誤，且錯誤訊息指出「Requests to this API firebasevertexai.googleapis.com ... are blocked.」，通常表示 Firebase 設定檔或物件中的 Firebase API 金鑰，未在允許清單中列出您嘗試使用的產品所需 API。

請確認應用程式使用的 Firebase API 金鑰，已在金鑰的「API 限制」允許清單中加入所有必要 API。如要使用 Firebase AI Logic，Firebase API 金鑰的允許清單中至少要有 Firebase AI Logic API。您在 Firebase 控制台中啟用必要 API 時，系統應會自動將這個 API 加入 API 金鑰的許可清單。

您可以在 Google Cloud 控制台的「APIs & Services」(API 和服務) >「Credentials」(憑證) 面板中，查看所有 API 金鑰。

注意： Firebase 相關 API 使用 API 金鑰僅是為了識別 Firebase 專案或應用程式，並非授權呼叫 API (如同其他 API 允許的做法)。Firebase 相關 API 的授權與 API 金鑰分開處理，可透過 Google Cloud IAM 權限、Firebase Security Rules或 Firebase App Check 進行授權。進一步瞭解 Firebase API 金鑰。

提供有關 Firebase AI Logic 的使用體驗意見回饋