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

1. 简介

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

您应执行的操作：

  • 获取此 Codelab 的 Web 应用的起始代码。
  • 设置 Firebase 项目。
  • 在 Web 应用中设置并初始化 Firebase 服务（例如 Firebase AI Logic）。
  • 在 Firebase 控制台中配置服务器端提示模板。
  • 通过从类似 React 的 TypeScript 前端对生成式 AI 服务的调用来访问模板。

所需条件：

  • 网络浏览器，例如 Chrome。
  • 基本熟悉 TypeScript 和 Node.js。
  • 您选择的 IDE 或文本编辑器。反重力是不错的选择。

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 账号要求提供付款方式，例如信用卡。
  • 在特殊促销活动期间，或者如果您是在活动中完成此 Codelab，则可能会有 Google Cloud 赠金可用。
  • 如果您刚开始接触 Firebase 和 Google Cloud，请确认您是否有资格获得 $300 赠金和免费试用 Cloud Billing 账号。

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

  1. 在 Firebase 控制台中，选择升级您的方案。
  2. 选择 Blaze 方案。按照屏幕上的说明将 Cloud Billing 账号关联到您的项目。
    • 如果您在此 Codelab 中使用 Google Cloud 赠金，则结算账号可能名为 Google Cloud Platform Trial Billing Account 或 My Billing Account。
    • 如果您需要在此升级过程中创建 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 逻辑。
  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 Web 应用并将配置添加到源代码中。

  1. 在 Firebase AI Logic 设置流程中看到提示时，点击 Web () 图标以注册新的 Web 应用。
  2. 为应用命名（例如，Rugged Web）。
  3. 从设置说明中复制 firebaseConfig 对象。

接下来，更新起始代码：

  1. 在代码编辑器中，打开 src/firebase.ts。
  2. 将现有 firebaseConfig 替换为您从 Firebase 控制台中复制的 firebaseConfig。

您的文件应如下所示：

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. 从为此 Codelab 提供的起始代码中，复制 product-agent.prompt 的内容（在根目录中找到此文件）。然后，将此内容粘贴到 Firebase 控制台中服务器提示模板的提示和（可选）系统指令字段中。此内容安全地指示模型如何以“Rugged Operator”的身份行事并引用产品目录。
  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 来确保只有您的实际 Web 应用才能成功向 Gemini API 发出请求，从而阻止机器人和未经授权的客户端。

  1. 在 Google Cloud 控制台中，依次前往安全性 > Fraud Defense
  2. 点击创建密钥，然后填写以下字段：
    • Display name：Codelab Key
    • 应用类型：Web
    • 网域列表：添加 localhost 和 127.0.0.1，以便允许本地 Vite 服务器发出请求。
  3. 点击创建密钥以注册密钥。
  4. 从“Fraud Defense 密钥详情”页面顶部，将网站密钥 ID 复制到剪贴板。
  5. 在 Firebase 控制台中，依次前往安全性 > App Check。
  6. 点击应用标签页，展开您的 Web 应用 (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 配置并连接支持聊天 widget 后，就可以运行应用了。

  1. 在终端中，运行 Vite 开发服务器：
    npm run dev
  2. 打开提供的本地网址（通常为 http://localhost:5173/）。
  3. 点击右下角的战术支持悬浮操作按钮 (FAB)。
  4. 您可以尝试询问有关产品的问题，例如：
    • “我想找一件防风雨外套”
    • “我的零下温度针织帽有缺陷，该怎么办？”
    • 不断拒绝，以触发 AI 的“安抚预算”逻辑！

9. （可选）清理 Codelab 中的资源

为避免您的 Google Cloud Billing 账号可能产生费用，您可以删除在此 Codelab 中创建的资源。

  1. 在 Firebase 控制台中，依次前往设置 > 常规标签页。
  2. 确保您查看的项目是您为此 Codelab 使用的项目。如果不是您的 Codelab 项目，您可以使用左上角的项目选择器下拉菜单来更改项目。
  3. 前往页面底部，然后点击删除项目。
  4. 按照屏幕上的说明确认删除。

10. 恭喜！

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

您的学习成果：

  • 已初始化的 Firebase 和客户端应用上的 Agent Platform 后端。
  • 配置了安全的服务器端提示模板，使用 Handlebars 和严格的输入架构来定义代理的复杂行为。
  • 动态调用 LLM，安全传递对话记录和上下文产品 ID，同时不会向客户端公开内部提示逻辑。

接下来怎么做？