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

כשמייבאים נתונים מובְנים באמצעות מסוף 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, כשמייבאים נתונים בפורמט 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 כדי לקבל את פעולת ברירת המחדל הצפויה.

  • ‫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. אופציונלי: בודקים את הסכימה לפי ההליך הצגת הגדרת סכימה.

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