Fornire o rilevare automaticamente uno schema

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

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

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

Approcci per fornire lo schema per il datastore

Esistono vari approcci per determinare lo schema per i dati strutturati.

  • Rilevamento e modifica automatici. Consenti alle applicazioni AI di rilevare e suggerire automaticamente 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 istruzioni della console Google Cloud per i dati strutturati in Crea un datastore di ricerca e Crea un datastore di consigli personalizzati.

  • Fornisci lo schema come oggetto JSON. Fornisci lo schema ad AI Applications 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 (o programma) curl. Ad esempio, vedi Importa una volta da BigQuery. Consulta anche le seguenti istruzioni: Fornisci il tuo schema.

  • Media: fornisci i tuoi dati nello schema definito da Google. Se crei un datastore per i contenuti multimediali, puoi scegliere di utilizzare lo schema predefinito di Google. La scelta di questa opzione presuppone che tu abbia strutturato l'oggetto JSON nel formato indicato in Informazioni sui documenti multimediali e sull'archivio dati. Per impostazione predefinita, il rilevamento automatico aggiunge allo schema tutti i nuovi campi che trova durante l&#3importazione datiti.

    Questo è l'approccio che utilizzi quando segui le istruzioni in Crea un'app multimediale e un datastore. È anche l'approccio utilizzato nei tutorial Inizia a usare suggerimenti sui contenuti multimediali e Inizia a utilizzare la ricerca di contenuti multimediali, in cui i dati di esempio vengono forniti nello schema predefinito di Google.

  • Media: rilevamento e modifica automatici, assicurandosi di includere le proprietà dei media richieste. Per i dati multimediali, puoi utilizzare il rilevamento automatico per suggerire lo schema e modificarlo per perfezionarlo. Nell'oggetto JSON devi includere campi che possono essere mappati alle proprietà della chiave multimediale: title, uri, category, media_duration e media_available_time.

    Questo è l'approccio che utilizzerai quando importi i dati multimediali tramite la consoleGoogle Cloud se i dati multimediali non sono nello schema definito da Google.

  • Media: fornisci il tuo schema come oggetto JSON. Fornisci lo schema ad AI Applications come oggetto JSON. Devi aver preparato un oggetto JSON corretto. Lo schema deve includere campi che possono essere mappati alle proprietà della chiave multimediale: title, uri, category, media_duration e media_available_time.

    Per un esempio di oggetto JSON, consulta Schema di esempio come oggetto JSON. Dopo aver creato lo schema, carica i dati multimediali in base a questo schema.

    Per questo approccio, utilizzi l'API tramite un comando curl (o un programma). Consulta le seguenti istruzioni: Fornire il proprio schema.

Informazioni sul rilevamento e la modifica automatici

Quando inizi a importare i dati, Vertex AI Search campiona i primi documenti importati. In base a questi documenti, propone uno schema per i dati, che puoi rivedere o modificare.

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

Se Vertex AI Search 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.

Esempio di schema come oggetto JSON

Puoi definire il tuo schema utilizzando il formato JSON Schema, che è 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
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

Se stai definendo uno schema multimediale, devi includere campi che possono essere mappati alle proprietà chiave dei contenuti multimediali. Queste proprietà chiave sono mostrate in questo esempio.

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 e i valori non 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, anche se title e description vengono importate.

    Il valore predefinito è "true".

  • datetime_detection. Se datetime_detection è impostato sul valore booleano true, quando vengono importati 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 dati in formato datetime, 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 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 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 sui campi critici dei tuoi documenti, contribuendo a chiarirne il significato semantico. I valori includono title, description, uri e category. Tieni presente che il nome del campo non deve corrispondere al valore di keyPropertyValues. Ad esempio, per un campo che hai chiamato my_title, puoi includere un campo keyPropertyValues con un valore di title.

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

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

I seguenti campi delle proprietà si applicano solo alle app di ricerca:

  • 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 recuperabile un campo, includi "retrievable": true con il campo.

  • indexable. Indica se questo campo può essere filtrato, sfaccettato, 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 sfaccettabile, 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 compilabile un campo, includi "completable": true con il campo.

Inoltre, il seguente campo si applica solo alle app di consigli:

  • recommendationsFilterable. Indica che il campo può essere utilizzato in un'espressione di filtro per i consigli. Per informazioni generali sul filtraggio dei consigli, vedi Filtrare i consigli.

      ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },

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 Esempio di schema come oggetto JSON come guida.

  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 del tuo Google Cloud progetto.
    • DATA_STORE_ID: l'ID del datastore Vertex AI Search che vuoi creare. Questo ID può contenere solo lettere minuscole, cifre, trattini bassi e trattini.
    • DATA_STORE_DISPLAY_NAME: il nome visualizzato del datastore Vertex AI Search che vuoi creare.
    • INDUSTRY_VERTICAL: GENERIC o MEDIA

  3. Utilizza il metodo API schemas.patch 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 del tuo Google Cloud progetto.
    • DATA_STORE_ID: l'ID del datastore Vertex AI Search.

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

  4. (Facoltativo) Esamina lo schema seguendo la procedura Visualizzare una definizione dello schema.

Passaggi successivi