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

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

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

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

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

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

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

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

  • מספקים את הסכימה כאובייקט 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. הפורמטים הנתמכים הם 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 לשדה.

הוספת סכימה משלכם כאובייקט 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"
    }
  }
}

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

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