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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

סכימה לדוגמה כאובייקט 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
    }
  }
}

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

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

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

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

• ‫datetime_detection. אם הערך של datetime_detection הוא בוליאני true, כשמייבאים נתונים בפורמט datetime, סוג הסכימה מוגדר כ-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, כשמייבאים נתונים בפורמט datetime, סוג הסכימה מוגדר כ-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 ניתנים כברירת מחדל להוספה לאינדקס ולחיפוש, אבל לא לאחזור, להשלמה או ל-dynamicFacetable. כלומר, לא צריך לכלול את השדות indexable או searchable עם השדה keyPropertyValues כדי לקבל את פעולת ברירת המחדל הצפויה.

  הערה: מאפייני מפתח יכולים לשפר את האיכות של תוצאות החיפוש ואת הדיוק של ההשלמה האוטומטית בחיפוש. אם משתמשים בזיהוי סכימה אוטומטי, מאפייני המפתח לא מתווספים באופן אוטומטי. מומלץ מאוד להשתמש בשיטה schemas.patch כדי לסמן שדות נתונים כמאפייני מפתח, במיוחד title,‏ uri ו-description.

• ‫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 בשדה.

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

לספק סכימה משלכם כאובייקט 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: מזהה הפרויקט.
   • ‫DATA_STORE_ID: המזהה של מאגר הנתונים שרוצים ליצור. המזהה יכול להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים.
   • ‫DATA_STORE_DISPLAY_NAME: השם המוצג של מאגר הנתונים שרוצים ליצור.
   • INDUSTRY_VERTICAL: GENERIC

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: מזהה הפרויקט.
   • ‫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"
         }
       }
     }

     דוגמה לפקודה ולתוצאה

     curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
     "structSchema": {
     "$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"
     }
     }
     }
     }'
     
     {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
     "metadata": {
     "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
     }
     }
     

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

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

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