使用 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 帳戶需要付款方式，例如信用卡。
  • 如果您剛開始使用 Firebase 和 Google Cloud，請確認是否符合 $300 美元抵免額和免費試用 Cloud Billing 帳戶的資格。
  • 如果您是在活動中進行這項程式碼研究室，請詢問主辦單位是否有可用的 Cloud 抵免額。

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

  1. 在 Firebase 控制台中，選取「升級方案」。
  2. 選取 Blaze 方案。按照畫面上的指示，將 Cloud Billing 帳戶連結至專案。
    如果你在升級過程中需要建立 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. 在「Vertex AI Gemini API」資訊卡上，按一下「開始使用這個 API」，然後按照畫面上的指示操作。這個流程會啟用必要 API，讓您搭配 Vertex AI Gemini API 使用 Firebase AI Logic。
  4. (選用) 選取「啟用 AI 監控」，即可觀察各種應用程式層級指標和用量，全面掌握透過 Firebase AI Logic 提出的要求。

將程式碼連結至 Firebase 專案

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

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

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

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

檔案應如下所示：

import { getAI, getTemplateGenerativeModel, VertexAIBackend } 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 VertexAIBackend() });

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

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

這樣一來，使用者就不會看到「補償預算」規則。

  1. 在 Firebase 控制台中，前往「Vertex AI」或「提示詞管理」專區。
  2. 建立新的提示範本，並命名為 product-agent。
  3. 將模型設為 gemini-2.5-flash。
  4. 請按照下列方式定義輸入結構定義：
    input:
  schema:
    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
  5. 將根目錄中的 agent-product.prompt 內容複製到「提示詞和系統指令 (後者可視需求使用)」欄位。這項指令會安全地指示模型如何扮演「強固的作業人員」，並注入產品目錄。
  6. 在 Firebase 控制台中，儲存並發布 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，確保只有實際的網頁應用程式可以呼叫 Vertex AI 生成模型，並封鎖機器人和未授權的用戶端。

  1. 在 Firebase 控制台中，依序前往 建構 > App Check。
  2. 按一下「應用程式」分頁標籤，展開網頁應用程式 (Rugged Web)，然後按一下「reCAPTCHA Enterprise」供應商。
  3. 選取「建立新的 reCAPTCHA Enterprise 金鑰」，然後填寫提示：
    • Name (名稱)：Codelab Key
    • 網域：新增 localhost 和 127.0.0.1，允許本機 Vite 伺服器發出要求。
  4. 按一下「儲存」即可註冊應用程式。
  5. 註冊完成後，Firebase 控制台會顯示您的網站金鑰。複製這個字串。
  6. 在程式碼編輯器中，再次開啟 src/firebase.ts。
  7. 在頂端新增下列匯入項目：
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. 在 initializeApp(firebaseConfig) 呼叫後立即新增 App Check 初始化，並貼上您複製的網站金鑰：
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. 更新 getAI() 函式呼叫，以使用這些權杖。進行下列變更：
    const ai = getAI(app, { backend: new VertexAIBackend(), 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. 選取 rugged-terrain-ai 專案。
  3. 前往「專案設定」(齒輪圖示)。
  4. 捲動至底部，然後按一下「刪除專案」。
  5. 按照畫面上的指示確認刪除。

10. 恭喜！

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

完成的目標：

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

後續步驟