Nota:Vertex AI Search verrà rinominato Agent Search. Stiamo aggiornando i contenuti per riflettere il nuovo brand.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Aggiornare uno schema

Puoi aggiornare lo schema per tutti i dati che supportano uno schema, ad esempio dati strutturati, dati di siti web con dati strutturati, o altri dati non strutturati con metadati.

Puoi aggiornare lo schema nella Google Cloud console o utilizzando il metodo API schemas.patch. L'aggiornamento dello schema di un sito web è supportato solo tramite l'API REST.

Per aggiornare lo schema, puoi aggiungere nuovi campi, modificare le annotazioni indicizzabili, ricercabili e recuperabili per un campo o contrassegnare un campo come proprietà della chiave, ad esempio title, uri e description.

Prima di iniziare

Prima di aggiornare lo schema, comprendi i concetti chiave spiegati in questa sezione.

Importanza delle proprietà della chiave

Ecco alcuni motivi per cui devi mappare i campi dello schema alle proprietà della chiave:

Google consiglia vivamente di aggiornare lo schema con le mappature delle proprietà della chiave, in particolare per title. In questo modo, i risultati vengono visualizzati correttamente e la ricerca dell'agente può identificare le informazioni importanti che le consentono di generare risultati migliori.
Nei datastore di dati strutturati, per ottenere l'indicatore keywordSimilarityScore nella risposta di ricerca, devi aggiornare lo schema per eseguire le seguenti operazioni:
- Mappa i campi di testo essenziali per la corrispondenza delle parole chiave alle proprietà della chiave title e description
- Aggiorna l'annotazione per i campi di testo come Searchable

Requisiti

Quando aggiorni uno schema, assicurati che il nuovo schema sia compatibile con le versioni precedenti dello schema che stai aggiornando. Per aggiornare uno schema con un nuovo schema non compatibile con le versioni precedenti, devi eliminare tutti i documenti nel datastore, eliminare lo schema e creare un nuovo schema.

L'aggiornamento di uno schema attiva la reindicizzazione di tutti i documenti. Questa operazione può richiedere tempo e comportare costi aggiuntivi:

Tempo. La reindicizzazione di un datastore di grandi dimensioni può richiedere ore o giorni.
Spese. La reindicizzazione può comportare costi, a seconda del parser. Ad esempio, la reindicizzazione dei datastore che utilizzano il parser OCR o il parser di layout comporta costi. Per saperne di più, consulta i prezzi delle funzionalità di Document AI.
Impatto sul servizio. La reindicizzazione potrebbe comportare servizi lenti o non disponibili, soprattutto per i datastore di grandi dimensioni. Google consiglia di pianificare gli aggiornamenti dello schema di conseguenza, tenendo conto del potenziale downtime per le applicazioni critiche.

Gli aggiornamenti dello schema non supportano quanto segue:

Modifica del tipo di campo. Un aggiornamento dello schema non supporta la modifica del tipo di campo. Ad esempio, un campo mappato su integer non può essere modificato in string.
Rimozione di un campo. Una volta definito, un campo non può essere rimosso. Puoi continuare ad aggiungere nuovi campi, ma non puoi rimuovere un campo esistente.

Aggiorna lo schema

Puoi aggiornare lo schema nella Google Cloud console o utilizzando l'API.

Console

Per aggiornare uno schema nella Google Cloud console:

Esamina la sezione Requisiti e limitazioni per verificare che l'aggiornamento dello schema sia valido.
Se stai aggiornando le annotazioni dei campi (impostando i campi come indicizzabili, recuperabili, con filtri dinamici, ricercabili o completabili), consulta Configurare le impostazioni dei campi per conoscere le limitazioni e i requisiti di ogni tipo di annotazione.
Verifica di aver completato importazione dati. In caso contrario, lo schema potrebbe non essere ancora disponibile per la modifica.
Nella Google Cloud console, vai alla pagina AI Applications.

AI Applications
Nel menu di navigazione, fai clic su Datastore.
Nella colonna Nome, fai clic sul datastore con lo schema che vuoi aggiornare.
Fai clic sulla scheda Schema per visualizzare lo schema dei dati.

Questa scheda potrebbe essere vuota se è la prima volta che modifichi i campi.
Fai clic sul pulsante Modifica.
Aggiorna lo schema:
- Mappa le proprietà della chiave: nella colonna Proprietà della chiave dello schema, seleziona una proprietà della chiave a cui mappare un campo. Ad esempio, se un campo denominato details contiene sempre la descrizione di un documento, mappa questo campo alla proprietà della chiave Descrizione.
- Aggiorna il numero di dimensioni (avanzato): puoi aggiornare questa impostazione se utilizzi vector embedding personalizzati con la ricerca dell'agente. Consulta Avanzato: utilizzare gli embedding personalizzati.
- Aggiorna le annotazioni dei campi: per aggiornare le annotazioni di un campo, seleziona o deseleziona l'impostazione di annotazione di un campo. Le annotazioni disponibili sono Recuperabile, Indicizzabile, Con filtri dinamici, Ricercabile e Completabile. Alcune impostazioni dei campi hanno limitazioni. Consulta Configurare le impostazioni dei campi per le descrizioni e i requisiti di ogni tipo di annotazione.
- Aggiungi un nuovo campo: l'aggiunta di nuovi campi allo schema prima di importare nuovi documenti con questi campi può ridurre il tempo necessario alla ricerca dell'agente per reindicizzare i dati dopo l'importazione.
  1. Fai clic su Aggiungi nuovi campi per espandere la sezione.
  2. Fai clic add_box Aggiungi nodo e specifica le impostazioni per il nuovo campo.
    
    Per indicare un array, imposta Array su Sì. Ad esempio, per aggiungere un array di stringhe, imposta type su string e Array su Yes.
    
    Per un indice del datastore dei dati del sito web, tutti i campi che aggiungi sono array per impostazione predefinita.
Fai clic su Salva per applicare le modifiche allo schema.

La modifica dello schema attiva la reindicizzazione. Per i datastore di grandi dimensioni, la reindicizzazione può richiedere ore.

REST

Per utilizzare l'API per aggiornare lo schema:

Esamina le sezioni Requisiti e limitazioni ed Esempi di limitazioni (solo REST) per verificare che le modifiche allo schema siano valide.

Per aggiornare lo schema dei datastore con siti web o dati non strutturati con metadati, vai al passaggio 5 per chiamare il metodo schema.patch.
Se stai aggiornando le annotazioni dei campi (impostando i campi come indicizzabili, recuperabili, con filtri dinamici o ricercabili), consulta Configurare le impostazioni dei campi per conoscere le limitazioni e i requisiti di ogni tipo di annotazione.
Se stai modificando uno schema rilevato automaticamente, assicurati di aver completato importazione dati. In caso contrario, lo schema potrebbe non essere ancora disponibile per la modifica.
Trova l'ID del datastore. Se hai già l'ID del datastore, vai al passaggio successivo.
1. Nella Google Cloud console, vai alla pagina AI Applications e nel menu di navigazione, fai clic su Datastore.
  
  Vai alla pagina Datastore
2. Fai clic sul nome del tuo datastore.
3. Nella pagina Dati del datastore, recupera l'ID del datastore.

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 del tuo Google Cloud progetto.
DATA_STORE_ID: l'ID del datastore della ricerca dell'agente.

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

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

C#

Per saperne di più, consulta la documentazione di riferimento dell' API C# per la ricerca dell'agente.

Per eseguire l'autenticazione nella ricerca dell'agente, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Per saperne di più, consulta la documentazione di riferimento dell' API Go per la ricerca dell'agente.


//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

Per saperne di più, consulta la documentazione di riferimento dell'JavaAPI per la ricerca dell'agente.

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

Per saperne di più, consulta la documentazione di riferimento dell' API Python per la ricerca dell'agente.

# 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

Per saperne di più, consulta la documentazione di riferimento dell' API Ruby per la ricerca dell'agente.

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

Esempi di limitazioni (solo REST)

Questa sezione mostra esempi di tipi di aggiornamenti dello schema validi e non validi. Questi esempi utilizzano il seguente schema JSON di esempio:

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

Esempi di aggiornamenti supportati

Sono supportati i seguenti aggiornamenti dello schema di esempio.

Aggiunta di un campo. In questo esempio, il campo properties.uri è stato aggiunto allo schema.

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

Aggiunta o rimozione di annotazioni delle proprietà della chiave per title, description o uri. In questo esempio, keyPropertyMapping è stato aggiunto al campo 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"
      }
    }
  }
}

Esempi di aggiornamenti dello schema non validi

I seguenti aggiornamenti dello schema di esempio non sono supportati.

Modifica del tipo di campo. In questo esempio, il campo title ha avuto il tipo modificato da stringa a numero. Questa operazione non è supportata.

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

Rimozione di un campo. In questo esempio, il campo title è stato rimosso. Questa operazione non è supportata.

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