使用 Firebase AI Logic 构建 AI 赋能的客户支持客服

1. 简介

在本 Codelab 中，您将向一家名为 Rugged Terrain Guide 的户外装备电子商务商店添加一个智能客户支持聊天小部件。您将使用 Firebase AI Logic 构建此代理，并了解如何配置服务器端提示模板 (product-agent)，该模板可处理 AI 的角色设定、严格的安抚预算规则，并动态使用商品清单作为上下文。

您应执行的操作：

  • 获取此 Codelab 的 Web 应用的起始代码。
  • 设置 Firebase 项目。
  • 在 Web 应用中设置和初始化 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. 对于此 Codelab，您不需要 使用 Google Analytics（分析），因此请关闭 Google Analytics（分析）选项。
  7. 点击创建项目，等待您的项目完成预配，然后点击继续。

升级您的 Firebase 定价方案

如需使用此 Codelab 中的 Firebase 服务，您的 Firebase 项目必须采用随用随付 (Blaze) 定价方案，这意味着该项目与一个Cloud Billing 账号相关联。

  • Cloud Billing 账号要求提供支付方式，例如信用卡。
  • 如果您刚开始接触 Firebase 和 Google Cloud，请确认您是否有资格获得 $300 赠金和免费试用 Cloud Billing 账号。
  • 如果您是作为活动的一部分完成此 Codelab，请询问主办方是否有可用的 Cloud 赠金。

如需将项目升级到 Blaze 方案，请按以下步骤操作：

  1. 在 Firebase 控制台中，选择升级您的方案。
  2. 选择 Blaze 方案。按照屏幕上的说明将 Cloud Billing 账号与您的项目相关联。
    如果您需要创建 Cloud Billing 账号作为此升级的一部分，则可能需要返回 Firebase 控制台中的升级流程以完成升级。

4. 设置 Firebase 服务并关联应用

对于此 Codelab，您需要在 Firebase 项目中设置 Cloud Storage for Firebase 和 Firebase AI Logic。您还需要将应用源代码与 Firebase 项目相关联。

设置 Cloud Storage for Firebase

此 Codelab 使用 Cloud Storage for Firebase 来存储产品说明。

  1. 在 Firebase 控制台中，前往数据库和存储空间 > 存储空间。
  2. 点击开始使用 。
  3. 为默认存储分区选择一个位置。
    US-WEST1、US-CENTRAL1 和 US-EAST1 中的存储分区可为 Google Cloud Storage 使用“始终免费”层级。所有其他位置的存储分区都遵循 Google Cloud Storage 价格和用量。
  4. 点击生产模式 。在下面的步骤中，您将更新这些安全规则，使其专门用于此 Codelab。
  5. 点击创建 。
  6. 更新安全规则：
    1. 存储分区预配完毕后，前往规则 标签页。
    2. 复制以下规则，然后将其粘贴到相应位置：
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. 点击发布 。
  7. 上传起始代码中的产品说明：
    1. 点击存储分区的文件 标签页。
    2. 点击上传文件 ，然后上传起始代码中的 products.txt 文件。此文件位于：src/data/products.txt。

配置 Firebase AI Logic

Firebase AI Logic 是您在此 Codelab 中使用的主要 Firebase 服务。

  1. 在 Firebase 控制台中，前往 AI 服务 > AI Logic。
  2. 点击开始使用 。
  3. 在 Vertex AI Gemini API 卡片上，点击开始使用此 API ，然后按照屏幕上的说明操作。此流程将启用您使用 Firebase AI Logic 和 Vertex AI Gemini API 所需的 API。
  4. （可选） 选择启用 AI 监控 ，以便观察各种应用级指标和用量，从而全面了解通过 Firebase AI Logic 发出的请求。

将代码与 Firebase 项目相关联

在设置 Firebase AI Logic 的过程中，系统会提示您创建 Firebase Web 应用并将配置添加到源代码中。

  1. 在 Firebase AI Logic 设置流程中看到提示时，点击 Web () 图标以注册新的 Web 应用。
  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. 创建服务器端提示模板

您将使用 Dotprompt 语法 在服务器上安全地管理指令，而不是在客户端应用中硬编码复杂的 AI 提示。

这样可以防止最终用户看到机密的“安抚预算”规则。

  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 的内容复制到提示和可选系统指令 字段中。这会安全地指示模型如何以“Rugged Operator”的身份运行并注入商品清单。
  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，以确保只有实际的 Web 应用可以调用 Vertex AI 生成式模型，从而阻止机器人和未经授权的客户端。

  1. 在 Firebase 控制台中，前往构建 > App Check 。
  2. 点击应用 标签页，展开 Web 应用 (Rugged Web)，然后点击 reCAPTCHA Enterprise 提供程序。
  3. 选择创建新的 reCAPTCHA Enterprise 密钥 ，然后填写提示：
    • 名称: Codelab Key
    • 网域：添加 localhost 和 127.0.0.1，以便允许本地 Vite 服务器发出请求。
  4. 点击保存 以注册应用。
  5. 注册后，Firebase 控制台将显示您的网站密钥 。复制此字符串。
  6. 在代码编辑器中，再次打开 src/firebase.ts。
  7. 在顶部添加以下 import：
    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. （可选）清理 Codelab 中的资源

为避免可能向您的 Google Cloud Billing 账号收取费用，您可以删除在此 Codelab 期间创建的资源。

  1. 转到 Firebase 控制台。
  2. 选择 rugged-terrain-ai 项目。
  3. 前往项目设置 （齿轮图标）。
  4. 滚动到底部，然后点击删除项目 。
  5. 按照屏幕上的说明确认删除。

10. 恭喜！

🎊 任务完成！您已成功集成一个强大的、由模板驱动的 AI 客户支持代理。

您已完成以下操作：

  • 在客户端应用上初始化 Firebase 和 Vertex AI 后端。
  • 使用 Handlebars 和严格的输入架构配置安全的服务器端提示模板 ，以定义代理的复杂行为。
  • 动态调用 LLM ，安全地传递聊天记录和上下文产品 ID，而不会向客户端公开内部提示逻辑。

接下来怎么做？