使用 Firebase AI Logic 建構 AI 輔助客戶服務專員

1. 簡介

在本程式碼研究室中，您將在名為「Rugged Terrain Guide」的戶外用品電子商務商店中，新增智慧型客戶服務即時通訊小工具。您將使用 Firebase AI Logic 建構這個代理程式，並瞭解如何設定伺服器端提示詞範本 (product-agent)，處理 AI 角色、嚴格的補償預算規則，以及動態使用產品目錄做為內容。

要執行的步驟：

  • 取得本程式碼研究室網頁應用程式的範例程式碼。
  • 設定 Firebase 專案。
  • 在網頁應用程式中設定及初始化 Firebase 服務 (例如 Firebase AI Logic)。
  • 在 Firebase 控制台中設定伺服器端提示詞範本。
  • 從類似 React 的 TypeScript 前端呼叫生成式 AI 服務，即可存取範本。

您需要準備：

  • 網路瀏覽器，例如 Chrome。
  • 對 TypeScript 和 Node.js 有基本的瞭解。
  • 您選擇的 IDE 或文字編輯器。Antigravity 是不錯的選擇。

2. 取得範例程式碼

  1. 在終端機中，複製範例存放區：
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. 前往程式碼目錄並安裝依附元件：
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. 設定 Firebase 專案

建立 Firebase 專案

  1. 使用 Google 帳戶登入 Firebase 控制台。
  2. 按一下按鈕建立新專案，然後輸入專案名稱 (例如 rugged-terrain-ai)。
  3. 按一下「繼續」。
  4. 如果系統提示，請詳閱並接受 Firebase 條款，然後按一下「繼續」。
  5. (選用) 在 Firebase 控制台中啟用 AI 輔助功能 (稱為「Gemini in Firebase」)。
  6. 本程式碼研究室不需要 Google Analytics，因此請關閉 Google Analytics 選項。
  7. 按一下「建立專案」，等待專案佈建完成，然後按一下「繼續」。

升級 Firebase 定價方案

如要在本程式碼研究室中使用 Firebase 服務，Firebase 專案必須採用即付即用 (Blaze) 定價方案，也就是連結至 Cloud Billing 帳戶。

  • Cloud Billing 帳戶需要付款方式，例如信用卡。
  • 在特別促銷活動期間，或如果您是參加活動並完成這項程式碼研究室，可能可以獲得 Google Cloud 抵免額。
  • 如果您剛開始使用 Firebase 和 Google Cloud，請確認是否符合 $300 美元抵免額和免費試用 Cloud Billing 帳戶的資格。

如要將專案升級至 Blaze 方案，請按照下列步驟操作：

  1. 在 Firebase 控制台中，選取「升級方案」。
  2. 選取 Blaze 方案。按照畫面上的指示，將 Cloud Billing 帳戶連結至專案。
    • 如果您使用 Google Cloud 抵免額進行本程式碼研究室，帳單帳戶可能稱為 Google Cloud Platform Trial Billing Account 或 My Billing Account。
    • 如果您在升級過程中需要建立 Cloud Billing 帳戶，可能需要返回 Firebase 控制台的升級流程，才能完成升級。

4. 設定 Firebase 服務並連結應用程式

在本程式碼實驗室中，您需要在 Firebase 專案中設定 Cloud Storage for Firebase 和 Firebase AI Logic。您也需要將應用程式的原始碼連結至 Firebase 專案。

設定 Cloud Storage for Firebase

本程式碼研究室使用 Cloud Storage for Firebase 儲存產品說明。

  1. 在 Firebase 控制台中，依序前往「資料庫和儲存空間」>「儲存空間」。
  2. 按一下「開始使用」。
  3. 選取預設 Storage bucket 的位置。
    US-WEST1、US-CENTRAL1 和 US-EAST1 中的 bucket 可享有 Google Cloud Storage 的「一律免費」方案。其他所有位置的值區皆遵循 Google Cloud Storage 定價和用量。
  4. 按一下「正式版模式」。在接下來的步驟中，您將更新這些安全規則，使其適用於本程式碼研究室。
  5. 點選「建立」。
  6. 更新安全性規則：
    1. 值區佈建完成後，請前往「規則」分頁。
    2. 複製並貼上下列規則：
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. 按一下「發布」。
  7. 從範例程式碼上傳產品說明：
    1. 按一下 Storage bucket 的「檔案」分頁標籤。
    2. 按一下「Upload File」(上傳檔案)，然後上傳範例程式碼中的 products.txt 檔案。這個檔案位於：src/data/products.txt。

設定 Firebase AI Logic

Firebase AI Logic 是本程式碼實驗室中使用的主要 Firebase 服務。

  1. 在 Firebase 控制台中，依序前往「AI 服務」 >「AI 邏輯」。
  2. 按一下「開始使用」。
  3. 在「Agent Platform Gemini API」資訊卡上，按一下「開始使用這個 API」，然後按照畫面上的指示操作。這個流程會啟用必要的 API，讓您搭配使用 Firebase AI Logic 和 Agent Platform Gemini API。
  4. (選用) 選取「啟用 AI 監控」，即可觀察各種應用程式層級指標和用量，全面掌握透過 Firebase AI Logic 提出的要求。

將程式碼連結至 Firebase 專案

設定 Firebase AI Logic 時，系統會提示您建立 Firebase 網頁應用程式，並將設定新增至原始碼。

  1. 在 Firebase AI Logic 設定流程中，系統會提示您註冊新的網頁應用程式，請按一下「Web」 () 圖示。
  2. 為應用程式命名 (例如 Rugged Web)。
  3. 從設定說明複製 firebaseConfig 物件。

接著，請更新範例程式碼：

  1. 在程式碼編輯器中開啟 src/firebase.ts。
  2. 將現有 firebaseConfig 替換為從 Firebase 控制台複製的內容。

檔案應如下所示：

import { getAI, getTemplateGenerativeModel, AgentPlatformBackend } from "firebase/ai";
import { initializeApp } from "firebase/app";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.firebasestorage.app",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID"
};

// Initialize Firebase
export const app = initializeApp(firebaseConfig);

const ai = getAI(app, { backend: new AgentPlatformBackend() });

5. 建立伺服器端提示詞範本

您可以使用 Dotprompt 語法，在伺服器上安全地管理指令，不必在用戶端應用程式中以硬式編碼方式編寫複雜的 AI 提示。

以免使用者看到「補償預算」規則。

  1. 在 Firebase 控制台中，依序前往「AI 服務」 >「AI 邏輯」 >「提示範本」分頁。
  2. 按一下「建立範本」，然後選擇「空白範本」。
  3. 將範本名稱設為 Product Agent，ID 設為 product-agent。
  4. 將模型設為 gemini-3.1-flash-lite (或最新版本)。
  5. 從本程式碼研究室提供的範例程式碼中，複製 product-agent.prompt 的內容 (在根目錄中找到這個檔案)。然後將這項內容貼到 Firebase 控制台伺服器提示詞範本的「提示詞和 (選用) 系統指令」欄位。這項內容會安全地指示模型如何扮演「強固型裝置操作員」，並參照產品目錄。
  6. 在「測試輸入」欄位中，完全按照下列方式定義輸入結構定義：
    {
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "the customers ask of the robot"
    },
    "productId": {
      "type": "string",
      "description": "the product the customer is looking at right now"
    },
    "history": {
      "type": "array",
      "description": "list of previous history between the user and system",
      "items": {
        "type": "object",
        "required": [
          "role",
          "contents"
        ],
        "properties": {
          "role": {
            "type": "string"
          },
          "contents": {
            "type": "string"
          }
        }
      }
    }
  }
}
  7. 按一下「儲存範本」，即可儲存並發布 product-agent 範本。

6. 呼叫 AI 模型

範本已在伺服器上安全定義，現在只要從應用程式前端呼叫即可。

  1. 在程式碼編輯器中，返回 src/firebase.ts。
  2. 在初始化下方，使用 getTemplateGenerativeModel 連線至範本：
    const model = getTemplateGenerativeModel(ai);

export const callCustomerSupportModel = async (query: string, productId?: string, history?: { role: string, contents: string }[]) => {
    // Generate content using the published 'product-agent' template
    const result = await model.generateContent('product-agent', {
        query,
        productId,
        history,
    });
    return result.response.text();
}

7. 使用 Firebase App Check 保護代理程式

AI 模型功能強大，但如果公開端點未受保護，也可能遭到濫用。請務必使用 Firebase App Check，確保只有實際的網頁應用程式可以向 Gemini API 提出要求，並封鎖機器人和未經授權的用戶端。

  1. 前往 Google Cloud 控制台的「安全性」>「Fraud Defense」
  2. 按一下「建立金鑰」並填寫欄位：
    • 顯示名稱：Codelab Key
    • 應用程式類型：網頁
    • 網域清單：新增 localhost 和 127.0.0.1，允許本機 Vite 伺服器發出要求。
  3. 按一下「建立金鑰」註冊金鑰。
  4. 在 Fraud Defense 金鑰詳細資料頁面頂端，將網站金鑰 ID 複製到剪貼簿。
  5. 在 Firebase 控制台中，依序前往「安全性」 >「App Check」。
  6. 按一下「應用程式」分頁標籤，展開網頁應用程式 (Rugged Web)，然後按一下「reCAPTCHA Enterprise」供應商。
  7. 在「reCAPTCHA Enterprise 網站金鑰」欄位中，貼上「詐欺防護金鑰詳細資料」頁面中的網站金鑰 ID，然後按一下「儲存」。
  8. 在程式碼編輯器中，再次開啟 src/firebase.ts。
  9. 在頂端新增下列匯入項目：
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  10. 在 initializeApp(firebaseConfig) 呼叫後方新增 App Check 初始化作業，並貼上您複製的網站金鑰 ID：
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  isTokenAutoRefreshEnabled: true
});
  11. 更新 getAI() 函式呼叫，以使用這些權杖。進行下列變更：
    const ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });
    將 useLimitedUseAppCheckTokens 的值設為 true，可確保系統套用短期有效權杖，有助於限制後端可能收到的濫用行為。

8. 執行應用程式

完成 Firebase 設定並連結支援即時通訊小工具後，現在可以執行應用程式。

  1. 在終端機中執行 Vite 開發伺服器：
    npm run dev
  2. 開啟提供的本機網址 (通常為 http://localhost:5173/)。
  3. 按一下右下角的「戰術支援」懸浮動作按鈕 (FAB)。
  4. 你可以詢問產品相關問題，例如：
    • 「我想找防風雨外套」
    • 「我的零下低溫毛帽有瑕疵，該怎麼辦？」
    • 繼續延後，觸發 AI 的「安撫預算」邏輯！

9. (選用) 清理程式碼研究室的資源

如要避免 Google Cloud Billing 帳戶產生費用，請刪除本程式碼研究室建立的資源。

  1. 在 Firebase 控制台中，依序前往「設定」 >「一般」分頁。
  2. 請確認您查看的專案是本程式碼研究室使用的專案。如果不是程式碼研究室的專案，請使用左上角的專案挑選器下拉式選單變更專案。
  3. 前往頁面底部，然後按一下「刪除專案」。
  4. 按照畫面上的指示確認刪除。

10. 恭喜！

🎊 任務完成！您已成功整合強大的 AI 顧客服務專員，並採用範本驅動式設計。

您已完成以下事項：

  • 在用戶端應用程式上初始化 Firebase 和 Agent Platform 後端。
  • 使用 Handlebars 和嚴格的輸入結構定義，設定安全的伺服器端提示詞範本，定義代理程式的複雜行為。
  • 動態呼叫 LLM，安全地傳遞對話記錄和脈絡產品 ID，不會向用戶端公開內部提示邏輯。

後續步驟