הוספה או זיהוי אוטומטי של סכימה

כשמייבאים נתונים מובְנים באמצעות Google Cloud המסוף, התכונה 'חיפוש באמצעות סוכן' מזהה באופן אוטומטי את הסכימה. אתם יכולים להשתמש בסכימה שזוהתה אוטומטית במנוע שלכם, או להשתמש ב-API כדי לספק סכימה שתציין את מבנה הנתונים.

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

מידע נוסף על הסכימה זמין במאמר dataStores.schemas.

שיטות להזנת הסכימה של מאגר הנתונים

יש גישות שונות לקביעת הסכימה של נתונים מובְנים.

  • זיהוי ועריכה אוטומטיים אפשר לתכונה 'חיפוש מבוסס סוכנים' לזהות ולהציע באופן אוטומטי סכימה ראשונית. לאחר מכן, משפרים את הסכימה דרך ממשק המסוף. ‫Google ממליצה מאוד, אחרי שהשדות מזוהים אוטומטית, למפות מאפיינים מרכזיים לכל השדות החשובים.

    זו הגישה שבה תשתמשו כשאתם פועלים לפי ההוראות של Google Cloud המסוף בנוגע לנתונים מובְנים במאמרים יצירת מאגר נתוני חיפוש ויצירת מאגר נתוני המלצות בהתאמה אישית.

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

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

  • מדיה: צריך לספק את הנתונים בסכימה שהוגדרה על ידי Google. אם יוצרים מאגר נתונים למדיה, אפשר להשתמש בסכימה המוגדרת מראש של Google. אם בוחרים באפשרות הזו, מניחים שאובייקט ה-JSON בנוי בפורמט שמופיע במאמר מידע על מסמכי מדיה ומאגר נתונים. כברירת מחדל, התכונה 'זיהוי אוטומטי' מוסיפה לסכימה כל שדה חדש שהיא מוצאת במהלך הטמעת הנתונים.

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

  • מדיה: זיהוי ועריכה אוטומטיים, תוך הקפדה על הכללת מאפייני המדיה הנדרשים. לגבי נתוני מדיה, אפשר להשתמש באפשרות 'זיהוי אוטומטי' כדי לקבל הצעות לסכימה ולערוך אותה כדי לשפר אותה. באובייקט ה-JSON צריך לכלול שדות שאפשר למפות למאפייני מפתח המדיה: title, uri, category, media_duration ו-media_available_time.

    זו הגישה שתשתמשו בה כשאתם מייבאים נתוני מדיה דרך Google Cloud המסוף אם נתוני המדיה לא נמצאים בסכימה שמוגדרת על ידי Google.

  • Media: Provide your own schema as a JSON object. מספקים את הסכימה לחיפוש מבוסס סוכנים כאובייקט JSON. צריך להכין אובייקט JSON תקין. הסכימה צריכה לכלול שדות שאפשר למפות למאפייני מפתח המדיה: title,‏ uri,‏ category,‏ media_duration ו-media_available_time.

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

    בגישה הזו, משתמשים ב-API באמצעות פקודת curl (או תוכנית). הוראות מפורטות

מידע על זיהוי ועריכה אוטומטיים

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

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

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

דוגמה לסכימה כאובייקט JSON

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

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

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

הנה כמה מהשדות בדוגמה הזו של סכימה:

  • ‫dynamic. אם dynamic מוגדר למחרוזת "true", כל מאפיין חדש שנמצא בנתונים המיובאים יתווסף לסכימה. אם הערך של dynamic מוגדר כ-"false", המערכת מתעלמת ממאפיינים חדשים שנמצאים בנתונים המיובאים. המאפיינים לא מתווספים לסכימה והערכים לא מיובאים.

    לדוגמה, בסכימה יש שני מאפיינים: title ו-description, ואתם מעלים נתונים שמכילים מאפיינים של title, description ו-rating. אם הערך של dynamic הוא "true", מאפיין הדירוגים והנתונים מיובאים. אם dynamic הוא "false", המאפיינים rating לא מיובאים, אבל המאפיינים title ו-description כן מיובאים.

    ערך ברירת המחדל הוא "true".

  • ‫datetime_detection. אם הערך של datetime_detection מוגדר כבוליאני true, אז כשמייבאים נתונים בפורמט של תאריך ושעה, סוג הסכימה מוגדר כ-datetime. הפורמטים הנתמכים הם RFC 3339 ו-ISO 8601.

    לדוגמה:

    • 2024-08-05 08:30:00 UTC

    • 2024-08-05T08:30:00Z

    • 2024-08-05T01:30:00-07:00

    • 2024-08-05

    • 2024-08-05T08:30:00+00:00

    אם datatime_detection מוגדר לערך הבוליאני false, אז כשמייבאים נתונים בפורמט תאריך ושעה, סוג הסכימה מוגדר ל-string.

    ערך ברירת המחדל הוא true.

  • ‫geolocation_detection. אם הערך של geolocation_detection מוגדר כבוליאני true, אז כשמייבאים נתונים בפורמט של מיקום גיאוגרפי, סוג הסכימה מוגדר כ-geolocation. הנתונים מזוהים כמיקום גיאוגרפי אם הם אובייקט שמכיל מספר של קו רוחב ומספר של קו אורך, או אובייקט שמכיל מחרוזת של כתובת.

    לדוגמה:

    • "myLocation": {"latitude":37.42, "longitude":-122.08}

    • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

    אם הערך של geolocation_detection הוא בוליאני false, אז כשמייבאים נתונים בפורמט של מיקום גיאוגרפי, סוג הסכימה מוגדר כ-object.

    ערך ברירת המחדל הוא true.

  • ‫keyPropertyMapping. שדה שממפה מילות מפתח מוגדרות מראש לשדות קריטיים במסמכים, ועוזר להבהיר את המשמעות הסמנטית שלהם. הערכים כוללים את title,‏ description,‏ uri וcategory. שימו לב: שם השדה לא צריך להיות זהה לערך keyPropertyValues. לדוגמה, בשדה שנקרא my_title, אפשר לכלול שדה keyPropertyValues עם ערך של title.

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

  • ‫type. סוג השדה. זהו ערך מחרוזת שהוא datetime,‏ geolocation או אחד מסוגי הנתונים הפרימיטיביים (integer,‏ boolean,‏ object,‏ array,‏ number או string).

השדות הבאים של הנכס רלוונטיים רק לאפליקציות לחיפוש:

  • ‫retrievable. מציין אם אפשר להחזיר את השדה הזה בתגובה לחיפוש. אפשר להגדיר את זה לשדות מסוג number,‏ string,‏ boolean,‏ integer,‏ datetime ו-geolocation. אפשר להגדיר עד 50 שדות לאחזור. אי אפשר לאחזר כברירת מחדל שדות שהוגדרו על ידי המשתמש ושדות keyPropertyValues. כדי לאפשר אחזור של שדה, צריך לכלול את "retrievable": true עם השדה.

  • ‫indexable. מציין אם אפשר לסנן, להוסיף היבטים, להגביר או למיין את השדה הזה בשיטה servingConfigs.search. אפשר להגדיר את זה לשדות מסוג number,‏ string,‏ boolean,‏ integer,‏ datetime ו-geolocation. אפשר להגדיר עד 50 שדות כניתנים לאינדוקס. כברירת מחדל, אי אפשר ליצור אינדקס לשדות שהוגדרו על ידי המשתמש, למעט שדות שמכילים את השדה keyPropertyMapping. כדי להפוך שדה לאינדקס, מוסיפים את "indexable": true לשדה.

  • ‫dynamicFacetable. מציין שאפשר להשתמש בשדה כמאפיין דינמי. אפשר להגדיר את זה לשדות מסוג number, string, boolean ו-integer. כדי להגדיר שדה כפילטור דינמי, צריך גם להגדיר אותו כניתן לאינדוקס: כוללים את "dynamicFacetable": true ואת "indexable": true בשדה.

  • ‫searchable. מציין אם אפשר להוסיף את השדה הזה לאינדקס הפוך כדי להתאים לשאילתות של טקסט לא מובנה. אפשר להגדיר את זה רק לשדות מסוג string. אפשר להגדיר עד 50 שדות כניתנים לחיפוש. כברירת מחדל, אי אפשר לחפש שדות שהוגדרו על ידי המשתמש, למעט שדות שמכילים את השדה keyPropertyMapping. כדי להגדיר שדה כניתן לחיפוש, צריך לכלול את התג "searchable": true בשדה.

  • ‫completable. מציין אם אפשר להחזיר את השדה הזה כהצעה של ההשלמה האוטומטית. אפשר להגדיר את האפשרות הזו רק לשדות מסוג string. כדי להגדיר שדה כחובה, מוסיפים את "completable": true לשדה.

בנוסף, השדה הבא רלוונטי רק לאפליקציות המלצות:

  • ‫recommendationsFilterable. מציין שאפשר להשתמש בשדה בביטוי סינון של המלצות. מידע כללי על סינון המלצות זמין במאמר סינון המלצות.

      ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },

אספקת סכימה משלכם כאובייקט JSON

כדי לספק סכימה משלכם, אתם יוצרים מאגר נתונים שמכיל סכימה ריקה, ואז מעדכנים את הסכימה ומספקים את הסכימה שלכם כאובייקט JSON. איך לעשות את זה?

  1. מכינים את הסכימה כאובייקט JSON, בעזרת הסכימה לדוגמה כאובייקט JSON.

  2. יוצרים מאגר נתונים.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "INDUSTRY_VERTICAL"
}'

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫DATA_STORE_ID: המזהה של מאגר הנתונים של חיפוש מבוסס סוכנים שרוצים ליצור. המזהה יכול להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים.
    • ‫DATA_STORE_DISPLAY_NAME: השם המוצג של מאגר הנתונים של חיפוש מבוסס סוכנים שרוצים ליצור.
    • INDUSTRY_VERTICAL: GENERIC או MEDIA

  3. משתמשים ב-method schemas.patch של API כדי לספק את סכימת ה-JSON החדשה כאובייקט JSON.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫DATA_STORE_ID: המזהה של מאגר הנתונים של חיפוש מבוסס סוכנים.

    • ‫JSON_SCHEMA_OBJECT: סכמת ה-JSON החדשה כאובייקט JSON. לדוגמה:

      {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

  4. אופציונלי: בודקים את הסכימה לפי השלבים שמפורטים במאמר הצגת הגדרת סכימה.

המאמרים הבאים