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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

סוג השדה הגדרות ברירת המחדל לשדות שזוהו אוטומטית
string indexable,‏ retrievable,‏ searchable,‏ dynamicFacetable
integer, number, boolean indexable, retrievable, dynamicFacetable
כל סוג אחר חוץ מ-object (datetime,‏ geolocation,‏ array) indexable, retrievable
object ללא

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

הגדרות סכימה ברמה העליונה

השדות הבאים ברמה העליונה בסכימת ה-JSON קובעים איך Gemini Enterprise מזהה ומוסיף שדות כשמייבאים מסמכים:

  • ‫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

    אם הערך של datetime_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.

הגדרות שדות ברמת הנכס

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

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

    שדות עם הערה keyPropertyMapping משתמשים בהגדרות indexable ו-searchable שנקבעו מראש על ידי מאפיין המפתח, והם לא retrievable, completable או dynamicFacetable כברירת מחדל. מכיוון שהשדות indexable ו-searchable מוגדרים מראש, אסור לכלול הערות מפורשות של "indexable" או "searchable" באותו שדה בסכימת ה-JSON, גם עם הערך false. אחרת, הבקשה תיכשל ותוצג השגיאה INVALID_ARGUMENT: Key property FIELD_NAME should not contain searchable or indexable annotation.. עדיין אפשר לכלול את "retrievable": true כדי שהשדה הממופה יוחזר בתוצאות החיפוש.

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

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

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

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

  • ‫searchable. מציין אם אפשר להוסיף את השדה הזה לאינדקס הפוך כדי להתאים לשאילתות טקסט לא מובנות. אפשר להגדיר את זה רק לשדות מסוג string. אפשר להגדיר עד 50 שדות שניתנים לחיפוש. כשמציינים או מעדכנים סכימת JSON באופן מפורש, שדות שמוגדרים על ידי המשתמש מקבלים את ערך ברירת המחדל false עבור searchable (חוץ משדות שמכילים את הערך 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 של ה-API‏ schemas.patch כדי לספק את סכימת ה-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. אופציונלי: בודקים את הסכימה לפי ההליך הצגת הגדרת סכימה.

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