使用訂餐 AI 代理 API 整合菜單資料

本指南說明如何建構、轉換餐廳菜單資料,並將資料擷取至「訂餐 AI 代理」選單 API。這樣一來,AI 代理就能瞭解菜單內容,並準確接受顧客點餐。

事前準備

您必須先完成下列事項,才能使用「訂餐 AI 代理」API 擷取及管理菜單:

  1. 啟用訂餐 AI 代理 API:

      gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT
    
  2. 確認您具備必要的 IAM 權限。將下列 Identity and Access Management (IAM) 角色授予與 API 互動的使用者或服務帳戶:

    • 訂餐 AI 代理管理員 (roles/foodorderingaiagent.admin):這個角色具備完整存取權,可建立、讀取、更新及刪除所有訂餐 AI 代理資源,包括品牌、商店和菜單。

    您可以使用 Google Cloud 控制台、gcloud指令列工具或 IAM API 授予 IAM 角色。詳情請參閱「授予 IAM 角色」。

    如要使用 Google Cloud 控制台授予角色,請按照下列步驟操作:

    1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。
    2. 按一下「新增」。
    3. 輸入主體 (使用者或服務帳戶電子郵件地址)。
    4. 選取「訂餐 AI 代理 Admin」角色。
    5. 按一下「儲存」。

    如果沒有適當權限,系統會拒絕建立或修改品牌、商店或菜單的 API 呼叫。Food Ordering Agent Viewer 角色僅授予唯讀存取權,不足以執行本指南所述的工作。

總覽

Food Ordering AI Agent Menu API 具有彈性,可容納各種菜單結構,從獨立品項的簡短清單,到含有巢狀修飾符和套餐的複雜菜單,都能輕鬆處理。此 API 是圍繞著以下幾個關鍵概念建構而成:

  • 菜單:所有可訂購實體的頂層容器。
  • Item:代表菜單中可訂購的頂層產品,例如餐點、主菜或任何可單獨訂購的產品。Item 可參照 ModifierGroup。
  • ModifierGroup:可套用至 Item 或其他 Modifier 的 Modifier 選項集合 (允許巢狀結構)。例如「選擇配菜」、「添加配料」或「選擇飲料口味」。
  • 修改項目:ModifierGroup中的個別選項,例如「薯條」、「額外起司」或「可樂」。修飾符可以調整價格,也可以有自己的巢狀 ModifierGroup。
  • MenuCategory:用於將 Item 整理成不同部分,以便顯示及理解 (例如「開胃菜」、「漢堡」、「飲料」)。

重要概念和結構

本節將詳細說明訂餐 AI 代理選單 API 架構的核心元件,以及這些元件的結構。瞭解這些概念,才能正確建立菜單資料模型。

項目

菜單上的每個不同品項都應定義為 Item。重要欄位包括:

  • id:選單中的專屬 ID。
  • display_name::客戶看到的名稱。
  • base_price:商品的底價。
  • modifier_groups:可套用至這項商品的ModifierGroup參照。
  • category_ids:這個項目所屬 MenuCategory ID 的參照。
  • availability:指定項目的供應時間 (例如依狀態或時段)。如未指定,預設為 STATUS_AVAILABLE。

修飾符和 ModifierGroup

你可以使用修飾符自訂項目。

  • 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。(例如「起司加量」、「培根」)。

可用性

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 架構中,與來源資料各元素對應的實體。舉例來說,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 對應至其類別。
    • 將來源系統 ID (例如 PLU 或 SKU) 儲存在 item.integration_attributes.custom_integration_attributes 中。
  3. 擷取及對應修飾符:
    • 找出來源資料中的商品自訂選項、選項或加購內容。
    • 將相關選項 (例如「配菜選項」、「飲料選擇」、「額外配料」) 分組到 ModifierGroup 物件中。為每個ModifierGroup定義選取規則的上下限。
    • 將每個選項 (例如「薯條」、「可樂」、「額外起司」) 轉換為適當 ModifierGroup 中的 Modifier 物件。視情況填入 price_adjustment。
    • 將來源系統 ID 儲存在 modifier_group.integration_attributes.custom_integration_attributes 和 modifier.integration_attributes.custom_integration_attributes。
  4. 建立關係:
    • 針對每個 Item,請在 modifier_groups 欄位中填入適用的 ModifierGroup id 參照。
    • 如果 Modifier 允許進一步自訂 (例如為「汽水」修飾符選擇口味),請填入 modifier_groups 欄位,建立巢狀修飾符。
  5. 彙整及擷取:
    • 將所有 MenuCategory、Item、ModifierGroup 和 Modifier 物件合併到單一 Menu 訊息中的清單。
    • 呼叫 CreateMenu RPC,並以完整組合的 Menu 訊息做為輸入內容。

處理菜單更新

Menu 不可變動。使用 CreateMenu RPC 呼叫建立選單後,即無法修改。如要將選單更新內容 (例如變更商品價格、修改選項或調整供應情形) 傳播至選單,您必須再次呼叫 CreateMenu,建立新的選單資源。每個版本的菜單都應擷取為新的 Menu 資源,並具有不重複的 menu_id。

擷取新版菜單的程序與首次擷取菜單相同,且會經過相同的清理和驗證步驟。處理訂單時,代理的行為一律會反映最近建立的 Menu,並與工作階段設定中參照的 Store 相關聯。

自動清理菜單

CreateMenu API 會自動執行多個清理步驟,修正常見問題,並確保 API 中的菜單內容呈現方式一致。系統會在清理後套用驗證,簡化用戶端的菜單整合程序:

  • 預設適用情況:如果 Item 和 Modifier 沒有明確的 Availability.Status,則會設為 STATUS_AVAILABLE。
  • 捨棄未參照的實體:如果 Modifier 和 ModifierGroup 未由任何 Item 遞移參照,則會從菜單中移除,因為這些項目無法訂購。
  • 捨棄空白修飾符群組:不含 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 內選項數量的下限或上限,確保邏輯一致。
    • 系統會根據參照 ModifierGroup 的選取數量限制,驗證 Item 或 Modifier 層級 modifier_constraints,確保這些限制可以滿足。
  • 巢狀深度:巢狀修飾符的深度有限制 (例如 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 欄位都是專屬 ID。
  • 明確的名稱:使用清楚、容易理解的 display_name。為語意不同的產品提供不同的 display_name,引導代理適當釐清。
  • 有效建立套餐模型:將套餐建立為 Item,並使用 ModifierGroup 代表配菜、飲料和其他選項,詳情請參閱套餐。這樣一來,代理就能正確引導顧客選擇套餐。
  • 使用整合屬性:將任何必要的 POS 或內部系統 ID 儲存在 custom_integration_attributes 中,以便順利整合訂單。
  • 管理供應情形:隨時更新Availability狀態。
  • 僅納入可訂購的項目:請勿加入顧客無法在管道中訂購的項目,例如僅限外送的項目、重複項目,以及非食品或飲料產品的項目。大型選單可能會超出代理模型接受的輸入量。詳情請參閱「代理重複傳送重試訊息,然後結束工作階段」。
  • 徹底測試:擷取完成後,請測試代理對菜單的理解程度,並嘗試各種點餐組合。