Esta página foi traduzida pela API Cloud Translation.

Atualizar um esquema

É possível atualizar o esquema para quaisquer dados que contenham dados compatíveis com um esquema, como dados estruturados, dados do site com dados estruturados ou outros dados não estruturados com metadados.

É possível atualizar o esquema no console do Google Cloud ou usando o método da API schemas.patch. Só é possível atualizar o esquema de um site usando a API REST.

Para atualizar o esquema, adicione novos campos, mude as anotações indexáveis, pesquisáveis e recuperáveis de um campo ou marque um campo como uma propriedade de chave, como title, uri e description.

Atualizar o esquema

É possível atualizar o esquema no console do Google Cloud ou usando a API.

Console

Para atualizar um esquema no console do Google Cloud, siga estas etapas:

Consulte a seção Requisitos e limitações para verificar se a atualização do esquema é válida.
Se você estiver atualizando anotações de campo (definindo campos como indexáveis, recuperável, dinâmico, pesquisável ou completável), analise Defina as configurações de campo para o as limitações e os requisitos de cada tipo de anotação.
Verifique se você concluiu a ingestão de dados. Caso contrário, o esquema pode não estar disponível para edição.
No Console do Google Cloud, acesse a página Criador de agentes.

Agent Builder.
No menu de navegação, clique em Repositórios de dados.
Na coluna Nome, clique no armazenamento de dados com o esquema que você quer atualizar.
Clique na guia Esquema para conferir o esquema dos seus dados.

Essa guia pode estar vazia se for a primeira vez que você edita os campos.
Clique no botão Editar.
Atualize seu esquema:
- Mapear propriedades principais: na coluna Propriedades principais do esquema, faça o seguinte: selecione uma propriedade de chave para mapear um campo. Por exemplo, se um campo chamado details sempre contém a descrição de um documento. Mapeie esse campo à propriedade da chave Descrição.
- Atualizar o número de dimensões (avançado): atualize esse campo. se estiver usando embeddings de vetores personalizados com Vertex AI para Pesquisa. Consulte Avançado: use embeddings personalizados.
- Atualizar anotações de campo:para atualizar as anotações de um campo, selecione ou desmarque a configuração de anotação de um campo. As anotações disponíveis são Retrievable, Indexable, Dynamic Facetable, Searchable e Completable. Algumas configurações de campo têm limitações. Consulte Definir as configurações de campo para descrições e os requisitos de cada tipo de anotação.
- Adicionar um novo campo:adicionar novos campos ao esquema antes de importar novos documentos com esses campos pode reduzir o tempo necessário Vertex AI Agent Builder para reindexar seus dados após a importação.
  1. Clique em Adicionar novos campos para expandir essa seção.
  2. Clique em add_box Adicionar nó e especificar as configurações do novo campo.
    
    Para indicar uma matriz, defina Matriz como Sim. Por exemplo, para adicionar Uma matriz de strings, defina type como string e Array como Yes.
    
    Para um índice de repositório de dados de um site, todos os campos que você adicionar são matrizes por padrão.
Clique em Salvar para aplicar as mudanças no esquema.

A mudança do esquema aciona a reindexação. Para grandes repositórios de dados, a reindexação pode levar horas.

REST

Se quiser usar a API para atualizar o esquema, siga estas etapas:

Leia os requisitos e limitações e a limitação exemplos (somente REST) para verificar se o esquema muda são válidos.

Para atualizar o esquema de repositórios de dados com sites ou dados não estruturados com metadados, pule para a etapa 5 para chamar o método schema.patch.
Se você estiver atualizando anotações de campo (definindo campos como indexáveis, recuperável, dinâmico ou pesquisável), revisão Defina as configurações de campo para o as limitações e os requisitos de cada tipo de anotação.
Se você estiver editando um esquema detectado automaticamente, verifique se a transferência de dados foi concluída. Caso contrário, o esquema pode não estar disponível para edição ainda.
Encontre o ID do repositório de dados. Se você já tem seu repositório de dados ID, pule para a próxima etapa.
1. No console do Google Cloud, acesse a página Criador de agentes e, no menu de navegação, clique em Repositórios de dados.
  
  Acessar a página "Repositórios de dados"
2. Clique no nome do seu repositório de dados.
3. Na página Dados do seu repositório de dados, encontre o ID do repositório.

Use o método da API schemas.patch para fornecer o novo esquema JSON como um 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
}'

Substitua:

PROJECT_ID: o ID do seu projeto do Google Cloud.
DATA_STORE_ID: o ID do repositório de dados da Vertex AI para Pesquisa.

JSON_SCHEMA_OBJECT: seu novo esquema JSON como um objeto JSON. Exemplo:

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

Exemplo de comando e resultado

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

Opcional: revise o esquema seguindo o procedimento Conferir uma definição de esquema.

C#

Para mais informações, consulte a documentação de referência da API C# do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a documentação de referência da API Go do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a documentação de referência da API Java do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a API Vertex AI Agent Builder Python documentação de referência.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 mais informações, consulte a API Vertex AI Agent Builder Ruby documentação de referência.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Requisitos e limitações

Ao atualizar um esquema, verifique se o novo esquema é compatível com o esquema que você está atualizando. Para atualizar um esquema com um novo esquema que não seja compatível com versões anteriores, exclua todos os documentos no armazenamento de dados, exclua o esquema e crie um novo.

Atualizar um esquema aciona a reindexação de todos os documentos. Isso pode levar algum tempo ter custos adicionais:

Tempo. A reindexação de um grande repositório de dados pode levar horas ou dias.
Despesa. A reindexação pode gerar custos, dependendo do analisador. Por exemplo, a reindexação de repositórios de dados que usam o analisador OCR ou o analisador de layout gera custos. Para mais informações, consulte Preços do recurso Document AI.

As atualizações de esquema não são compatíveis com o seguinte:

Alterar um tipo de campo. Uma atualização de esquema não é compatível com a mudança do tipo do campo. Por exemplo, um campo mapeado para número inteiro não pode ser alterado para fio.
Remoção de um campo. Depois de definido, não é possível remover um campo. Você pode continuar adicionando novos campos, mas não remover um existente.

Exemplos de limitação (somente REST)

Nesta seção, mostramos exemplos de tipos válidos e inválidos de atualizações de esquema. Esses usam o seguinte esquema JSON de exemplo:

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

Exemplos de atualizações com suporte

As atualizações a seguir do esquema de exemplo são compatíveis.

Adicionar um campo. Neste exemplo, o campo properties.uri foi adicionados ao 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"
      }
    }
  }
}

Adicionar ou remover anotações de propriedade principal para title, description ou uri. Neste exemplo, keyPropertyMapping foi adicionado 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"
      }
    }
  }
}

Exemplos de atualizações de esquema inválidas

As atualizações a seguir no esquema de exemplo não são compatíveis.

Como mudar o tipo de um campo. Neste exemplo, o tipo do campo title foi alterado de string para número. Isso não é possível.

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

Remoção de um campo. Neste exemplo, o campo title foi removido. Isso não é possível.

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

Atualizar um esquema

Atualizar o esquema

Console

REST

Exemplo de comando e resultado

C#

Go

Java

Python

Ruby

Requisitos e limitações

Exemplos de limitação (somente REST)

Exemplos de atualizações com suporte

Exemplos de atualizações de esquema inválidas

A seguir