עדכון סכימה

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

אפשר לעדכן את הסכימה במסוף Google Cloud או באמצעות שיטת ה-API‏ schemas.patch. אפשר לעדכן את הסכימה של אתר רק באמצעות API בארכיטקטורת REST.

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

לפני שמתחילים

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

חשיבות המאפיינים העיקריים

יש כמה סיבות לכך שצריך למפות את שדות הסכימה למאפייני מפתח:

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

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

  • ממפים את שדות הטקסט שחיוניים להתאמה למילות מפתח למאפייני המפתח title ו-description
  • תעדכן את ההערה לשדות הטקסט ל-Searchable

דרישות

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

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

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

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

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

עדכוני סכימה לא תומכים בפעולות הבאות:

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

עדכון הסכימה

אפשר לעדכן את הסכימה במסוף Google Cloud או באמצעות ה-API.

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

המסוף

כדי לעדכן סכימה במסוף Google Cloud :

1. כדאי לעיין בקטע דרישות ומגבלות כדי לוודא שעדכון הסכימה תקין.

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

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

4. נכנסים לדף AI Applications במסוף Google Cloud .

   אפליקציות AI

5. בתפריט הניווט, לוחצים על מאגרי נתונים.

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

7. לוחצים על הכרטיסייה סכימה כדי לראות את הסכימה של הנתונים.

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

8. לוחצים על הלחצן עריכה.

9. מעדכנים את הסכימה:

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

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

   • עדכון הערות בשדות: כדי לעדכן הערות בשדה, בוחרים או מבטלים את הבחירה בהגדרת ההערה של השדה. ההערות הזמינות הן Retrievable,‏ Indexable,‏ Dynamic Facetable,‏ Searchable ו-Completable. יש מגבלות על חלק מההגדרות של השדות. בקטע הגדרת שדות מופיעים תיאורים ודרישות לכל סוג של הערה.

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

     1. לוחצים על הוספת שדות חדשים כדי להרחיב את הקטע הזה.

     2. לוחצים על add_box הוספת צומת ומציינים את ההגדרות של השדה החדש.

        כדי לציין מערך, מגדירים את Array (מערך) לערך Yes (כן). לדוגמה, כדי להוסיף מערך של מחרוזות, מגדירים את type ל-string ואת Array ל-Yes.

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

10. לוחצים על שמירה כדי להחיל את השינויים בסכימה.

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

REST

כדי להשתמש ב-API לעדכון הסכימה, פועלים לפי השלבים הבאים:

1. כדאי לעיין בקטע דרישות ומגבלות ובקטע דוגמאות למגבלות (ל-REST בלבד) כדי לוודא ששינויי הסכימה שלכם תקינים.

   כדי לעדכן את הסכימה של מאגרי נתונים עם אתרים או נתונים לא מובְנים עם מטא-נתונים, אפשר לדלג לשלב 5 כדי להפעיל את השיטה schema.patch.

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

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

4. איך מוצאים את המזהה של מאגר הנתונים אם כבר יש לכם מזהה של מאגר נתונים, אפשר לדלג לשלב הבא.

   1. במסוף Google Cloud , עוברים לדף AI Applications ובתפריט הניווט לוחצים על Data Stores.

      מעבר לדף Data Stores

   2. לוחצים על השם של מאגר הנתונים.

   3. בדף Data של מאגר הנתונים, מעתיקים את המזהה של מאגר הנתונים.

5. משתמשים ב-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"
         }
       }
     }

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

     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"
     }
     }
     

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

C#

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים C#.

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

using Google.Cloud.DiscoveryEngine.V1;
using Google.LongRunning;

public sealed partial class GeneratedSchemaServiceClientSnippets
{
    /// <summary>Snippet for UpdateSchema</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void UpdateSchemaRequestObject()
    {
        // Create client
        SchemaServiceClient schemaServiceClient = SchemaServiceClient.Create();
        // Initialize request argument(s)
        UpdateSchemaRequest request = new UpdateSchemaRequest
        {
            Schema = new Schema(),
            AllowMissing = false,
        };
        // Make the request
        Operation<Schema, UpdateSchemaMetadata> response = schemaServiceClient.UpdateSchema(request);

        // Poll until the returned long-running operation is complete
        Operation<Schema, UpdateSchemaMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Schema result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Schema, UpdateSchemaMetadata> retrievedResponse = schemaServiceClient.PollOnceUpdateSchema(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Schema retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים Go.

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

//go:build examples

package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewSchemaClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.UpdateSchemaRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#UpdateSchemaRequest.
	}
	op, err := c.UpdateSchema(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים Java.

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

import com.google.cloud.discoveryengine.v1.Schema;
import com.google.cloud.discoveryengine.v1.SchemaServiceClient;
import com.google.cloud.discoveryengine.v1.UpdateSchemaRequest;

public class SyncUpdateSchema {

  public static void main(String[] args) throws Exception {
    syncUpdateSchema();
  }

  public static void syncUpdateSchema() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
      UpdateSchemaRequest request =
          UpdateSchemaRequest.newBuilder()
              .setSchema(Schema.newBuilder().build())
              .setAllowMissing(true)
              .build();
      Schema response = schemaServiceClient.updateSchemaAsync(request).get();
    }
  }
}

Python

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים Python.

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

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_update_schema():
    # Create a client
    client = discoveryengine_v1.SchemaServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.UpdateSchemaRequest()

    # Make the request
    operation = client.update_schema(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

מידע נוסף מופיע בתיעוד העזר של ה-API של חיפוש מבוסס סוכנים Ruby.

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

require "google/cloud/discovery_engine/v1"

##
# Snippet for the update_schema call in the SchemaService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::SchemaService::Client#update_schema.
#
def update_schema
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::SchemaService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::UpdateSchemaRequest.new

  # Call the update_schema method.
  result = client.update_schema request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

דוגמאות למגבלות (REST בלבד)

בקטע הזה מופיעות דוגמאות לעדכונים תקינים ולא תקינים של סכימה. בדוגמאות האלה נעשה שימוש בסכימת ה-JSON הבאה:

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

דוגמאות לעדכונים נתמכים

העדכונים הבאים בסכימת הדוגמה נתמכים.

• הוספת שדה. בדוגמה הזו, השדה properties.uri נוסף לסכימה.

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

• הוספה או הסרה של הערות לגבי מאפיינים מרכזיים של title, ‏description או uri. בדוגמה הזו, הערך keyPropertyMapping נוסף לשדה title.

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

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

העדכונים הבאים לסכימה לדוגמה לא נתמכים.

• שינוי סוג השדה. בדוגמה הזו, הסוג של השדה title השתנה ממחרוזת למספר. האפשרות הזו לא אפשרית.

    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "title": {
          "type": "number" // Changed from string. Not allowed.
        },
        "description": {
          "type": "string",
          "keyPropertyMapping": "description"
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string",
            "keyPropertyMapping": "category"
          }
        }
      }
    }
  

• הסרת שדה בדוגמה הזו, השדה title הוסר. האפשרות הזו לא אפשרית.

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

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

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