准备工作
您必须先完成以下操作,然后才能使用 Food Ordering AI Agent API 注入和管理菜单:
启用订餐 AI 智能体 API:
gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT确保您拥有必要的 IAM 权限。向与该 API 交互的用户或服务账号授予以下 Identity and Access Management (IAM) 角色:
- Food Ordering Agent Admin (
roles/foodorderingaiagent.admin):此角色提供创建、读取、更新和删除所有订餐 AI 智能体资源(包括品牌、商店和菜单)的完整权限。
您可以使用 Google Cloud 控制台、
gcloud命令行工具或 IAM API 授予 IAM 角色。如需了解详情,请参阅授予 IAM 角色。如需使用 Google Cloud 控制台授予角色,请执行以下操作:
- 在 Google Cloud 控制台中,前往 IAM 页面。
- 点击 Add(添加)。
- 输入主账号(用户或服务账号邮箱)。
- 选择 订餐 AI 智能体管理员 角色。
- 点击保存。
如果没有适当的权限,用于创建或修改品牌、商店或菜单的 API 调用将被拒绝。
Food Ordering Agent Viewer角色不足以执行本指南中所述的任务,因为它仅授予只读权限。- Food Ordering Agent Admin (
概览
订餐 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:对此项所属MenuCategoryID 的引用。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 调用提取的。
步骤
- 转换数据:将现有菜单数据(来自 POS、API 或其他来源)转换为
google.cloud.foodorderingaiagent.v1beta.Menu消息定义的结构。这涉及将您的商品、修饰符、类别和价格映射到相应的 API 消息类型。 - 构建
CreateMenuRequest:- 设置
parent字段(例如projects/PROJECT/locations/LOCATION)。 - 使用转换后的
Menu对象填充menu字段。 - (可选)提供
menu_id。
- 设置
- 调用 API:将
CreateMenuRequest发送到MenuService.CreateMenu端点。API 会先清理菜单,然后对其进行验证,最后返回最终的Menu对象。 - 处理菜单更新:每次更新菜单源数据(例如,推出新商品或商品缺货)时,都应按照处理菜单更新中的说明,创建一个反映更新后的源数据的新
Menu。
数据转换指南
转换菜单数据的具体逻辑取决于源系统(例如 POS API、数据库架构)的格式和结构。以下是常规方法:
- 导出数据:获取菜单数据的完整导出文件,包括所有商品、修饰符、价格和关系。
- 映射实体:
- 在订餐 AI 智能体 API schema 中,为源数据中的每个元素确定对应的实体。例如,您的 POS“菜单项”可能会映射到
Item对象。“订购选项”或“加购项”将映射到Modifier和ModifierGroup。 - 使用 ID 建立关系。例如,使用
modifier_groups引用字段将Item关联到其适用的ModifierGroup。
- 在订餐 AI 智能体 API schema 中,为源数据中的每个元素确定对应的实体。例如,您的 POS“菜单项”可能会映射到
- 处理嵌套结构:如果您的菜单包含嵌套修饰符(例如,为套餐中的汽水选择饮料口味),请通过让
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 格式的过程:
- 提取和映射类别:
- 识别源数据中的类别或部分(例如“开胃菜”“主菜”)。
- 将每个对象转换为具有唯一
id和display_name的MenuCategory对象。
- 提取和映射项:
- 在源数据中识别可销售的商品。
- 将每个对象转换为
Item对象,并填充id、display_name、base_price和availability。 - 使用
category_ids字段将每个Item映射到其类别。 - 将源系统标识符(例如 PLU 或 SKU)存储在
item.integration_attributes.custom_integration_attributes中。
- 提取和映射修饰符:
- 在来源数据中确定商品定制、选项或加购项。
- 将相关选项(例如“配菜选项”“饮料选择”“额外配料”)分组到
ModifierGroup对象中。为每个ModifierGroup定义选择规则的下限和上限。 - 将每个单独的选项(例如“薯条”“可乐”“额外奶酪”)转换为相应
ModifierGroup中的Modifier对象。填充price_adjustment(如果适用)。 - 将源系统标识符存储在
modifier_group.integration_attributes.custom_integration_attributes和modifier.integration_attributes.custom_integration_attributes中。
- 建立关系:
- 对于每个
Item,使用对适用于它的ModifierGroup的id的引用来填充其modifier_groups字段。 - 如果
Modifier允许进一步自定义(例如,为“苏打水”修饰符选择口味),请填充其modifier_groups字段以创建嵌套修饰符。
- 对于每个
- 组装和提取:
- 将所有
MenuCategory、Item、ModifierGroup和Modifier对象合并到单个Menu消息中的列表中。 - 使用完全组装的
Menu消息作为输入来调用CreateMenuRPC。
- 将所有
处理菜单更新
菜单不可变。使用 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状态。 - 仅包含可订购的商品:请勿添加客户无法在渠道中订购的条目,例如仅限外送的商品、重复的商品以及非食品或饮料商品的条目。大型菜单可能会超出代理模型接受的输入量。如需了解详情,请参阅智能体重复重试消息,然后结束会话。
- 全面测试:提取后,通过各种订单组合测试代理对菜单的理解。