음식 주문 AI 에이전트 API를 사용하여 메뉴 데이터 통합

이 가이드에서는 음식 주문 AI 에이전트 메뉴 API에 음식점 메뉴 데이터를 구조화, 변환, 수집하는 방법을 설명합니다. 이렇게 하면 AI 에이전트가 메뉴를 이해하고 고객의 주문을 정확하게 받을 수 있습니다.

시작하기 전에

음식 주문 AI 에이전트 API를 사용하여 메뉴를 수집하고 관리하려면 먼저 다음을 수행해야 합니다.

  1. 음식 주문 AI 에이전트 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를 표시 및 표시 이해를 위한 섹션으로 구성하는 데 사용됩니다(예: '애피타이저', '버거', '음료').

주요 개념 및 구조

이 섹션에서는 음식 주문 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: 특정 시간대에만 제공되는 항목(예: '아침 메뉴')인 경우 특정 시간대 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 포함: 각 항목, 수정자, 그룹의 내부 POS 또는 시스템 ID를 custom_integration_attributes 필드에 저장하는 것이 중요합니다. 이를 통해 에이전트가 생성한 Order를 애플리케이션의 최종 주문 또는 진행 중인 장바구니 표현으로 다시 변환할 수 있습니다.
  • 스크립팅: 소스에서 데이터를 가져오고, 변환을 수행하고, CreateMenu 메서드를 호출하는 스크립트(예: Python, Node.js, Go)를 작성해야 할 수 있습니다. 이 스크립트는 인증 및 API 상호작용에 Google Cloud 클라이언트 라이브러리를 사용합니다.

개념적 변환 워크플로:

이 워크플로는 소스 시스템의 메뉴 데이터를 음식 주문 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가 있어야 합니다.
  • 수정자 그룹 제약조건:
    • ModifierGroup은(는) 비워 둘 수 없습니다.
    • ModifierGroup 내의 최소 또는 최대 선택 개수가 논리적 일관성을 위해 확인됩니다.
    • Item 또는 Modifier 수준 modifier_constraints는 참조된 ModifierGroup의 선택 수 제약조건에 따라 검증되어 충족 가능한지 확인합니다.
  • 중첩 깊이: 중첩된 수정자의 깊이는 최대 5단계로 제한됩니다(예: Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier…).
  • 시간대 유효성 검사: 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를 제공하여 에이전트가 적절하게 모호성을 해소하도록 유도합니다.
  • 효과적인 콤보 모델링: 콤보 메뉴에 설명된 대로 사이드, 음료, 기타 선택사항을 나타내는 ModifierGroup가 포함된 Item로 콤보 메뉴를 모델링합니다. 이렇게 하면 상담사가 고객에게 콤보 선택을 올바르게 안내할 수 있습니다.
  • 통합 속성 사용: 원활한 주문 통합을 위해 필요한 POS 또는 내부 시스템 식별자를 custom_integration_attributes에 저장합니다.
  • 재고 관리: Availability 상태를 최신 상태로 유지합니다.
  • 주문 가능한 항목만 포함: 배달 전용 항목, 중복 항목, 식음료 제품이 아닌 항목 등 고객이 채널에서 주문할 수 없는 항목은 제외합니다. 큰 메뉴는 에이전트 모델이 허용하는 입력량을 초과할 수 있습니다. 자세한 내용은 에이전트가 재시도 메시지를 반복한 후 세션을 종료함을 참조하세요.
  • 철저하게 테스트: 수집 후 다양한 주문 조합으로 에이전트의 메뉴 이해도를 테스트합니다.