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

本指南介绍了如何对餐厅菜单数据进行结构化、转换并将其注入到“订餐 AI 智能体菜单 API”中。这样,AI 智能体就能理解您的菜单内容,并准确地接受客户的订单。

准备工作

您必须先完成以下操作,然后才能使用 Food Ordering AI Agent API 注入和管理菜单:

  1. 启用订餐 AI 智能体 API:

      gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT
    
  2. 确保您拥有必要的 IAM 权限。向与该 API 交互的用户或服务账号授予以下 Identity and Access Management (IAM) 角色:

    • Food Ordering Agent Admin (roles/foodorderingaiagent.admin):此角色提供创建、读取、更新和删除所有订餐 AI 智能体资源(包括品牌、商店和菜单)的完整权限。

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

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

    1. 在 Google Cloud 控制台中,前往 IAM 页面。
    2. 点击 Add(添加)。
    3. 输入主账号(用户或服务账号邮箱)。
    4. 选择 订餐 AI 智能体管理员 角色。
    5. 点击保存。

    如果没有适当的权限,用于创建或修改品牌、商店或菜单的 API 调用将被拒绝。Food Ordering Agent Viewer 角色不足以执行本指南中所述的任务,因为它仅授予只读权限。

概览

订餐 AI 智能体菜单 API 旨在提供灵活性,可适应各种菜单结构,从简短的独立商品列表到包含嵌套修饰符和组合餐点的复杂菜单,均可轻松应对。该 API 基于以下几个关键概念构建:

  • 菜单:所有可订购实体的顶级容器。
  • Item:表示菜单中可订购的顶级商品,例如套餐、主菜或任何可单独订购的商品。Item 可以引用 ModifierGroup。
  • ModifierGroup:可应用于 Item 或其他 Modifier(允许嵌套)的一组 Modifier 选项。例如“选择配菜”“添加配料”或“选择饮料口味”。
  • 修饰符:ModifierGroup中的单个选项,例如“薯条”“额外加芝士”或“可乐”。修饰符可以调整价格,也可以有自己的嵌套 ModifierGroup。
  • MenuCategory:用于将 Item 整理到不同部分,以便于显示和理解(例如,“开胃菜”“汉堡”“饮品”)。

主要概念和结构

本部分详细介绍了订餐 AI 智能体 Menu API schema 的核心组件及其结构。了解这些概念对于正确对菜单数据进行建模至关重要。

内容

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

  • id:菜单中的唯一标识符。
  • display_name:面向客户的名称。
  • base_price:商品的基本价格。
  • modifier_groups:对可应用于此商品的 ModifierGroup 的引用。
  • category_ids:对此项所属 MenuCategory ID 的引用。
  • availability:指定商品的供应时间(例如,按状态或时段)。如果未指定,则默认值为 STATUS_AVAILABLE。

Modifiers 和 ModifierGroups

修饰符可用于自定义内容。

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

示例 1:配料

“培根芝士汉堡”Item 可能会引用“配料”ModifierGroup。此 ModifierGroup 将包含“Extra Cheese”(额外加芝士)、“No Onions”(不加洋葱)等 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、数据库架构)的格式和结构。以下是常规方法:

  • 导出数据:获取菜单数据的完整导出文件,包括所有商品、修饰符、价格和关系。
  • 映射实体:
    • 在订餐 AI 智能体 API schema 中,为源数据中的每个元素确定对应的实体。例如,您的 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 交互。

概念转换工作流:

此工作流概述了将菜单数据从源系统转换为订餐 AI 智能体 API 格式的过程:

  1. 提取和映射类别:
    • 识别源数据中的类别或部分(例如“开胃菜”“主菜”)。
    • 将每个对象转换为具有唯一 id 和 display_name 的 MenuCategory 对象。
  2. 提取和映射项:
    • 在源数据中识别可销售的商品。
    • 将每个对象转换为 Item 对象,并填充 id、display_name、base_price 和 availability。
    • 使用 category_ids 字段将每个 Item 映射到其类别。
    • 将源系统标识符(例如 PLU 或 SKU)存储在 item.integration_attributes.custom_integration_attributes 中。
  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_id 的新 Menu 资源进行提取。

提取新版菜单的过程与首次提取菜单的过程相同,并且会经历相同的排查和验证步骤。在处理订单时,代理的行为将始终反映与会话配置中引用的 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 必须存在。
  • 修饰符组限制:
    • ModifierGroups 不能为空。
    • 系统会检查 ModifierGroup 中的选择数量下限或上限,以确保逻辑一致性。
    • Item 或 Modifier 级 modifier_constraints 会根据所引用 ModifierGroup 的选择计数限制条件进行验证,以确保它们可以满足要求。
  • 嵌套深度:嵌套修饰符的深度(例如 Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier…)最多为 5 级。
  • 时段验证:如果在 Availability 中使用了时段,则必须在关联的 Store 资源中定义这些时段。
  • 修饰符商品引用:使用 item_id 引用 Item 的 Modifier 不能设置 display_name 或 availability 等字段,因为这些字段是从引用的 Item 继承的。

如果任何验证规则失败,系统将无法创建或更新菜单。出错提示会详细说明哪些实体导致了违规。

API 参考文档

如需详细了解所有消息和字段,请参阅订餐 AI 智能体 API RPC 参考文档。

最佳做法

  • 唯一 ID:确保 Menu 范围内的所有 id 字段(对于 Item、Modifier、ModifierGroup、MenuCategory)都是唯一的。
  • 清晰的名称:使用清晰、便于客户理解的 display_name。为语义不同的产品提供不同的 display_name,以引导智能体进行适当的消除歧义。
  • 有效对套餐进行建模:将套餐建模为 Item,并使用 ModifierGroup 表示配菜、饮料和其他选项,如套餐中所述。这样可以确保智能体能够正确引导客户选择套餐。
  • 使用集成属性:将任何必要的 POS 或内部系统标识符存储在 custom_integration_attributes 中,以便实现无缝订单集成。
  • 管理库存状况:及时更新 Availability 状态。
  • 仅包含可订购的商品:请勿添加客户无法在渠道中订购的条目,例如仅限外送的商品、重复的商品以及非食品或饮料商品的条目。大型菜单可能会超出代理模型接受的输入量。如需了解详情,请参阅智能体重复重试消息,然后结束会话。
  • 全面测试:提取后,通过各种订单组合测试代理对菜单的理解。