Actualizar un esquema

Puede actualizar el esquema de cualquier dato que lo admita, como los datos estructurados, los datos de sitios web con datos estructurados u otros datos no estructurados con metadatos.

Puedes actualizar el esquema en la Google Cloud consola o mediante el método de la API schemas.patch. Solo se puede actualizar el esquema de un sitio web a través de la API REST.

Para actualizar el esquema, puedes añadir campos nuevos, cambiar las anotaciones indexables, de búsqueda y recuperables de un campo, o marcar un campo como propiedad clave, como title, uri y description.

Antes de empezar

Antes de actualizar el esquema, familiarízate con los conceptos clave que se explican en esta sección.

Importancia de las propiedades clave

A continuación, se indican algunos motivos por los que debes asignar los campos de tu esquema a propiedades clave:

  • Google te recomienda que actualices tu esquema con asignaciones de propiedades clave, sobre todo para title. De esta forma, los resultados se muestran correctamente y Vertex AI Search puede identificar información importante que le permite generar mejores resultados.

  • En los almacenes de datos estructurados, para obtener la señal keywordSimilarityScore en la respuesta de búsqueda, debes actualizar el esquema para hacer lo siguiente:

    • Asigna los campos de texto esenciales para la concordancia de palabras clave a las propiedades de clave title y description.
    • Actualiza la anotación de los campos de texto como Searchable

Requisitos

Cuando actualices un esquema, asegúrate de que el nuevo esquema sea compatible con el esquema que estás actualizando. Para actualizar un esquema con un esquema nuevo que no sea compatible con versiones anteriores, debes eliminar todos los documentos del almacén de datos, eliminar el esquema y crear uno nuevo.

Si actualizas un esquema, se volverán a indexar todos los documentos. Este proceso puede llevar tiempo y generar costes adicionales:

  • Hora. Volver a indexar un almacén de datos grande puede llevar horas o días.

  • Gasto. La reindexación puede generar costes, en función del analizador. Por ejemplo, se aplican costes a la reindexación de almacenes de datos que usan el analizador OCR o el analizador de diseño. Para obtener más información, consulta los precios de las funciones de Document AI.

Las actualizaciones de esquemas no admiten lo siguiente:

  • Cambiar el tipo de un campo. Una actualización del esquema no permite cambiar el tipo del campo. Por ejemplo, un campo asignado a integer no se puede cambiar a string.
  • Quitar un campo. Una vez definido, no se puede eliminar. Puedes seguir añadiendo campos, pero no puedes quitar ninguno.

Actualizar el esquema

Puedes actualizar tu esquema en la Google Cloud consola o mediante la API.

Consola

Para actualizar un esquema en la Google Cloud consola, sigue estos pasos:

  1. Consulta la sección Requisitos y limitaciones para comprobar que la actualización del esquema sea válida.

  2. Si vas a actualizar las anotaciones de campo (es decir, si vas a definir campos como indexables, recuperables, facetables dinámicos, aptos para búsquedas o completables), consulta las limitaciones y los requisitos de cada tipo de anotación.

  3. Comprueba que has completado la ingestión de datos. De lo contrario, es posible que el esquema aún no esté disponible para editarse.

  4. En la Google Cloud consola, ve a la página Aplicaciones de IA.

    Aplicaciones de IA

  5. En el menú de navegación, haga clic en Almacenes de datos.

  6. En la columna Nombre, haga clic en el almacén de datos con el esquema que quiera actualizar.

  7. Haga clic en la pestaña Esquema para ver el esquema de sus datos.

    Esta pestaña puede estar vacía si es la primera vez que editas los campos.

  8. Haz clic en el botón Edit (Editar).

  9. Actualiza el esquema:

    • Asignar propiedades clave: en la columna Propiedades clave de su esquema, seleccione una propiedad clave para asignar un campo. Por ejemplo, si un campo llamado details siempre contiene la descripción de un documento, asigne ese campo a la propiedad de clave Description.

    • Actualizar el número de dimensiones (opción avanzada): puede actualizar este ajuste si utiliza inserciones de vectores personalizadas con Vertex AI Search. Consulta Avanzado: usar inserciones personalizadas.

    • Actualizar anotaciones de campos: para actualizar las anotaciones de un campo, selecciona o desmarca el ajuste de anotación de un campo. Las anotaciones disponibles son Retrievable, Indexable, Dynamic Facetable, Searchable y Completable. Algunos ajustes de campo tienen limitaciones. Consulta Configurar ajustes de campos para ver las descripciones y los requisitos de cada tipo de anotación.

    • Añadir un campo nuevo: si añade campos nuevos a su esquema antes de importar documentos con esos campos, puede reducir el tiempo que tarda Vertex AI Search en reindexar sus datos después de la importación.

      1. Haga clic en Añadir campos para desplegar esa sección.

      2. Haz clic en add_box Añadir nodo y especifica los ajustes del nuevo campo.

        Para indicar una matriz, selecciona Sí en Matriz. Por ejemplo, para añadir un array de cadenas, asigna el valor string a type y el valor Yes a Array.

        En el caso de los índices de almacén de datos de sitios web, todos los campos que añada serán matrices de forma predeterminada.

  10. Haz clic en Guardar para aplicar los cambios en el esquema.

    Si se cambia el esquema, se activa la reindexación. En el caso de los grandes almacenes de datos, la reindexación puede tardar horas.

REST

Para usar la API y actualizar tu esquema, sigue estos pasos:

  1. Consulta las secciones Requisitos y limitaciones y Ejemplos de limitaciones (solo REST) para comprobar que los cambios en el esquema son válidos.

    Para actualizar el esquema de los almacenes de datos con sitios web o datos no estructurados con metadatos, ve al paso 5 para llamar al método schema.patch.

  2. Si vas a actualizar las anotaciones de campo (es decir, si vas a definir campos como indexables, recuperables, facetables dinámicos o aptos para búsquedas), consulta el artículo Configurar los ajustes de los campos para conocer las limitaciones y los requisitos de cada tipo de anotación.

  3. Si está editando un esquema detectado automáticamente, asegúrese de que ha completado la ingestión de datos. De lo contrario, es posible que el esquema aún no esté disponible para editarlo.

  4. Busca el ID de tu almacén de datos. Si ya tienes el ID del almacén de datos, ve al siguiente paso.

    1. En la Google Cloud consola, ve a la página Aplicaciones de IA y, en el menú de navegación, haz clic en Almacenes de datos.

      Ir a la página Almacenes de datos

    2. Haga clic en el nombre de su almacén de datos.

    3. En la página Datos de su almacén de datos, obtenga el ID del almacén de datos.

  5. Usa el método de la API schemas.patch para proporcionar tu nuevo esquema JSON como objeto 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
}'

    Haz los cambios siguientes:

    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • DATA_STORE_ID: el ID del almacén de datos de Vertex AI Search.

    • JSON_SCHEMA_OBJECT: tu nuevo esquema JSON como objeto JSON. Por ejemplo:

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

  6. Opcional: Consulta el esquema siguiendo el procedimiento Ver una definición de esquema.

C#

Para obtener más información, consulta la documentación de referencia de la API C# Vertex AI Search.

Para autenticarte en Vertex AI Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local. 

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

Para obtener más información, consulta la documentación de referencia de la API Go Vertex AI Search.

Para autenticarte en Vertex AI Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local. 


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

Para obtener más información, consulta la documentación de referencia de la API Java Vertex AI Search.

Para autenticarte en Vertex AI Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local. 

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

Para obtener más información, consulta la documentación de referencia de la API Python Vertex AI Search.

Para autenticarte en Vertex AI Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local. 

# 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

Para obtener más información, consulta la documentación de referencia de la API Ruby Vertex AI Search.

Para autenticarte en Vertex AI Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local. 

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

Ejemplos de limitaciones (solo REST)

En esta sección se muestran ejemplos de tipos de actualizaciones de esquemas válidos y no válidos. En estos ejemplos se usa el siguiente esquema 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"
      }
    }
  }
}

Ejemplos de actualizaciones admitidas

Se admiten las siguientes actualizaciones del esquema de ejemplo.

  • Añadir un campo En este ejemplo, se ha añadido el campo properties.uri al esquema.

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

  • Añadir o quitar anotaciones de propiedades clave de title, description o uri. En este ejemplo, se ha añadido keyPropertyMapping 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"
      }
    }
  }
}

Ejemplos de actualizaciones de esquemas no válidas

No se admiten las siguientes actualizaciones del esquema de ejemplo.

  • Cambiar el tipo de un campo. En este ejemplo, el tipo del campo title ha cambiado de cadena a número. Esta opción no está disponible.

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

  • Quitar un campo. En este ejemplo, se ha quitado el campo title. Esta opción no está disponible.

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

Siguientes pasos