Fornire o rilevare automaticamente uno schema

Quando importi dati strutturati utilizzando la Google Cloud console, Gemini Enterprise rileva automaticamente lo schema. Puoi utilizzare questo schema rilevato automaticamente nel motore o utilizzare l'API per fornire uno schema che indichi la struttura dei dati.

Se fornisci uno schema e in un secondo momento lo aggiorni con un nuovo schema, il nuovo schema deve essere compatibile con il precedente. In caso contrario, l'aggiornamento dello schema non riesce.

Importante: se non fornisci uno schema, la funzionalità di rilevamento automatico può aggiornare lo schema incorporando tutti i campi appena rilevati quando importi nuovi dati. Se alcuni documenti nei dati importati contengono nuovi campi che non sono compatibili con lo schema originale, l'importazione di questi documenti non riesce.

Per informazioni di riferimento sullo schema, consulta dataStores.schemas.

Termini chiave: nel contesto dello schema, i termini campo e proprietà vengono utilizzati in modo intercambiabile.

Approcci per fornire lo schema per il datastore

Esistono vari approcci per determinare lo schema dei dati strutturati.

• Rilevamento automatico e modifica. Consenti a Gemini Enterprise di rilevare automaticamente e suggerire uno schema iniziale. Poi, perfeziona lo schema tramite l'interfaccia della console. Google consiglia vivamente di mappare le proprietà chiave a tutti i campi importanti dopo che i campi sono stati rilevati automaticamente.

  Questo è l'approccio che utilizzerai quando segui le Google Cloud istruzioni della console per i dati strutturati in Creare un datastore di dati proprietari.

• Fornisci lo schema come oggetto JSON. Fornisci lo schema a Gemini Enterprise come oggetto JSON. Devi aver preparato un oggetto JSON corretto. Per un esempio di oggetto JSON, consulta Schema di esempio come oggetto JSON. Dopo aver creato lo schema, carica i dati in base a questo schema.

  Questo è l'approccio che puoi utilizzare quando crei un datastore tramite l'API utilizzando un comando curl (o un programma). Ad esempio, consulta Importare una sola volta da BigQuery. Consulta anche le seguenti istruzioni: Fornire il proprio schema.

Informazioni sul rilevamento automatico e sulla modifica

Quando inizi a importare i dati, Gemini Enterprise campiona i primi documenti importati. In base a questi documenti, propone uno schema per i dati, che puoi esaminare o modificare.

Se i campi che vuoi mappare alle proprietà chiave non sono presenti nei documenti campionati, puoi aggiungerli manualmente quando esamini lo schema.

Suggerimento: assicurati che i documenti all'inizio del set di dati siano di buona qualità, ovvero che tutti i campi chiave siano rappresentati. In questo modo, non dovrai aggiungere o modificare i campi in un secondo momento.

Se Gemini Enterprise rileva altri campi in un secondo momento durante l'importazione dei dati, li importa comunque e li aggiunge allo schema. Se vuoi modificare lo schema dopo aver importato tutti i dati, consulta Aggiornare lo schema.

Schema di esempio come oggetto JSON

Puoi definire il tuo schema utilizzando il formato JSON Schema , un linguaggio dichiarativo open source per definire, annotare e convalidare i documenti JSON. Ad esempio, questa è un'annotazione dello schema JSON valida:

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

Ecco alcuni dei campi in questo esempio di schema:

• dynamic. Se dynamic è impostato sul valore stringa "true", tutte le nuove proprietà trovate nei dati importati vengono aggiunte allo schema. Se dynamic è impostato su "false", le nuove proprietà trovate nei dati importati vengono ignorate; le proprietà non vengono aggiunte allo schema né i valori vengono importati.

  Ad esempio, uno schema ha due proprietà: title e description e carichi dati che contengono proprietà per title, description e rating. Se dynamic è "true", la proprietà e i dati delle valutazioni vengono importati. Se dynamic è "false", le proprietà rating non vengono importate, mentre title e description sì.

  Il valore predefinito è "true".

• datetime_detection. Se datetime_detection è impostato sul valore booleano true, quando vengono importati i dati in formato data e ora, il tipo di schema viene impostato su datetime. I formati supportati sono RFC 3339 e ISO 8601.

  Ad esempio:

  • 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

  Se datatime_detection è impostato sul valore booleano false, quando vengono importati i dati in formato data e ora, il tipo di schema viene impostato su string.

  Il valore predefinito è true.

• geolocation_detection. Se geolocation_detection è impostato sul valore booleano true, quando vengono importati i dati in formato di geolocalizzazione, il tipo di schema viene impostato su geolocation. I dati vengono rilevati come geolocalizzazione se sono un oggetto contenente un numero di latitudine e un numero di longitudine o un oggetto contenente una stringa di indirizzo.

  Ad esempio:

  • "myLocation": {"latitude":37.42, "longitude":-122.08}

  • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

  Se geolocation_detection è impostato sul valore booleano false, quando vengono importati i dati in formato di geolocalizzazione, il tipo di schema viene impostato su object.

  Il valore predefinito è true.

• keyPropertyMapping. Un campo che mappa le parole chiave predefinite ai campi critici nei documenti, contribuendo a chiarire il loro significato semantico. I valori includono title, description, uri e category. Tieni presente che il nome del campo non deve corrispondere al valore keyPropertyValues. Ad esempio, per un campo denominato my_title, puoi includere un keyPropertyValues campo con un valore title.

  I campi contrassegnati con keyPropertyMapping sono indicizzabili e ricercabili per impostazione predefinita, ma non recuperabili, completabili o dynamicFacetable. Ciò significa che non devi includere i campi indexable o searchable con un campo keyPropertyValues per ottenere il comportamento predefinito previsto.

  Nota: le proprietà chiave possono migliorare la qualità dei risultati di ricerca e l'accuratezza del completamento automatico della ricerca. Se utilizzi il rilevamento automatico dello schema, le proprietà chiave non vengono aggiunte automaticamente. Ti consigliamo vivamente di utilizzare il schemas.patch metodo per contrassegnare i campi dati come proprietà chiave, in particolare title, uri, e description.

• type. Il tipo di campo. Si tratta di un valore stringa che può essere datetime, geolocation o uno dei tipi primitivi (integer, boolean, object, array, number o string).

• retrievable. Indica se questo campo può essere restituito in una risposta di ricerca. Può essere impostato per i campi di tipo number, string, boolean, integer, datetime e geolocation. È possibile impostare un massimo di 50 campi come recuperabili. I campi definiti dall'utente e i campi keyPropertyValues non sono recuperabili per impostazione predefinita. Per rendere un campo recuperabile, includi "retrievable": true con il campo.

• indexable. Indica se questo campo può essere filtrato, suddiviso in facet, potenziato o ordinato nel metodo servingConfigs.search. Può essere impostato per i campi di tipo number, string, boolean, integer, datetime e geolocation. È possibile impostare un massimo di 50 campi come indicizzabili. I campi definiti dall'utente non sono indicizzabili per impostazione predefinita, ad eccezione dei campi contenenti il campo keyPropertyMapping. Per rendere un campo indicizzabile, includi "indexable": true con il campo.

• dynamicFacetable. Indica che il campo può essere utilizzato come facet dinamico. Può essere impostato per i campi di tipo number, string, boolean e integer. Per rendere un campo dinamicamente suddiviso in facet, deve essere anche indicizzabile: includi "dynamicFacetable": true e "indexable": true con il campo.

• searchable. Indica se questo campo può essere indicizzato inversamente per corrispondere alle query di testo non strutturato. Può essere impostato solo per i campi di tipo string. È possibile impostare un massimo di 50 campi come ricercabili. I campi definiti dall'utente non sono ricercabili per impostazione predefinita, ad eccezione dei campi contenenti il campo keyPropertyMapping. Per rendere un campo ricercabile, includi "searchable": true con il campo.

• completable. Indica se questo campo può essere restituito come suggerimento di completamento automatico. Può essere impostato solo per i campi di tipo string. Per rendere un campo completabile, includi "completable": true con il campo.

Nota: per gli schemi rilevati automaticamente, i campi appena rilevati sono automaticamente indicizzabili, ricercabili e recuperabili, a condizione che rispettino i requisiti di tipo e non superino i limiti massimi.

Fornire il proprio schema come oggetto JSON

Per fornire il tuo schema, crea un datastore che contenga uno schema vuoto e poi aggiorna lo schema, fornendo il tuo schema come oggetto JSON. Segui questi passaggi:

1. Prepara lo schema come oggetto JSON, utilizzando come guida lo schema di esempio come oggetto JSON.

2. Crea un datastore.

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto.
   • DATA_STORE_ID: l'ID del datastore che vuoi creare. Questo ID può contenere solo lettere minuscole, cifre, trattini bassi e trattini.
   • DATA_STORE_DISPLAY_NAME: il nome visualizzato del datastore che vuoi creare.
   • INDUSTRY_VERTICAL: GENERIC

3. Utilizza il schemas.patch metodo API per fornire il nuovo schema JSON come oggetto 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
   }'
   

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto.
   • DATA_STORE_ID: l'ID del datastore.

   • JSON_SCHEMA_OBJECT: il nuovo schema JSON come oggetto JSON. Ad esempio:

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

     Esempio di comando e risultato

     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. (Facoltativo) Esamina lo schema seguendo la procedura Visualizzare una definizione dello schema.

Passaggi successivi

• Creare un'app di ricerca
• Ottenere la definizione dello schema per i dati strutturati
• Aggiornare uno schema per i dati strutturati