Fornire o rilevare automaticamente uno schema

Quando importi i dati strutturati utilizzando la console Google Cloud, Vertex AI Agent Builder 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, il nuovo schema deve essere compatibile con quello originale. 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 tuo datastore

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

  • Rilevamento e modifica automatici. Consenti a Vertex AI Agent Builder di rilevare automaticamente e suggerire un 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 il rilevamento automatico dei campi.

    Questo è l'approccio che utilizzerai quando seguirai le istruzioni della console Google Cloud per i dati strutturati in Creare un datastore per la ricerca e Creare un datastore per i consigli generici.

  • Fornisci lo schema come oggetto JSON. Fornisci lo schema a Vertex AI Agent Builder 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 allo schema.

    Questo è l'approccio che puoi utilizzare per creare un datastore tramite l'API utilizzando un comando (o un programma) curl. Ad esempio, consulta Importa una volta da BigQuery. Consulta anche le seguenti istruzioni, Fornisci il tuo schema.

  • Media: fornisci i dati nello schema definito da Google. Se crei un datastore per i contenuti multimediali, puoi scegliere di utilizzare lo schema predefinito di Google. Se scegli questa opzione, presupponiamo che tu abbia strutturato l'oggetto JSON nel formato indicato in Informazioni sui documenti multimediali e sullo spazio di archiviazione dei dati. Per impostazione predefinita, il rilevamento automatico aggiunge allo schema tutti i nuovi campi trovati durante l'importazione dati.

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

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

    Questo è l'approccio che utilizzerai per importare i dati multimediali tramite la console Google Cloud se non sono presenti nello schema definito da Google.

  • Media: fornisci il tuo schema come oggetto JSON. Fornisci lo schema a Vertex AI Agent Builder come oggetto JSON. Devi aver preparato un oggetto JSON corretto. Lo schema deve includere campi che possono essere mappati alle proprietà delle chiavi multimediali: 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 allo schema.

    Per questo approccio, utilizzi l'API tramite un comando (o un programma) curl. Consulta le istruzioni riportate di seguito, Fornisci il tuo schema.

Informazioni sul rilevamento automatico e sulla modifica

Quando inizi a importare i dati, Vertex AI Search esegue il campionamento dei 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 alle proprietà chiave non sono presenti nei documenti campionati, puoi aggiungerli manualmente quando esamini lo schema.

Se Vertex AI Search rileva campi aggiuntivi in un secondo momento durante l'importazione dei dati, li importa comunque e li aggiunge allo schema. Se vuoi modificare lo schema dopo l'importazione di 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
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

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

Ecco alcuni dei campi in questo esempio di schema:

  • dynamic. Se dynamic è impostato sul valore di 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 caricate 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 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/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 si tratta di 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 dei documenti, contribuendo a chiarirne il significato semantico. I valori includono title, description, uri e category. Tieni presente che il nome del campo non deve necessariamente corrispondere al valore keyPropertyValues. Ad esempio, per un campo denominato my_title, puoi includere un campo keyPropertyValues con un valore title.

    Per i datastore di ricerca, i campi contrassegnati con keyPropertyMapping sono per impostazione predefinita indicizzabili e disponibili per la ricerca, ma non recuperabili, compilabili o con visualizzazione dinamica. Ciò significa che non è necessario 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 di stringa che è datetime, geolocation o uno dei tipi primitivi (integer, boolean, object, array, number o string).

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

  • retrievable. Indica se questo campo può essere restituito in una risposta alla ricerca. Questo valore può essere impostato per i campi di tipo number, string, boolean, integer, datetime e geolocation. È possibile impostare come recuperabili un massimo di 50 campi. 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 aspetti, migliorato o ordinato nel metodo servingConfigs.search. Questo valore può essere impostato per i campi di tipo number, string, boolean, integer, datetime e geolocation. È possibile impostare come indicizzati un massimo di 50 campi. I campi definiti dall'utente non sono indicizzabili per impostazione predefinita, ad eccezione dei campi contenenti il campo keyPropertyMapping. Per rendere un campo indicizzato, includi "indexable": true nel campo.

  • dynamicFacetable. Indica che il campo può essere utilizzato come facet dinamico. Questo valore può essere impostato per i campi di tipo number, string, boolean e integer. Per rendere un campo dinamicamente visualizzabile, deve essere anche indicizzato: includere "dynamicFacetable": true e "indexable": true con il campo.

  • searchable. Indica se questo campo può essere sottoposto a indicizzazione inversa per trovare corrispondenze per le query di testo non strutturato. Questo valore può essere impostato solo per i campi di tipo string. È possibile impostare come disponibili per la ricerca un massimo di 50 campi. I campi definiti dall'utente non sono disponibili per la ricerca per impostazione predefinita, ad eccezione dei campi contenenti il campo keyPropertyMapping. Per rendere un campo disponibile per la ricerca, includi"searchable": true nel campo.

  • completable. Indica se questo campo può essere restituito come suggerimento di completamento automatico. Questo valore può essere impostato solo per i campi di tipo string. Per rendere un campo compilabile, includi "completable": true nel 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 dei consigli. Per informazioni generali sui consigli per filtrare, vedi Filtrare i consigli.

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

Fornisci il tuo schema come oggetto JSON

Per fornire il tuo schema, crea un datastore contenente uno schema vuoto, quindi aggiornalo fornendo lo 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 del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID del datastore di 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 di ricerca Vertex AI che vuoi creare.
    • INDUSTRY_VERTICAL: GENERIC o MEDIA

  3. Utilizza il metodo dell'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 progetto Google Cloud.
    • DATA_STORE_ID: l'ID dello datastore di Vertex AI Search.

    • JSON_SCHEMA_OBJECT: il tuo 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 di schema.

Passaggi successivi