本頁面由 Cloud Translation API 翻譯而成。

搭配使用伺服器端遠端設定搭配 Cloud Functions 和 Vertex AI

本指南說明如何搭配使用第 2 代 Cloud Functions 和伺服器端遠端設定，對 Vertex AI Gemini API 進行伺服器端呼叫。

在這個教學課程中，您會將遠端設定新增至類似聊天機器人的函式，運用 Gemini 模型回答使用者問題。遠端設定功能會管理 Gemini API 輸入內容 (包括您將在收到的使用者查詢之前顯示的提示)，而您可以在 Firebase 控制台中視需要更新這些輸入內容。您也會使用 Firebase 本機模擬器套件來測試和偵錯函式。確認函式能正常運作之後，您就會在 Google Cloud 中部署和測試該函式。

先備知識

本指南假設您已熟悉如何使用 JavaScript 開發應用程式。

設定 Firebase 專案

如果您還沒有 Firebase 專案：

登入 Firebase 控制台。
按一下「建立專案」，然後使用以下任一選項：
- 選項 1：在「建立專案」工作流程的第一個步驟中輸入新專案名稱，即可建立新的 Firebase 專案 (以及基礎 Google Cloud 專案)。
- 方法 2：在「建立專案」工作流程的第一個步驟中，從下拉式選單選取 Google Cloud 專案名稱，即可「新增 Firebase」至現有的 Google Cloud 專案。
看到提示訊息時，您「不需要」設定 Google Analytics (分析)，即可使用此解決方案。
繼續按照畫面上的指示建立專案。

如果您已有 Firebase 專案：

前往「設定開發環境」。

設定開發環境

您需要 Node.js 環境來編寫函式，而您需要 Firebase CLI，才能將函式部署至 Cloud Functions 執行階段。

安裝 Node.js 和 npm。

如要安裝 Node.js 和 npm，建議使用 Node Version Manager。

重要事項： 建議您使用 Node.js v20 以上版本。如需持續支援 Node.js 版本支援的重要資訊，請參閱「設定執行階段選項」一文。
使用您偏好的方法安裝 Firebase CLI。例如，如要使用 npm 安裝 CLI，請執行下列指令：
```
npm install -g firebase-tools@latest
```
這個指令會安裝全球通用的 firebase 指令。如果這個指令失敗，您可能需要變更 npm 權限。

如要更新至最新版 firebase-tools，請再次執行相同的指令。
安裝 firebase-functions 和 firebase-admin，並使用 --save 將其儲存到 package.json：
```
npm install firebase-functions@latest firebase-admin@latest --save
```

您現在可以開始實作此解決方案。

導入作業

請按照下列步驟，使用遠端設定和 Vertex AI 建立、測試及部署第 2 代 Cloud Functions：

在 Google Cloud 控制台中啟用 Vertex AI 建議的 API。
初始化專案並安裝節點依附元件。
為 Admin SDK 服務帳戶設定 IAM 權限及儲存金鑰。
建立函式。
建立伺服器專屬的遠端設定範本。
部署函式並在 Firebase 本機模擬器套件中測試。
將函式部署至 Google Cloud。

步驟 1：在 Google Cloud 控制台中啟用 Vertex AI 建議的 API

開啟 Google Cloud 控制台，然後在系統提示時選取專案。
在控制台頂端的「Search」欄位中，輸入 Vertex AI，然後等待 Vertex AI 出現在搜尋結果中。
選取「Vertex AI」。Vertex AI 資訊主頁會隨即顯示。
點選「Enable All Recommended APIs」。

API 啟用作業可能需要一些時間才能完成。在啟用作業完成前，請讓頁面保持啟用狀態並保持開啟。
如果未啟用計費功能，系統會提示您新增或連結 Cloud Billing 帳戶。啟用帳單帳戶後，請返回 Vertex AI 資訊主頁，確認已啟用所有建議的 API。

步驟 2：初始化專案並安裝節點依附元件

在電腦上開啟終端機，然後前往您打算建立函式的目錄。
登入 Firebase：
```
firebase login
```
執行下列指令，初始化 Cloud Functions for Firebase：
```
firebase init functions
```
選取「使用現有專案」，並指定專案 ID。
系統提示您選取語言時，請選擇「JavaScript」並按下 Enter 鍵。
至於其他選項，則選取預設設定。

系統會在目前的目錄中建立 functions 目錄。您將在當中找到用來建構函式的 index.js 檔案、包含函式依附元件的 node_modules 目錄，以及包含套件依附元件的 package.json 檔案。
使用 --save 執行下列指令，新增 Admin SDK 和 Vertex AI 套件，確保套件已儲存至 package.json 檔案：
```
cd functions
npm install firebase-admin@latest @google-cloud/vertexai --save
```

您的 functions/package.json 檔案現在應如下所示，其中已指定最新版本：

  {
    "name": "functions",
    "description": "Cloud Functions for Firebase",
    "scripts": {
      "serve": "firebase emulators:start --only functions",
      "shell": "firebase functions:shell",
      "start": "npm run shell",
      "deploy": "firebase deploy --only functions",
      "logs": "firebase functions:log"
    },
    "engines": {
      "node": "20"
    },
    "main": "index.js",
    "dependencies": {
      "@google-cloud/vertexai": "^1.1.0",
      "firebase-admin": "^12.1.0",
      "firebase-functions": "^5.0.0"
    },
    "devDependencies": {
      "firebase-functions-test": "^3.1.0"
    },
    "private": true
  }

請注意，如果您使用的是 ESLint，您會看到包含該 ESLint 的汙染物。此外，請確認節點引擎版本與安裝的 Node.js 版本，以及您最終在 Google Cloud 上執行的版本相符。例如，如果 package.json 中的 engines stanza 設為 Node 18 版本，且您使用 Node.js 20，請將檔案更新為使用 20：

  "engines": {
    "node": "20"
  },

步驟 3：設定 Admin SDK 服務帳戶的 IAM 權限並儲存金鑰

在本解決方案中，您將使用 Firebase Admin SDK 服務帳戶執行函式。

在 Google Cloud 控制台中開啟「IAM 與管理」頁面，然後找出 Admin SDK 服務帳戶 (名為 firebase-adminsdk)。
選取帳戶，然後按一下「編輯主體」。「Edit access」(編輯存取權) 頁面隨即顯示。
按一下「新增其他角色」，選取「遠端設定檢視者」。
按一下「新增其他角色」，選取「AI 平台開發人員」。
按一下「新增其他角色」，選取「Vertex AI 使用者」。
按一下「Add another role」(新增其他角色)，然後選取「Cloud Run Invoker」。
點選「Save」。

接著，匯出 Admin SDK 服務帳戶的憑證，並儲存在 GOOGLE_APPLICATION_CREDENTIALS 環境變數中。

在 Google Cloud 控制台中，開啟「Credentials」(憑證) 頁面。
按一下「Admin SDK」服務帳戶，開啟「詳細資料」頁面。
按一下「鍵」。
依序按一下「新增金鑰」 >「建立新的金鑰」。
確認您已選取「JSON」做為「金鑰類型」，然後按一下「建立」。
將金鑰下載至電腦上的安全位置。

在終端機中，將金鑰匯出為環境變數：

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

步驟 4：建立函式

在這個步驟中，您將建構一個函式來處理使用者輸入內容，並產生 AI 技術輔助的回應。您將合併多個程式碼片段來建立全方位函式，用於初始化 Admin SDK 和 Vertex AI Gemini API、使用遠端設定設定預設參數、擷取最新的遠端設定參數、處理使用者輸入內容，以及將回應串流給使用者。

在程式碼集中，在文字編輯器或 IDE 中開啟 functions/index.js。

刪除現有內容，然後新增 Admin SDK、遠端設定和 Vertex AI SDK，並在該檔案中貼上下列程式碼，初始化應用程式：

const { onRequest } = require("firebase-functions/v2/https");
const logger = require("firebase-functions/logger");

const { initializeApp } = require("firebase-admin/app");
const { VertexAI } = require('@google-cloud/vertexai');
const { getRemoteConfig } = require("firebase-admin/remote-config");

// Set and check environment variables.
const project = process.env.GCLOUD_PROJECT;

// Initialize Firebase.
const app = initializeApp();

設定函式在無法連線至遠端設定伺服器時，要使用的預設值。本解決方案會將 textModel、generationConfig、safetySettings、textPrompt 和 location 設為與遠端設定參數相對應的遠端設定參數，您將在本指南中進一步調整這些參數。如要進一步瞭解這些參數，請參閱 Vertex AI Node.js 用戶端。

或者，您也可以設定參數來控管您是否可存取 Vertex AI Gemini API (本例中為 vertex_enabled 的參數)。在測試函式時，這項設定非常實用。在下列程式碼片段中，這個值設為 false，因此當您測試基本函式部署時，這個值會略過使用 Vertex AI 的程序。如果設為 true，就會叫用 Vertex AI Gemini API。
```
// Define default (fallback) parameter values for Remote Config.
const defaultConfig = {

  // Default values for Vertex AI.
  model_name: "gemini-1.5-flash-preview-0514",
  generation_config: [{
    "stopSequences": [], "temperature": 0.7,
    "maxOutputTokens": 64, "topP": 0.1, "topK": 20
  }],
  prompt: "I'm a developer who wants to learn about Firebase and you are a \
    helpful assistant who knows everything there is to know about Firebase!",
  safety_settings: [{
    "category":
      "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT",
    "threshold": "HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE"
  }],
  location: 'us-central1',

  // Disable Vertex AI Gemini API access for testing.
  vertex_enabled: false
};
```

建立函式並設定伺服器端遠端設定：

// Export the function.
exports.generateWithVertex = onRequest(async (request, response) => {

  try {

    // Set up Remote Config.
    const rc = getRemoteConfig(app);

    // Get the Remote Config template and assign default values.
    const template = await rc.getServerTemplate({
      defaultConfig: defaultConfig
    });

    // Add the template evaluation to a constant.
    const config = template.evaluate();

    // Obtain values from Remote Config.
    const textModel = config.getString("model_name") ||
        defaultConfig.model_name;
    const textPrompt = config.getString("prompt") || defaultConfig.prompt;
    const generationConfig = config.getString("generation_config") ||
        defaultConfig.generation_config;
    const safetySettings = config.getString("safety_settings") ||
        defaultConfig.safety_settings;
    const location = config.getString("location") ||
        defaultConfig.location;
    const vertexEnabled = config.getBoolean("is_vertex_enabled") ||
        defaultConfig.vertex_enabled;

設定 Vertex AI 並新增即時通訊和回應邏輯：

  // Allow user input.
  const userInput = request.query.prompt || '';

  // Instantiate Vertex AI.
    const vertex_ai = new VertexAI({ project: project, location: location });
    const generativeModel = vertex_ai.getGenerativeModel({
      model: textModel,
      safety_settings: safetySettings,
      generation_config: generationConfig,
    });

    // Create the chat; append user input to Remote Config-defined prompt.
    const chat = generativeModel.startChat();
    const chatInput = textPrompt + " " + userInput;

    if (!chatInput) {
      return res.status(400).send('Missing text prompt');
    }
    // If vertexEnabled isn't true, do not send queries to Vertex AI.
    if (vertexEnabled !== true) {
      response.status(200).send({
        message: "Vertex AI call skipped. Vertex is not enabled."
      });
      return;
    }

    console.log("\nRunning with model ", textModel, ", prompt: ", textPrompt,
      ", generationConfig: ", generationConfig, ", safetySettings: ",
      safetySettings, " in ", location, "\n");

    const result = await chat.sendMessageStream(chatInput);
    response.writeHead(200, { 'Content-Type': 'text/plain' });

    for await (const item of result.stream) {
      const chunk = item.candidates[0].content.parts[0].text;
      console.log("Received chunk:", chunk);
      response.write(chunk);
    }

    response.end();

  } catch (error) {
    console.error(error);
    response.status(500).send('Internal server error');
  }
});

儲存並關閉檔案。

步驟 5：建立伺服器專屬的遠端設定範本

接下來，建立伺服器端遠端設定範本，並設定要用於函式的參數和值。如何建立伺服器專屬的遠端設定範本：

開啟 Firebase 控制台，從導覽選單中展開「Run」(執行) 並選取「Remote Config」(遠端設定)。
從遠端設定頁面頂端的「Client/Server」選取器，選取「Server」。
- 如果您是第一次使用遠端設定或伺服器範本，請按一下「Create Configuration」。系統會隨即顯示「Create your first server-side parameters」(建立第一個伺服器端參數) 窗格。
- 如果這不是您第一次使用遠端設定伺服器範本，請按一下「Add parameters」。

請定義下列遠端設定參數：

參數名稱	說明	類型	預設值
`model_name`	模型名稱如需可在程式碼中使用的模型名稱最新清單，請參閱「模型版本和生命週期」或「可用的模型名稱」一節。	字串	`gemini-1.5-pro-preview-0514`
`prompt`	提示在使用者的查詢前面加上項目。	字串	`I'm a developer who wants to learn about Firebase and you are a helpful assistant who knows everything there is to know about Firebase!`
`generation_config`	要傳送至模型的參數。	JSON	`[{"stopSequences": ["I hope this helps"],"temperature": 0.7,"maxOutputTokens": 512, "topP": 0.1,"topK": 20}]`
`safety_settings`	Vertex AI 安全性設定。	JSON	`[{"category": "HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "HarmBlockThreshold.BLOCK_LOW_AND_ABOVE"}]`
`location`	要執行 Vertex AI 服務和模型的位置。	字串	`us-central1`
`is_vertex_enabled`	控制查詢是否傳送至 Vertex AI 的選用參數。	布林值	`true`

參數新增完畢後，請仔細檢查參數並確認資料類型正確無誤，然後按一下「發布變更」。

步驟 6：部署函式並在 Firebase 本機模擬器套件中測試

您現在可以使用 Firebase 本機模擬器套件在本機部署及測試函式了。

請確認您已按照步驟 3：為 Admin SDK 服務帳戶設定 IAM 權限，並儲存金鑰中的說明，將 GOOGLE_APPLICATION_CREDENTIALS 設為環境變數。接著，從 functions 目錄的父項目錄中，將函式部署至 Firebase 模擬器：
```
firebase emulators:start --project PROJECT_ID --only functions
```
提示： 您也可以透過從 functions 目錄執行 npm run serve，在模擬器中執行函式。
開啟模擬器的「記錄檔」頁面。這樣應該就會顯示函式已載入。
執行下列指令來存取函式，其中 PROJECT_ID 是您的專案 ID，LOCATION 則是您部署函式的區域 (例如 us-central1)：
```
curl http://127.0.0.1:5001/PROJECT_ID/LOCATION/generateWithVertex
```
提示： 啟動模擬器後，這個連結也會顯示在主控台輸出內容中。你也可以剪下並貼到瀏覽器中。
請等待回應，然後返回 Firebase Emulator 記錄頁面或主控台，查看是否有任何錯誤或警告。
請嘗試傳送部分使用者輸入內容，請注意，由於遠端設定伺服器範本中的 is_vertex_enabled 已設定完成，系統應該透過 Vertex AI Gemini API 存取 Gemini，並可能因此產生費用：
```
curl http://127.0.0.1:5001/PROJECT_ID/LOCATION/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20cats
```
在 Firebase 控制台上變更遠端設定伺服器範本，然後重新存取函式來觀察變更。

步驟 7：將函式部署至 Google Cloud

測試及驗證函式後，您就可以部署至 Google Cloud 並測試運作中的功能。

部署函式

使用 Firebase CLI 部署函式：

firebase deploy --only functions

禁止在未經驗證的情況下存取函式

使用 Firebase 部署函式時，如果機構政策未限制叫用，則根據預設，系統會允許未經驗證的叫用。在測試期間和使用 App Check 確保安全前，建議封鎖未經驗證的存取權。

如何禁止在未經驗證的情況下存取函式：

在 Google Cloud 控制台中開啟 Cloud Run。
依序按一下 generateWithVertex 和「安全性」分頁標籤。
啟用「需要驗證」，然後按一下「儲存」。

將使用者帳戶設為使用 Admin SDK 服務帳戶憑證

由於 Admin SDK 服務帳戶具備所有必要角色和權限，可以執行函式，以及與遠端設定和 Vertex AI Gemini API 互動，因此建議您使用該帳戶來執行函式。為此，您必須能夠從使用者帳戶建立該帳戶的權杖。

下列步驟說明如何設定使用者帳戶，以及要以 Admin SDK 服務帳戶權限執行的功能。

在 Google Cloud 控制台中，啟用 IAM Service Account Credentials API。
將「Service Account Token Creator」角色授予使用者帳戶：在 Google Cloud 控制台中開啟「IAM & Admin」(IAM 與管理) >「IAM」 (身分與存取權管理)，選取您的使用者帳戶，然後按一下「Edit principal」(編輯主體) >「Add another role」(新增其他角色)。
選取「Service Account Token Creator」，然後按一下「Save」。

如要進一步瞭解服務帳戶模擬功能，請參閱 Google Cloud 說明文件中的服務帳戶模擬功能。
開啟 Google Cloud 控制台的「Cloud Functions」頁面，然後點選「函式」清單中的「generateWithVertex」函式。
依序選取「Trigger」(觸發條件) >「Edit」(編輯)，然後展開「Runtime, build, connections and security settings」(執行階段、建構、連線和安全性設定)。
在「Runtime」(執行階段) 分頁中，將「Runtime 服務帳戶」變更為「Admin SDK 帳戶」。
依序按一下「Next」和「Deploy」。

設定 gcloud CLI

如要透過指令列安全地執行及測試函式，您需要透過 Cloud Functions 服務進行驗證，並取得有效的驗證權杖。

如要啟用權杖產生功能，請安裝並設定 gcloud CLI：

如果您尚未在電腦上安裝，請按照「安裝 gcloud CLI」一節所述的方式安裝 gcloud CLI。
取得 Google Cloud 帳戶的存取憑證：
```
gcloud auth login
```
在 gcloud 中設定專案 ID：
```
gcloud config set project PROJECT_ID
```

測試函式

您現在可以在 Google Cloud 中測試函式。如要測試函式，請執行下列指令：

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex \
  -H "Authorization: bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json"

請以使用者提供的資料再試一次：

curl -X POST https://LOCATION-PROJECT_ID.cloudfunctions.net/generateWithVertex?prompt=Tell%20me%20everything%20you%20know%20about%20dogs \
 -H "Authorization: bearer $(gcloud auth print-identity-token)" \
 -H "Content-Type: application/json"

您現在可以變更遠端設定伺服器範本、發布這些變更，以及測試不同選項。

後續步驟

Firebase 建議使用 App Check 保護 Cloud Functions。如要進一步瞭解如何使用 App Check 保護函式，請參閱「為 Cloud Functions 啟用 App Check 強制執行功能」一文。
進一步瞭解 Cloud Functions for Firebase。
進一步瞭解如何在伺服器環境中使用遠端設定。