常見問題與疑難排解

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

為什麼名稱會從「Vertex AI in Firebase」變更為「Firebase AI Logic」？

我們在 2024 年推出一組 Firebase 用戶端 SDK，可使用 Vertex AI Gemini API 和 Firebase 代理閘道，保護 API 免於遭到濫用，並整合其他 Firebase 產品。我們將產品命名為「Firebase 中的 Vertex AI」，這個產品名稱準確描述了我們產品當時可用的用途。

不過，我們自推出以來，已擴充產品的功能。舉例來說，自 2025 年 5 月起，我們現在提供 Gemini Developer API 支援服務，包括透過與 Firebase App Check 整合，保護 Gemini Developer API 免於遭到濫用。

因此，「Firebase 中的 Vertex AI」這個名稱不再準確反映產品的擴大範圍。因此，我們將名稱改為 Firebase AI Logic，以更貼切地反映不斷進化的功能組合，並讓我們日後持續擴大產品服務！

請參閱遷移指南，確保您能使用 Firebase AI Logic 提供的所有最新功能 (並視需要開始使用 Gemini Developer API)。

使用 Gemini Developer API 和 Vertex AI Gemini API 有何不同？

以下是兩個「Gemini API」供應商之間的差異：

• 定價

  • Gemini Developer API 提供「免費方案」和即付即用式定價。

  • Vertex AI Gemini API 與 Firebase AI Logic 搭配使用時，一律必須採用即付即用 Blaze 定價方案。

  請注意，這兩個 API 供應商的付費制價格有所不同 (詳情請參閱各自的說明文件)。

• 費率限制 (配額)

  • Gemini Developer API 有明確的頻率限制。

  • Vertex AI Gemini API 會使用「動態共用配額 (DSQ)」，該配額由該地區使用該模型的所有使用者共用。您也可以視需要設定已配置的傳輸量 (PT)。

• 指定模型存取位置

  • 只有 Vertex AI Gemini API 可讓您選擇存取模型的位置。

下表列出兩個「Gemini API」供應商常見功能的可用性。這份表格適用於使用 Firebase AI Logic 用戶端 SDK 時。

¹ Gemini Developer API 的 Files API 不支援 Firebase AI Logic SDK。

我可以同時使用 Gemini Developer API 和 Vertex AI Gemini API 嗎？

是的，您可以在 Firebase 專案中啟用兩種「Gemini API」供應器，並在應用程式中使用這兩種 API。

如要在程式碼中切換 API 供應商，請務必在程式碼中適當設定後端服務。

哪些 API 是必要的？如何啟用這些功能？

如要搭配 Gemini Developer API 使用 Firebase AI Logic SDK，專案必須啟用下列兩個 API：

• Gemini Developer API (generativelanguage.googleapis.com)
• Firebase AI Logic API (firebasevertexai.googleapis.com)

您應使用 Firebase 主控台啟用這兩個 API：

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

2. 按一下「開始使用」。

3. 選取 Gemini Developer API 即可開始使用。

   這會啟動引導式工作流程，為您啟用這兩個 API。控制台也會產生 Gemini API 金鑰，並將 Firebase AI Logic API 新增至 Firebase API 金鑰的許可清單。

哪些型號可搭配 Firebase AI Logic SDK 使用？

• 您可以搭配 Firebase AI Logic SDK 使用任何 Gemini 和 Imagen 3 基礎模型，包括預覽版和實驗版。如要查看這些型號的清單，請參閱「瞭解支援的型號」。

• 您無法使用非基礎 Gemini 模型 (例如 PaLM 模型、調校模型或以 Gemma 為基礎的模型) 搭配 Firebase AI Logic SDK。

  Firebase AI Logic 也不支援較舊的 Imagen 型號或 imagen-3.0-capability-001。

• Gemini Developer API (無論如何存取) 不支援 imagen-3.0-fast-generate-001 或舊版 imagen-3.0-generate-001。

我們會經常在 SDK 中新增功能，因此請回來看看這份常見問題清單 (以及發布說明、部落格和社群媒體貼文)，瞭解最新消息。

模型停用後該怎麼辦？

我們會盡力確保穩定版模型至少可使用一年。我們會在 Firebase 和 Google Cloud 說明文件的多個位置列出這項「停用日期」資訊 (例如，在「模型」頁面中)。

模型停用後，任何對該模型的要求都會失敗，並傳回 404 錯誤。因此，我們強烈建議您設定並使用 Firebase Remote Config，這樣一來，您就能動態變更應用程式中的模型和版本，而無須發布新版應用程式。

更新應用程式以使用新模型版本時，建議您測試應用程式，確保回應仍符合預期。請注意，使用 Firebase AI Logic 時，通常不需要修改任何實際呼叫模型的程式碼。

以下是各型號的停產日期：

• Gemini 1.5 Pro 型號：

  • gemini-1.5-pro-002 (和 gemini-1.5-pro)：2025 年 9 月 24 日
  • gemini-1.5-pro-001：2025 年 5 月 24 日

• Gemini 1.5 Flash 型號：

  • gemini-1.5-flash-002 (和 gemini-1.5-flash)：2025 年 9 月 24 日
  • gemini-1.5-flash-001：2025 年 5 月 24 日

• Gemini 1.0 Pro Vision 型號：2025 年 4 月 21 日 (原定於 2025 年 4 月 9 日)

• Gemini 1.0 Pro 型號：2025 年 4 月 21 日 (原定於 2025 年 4 月 9 日)

如何設定每位使用者的頻率限制？

根據預設，Firebase AI Logic 會將每位使用者的要求限制設為每分鐘 100 個要求 (RPM)。

如要調整每位使用者的速率限制，您必須調整 Firebase AI Logic API 的配額設定。

進一步瞭解 Firebase AI Logic API 配額。您也可以在該頁面瞭解如何查看及編輯配額。

使用 Firebase AI Logic SDK 需要哪些權限？

Firebase AI Logic 會使用我的資料訓練模型嗎？

請參閱「資料管理與負責任 AI 技術」。

多模式要求是否需要 MIME 類型？(例如圖片、PDF、影片和音訊輸入內容)

是的，在每個多模態要求中，您都必須提供下列項目：

• 檔案為 mimeType。請參閱下方的例外狀況。

• 檔案。您可以將檔案做為內嵌資料提供，也可以使用檔案的網址提供檔案。

如要瞭解支援的輸入檔案類型、如何指定 MIME 類型，以及在 支援的輸入檔案和相關規定中提供檔案的兩種方式，請參閱相關說明。

在要求中加入 MIME 類型的例外狀況

對於原生 Android 和 Apple 平台應用程式的要求，則可例外提供內嵌圖片輸入內容，以便提供 MIME 類型。

適用於 Android 和 Apple 平台的 Firebase AI Logic SDK 提供簡化且平台友善的方式，可處理要求中的圖片。所有圖片 (不論格式為何) 都會在傳送至伺服器前，以 80% 的品質在用戶端轉換為 JPEG。也就是說，當您使用 Android 和 Apple 平台 SDK 提供圖片做為內嵌資料時，不必在要求中指定 MIME 類型。

這類簡化處理方式，可參考 Firebase AI Logic 文件中的範例，瞭解如何在要求中傳送 base64 編碼圖片。

以下是這項功能的其他平台專屬資訊：

• Android 裝置：

  • 您可以利用簡化方式，在包含圖片做為內嵌資料的多模態提示中，處理平台原生圖片類型 (Bitmap) (請參閱範例)。

  • 如要進一步控制圖片格式和轉換作業，您可以將圖片做為 InlineDataPart 提供，並提供特定 MIME 類型。例如：

    content { inlineData(/* PNG as byte array */, "image/png") }

• 適用於 Apple 平台：

  • 您可以利用簡化方式，在包含圖片做為內嵌資料的多模態提示中，處理平台原生圖片類型 (UIImage、NSImage、CIImage 和 CGImage) (請參閱範例)。

  • 如要進一步控制圖片格式和轉換作業，您可以將圖片做為 InlineDataPart 提供，並提供特定 MIME 類型。例如：

    InlineDataPart(data: Data(/* PNG Data */), mimeType: "image/png")

使用 Firebase AI Logic 時，這些功能是否可用？您是否使用了內容快取、將搜尋做為工具、以 Google 搜尋建立基準、執行程式碼、微調模型、產生嵌入資料和語意檢索功能？

各種模型或 Vertex AI Gemini API 支援內容快取、以搜尋做為工具、以 Google 搜尋建立基準、程式碼執行、模型微調、嵌入生成和語義檢索，但使用 Firebase AI Logic 時無法使用這些功能。

如要將這些功能列為功能要求，或對現有功能要求進行投票，請前往 Firebase UserVoice。

什麼是 Gemini API 金鑰？

Gemini Developer API 會使用「Gemini API 金鑰」授權呼叫端。因此，如果您是透過 Firebase AI Logic SDK 使用 Gemini Developer API，就需要在 Firebase 專案中提供有效的 Gemini API 金鑰，才能呼叫該 API。

「Gemini API 金鑰」只是指 API 金鑰的 API 許可清單中含有 Gemini Developer API。

當您在 Firebase 控制台中完成 Firebase AI Logic 設定工作流程時，我們會建立 Gemini API 金鑰，並限制其僅可用於 Gemini Developer API，然後設定 Firebase AI Logic 代理服務以使用此 API 金鑰。在 Google Cloud 控制台的憑證頁面中，這組 Firebase 產生的 Gemini API 金鑰名稱為「Gemini Developer API key (auto created by Firebase)」。

進一步瞭解 API 金鑰的 API 限制。

使用 Firebase AI Logic SDK 時，請不將 Gemini API 金鑰加入應用程式的程式碼集。進一步瞭解如何保護 Gemini API 金鑰。

應將 Gemini API 金鑰新增至行動或網頁應用程式的程式碼庫嗎？

使用 Firebase AI Logic SDK 時，請不要將 Gemini API 金鑰新增至應用程式的程式碼庫。

事實上，在使用 Firebase AI Logic SDK 進行開發時，您不會直接與 Gemini API 金鑰互動。相反地，我們的 Firebase AI Logic 代理服務會在每個對 Gemini Developer API 的請求中，在後端內部加入 Gemini API 金鑰。

如何變更用來呼叫 Gemini Developer API 的 Gemini API 金鑰？

使用 Firebase AI Logic SDK 時，您不太可能需要變更 Gemini API 金鑰。不過，以下兩種情況可能需要您採取行動：

• 不小心洩漏金鑰，並想以新的安全金鑰取代。

• 如果不小心刪除金鑰，請注意，您可以在刪除後的 30 天內取消刪除金鑰。

以下是變更 Firebase AI Logic SDK 使用的 Gemini API 金鑰的方法：

1. 如果 Firebase 產生的 Gemini API 金鑰仍存在，請將其刪除。

   您可以在 Google Cloud 主控台的 API 和服務 >「憑證」面板中刪除這個 API 金鑰。名稱為：
   Gemini Developer API 金鑰 (由 Firebase 自動建立)。

2. 在 Google Cloud 控制台的同一頁面中，建立新的 API 金鑰。建議您將其命名為「
   Gemini Developer API key for Firebase」。

3. 針對這個新的 API 金鑰，請新增 API 限制，並只選取「生成式語言 API」。
   Gemini Developer API 在 Google Cloud 控制台中有時會稱為「生成式語言 API」。

   請不要新增任何應用程式限制，否則 Firebase AI Logic 代理服務將無法正常運作。

4. 執行下列指令，將這個新金鑰設為 Firebase AI Logic Proxy 服務應使用的 Gemini API 金鑰。

   PROJECT_ID="PROJECT_ID"
   GENERATIVE_LANGUAGE_API_KEY="DEVELOPER_CREATED_GEMINI_API_KEY"
   curl \
     -X PATCH \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://firebasevertexai.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global/config" \
     -d "{\"generativeLanguageConfig\": {\"apiKey\": \"${GENERATIVE_LANGUAGE_API_KEY}\"}}"
   

   瞭解 gcloud CLI。

請務必不將這個新的 Gemini API 金鑰新增至應用程式的程式碼集。進一步瞭解如何保護 Gemini API 金鑰。

我可以將「Firebase API 金鑰」用作 Gemini API 金鑰嗎？

否，您不應將「Firebase API 金鑰」用作 Gemini API 金鑰。我們強烈建議您不要將 Gemini Developer API 新增至 Firebase API 金鑰的許可清單。

Firebase API 金鑰是指 Firebase 設定檔或物件中列出的 API 金鑰，您可以將這組金鑰新增至應用程式的程式碼集，藉此將應用程式連結至 Firebase。如果您只在 Firebase 相關 API (例如 Firebase AI Logic) 中使用金鑰，則可以將 Firebase API 金鑰納入程式碼。 瞭解 Firebase API 金鑰的重要資訊。

在 Google Cloud 控制台的 API 和服務 >「憑證」面板中，Firebase API 金鑰的樣式如下：

您必須將 Firebase API 金鑰新增至應用程式的程式碼集，才能讓 Firebase 相關 API 正常運作，且由於 Gemini Developer API 是透過 API 金鑰授權，因此我們強烈建議您不要將 Gemini Developer API (在 Google Cloud 控制台中稱為「生成式語言 API」) 新增至 Firebase API 金鑰的 API 許可清單。否則，Gemini Developer API 就可能遭到濫用。

如何妥善保管 Gemini API 金鑰？

本常見問題說明瞭一些建議的最佳做法，可確保 Gemini API 金鑰的安全。

如果您要直接從行動或網頁應用程式呼叫 Gemini Developer API：

• 使用 Firebase AI Logic 用戶端 SDK。
• 請不將 Gemini API 金鑰加入應用程式的程式碼集。

Firebase AI Logic 提供 Proxy 服務，在每個對 Gemini Developer API 的請求中，內部加入您的 Gemini API 金鑰，完全在後端執行。

此外，我們強烈建議您採取以下做法：

• 一旦開始認真開發應用程式，請整合 Firebase App Check，以便保護後端資源，以及用於存取生成式模型的 API。

• 請不在 Firebase AI Logic 以外重複使用 Firebase 產生的 Gemini API 金鑰。如果您需要 Gemini API 金鑰來執行其他用途，請建立個別金鑰。

• 一般來說，您不應修改 Firebase 產生的 Gemini API 金鑰。這組金鑰在 Google Cloud 控制台中的名稱為「Gemini Developer API 金鑰 (由 Firebase 自動建立)」。

  • 請不要在 Firebase 產生的 Gemini API 金鑰 API 許可清單中新增任何其他 API。在 API 許可清單中，Gemini API 金鑰應「僅」包含 Gemini Developer API (在 Google Cloud 控制台中稱為「生成式語言 API」)。

  • 請不要新增任何應用程式限制，否則 Firebase AI Logic 代理服務將無法正常運作。

我的 Gemini API 金鑰遭到盜用。我需要做些什麼？

如果您的 Gemini API 金鑰遭到入侵，請按照操作說明變更用於呼叫 Gemini Developer API 的 Gemini API 金鑰。

此外，請參閱建議的最佳做法，確保 Gemini API 金鑰安全無虞。

如何修正這個 404 錯誤？Firebase AI Logic genai config not found

如果您嘗試使用 Gemini Developer API，但收到 Firebase AI Logic genai config not found 的 404 錯誤，通常表示您的 Firebase 專案沒有有效的 Gemini API 金鑰，無法搭配 Firebase AI Logic 用戶端 SDK 使用。

以下是這項錯誤最可能的原因：

• 您尚未為 Gemini Developer API 設定 Firebase 專案。

  操作說明：
  在 Firebase 控制台中，前往「Firebase AI Logic」頁面。按一下「開始使用」，然後選取 Gemini Developer API。啟用 API 後，控制台會為 Gemini Developer API 設定專案。完成工作流程後，請再次提出要求。

• 如果您最近才在 Firebase 主控台中完成 Firebase AI Logic 設定工作流程，則您的 Gemini API 金鑰可能還無法用於所有地區的所有必要後端服務。

  解決方法：
  請稍候幾分鐘，然後再嘗試提出要求。

• 您的 Gemini API 金鑰可能已從 Firebase 專案中刪除。

  操作說明：
  瞭解如何變更 Firebase AI Logic 使用的 Gemini API 金鑰。

如何修正這個 400 錯誤？Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

如果您嘗試傳送含有 Cloud Storage for Firebase 網址的多模態要求，可能會遇到下列 400 錯誤：
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

這個錯誤是因為在專案中啟用 Vertex AI API 時，該專案未正確自動佈建必要的服務代理。這是部分專案的已知問題，我們正在進行全局修正。

以下是修正專案的解決方法，並正確佈建這些服務代理程式，以便在多模態要求中加入 Cloud Storage for Firebase 網址。您必須是專案的擁有者，而且只需為專案完成這組工作一次。

1. 使用 gcloud CLI 存取及驗證。
   最簡單的方法是從 Cloud Shell 開始。詳情請參閱 Google Cloud 說明文件。

2. 如果出現提示，請按照終端機顯示的操作說明，針對 Firebase 專案執行 gcloud CLI。

   您需要 Firebase 專案 ID，可在 settings 專案設定 中找到。Firebase 主控台。

3. 請執行下列指令，在專案中佈建必要的服務代理程式：

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
   

4. 請稍候幾分鐘，確保服務代理已佈建完成，然後再重試傳送包含 Cloud Storage for Firebase 網址的多模態要求。

如果等待幾分鐘後仍收到這則錯誤訊息，請與 Firebase 支援團隊聯絡。

如何修正這個 400 錯誤？API key not valid. Please pass a valid API key.

如果您收到 400 錯誤，並顯示 API key not valid. Please pass a valid API key.，通常表示 Firebase 設定檔/物件中的 API 金鑰不存在，或是未設定為與應用程式和/或 Firebase 專案搭配使用。

請確認 Firebase 設定檔/物件中列出的 API 金鑰，與應用程式的 API 金鑰相符。您可以在 Google Cloud 控制台的「API 和服務」>「憑證」面板中查看所有 API 金鑰。

如果發現兩者不相符，請取得新的 Firebase 設定檔/物件，然後取代應用程式中的設定檔/物件。新的設定檔/物件應包含應用程式和 Firebase 專案的有效 API 金鑰。

如何修正這個 403 錯誤？Requests to this API firebasevertexai.googleapis.com ... are blocked.

如果您收到 403 錯誤，並顯示 Requests to this API firebasevertexai.googleapis.com ... are blocked.，通常表示 Firebase 設定檔/物件中的 API 金鑰，在您要使用的產品的許可清單中沒有必要的 API。

請確認應用程式使用的 API 金鑰含有所有金鑰「API 限制」許可清單中的必要 API。針對 Firebase AI Logic，API 金鑰的許可清單中至少必須包含 Firebase AI Logic API。

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

如何修正這個 403 錯誤？PERMISSION_DENIED: The caller does not have permission.

如果您收到 403 錯誤，並顯示 PERMISSION_DENIED: The caller does not have permission.，通常表示 Firebase 設定檔/物件中的 API 金鑰屬於其他 Firebase 專案。

請確認 Firebase 設定檔/物件中列出的 API 金鑰，與應用程式的 API 金鑰相符。您可以在 Google Cloud 控制台的「API 和服務」>「憑證」面板中查看所有 API 金鑰。

如果發現兩者不相符，請取得新的 Firebase 設定檔/物件，然後取代應用程式中的設定檔/物件。新的設定檔/物件應包含應用程式和 Firebase 專案的有效 API 金鑰。