שילוב נתוני תפריט באמצעות Food Ordering AI Agent API

במדריך הזה מוסבר איך לבנות, לשנות ולהטמיע את נתוני התפריט של המסעדה ב-API של התפריט של סוכן ה-AI להזמנה ממסעדה. כך סוכן ה-AI יוכל להבין את הפריטים בתפריט ולקבל הזמנות מלקוחות בצורה מדויקת.

לפני שמתחילים

כדי להזין ולנהל תפריטים באמצעות Food Ordering AI Agent API, קודם צריך:

  1. מפעילים את Food Ordering AI Agent API:

      gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT

  2. ודאו שיש לכם את הרשאות ה-IAM הנדרשות. נותנים למשתמש או לחשבון השירות שמבצע אינטראקציה עם ה-API את התפקיד הבא בניהול הזהויות והרשאות הגישה (IAM):

    • אדמין של סוכן AI להזמנת אוכל (roles/foodorderingaiagent.admin): התפקיד הזה מספק גישה מלאה ליצירה, לקריאה, לעדכון ולמחיקה של כל המשאבים של סוכן ה-AI להזמנת אוכל, כולל מותגים, חנויות ותפריטים.

    אפשר להקצות תפקידי IAM באמצעות מסוף Google Cloud , כלי שורת הפקודה gcloud או IAM API. מידע נוסף זמין במאמר הענקת תפקיד IAM.

    כדי להעניק את התפקיד באמצעות Google Cloud המסוף:

    1. נכנסים לדף IAM במסוף Google Cloud .
    2. לוחצים על הוספה.
    3. מזינים את הישות המורשית (כתובת האימייל בחשבון של המשתמש או של חשבון השירות).
    4. בוחרים בתפקיד אדמין של סוכן AI להזמנה ממסעדות.
    5. לוחצים על Save.

    ללא ההרשאות המתאימות, קריאות ל-API ליצירה או לשינוי של מותגים, חנויות או תפריטים נדחות. התפקיד Food Ordering Agent Viewer לא מספיק למשימות שמתוארות במדריך הזה, כי הוא מעניק הרשאת קריאה בלבד.

סקירה כללית

ממשק ה-API של התפריט של סוכן ה-AI להזמנת אוכל נועד להיות גמיש ולהתאים למבנים שונים של תפריטים, מרשימות קצרות של פריטים עצמאיים ועד לתפריטים מורכבים עם אפשרויות בחירה מקוננות ומנות משולבות. ה-API מבוסס על כמה מושגים מרכזיים:

  • תפריט: המאגר ברמה העליונה של כל הישויות שאפשר להזמין.
  • פריט: מייצג מוצר ברמה העליונה בתפריט שאפשר להזמין, כמו ארוחה, מנה עיקרית או כל מוצר שאפשר להזמין בנפרד. אפשר להפנות Items אל ModifierGroups.
  • ‫ModifierGroup: אוסף של Modifier אפשרויות שאפשר להחיל על Item או על Modifier אחר (אפשרות לקינון). לדוגמה, "Choose Your Side" (בחירת תוספת), "Add Toppings" (הוספת תוספות) או "Select Drink Flavor" (בחירת טעם המשקה).
  • אפשרות: אפשרות ספציפית בתוך ModifierGroup, כמו 'צ'יפס', 'גבינה נוספת' או 'קולה'. המשנים יכולים לשנות את המחיר, ויכולים גם לכלול תגי ModifierGroup משלהם.
  • ‫MenuCategory: משמש לארגון של Items בקטעים לתצוגה ולהבנה של התצוגה (למשל, 'מתאבנים', 'המבורגרים', 'משקאות').

מושגים ומבנה מרכזיים

בקטע הזה מפורטים רכיבי הליבה של סכימת ה-API של תפריט סוכן ה-AI להזמנה ממסעדה, והמבנה שלהם. כדי ליצור מודל נכון של נתוני התפריט, חשוב להבין את המושגים האלה.

פריטים

כל פריט ייחודי בתפריט צריך להיות מוגדר כ-Item. שדות עיקריים:

  • ‫id: מזהה ייחודי בתפריט.
  • ‫display_name: השם שמוצג ללקוחות.
  • ‫base_price: מחיר הבסיס של הפריט.
  • ‫modifier_groups: הפניות אל ModifierGroups שיכולות לחול על הפריט הזה.
  • ‫category_ids: הפניות למזהים של MenuCategory שהפריט הזה שייך אליהם.
  • ‫availability: מציין מתי הפריט זמין (למשל, לפי סטטוס או לפי חלק מהיום). אם לא מציינים ערך, ברירת המחדל היא STATUS_AVAILABLE.

גורמי שינוי וקבוצות של גורמי שינוי

אמצעי שינוי מאפשרים להתאים אישית פריטים.

  • ‫ModifierGroups מגדירים קבוצה של אפשרויות, כולל מגבלות כמו בחירות מינימליות או מקסימליות. צריכה להכיל לפחות Modifier אחד.
  • ‫Modifiers מייצגות את האפשרויות בפועל. יכול להיות שיש להם price_adjustment והם יכולים להפנות באופן רקורסיבי לModifierGroup אחרים להתאמות אישיות מקוננות (לדוגמה, לItem 'ארוחה משולבת' יכול להיות ModifierGroup 'בחירת משקה', ולModifier 'סודה' בתוך הקבוצה הזו יכול להיות ModifierGroup 'בחירת טעם').

דוגמה 1: תוספות

האזכור של Item Bacon Cheeseburger יכול להתייחס ל-ModifierGroup Toppings. המאפיין ModifierGroup יכיל Modifier כמו 'גבינה נוספת', 'בלי בצל' וכו'.

דוגמה 2: ארוחות משולבות

לחלק מהתפריטים יש מבנים מורכבים שכוללים כמה אפשרויות מקוננות, כמו ארוחות משולבות. אפשר ליצור מודל של חבילות כ-Item עם כמה ModifierGroup שמייצגים את הרכיבים של החבילה. לדוגמה, אפשר להגדיר את המוצר 'ארוחת המבורגר' Item, שכולל מנה עיקרית קבועה עם כמה אפשרויות למנה צדדית ושתייה, באופן הבא:

  • ModifierGroup לצד (לדוגמה, 'תוספות').
    • כל אפשרות של תוספת מעוצבת כ-Modifier (לדוגמה, 'צ'יפס', 'סלט').
      • כל אפשרות למשקה יכולה להפנות לModifierGroups מוטמעים (למשל, 'אפשרויות לקרח', 'גודל המשקה') שבתורם מפנים לModifiers (למשל, 'ללא קרח', 'משקה גדול', בהתאמה).
  • ModifierGroup למשקה (לדוגמה, 'משקאות').
    • כל אפשרות של משקה מוגדרת כModifier.
      • כל אפשרות למשקה יכולה להפנות ל-ModifierGroups מקוננים (למשל, 'אפשרויות לקרח', 'גודל המשקה') שמפנים בתורם ל-Modifiers (למשל, 'ללא קרח', 'משקה גדול').
  • ‫ModifierGroup לתוספות למנה העיקרית. (לדוגמה, "גבינה נוספת", "בייקון").

זמינות

ההודעה Availability ב-Item וגם ב-Modifier מאפשרת לכם לציין:

  • status: STATUS_AVAILABLE,‏ STATUS_OUT_OF_STOCK וכו'.
  • ‫daypart_availability: קישורים למזהים ספציפיים של חלקי יום אם הפריט זמין רק בשעות מסוימות (למשל, 'תפריט ארוחת בוקר').

מאפייני שילוב

ההודעות Item,‏ Modifier ו-ModifierGroup מכילות את השדה integration_attributes. השדה הזה (ItemIntegrationAttributes,‏ ModifierIntegrationAttributes וכו') מכיל google.protobuf.Struct שנקרא custom_integration_attributes. אפשר להשתמש במאפיין הזה כדי לאחסן נתוני מפתח-ערך שרירותיים, כמו:

  • מזהים ממערכת נקודת המכירה (POS).
  • מק"טים או קודים פנימיים אחרים.
  • כל מטא-נתונים אחרים שנדרשים לעיבוד הזמנות בהמשך או לשילוב עם מערכת ה-POS.

הנתונים האלה מועברים באופן אטום על ידי סוכן ה-AI.

תוויות

אפשר להשתמש בשדה labels במשאב Menu כדי לצרף מטא-נתונים לתפריטים, וכך לעזור בשילוב ובניפוי באגים.

התוויות הן תכונה נוחה, ואין להן השפעה על ההתנהגות של סוכן ה-AI.

יצירת תפריט

התפריטים מוזנים באמצעות קריאת ה-RPC‏ CreateMenu בתוך MenuService.

שלבים

  1. המרת הנתונים: המרת נתוני התפריט הקיימים (ממערכת הקופה, מ-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, סכימת מסד נתונים). הנה גישה כללית:

  • ייצוא נתונים: אפשר לקבל ייצוא מלא של נתוני התפריט, כולל כל הפריטים, האפשרויות, המחירים והקשרים.
  • Map Entities:
    • מזהים את הישויות התואמות בסכימת API של סוכן AI להזמנה ממסעדה לכל רכיב בנתוני המקור. לדוגמה, 'פריטים בתפריט' במערכת ה-POS ימופו כנראה לאובייקטים מסוג Item. האפשרויות 'הזמנת אפשרויות' או 'תוספים' ימופו ל-Modifiers ול-ModifierGroups.
    • יצירת קשרים באמצעות מזהים. לדוגמה, מקשרים Items ל-ModifierGroups הרלוונטיים באמצעות שדה ההפניה modifier_groups.
  • טיפול במבנים מוטמעים: אם בתפריט יש משני מחיר מוטמעים (לדוגמה, בחירת טעם לשתייה בארוחה עסקית), צריך ליצור מודל שבו Modifier מפנים אל ModifierGroup אחרים.
  • מילוי מאפיינים: ממלאים שדות כמו display_name, base_price, price_adjustment ו-availability על סמך נתוני המקור.
  • כוללים מזהי POS: חשוב מאוד לאחסן את מזהי ה-POS או המערכת הפנימיים שלכם לכל פריט, משנה וקבוצה בשדה custom_integration_attributes. כך תוכלו לתרגם את Order שנוצר על ידי הסוכן בחזרה לייצוג של הזמנה סופית או של עגלת קניות בתהליך באפליקציה שלכם.
  • סקריפטים: סביר להניח שתצטרכו לכתוב סקריפט (למשל ב-Python, ב-Node.js או ב-Go) כדי לאחזר נתונים מהמקור, לבצע את ההמרה ולקרוא ל-method‏ CreateMenu. הסקריפט הזה ישתמש בספריות הלקוח Google Cloud לאימות ולפעולות עם ה-API.

תהליך עבודה של טרנספורמציה מושגית:

בתהליך העבודה הזה מוסבר איך להמיר נתוני תפריט ממערכת מקור לפורמט של Food Ordering AI Agent API:

  1. חילוץ ומיפוי של קטגוריות:
    • מזהים קטגוריות או מדורים בנתוני המקור (לדוגמה, 'מנות ראשונות', 'מנות עיקריות').
    • הופכים כל אחד מהם לאובייקט MenuCategory עם id ו-display_name ייחודיים.
  2. חילוץ ומיפוי של פריטים:
    • מזהים פריטים שאפשר למכור בנתוני המקור.
    • הופכים כל אחד מהם לאובייקט Item ומאכלסים את id,‏ display_name,‏ base_price ו-availability.
    • ממפים כל Item לקטגוריות שלו באמצעות השדה category_ids.
    • שומרים מזהים של מערכת מקור (כמו PLU או מק"ט) ב-item.integration_attributes.custom_integration_attributes.
  3. חילוץ משנים ומיפוי שלהם:
    • מזהים בנתוני המקור התאמות אישיות, אפשרויות או תוספים של פריטים.
    • מקבצים אפשרויות קשורות (למשל, 'תוספות', 'אפשרויות שתייה', 'תוספות נוספות') לאובייקטים מסוג ModifierGroup. מגדירים כללי בחירה מינימליים ומקסימליים בכל ModifierGroup.
    • הופכים כל אפשרות בנפרד (למשל, 'צ'יפס', 'קולה', 'גבינה נוספת') לאובייקט Modifier בתוך ModifierGroup המתאים. ממלאים את השדה price_adjustment אם רלוונטי.
    • אחסון מזהים של מערכת מקור ב-modifier_group.integration_attributes.custom_integration_attributes וב-modifier.integration_attributes.custom_integration_attributes.
  4. יצירת קשרים:
    • לכל Item, מאכלסים את השדה modifier_groups בהפניות לid של ModifierGroup שרלוונטיים אליו.
    • אם Modifier מאפשר התאמה אישית נוספת (למשל, בחירת טעם לשינוי 'סודה'), מאכלסים את השדה modifier_groups כדי ליצור שינויים מוטמעים.
  5. הרכבה והטמעה:
    • לשלב את כל האובייקטים MenuCategory,‏ Item,‏ ModifierGroup ו-Modifier ברשימות בהודעה אחת של Menu.
    • קוראים ל-CreateMenu RPC עם הודעת Menu שהורכבה במלואה כקלט.

טיפול בעדכוני תפריט

התפריט הוא בלתי ניתן לשינוי. אחרי שיוצרים תפריט באמצעות קריאת ה-RPC‏ CreateMenu, אי אפשר לשנות אותו. כדי להפיץ עדכונים בתפריט – כמו שינוי מחירים של פריטים, שינוי אפשרויות או שינוי הזמינות – צריך ליצור משאב תפריט חדש על ידי קריאה חוזרת אל CreateMenu. כל גרסה של התפריט צריכה להיטמע כמשאב Menu חדש עם menu_id ייחודי.

תהליך ההטמעה של גרסה חדשה של תפריט זהה להטמעה של תפריט בפעם הראשונה, והוא עובר את אותם שלבים של ניקוי ואימות. במהלך הטיפול בהזמנות, התנהגות הסוכן תמיד תשקף את התצורה האחרונה שנוצרה Menu שמשויכת ל-Store שאליה מתייחסת ההגדרה של הסשן.

ניקוי אוטומטי של התפריט

ממשק CreateMenu API מבצע אוטומטית כמה שלבים של ניקוי כדי לתקן בעיות נפוצות ולוודא שתוכן התפריט מיוצג באופן עקבי בכל ממשק ה-API. האימותים מוחלים אחרי הניקויים האלה כדי לפשט את שילוב התפריטים עבור לקוחות:

  • זמינות ברירת מחדל: ערך ברירת המחדל של Item ו-Modifier ללא Availability.Status מוגדר כ-STATUS_AVAILABLE.
  • הסרת ישויות לא מקושרות: מערכות Modifier ו-ModifierGroup שלא מקושרות באופן טרנזיטיבי ל-Item כלשהו מוסרות מהתפריט, כי אי אפשר להזמין אותן.
  • הסרת קבוצות של משנים ריקות: ModifierGroups שלא מכילים modifier_ids יוסרו, וכל ההפניות אליהם יוסרו.

אחרי הניקוי, ה-API מאמת את התפריט לפי קבוצה מחמירה של כללים כדי לוודא שהוא בנוי בצורה תקינה ושהסוכן מבוסס ה-AI יכול להשתמש בו בצורה מהימנה. אם האימות נכשל, קריאת ה-API‏ CreateMenu תחזיר שגיאה עם פרטים על הבעיות. בין הבדיקות העיקריות:

  • שדות חובה: מוודא שכל שדות החובה כמו id, display_name ו-availability.status קיימים.
  • מזהים ייחודיים: לכל רכיבי Item, Modifier ו-ModifierGroup בתפריט צריך להיות מזהה ייחודי.
  • שמות לתצוגה ייחודיים:
    • לכל ערך Item צריך להיות ערך display_name ייחודי.
    • בכל תג ModifierGroup, כל התגים Modifier שכלולים בו חייבים להיות עם ערכים ייחודיים של display_name.
  • שלמות ההפניה:
    • כל modifier_group_ids שמוזכרים בItem או בModifier חייבים להופיע בתפריט.
    • כל modifier_ids שאליהם מתבצעת הפניה באמצעות ModifierGroups חייבים להופיע בתפריט.
    • המשנים שמוגדרים כברירת מחדל ב-ModifierGroupReference חייבים להיות קיימים ב-ModifierGroup שאליו מתייחסים.
    • אם Modifier משתמש ב-item_id כדי להפנות אל Item, Item הזה חייב להתקיים.
  • הגבלות על קבוצות של משני מחירים:
    • השדה ModifierGroup לא יכול להיות ריק.
    • המערכת בודקת את המספר המינימלי או המקסימלי של אפשרויות הבחירה בתוך ModifierGroup כדי לוודא שהוא הגיוני.
    • רמה Item או Modifier modifier_constraints עוברות אימות מול אילוצי ספירת הבחירות של ModifierGroups שאליהם יש הפניה, כדי לוודא שהן ניתנות למימוש.
  • עומק ההטמעה: העומק של משני מילות מפתח מוטמעות מוגבל (למשל, Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier...) ל-5 רמות לכל היותר.
  • אימות של חלקי יום: אם משתמשים בחלקי יום ב-Availability, צריך להגדיר אותם במשאב Store המשויך.
  • הפניות לפריטים של שינוי: Modifiers שמפנים אל Item באמצעות item_id לא יכולים להכיל שדות כמו display_name או availability, כי הם עוברים בירושה מ-Item שאליו מתבצעת ההפניה.

אם אחד מכללי האימות האלה לא יתקיים, לא תהיה אפשרות ליצור או לעדכן את התפריט. בהודעת השגיאה יופיעו פרטים על הישויות שגורמות להפרה.

הפניית API

פרטים מלאים על כל ההודעות והשדות מופיעים בחומר העזר בנושא Food Ordering AI Agent API RPC.

שיטות מומלצות

  • מזהים ייחודיים: מוודאים שכל השדות id בהיקף Menu (לשדות Item, Modifier, ModifierGroup, MenuCategory) הם ייחודיים.
  • שמות ברורים: כדאי להשתמש בdisplay_nameים ברורים וידידותיים ללקוחות. כדי שהסוכן יבצע את ההפרדה בצורה נכונה, צריך לספק display_names שונים למוצרים שונים מבחינה סמנטית.
  • הצגת שילובי מנות בצורה יעילה: מומלץ להציג ארוחות משולבות כItem עם ModifierGroup שמייצגים תוספות, משקאות ואפשרויות אחרות, כמו שמתואר במאמר בנושא ארוחות משולבות. כך הנציג יוכל להדריך את הלקוחות בצורה נכונה בתהליך הבחירה של חבילות.
  • שימוש במאפייני שילוב: כדי לאפשר שילוב חלק של הזמנות, מאחסנים את כל המזהים הנדרשים של מערכת ה-POS או של המערכת הפנימית במאפיין custom_integration_attributes.
  • ניהול הזמינות: חשוב לעדכן את הסטטוס Availability.
  • בדיקה יסודית: אחרי ההטמעה, בודקים את יכולת ההבנה של הנציג לגבי התפריט באמצעות שילובים שונים של הזמנות.