음식 주문 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) 역할을 부여합니다.

    • 음식 주문 에이전트 관리자 (roles/foodorderingaiagent.admin): 이 역할은 브랜드, 매장, 메뉴를 비롯한 모든 음식 주문 AI 에이전트 리소스를 생성, 읽기, 업데이트, 삭제할 수 있는 전체 액세스 권한을 제공합니다.

    Google Cloud 콘솔, gcloud 명령줄 도구 또는 IAM API를 사용하여 IAM 역할을 부여할 수 있습니다. 자세한 내용은 IAM 역할 부여를 참고하세요.

    Google Cloud 콘솔을 사용하여 역할을 부여하려면 다음 단계를 따르세요.

    1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
    2. 추가를 클릭합니다.
    3. 주 구성원 (사용자 또는 서비스 계정 이메일)을 입력합니다.
    4. 음식 주문 AI 에이전트 관리자 역할을 선택합니다.
    5. 저장을 클릭합니다.

    적절한 권한이 없으면 브랜드, 매장 또는 메뉴를 생성하거나 수정하는 API 호출이 거부됩니다. Food Ordering Agent Viewer 역할은 읽기 전용 액세스 권한만 부여하므로 이 가이드에 설명된 작업에 적합하지 않습니다.

개요

음식 주문 AI 에이전트 메뉴 API는 유연하게 설계되어 독립형 항목의 짧은 목록부터 중첩된 수정자 및 조합 식사가 포함된 복잡한 메뉴까지 다양한 메뉴 구조를 수용할 수 있습니다. 이 API는 다음과 같은 몇 가지 핵심 개념을 기반으로 합니다.

  • 메뉴: 주문 가능한 모든 항목의 최상위 컨테이너입니다.
  • 상품: 식사, 메인 요리, 단독으로 주문할 수 있는 제품 등 주문 가능한 최상위 제품을 메뉴에서 나타냅니다. Item는 ModifierGroup를 참조할 수 있습니다.
  • ModifierGroup: Item 또는 다른 Modifier에 적용할 수 있는 Modifier 옵션의 모음입니다 (중첩 허용). 예를 들어 '사이드 선택', '토핑 추가', '음료 맛 선택' 등이 있습니다.
  • 수정자: ModifierGroup 내의 개별 옵션입니다(예: '감자튀김', '치즈 추가', '콜라'). 수정자는 가격을 조정할 수 있으며 자체 중첩된 ModifierGroup를 가질 수도 있습니다.
  • MenuCategory: Item를 표시 및 표시 이해를 위한 섹션으로 구성하는 데 사용됩니다 (예: 'Appetizers', 'Burgers', 'Drinks').

주요 개념 및 구조

이 섹션에서는 음식 주문 AI 에이전트 메뉴 API 스키마의 핵심 구성요소와 구조를 자세히 설명합니다. 이러한 개념을 이해하는 것은 메뉴 데이터를 올바르게 모델링하는 데 매우 중요합니다.

항목

메뉴의 각 항목은 Item로 정의해야 합니다. 주요 필드는 다음과 같습니다.

  • 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: 콤보

일부 메뉴에는 콤보 식사와 같이 여러 중첩된 선택사항으로 구성된 복잡한 구조가 있습니다. 콤보는 콤보의 구성요소를 나타내는 여러 ModifierGroup가 있는 Item로 모델링할 수 있습니다. 예를 들어 고정된 메인 요리와 여러 옵션의 사이드 및 음료가 번들로 제공되는 '버거 콤보' Item는 다음과 같이 모델링할 수 있습니다.

  • 측면의 ModifierGroup (예: '사이드 메뉴').
    • 각 측면 옵션은 Modifier (예: '감자튀김', '샐러드').
      • 각 음료 옵션은 중첩된 ModifierGroup를 참조할 수 있습니다 (예: '얼음 옵션', '음료 크기')을 참조합니다. 이 옵션은 Modifier (예: '얼음 없음', '대형 음료')을 참조합니다.
  • 음료의 ModifierGroup (예: '음료').
    • 각 음료 옵션은 Modifier로 모델링됩니다.
      • 각 음료 옵션은 중첩된 ModifierGroup를 참조할 수 있습니다 (예: '얼음 옵션', '음료 크기')을 참조합니다.Modifier
  • 메인 요리의 토핑을 위한 ModifierGroup입니다. (예: '치즈 추가', '베이컨').

가용성

Item 및 Modifier의 Availability 메시지를 사용하면 다음을 지정할 수 있습니다.

  • status: STATUS_AVAILABLE, STATUS_OUT_OF_STOCK 등
  • daypart_availability: 상품이 특정 시간에만 제공되는 경우 (예: '아침 식사 메뉴').

통합 속성

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을 최종 주문 또는 진행 중인 장바구니에 대한 애플리케이션의 표현으로 다시 변환할 수 있습니다.
  • 스크립팅: 소스에서 데이터를 가져오고, 변환을 실행하고, CreateMenu 메서드를 호출하는 스크립트 (예: Python, Node.js, Go)를 작성해야 할 수 있습니다. 이 스크립트는 인증 및 API 상호작용을 위해 Google Cloud 클라이언트 라이브러리를 사용합니다.

개념적 변환 워크플로:

이 워크플로는 소스 시스템의 메뉴 데이터를 Food Ordering AI Agent API 형식으로 변환하는 프로세스를 설명합니다.

  1. 카테고리 추출 및 매핑:
    • 소스 데이터에서 카테고리 또는 섹션을 식별합니다 (예: 'Appetizers', 'Entrees').
    • 각각을 고유한 id 및 display_name가 있는 MenuCategory 객체로 변환합니다.
  2. 항목 추출 및 매핑:
    • 소스 데이터에서 판매 가능한 상품을 식별합니다.
    • 각각을 Item 객체로 변환하여 id, display_name, base_price, availability를 채웁니다.
    • category_ids 필드를 사용하여 각 Item를 카테고리에 매핑합니다.
    • item.integration_attributes.custom_integration_attributes에 소스 시스템 식별자 (예: PLU 또는 SKU)를 저장합니다.
  3. 수정자 추출 및 매핑:
    • 소스 데이터에서 상품 맞춤설정, 옵션 또는 부가기능을 식별합니다.
    • 관련 옵션 그룹화 (예: 'Side Options', 'Drink Choices', 'Extra Toppings')를 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가 있어야 합니다.
  • 수정자 그룹 제약 조건:
    • 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 Reference를 참고하세요.

권장사항

  • 고유 ID: Menu 범위 (Item, Modifier, ModifierGroup, MenuCategory) 내의 모든 id 필드가 고유해야 합니다.
  • 명확한 이름: 고객 친화적인 명확한 display_name를 사용합니다. 의미적으로 다른 제품에 대해 별도의 display_name를 제공하여 에이전트가 적절하게 모호성을 해소하도록 유도하세요.
  • 효과적인 모델 콤보: 콤보에 설명된 대로 ModifierGroup가 사이드, 음료, 기타 선택사항을 나타내는 Item로 콤보 식사를 모델링합니다. 이렇게 하면 상담사가 고객에게 콤보 선택을 올바르게 안내할 수 있습니다.
  • 통합 속성 사용: 원활한 주문 통합을 위해 필요한 POS 또는 내부 시스템 식별자를 custom_integration_attributes에 저장합니다.
  • 재고 관리: Availability 상태를 최신 상태로 유지합니다.
  • 철저하게 테스트: 인게스트 후 다양한 주문 조합으로 에이전트의 메뉴 이해도를 테스트합니다.