使用订餐 AI 代理 API 集成菜单数据

本指南介绍了如何将餐厅菜单数据结构化、转换并注入到 Food Ordering AI Agent Menu API 中。这样一来，AI 智能体就能了解您的菜单产品，并准确地接收客户的订单。

准备工作

在您使用 Food Ordering AI Agent API 注入和管理菜单之前，请先执行以下操作：

  1. 启用 Food Ordering AI Agent API：

      gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT

  2. 确保您拥有必要的 IAM 权限。向与该 API 互动的用户或服务账号授予以下 Identity and Access Management (IAM) 角色：

    • Food Ordering Agent Admin (roles/foodorderingaiagent.admin)：此角色提供对所有 Food Ordering AI Agent 资源的完全访问权限，包括品牌、商店和菜单，可用于创建、读取、更新和删除这些资源。

    您可以使用 Google Cloud 控制台、gcloud 命令行工具或 IAM API 授予 IAM 角色。如需了解详情，请参阅授予 IAM 角色。

    如需使用 Google Cloud 控制台授予角色，请执行以下操作：

    1. 在 Google Cloud 控制台中，前往 IAM 页面。
    2. 点击 Add（添加）。
    3. 输入主账号（用户或服务账号电子邮件地址）。
    4. 选择 Food Ordering AI Agent Admin 角色。
    5. 点击保存。

    如果没有适当的权限，则创建或修改品牌、商店或菜单的 API 调用会被拒绝。Food Ordering Agent Viewer 角色仅授予只读权限，因此不足以完成本指南中所述的任务。

概览

Food Ordering AI Agent Menu API 旨在实现灵活性，可适应各种菜单结构，从简短的单点菜品列表到包含嵌套修饰符和套餐的复杂菜单。该 API 围绕以下几个关键概念构建而成：

  • 菜单：所有可订购实体的顶级容器。
  • 商品：表示菜单中可订购的顶级商品，例如餐点、主菜或任何可单独订购的商品。Item 可以引用 ModifierGroup。
  • ModifierGroup：一组可应用于 Item 或另一个 Modifier 的 Modifier 选项（允许嵌套）。例如“选择配菜”“添加配料”或“选择饮料口味”。
  • 加料项：ModifierGroup 中的单个选项，例如“薯条”“加奶酪”或“可乐”。修饰符可以调整价格，还可以拥有自己的嵌套 ModifierGroup。
  • MenuCategory：用于将 Item 整理成多个部分，以便显示和理解（例如，“开胃菜”“汉堡”“饮料”）。

主要概念和结构

本部分详细介绍了 Food Ordering AI Agent Menu API 架构的核心组件及其结构。了解这些概念对于正确建模菜单数据至关重要。

内容

菜单上的每个不同项都应定义为 Item。关键字段包括：

  • id：菜单中的唯一标识符。
  • display_name：面向客户的名称。
  • base_price：商品的底价。
  • modifier_groups：可应用于相应商品的 ModifierGroup 的引用。
  • category_ids：相应商品所属的 MenuCategory ID 的引用。
  • availability：指定商品何时可供购买（例如按状态或时段）。如果未指定，则默认值为 STATUS_AVAILABLE。

修饰符和 ModifierGroups

借助修饰符，您可以自定义项。

  • ModifierGroup 定义了一组选项，包括选择次数下限或上限等限制。必须包含至少一个 Modifier。
  • Modifier表示实际的选项。它们可以具有 price_adjustment，并且可以递归引用其他 ModifierGroup 以实现嵌套自定义（例如，“套餐”Item 可能具有“选择饮料”ModifierGroup，而该组中的“苏打水”Modifier 可能具有“选择口味”ModifierGroup）。

示例 1：配料

“培根芝士汉堡”Item 可能会引用“配料”ModifierGroup。此 ModifierGroup 将包含“加奶酪”“不加洋葱”等 Modifier。

示例 2：套餐

有些菜单的结构很复杂，包含多个嵌套选项，例如套餐或“组合”。组合可以建模为 Item，其中包含多个表示组合组成部分的 ModifierGroup。例如，一个“汉堡套餐”Item，包含一份固定主菜，搭配多种可选的配菜和饮料，可以用以下方式建模：

  • 侧面 ModifierGroup（例如“侧面选择”）。
    • 每个侧面选项都以 Modifier（例如“薯条”“沙拉”）。
      • 每个饮料选项都可以引用嵌套的 ModifierGroup（例如“冰块选项”“饮料大小”），这些变量又会引用 Modifier（例如“不加冰”“大杯饮料”）。
  • 饮料的 ModifierGroup（例如，“饮料”）。
    • 每种饮料选项都以 Modifier 为模型。
      • 每个饮料选项都可以引用嵌套的 ModifierGroup（例如“冰块选项”“饮料大小”），而这些属性又会引用 Modifier（例如“不加冰”“大杯饮料”）。
  • 主菜的配料的 ModifierGroup。（例如，“Extra Cheese”“Bacon”）。

可用性

Item 和 Modifier 上的 Availability 消息可让您指定：

  • status：STATUS_AVAILABLE、STATUS_OUT_OF_STOCK 等
  • daypart_availability：如果商品仅在特定时段提供，则链接到特定时段 ID（例如 “早餐菜单”）。

集成属性

Item、Modifier 和 ModifierGroup 消息包含 integration_attributes 字段。此字段（ItemIntegrationAttributes、ModifierIntegrationAttributes 等）包含一个名为 custom_integration_attributes 的 google.protobuf.Struct。您可以使用此方法存储任意键值数据，例如：

  • 销售终端 (POS) 系统中的 ID。
  • SKU 或其他内部代码。
  • 下游订单处理或 POS 集成所需的任何其他元数据。

此数据由 AI 代理以不透明方式传递。

标签

您可以使用 Menu 资源中的 labels 字段将元数据附加到菜单，以帮助进行集成和调试。

标签是一项便利功能，不会影响 AI 代理的行为。

创建菜单

菜单通过 MenuService 中的 CreateMenu RPC 调用进行提取。

步骤

  1. 转换数据：将现有菜单数据（来自 POS、API 或其他来源）转换为 google.cloud.foodorderingaiagent.v1beta.Menu 消息定义的结构。这包括将您的商品、加项、类别和价格映射到相应的 API 消息类型。
  2. 构建 CreateMenuRequest：
    • 设置 parent 字段（例如，projects/PROJECT/locations/LOCATION）。
    • 使用转换后的 Menu 对象填充 menu 字段。
    • 可以选择提供 menu_id。
  3. 调用 API：将 CreateMenuRequest 发送到 MenuService.CreateMenu 端点。API 会先清理菜单，然后验证菜单，并返回最终的 Menu 对象。
  4. 处理菜单更新：每次更新菜单源数据（例如，推出新产品或产品变为不可用）时，都应创建一个新的 Menu 来反映更新后的源数据，并按照处理菜单更新中的说明进行操作。

数据转换指南

转换菜单数据的具体逻辑将取决于源系统的格式和结构（例如，POS API、数据库架构）。以下是一般方法：

  • 导出数据：获取菜单数据的完整导出内容，包括所有商品、加项、价格和关系。
  • 映射实体：
    • 针对源数据中的每个元素，确定 Food Ordering AI Agent API 架构中的相应实体。例如，您的 POS“菜单项”可能会映射到 Item 对象。“订购选项”或“加购项”将映射到 Modifier 和 ModifierGroup。
    • 使用 ID 建立关系。例如，使用 modifier_groups 引用字段将 Item 关联到适用的 ModifierGroup。
  • 处理嵌套结构：如果您的菜单包含嵌套的加项（例如，为套餐中的苏打选择饮料口味），请通过让 Modifier 引用其他 ModifierGroup 来对此进行建模。
  • 填充属性：根据源数据填写 display_name、base_price、price_adjustment 和 availability 等字段。
  • 包含销售终端 (POS) ID：至关重要的是，在 custom_integration_attributes 字段中存储每个商品、修饰符和组的内部销售终端 (POS) 或系统 ID。这样一来，您就可以将代理生成的 Order 翻译回应用中最终订单或正在进行中的购物车的表示形式。
  • 编写脚本：您可能需要编写一个脚本（例如使用 Python、Node.js、Go），用于从来源提取数据、执行转换，并调用 CreateMenu 方法。此脚本将使用 Google Cloud 客户端库进行身份验证和 API 交互。

概念性转换工作流程：

此工作流概述了将菜单数据从源系统转换为 Food Ordering AI Agent API 格式的过程：

  1. 提取和映射类别：
    • 确定源数据中的类别或部分（例如 “开胃菜”“主菜”）。
    • 将每个元素转换为具有唯一 id 和 display_name 的 MenuCategory 对象。
  2. 提取和映射项：
    • 识别源数据中的可售商品。
    • 将每个对象转换为 Item 对象，并填充 id、display_name、base_price 和 availability。
    • 使用 category_ids 字段将每个 Item 映射到其类别。
    • 在 item.integration_attributes.custom_integration_attributes 中存储源系统标识符（例如 PLU 或 SKU）。
  3. 提取和映射修饰符：
    • 确定来源数据中的商品定制、选项或加购项。
    • 相关选项组（例如，“配菜选项”“饮料选项”“额外配料”）转换为 ModifierGroup 对象。在每个 ModifierGroup 上定义最小和最大选择规则。
    • 转换每个单独的选项（例如，将“薯条”“可乐”“加奶酪”等字符串转换为相应 ModifierGroup 中的 Modifier 对象。如果适用，请填充 price_adjustment。
    • 在 modifier_group.integration_attributes.custom_integration_attributes 和 modifier.integration_attributes.custom_integration_attributes 中存储源系统标识符。
  4. 建立关系：
    • 对于每个 Item，使用适用于它的 ModifierGroup 的 id 的引用填充其 modifier_groups 字段。
    • 如果 Modifier 允许进一步自定义（例如，为“苏打水”修饰符选择口味），请填充其 modifier_groups 字段以创建嵌套修饰符。
  5. 组装和提取：
    • 将所有 MenuCategory、Item、ModifierGroup 和 Modifier 对象合并到单个 Menu 消息中的列表中。
    • 使用完全组装的 Menu 消息作为输入来调用 CreateMenu RPC。

处理菜单更新

菜单是不可变的。使用 CreateMenu RPC 调用创建菜单后，便无法修改。如需将菜单更新（例如更改商品价格、修改选项或调整供应情况）传播到菜单中，您必须通过再次调用 CreateMenu 来创建新的菜单资源。您菜单的每个版本都应作为新的 Menu 资源进行提取，并具有唯一的 menu_id。

植入新版菜单的过程与首次植入菜单的过程相同，并且会经历相同的清理和验证步骤。在处理订单时，代理的行为将始终反映与会话配置中引用的 Store 相关联的最近创建的 Menu。

自动菜单清理

CreateMenu API 会自动执行多项清理步骤，以修正常见问题并确保菜单内容在整个 API 中保持一致。在进行这些清理后，系统会应用验证，以简化客户端的菜单集成：

  • 默认可用性：未明确指定 Availability.Status 的 Item 和 Modifier 设置为 STATUS_AVAILABLE。
  • 舍弃未被引用的实体：未被任何 Item 传递性引用的 Modifier 和 ModifierGroup 会从菜单中移除，因为它们无法排序。
  • 舍弃空的修饰符组：舍弃不包含 modifier_ids 的 ModifierGroup，并移除对它们的任何引用。

清理完成后，API 会根据一组严格的规则验证菜单，以确保其格式正确，并且可以被 AI 代理可靠地使用。如果验证失败，CreateMenu 调用将返回一条详细说明问题的错误消息。主要验证包括：

  • 必填字段：确保所有必填字段（例如 id、display_name 和 availability.status）都存在。
  • 唯一 ID：所有 Item、Modifier 和 ModifierGroup 都必须在菜单中具有唯一 ID。
  • 唯一显示名称：
    • 所有 Item 都必须具有唯一的 display_name。
    • 在任何给定的 ModifierGroup 中，所有包含的 Modifier 都必须具有唯一的 display_name。
  • 参考完整性：
    • Item 或 Modifier 引用的所有 modifier_group_ids 都必须存在于菜单中。
    • ModifierGroup 引用的所有 modifier_ids 都必须存在于菜单中。
    • ModifierGroupReference 中指定的默认修饰符必须存在于所引用的 ModifierGroup 中。
    • 如果 Modifier 使用 item_id 引用 Item，则该 Item 必须存在。
  • 修饰符组限制：
    • ModifierGroup不得为空。
    • 系统会检查 ModifierGroup 内的最小或最大选择次数是否在逻辑上保持一致。
    • Item 或 Modifier 级 modifier_constraints 会根据所引用 ModifierGroup 的选择计数限制进行验证，以确保它们是可满足的。
  • 嵌套深度：嵌套修饰符的深度受到限制（例如，Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier...)，最多 5 个级别。
  • 时段验证：如果 Availability 中使用了时段，则必须在关联的 Store 资源中定义这些时段。
  • 修饰符商品引用：使用 item_id 引用 Item 的 Modifier 不得设置 display_name 或 availability 等字段，因为这些字段是从所引用的 Item 继承的。

如果违反了上述任何验证规则，系统将无法创建或更新菜单。错误消息会详细说明哪些实体导致了违规。

API 参考文档

如需详细了解所有消息和字段，请参阅 Food Ordering AI Agent API RPC 参考文档。

最佳做法

  • 唯一 ID：确保 Menu 范围（针对 Item、Modifier、ModifierGroup、MenuCategory）内的所有 id 字段都是唯一的。
  • 清晰的名称：使用清晰且便于客户理解的 display_name。为语义不同的产品提供不同的 display_name，以引导代理正确消除歧义。
  • 有效组合模型：将套餐视为 Item，其中 ModifierGroup 表示配菜、饮料和其他选项，如套餐中所述。这样可确保客服人员能够正确引导客户选择套餐。
  • 使用集成属性：在 custom_integration_attributes 中存储任何必要的 POS 或内部系统标识符，以实现无缝订单集成。
  • 管理库存状况：及时更新Availability状态。
  • 全面测试：在提取数据后，通过各种订单组合测试代理对菜单的理解程度。