Configure o preenchimento automático

Esta página descreve a funcionalidade de preenchimento automático básico do Vertex AI Search. O preenchimento automático gera sugestões de consultas com base nos primeiros carateres introduzidos para a consulta.

Notas:

Para informações sobre a pesquisa instantânea para apps de pesquisa de multimédia, consulte o artigo Obtenha resultados da pesquisa instantânea para uma app de multimédia.

Para usar o preenchimento automático com apps de pesquisa que estão ligadas a várias lojas de dados (pesquisa combinada) ou têm documentos com controlo de acesso, ou para melhorar idiomas específicos no preenchimento automático, consulte o artigo Configure o preenchimento automático avançado.

As sugestões geradas pelo preenchimento automático variam consoante o tipo de dados que a app de pesquisa usa:

• Dados estruturados e não estruturados. Por predefinição, o preenchimento automático gera sugestões com base no conteúdo dos documentos no repositório de dados. Após a importação de documentos, por predefinição, o preenchimento automático não começa a gerar sugestões até existirem dados de qualidade suficientes, normalmente, ao fim de alguns dias. Se fizer pedidos de preenchimento automático através da API, o preenchimento automático pode gerar sugestões baseadas no histórico de pesquisa ou nos eventos do utilizador.

• Dados do Website. Por predefinição, o preenchimento automático gera sugestões a partir do histórico de pesquisas. O preenchimento automático requer tráfego de pesquisa real. Depois de o tráfego de pesquisa começar, o preenchimento automático demora um ou dois dias a gerar sugestões. As sugestões podem ser geradas a partir de dados extraídos da Web de sites públicos com o modelo de dados de documentos avançado experimental.

• Dados de cuidados de saúde. Por predefinição, é usada uma origem de dados médicos canónica para gerar sugestões de preenchimento automático para arquivos de dados de cuidados de saúde.

O modelo de sugestões de consultas determina que tipo de dados o preenchimento automático usa para gerar sugestões. Existem quatro modelos de sugestões de consultas:

• Document. O modelo de documentos gera sugestões a partir de documentos importados pelo utilizador. Este modelo não está disponível para dados de Websites nem dados de cuidados de saúde.

• Campos preenchíveis. O modelo de campos preenchíveis sugere texto retirado diretamente dos campos de dados estruturados. Apenas os campos anotados com completable são usados para sugestões de preenchimento automático. Este modelo só está disponível para dados estruturados.

• Histórico de pesquisas. O modelo do histórico de pesquisas gera sugestões a partir do histórico de chamadas da API SearchService.search. Não use este modelo se não houver tráfego disponível para o método servingConfigs.search. Este modelo não está disponível para dados de cuidados de saúde.

• Evento do utilizador. O modelo de eventos do utilizador gera sugestões a partir de eventos importados pelo utilizador do tipo search. Este modelo não está disponível para dados de cuidados de saúde.

Os pedidos de preenchimento automático são enviados através do método dataStores.completeQuery.

Em alternativa, se não quiser usar um modelo de sugestões de consultas, pode usar sugestões importadas que fornecem sugestões de preenchimento automático com base numa lista de sugestões importada. Para mais informações, consulte o artigo Use uma lista importada de sugestões de preenchimento automático.

Tipos de modelos disponíveis de acordo com o tipo de dados

A tabela seguinte mostra os tipos de modelos de sugestões de consultas disponíveis para cada tipo de dados.

Modelo de sugestões de consultas	Origem de dados	Dados do Website	Dados estruturados	Dados não estruturados
Documento	Importado		✔* (predefinição)	✔ (predefinição)
Campos preenchíveis	Importado		✔
Histórico de pesquisas	Recolhidos automaticamente	✔ (predefinição)	✔	✔
User events	Importadas ou recolhidas automaticamente pelo widget	✔	✔	✔
Conteúdo rastreado na Web	Extraído de conteúdo de Websites públicos que especificar	✔^†

* : O esquema do documento tem de conter campos title ou description, ou têm de existir campos que tenham sido especificados como propriedades de chave title ou description. Consulte o artigo Atualize um esquema para dados estruturados.

^† : o conteúdo rastreado na Web só pode ser usado como origem de dados se o modelo de dados de documentos avançado experimental para o preenchimento automático estiver ativado. Consulte o artigo Modelo de dados de documentos avançado.

Se não quiser usar o modelo predefinido para o seu tipo de dados, pode especificar um modelo diferente quando enviar o seu pedido de preenchimento automático. Os pedidos de preenchimento automático são enviados através do método dataStores.completeQuery. Para mais informações, consulte as instruções da API: envie um pedido de preenchimento automático para escolher um modelo diferente.

Funcionalidades de preenchimento automático

O Vertex AI Search suporta as seguintes funcionalidades de preenchimento automático para mostrar as previsões mais úteis durante a pesquisa:

Funcionalidade	Descrição	Exemplo ou mais informações
Corrija erros ortográficos	Corrija a ortografia de palavras que são erros ortográficos.	Milc → Milk.
Remova termos inseguros	Com tecnologia da Pesquisa segura do Google. Remova consultas inadequadas. Suportado em alemão (de), espanhol (es), francês (fr), inglês (en), italiano (it), polaco (pl), português (pt), russo (ru) e ucraniano (uk).	Texto ofensivo, como pornografia, conteúdo sugestivo, vulgar ou violento.
Impeça a apresentação de informações de identificação pessoal (PII) básicas	Com tecnologia da Proteção de dados confidenciais, a Pesquisa da Vertex AI faz um esforço razoável para impedir a apresentação de tipos básicos de PII, como números de telefone e endereços de email.	Se existir um endereço de email [e-mail] no repositório de dados, a Pesquisa do Vertex AI não devolve o endereço de email como uma sugestão de preenchimento automático se o utilizador escrever jef na barra de pesquisa. Para se salvaguardar mais exaustivamente contra fugas de PII, a Google recomenda que aplique a sua própria solução de prevenção contra a perda de dados (DLP), além dos detetores fornecidos pela Vertex AI Search. Para mais informações, consulte o artigo Proteja-se contra fugas de PII.
Lista de negações	Remova os termos que estão na lista de recusa.	Para mais informações, consulte o artigo Use uma lista de recusa do preenchimento automático.
Remova termos duplicados	Com tecnologia de compreensão semântica baseada em IA. Para termos quase idênticos, qualquer um dos termos corresponde, mas apenas o mais popular é sugerido.	Shoes for Women, Womens Shoes e Womans Shoes são desduplicados e apenas é sugerido o mais popular.
Sugestões de correspondência detalhada	Não está disponível em várias regiões dos EUA e da UE. Definição opcional. Se não existirem correspondências de preenchimento automático para a consulta completa, sugira correspondências apenas para a última palavra da consulta. Não está disponível para a pesquisa de cuidados de saúde.	Para mais informações, consulte o artigo Sugestões de correspondência exata.

Sugestões de correspondência detalhada

As sugestões de correspondência final são feitas através da correspondência exata do prefixo com a última palavra numa string de consulta.

Por exemplo, suponhamos que a consulta "músicas com ele" é enviada num pedido de preenchimento automático. Quando a correspondência final está ativada, o preenchimento automático pode descobrir que o prefixo completo "songs with he" não tem correspondências. No entanto, a última palavra na consulta, "ele", tem uma correspondência exata de prefixo com "olá mundo" e "olá kitty". Nesse caso, as sugestões devolvidas são "músicas com hello world" e "músicas com hello kitty" porque não existem sugestões de correspondência exata.

Pode usar esta funcionalidade para reduzir os resultados de sugestões vazios e aumentar a diversidade das sugestões, o que é especialmente útil nos casos em que as origens de dados (contagem de eventos do utilizador, histórico de pesquisas e cobertura de tópicos de documentos) são limitadas. No entanto, a ativação das sugestões de correspondência final pode reduzir a qualidade geral das sugestões. Uma vez que a correspondência final só corresponde à palavra final do prefixo, algumas sugestões devolvidas podem não fazer sentido. Por exemplo, uma consulta como "músicas com ele" pode receber uma sugestão de correspondência final como "músicas com ajudantes guias".

As sugestões de correspondência final só são devolvidas se:

1. include_tail_suggestions está definido como true no pedido dataStores.completeQuery.

2. Não existem sugestões de correspondência de prefixo completo para a consulta.

Proteja-se contra fugas de PII

A definição de PII é ampla e a PII pode ser difícil de detetar. Como resultado, a Pesquisa da Vertex AI não pode garantir que as PII não são devolvidas em sugestões de preenchimento automático.

A Pesquisa da Vertex AI aplica o serviço de inspeção da proteção de dados confidenciais para procurar e bloquear tipos comuns de IIPs que apareçam como sugestões. No entanto, se os seus armazenamentos de dados contiverem PII ou se usar os modelos de sugestões de consultas do histórico de pesquisa ou de eventos do utilizador, reveja o seguinte e tome as medidas adequadas:

1. Se os tipos de PII que quer proteger forem bastante normais, como números de telefone e endereços de email, comece por testar extensivamente as sugestões de preenchimento automático para a sua app. A Pesquisa do Vertex AI não pode garantir que a PII não é devolvida nas sugestões de preenchimento automático.

2. Se forem detetadas fugas de IIP durante os testes de preenchimento automático ou se já souber que tem IIP não padrão para proteger (por exemplo, IDs de utilizadores proprietários), experimente ajustar o limite de preenchimento automático e os parâmetros de publicação de conteúdo. Para mais informações, consulte o artigo Reduza o risco de devolver sugestões que contenham PII.

3. Se ajustar os parâmetros não for suficiente para evitar fugas de PII, implemente a sua própria solução de DLP. Personalize a solução de DLP para os tipos de PII com maior probabilidade de serem encontrados nos seus repositórios de dados, eventos do utilizador ou consultas de pesquisa dos utilizadores. Pode usar a proteção de dados sensíveis ou um serviço de DLP de terceiros. Adote uma das seguintes abordagens:

   • Filtre as IIP antes de importar os documentos e os eventos do utilizador nos seus repositórios de dados.

   • Reveja as sugestões de preenchimento automático antes de as apresentar ao utilizador no momento da publicação e bloqueie as sugestões que contenham PII.

4. Se usar o modelo de histórico de pesquisas ou de eventos do utilizador, adicione algum texto informativo na barra de pesquisa a indicar aos utilizadores que não devem introduzir PII nas respetivas consultas de pesquisa.

5. Se tiver dúvidas ou encontrar desafios específicos com o bloqueio de PII, contacte o seu engenheiro de apoio ao cliente ou a equipa da Conta Google.

Ative ou desative o preenchimento automático para um widget

Para ativar ou desativar o preenchimento automático de um widget, siga estes passos:

Consola

1. Na Google Cloud consola, aceda à página Aplicações de IA.

   Aplicações de IA

2. Clique no nome da app que quer editar.

3. Clique em Configurações.

4. Clique no separador IU.

5. Ative/desative a opção Mostrar sugestões de preenchimento automático para ativar/desativar as sugestões de preenchimento automático do widget. Quando ativa o preenchimento automático, as sugestões podem demorar um ou dois dias a aparecer.

Atualize as definições de preenchimento automático

Para configurar as definições de preenchimento automático na IU, siga estes passos:

Consola

1. Na Google Cloud consola, aceda à página Aplicações de IA.

   Aplicações de IA

2. Clique no nome da app que quer editar.

3. Clique em Configurações.

4. Clique no separador Preenchimento automático.

5. Introduza ou selecione novos valores para as definições de preenchimento automático que quer atualizar:

   • Número máximo de sugestões: o número máximo de sugestões de preenchimento automático que podem ser oferecidas para uma consulta.
   • Comprimento mínimo para acionar: o número mínimo de carateres que podem ser introduzidos antes de serem oferecidas sugestões de preenchimento automático.
   • Ordem de correspondência: a localização numa string de consulta a partir da qual o preenchimento automático pode começar a fazer corresponder as respetivas sugestões.
   • Modelo de sugestões de consultas: o modelo de sugestões de consultas usado para gerar as sugestões obtidas. Esta definição pode ser substituída no dataStores.completeQuery através do parâmetro queryModel.

   • Ativar preenchimento automático: por predefinição, o preenchimento automático não começa a fazer sugestões até ter dados de qualidade suficientes, normalmente, ao fim de alguns dias. Se quiser substituir esta predefinição e começar a receber algumas sugestões de preenchimento automático mais cedo, selecione Agora.

     Mesmo quando seleciona Agora, pode demorar um dia até que as sugestões sejam geradas. Além disso, algumas sugestões de preenchimento automático vão estar em falta ou ter má qualidade até existirem dados bons suficientes.

   • Lista de recusa: importe uma lista de recusa como um ficheiro JSON num contentor do Cloud Storage. Para mais informações sobre as restrições e as especificações da lista de exclusão, consulte o artigo Use uma lista de exclusão do preenchimento automático.

6. Clique em Guardar e publicar. As alterações entram em vigor dentro de alguns minutos para os motores em que o preenchimento automático já foi ativado.

Reduza o risco de devolver sugestões que contenham PII

Pré-visualização

Esta funcionalidade está sujeita aos "Termos de ofertas de pré-disponibilidade geral" na secção de Termos de Utilização Gerais dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Os utilizadores finais têm todos os tipos de informações de PII, como cartas de condução e números de telefone, que devem manter privadas. No entanto, os utilizadores que procuram resultados específicos para si podem introduzir informações de PII na barra de pesquisa.

Se usar o modelo de histórico de pesquisas ou eventos do utilizador e existir uma probabilidade de os seus utilizadores escreverem PII na barra de pesquisa, pode reduzir as fugas de PII ajustando os seguintes parâmetros:

• queryFrequencyThreshold: antes de uma consulta poder ser devolvida como sugestão de preenchimento automático, tem de ter sido introduzida este número de vezes.

• numUniqueUsersThreshold: Antes de uma consulta poder ser devolvida como uma sugestão de preenchimento automático, tem de ter sido introduzida por este número de utilizadores únicos. O valor do campo userPseudoId no evento de utilizador de pesquisa determina se o utilizador é único.

Exemplo de utilização

Por exemplo, considere um caso em que os utilizadores têm números de conta que devem ser mantidos privados.

Se o modelo de sugestões do histórico de pesquisas ou de eventos do utilizador estiver em utilização, estes números de conta, juntamente com todos os outros termos que os utilizadores finais pesquisam, são usados para gerar sugestões. Assim, se o número de conta do utilizador A YZ-46789A tiver sido introduzido repetidamente na barra de pesquisa e o utilizador B tiver um número de conta YZ-42345B, quando o utilizador B escrever YZ-4 na barra de pesquisa, a sugestão de preenchimento automático devolvida pode ser o número de conta do utilizador A.

Para reduzir a probabilidade de este tipo de fuga de informação acontecer, o administrador das aplicações de IA decide:

• Aumente o valor do parâmetro queryFrequencyThreshold para 30. Neste caso, é muito improvável que um número de conta seja introduzido com tanta frequência. No entanto, as consultas de pesquisa populares são introduzidas, pelo menos, com essa frequência.

• Aumente o valor do parâmetro numUniqueUsersThreshold para 6. O administrador considera improvável que o mesmo número de conta seja introduzido na barra de pesquisa em seis eventos de pesquisa, cada um associado a um userPseudoId diferente.

Procedimento

Existem dois parâmetros de limite para o preenchimento automático. Estes parâmetros não estão disponíveis na consola Google Cloud , mas podem ser definidos com uma chamada da API REST para o método updateCompletionConfig.

Nota: estes parâmetros aplicam-se apenas aos modelos de histórico de pesquisas e eventos do utilizador.

Para configurar as definições do limite de preenchimento automático, siga estes passos. Cada passo é opcional, consoante o parâmetro que quer alterar.

REST

1. Atualize o campo CompletionConfig.queryFrequencyThreshold:

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: PROJECT_ID" \
     https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/completionConfig?updateMask=queryFrequencyThreshold \
     -d '{
       "name": "projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/completionConfig",
       "queryFrequencyThreshold": QUERY_FREQUENCY_THRESHOLD
     }'
   

   Substitua o seguinte:

   • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .

   • DATA_STORE_ID: o ID do repositório de dados associado à sua app.

   • QUERY_FREQUENCY_THRESHOLD: um valor inteiro que indica o número mínimo de vezes que uma consulta de pesquisa tem de ser introduzida antes de poder ser devolvida como uma sugestão de preenchimento automático. A contagem é somada num período contínuo de vários meses. A predefinição é 8.

   Exemplo de comando e resultado

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \$ curl -X PATCH \
     -H "X-Goog-User-Project: my-project-123" \t-access-token)" \
     https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig?updateMask=queryFrequencyThreshold \
     -d '{
     "name": "projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig",
     "queryFrequencyThreshold": 30
     }'
     
   
   {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig",
     "matchingOrder": "exact-prefix",
     "maxSuggestions": 20,
     "minPrefixLength": 1,
     "queryModel": "automatic",
     "enableMode": "AUTOMATIC",
     "queryFrequencyThreshold": 30
   }
   

2. Atualize o campo CompletionConfig.numUniqueUsersThreshold:

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: PROJECT_ID" \
     https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/completionConfig?updateMask=numUniqueUsersThreshold \
     -d '{
       "name": "projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/completionConfig",
       "numUniqueUsersThreshold": UNIQUE_USERS
     }'
   

   Substitua UNIQUE_USERS por um valor inteiro que represente o número mínimo de utilizadores únicos que têm de introduzir uma determinada consulta de pesquisa antes de poder ser devolvida como uma sugestão de preenchimento automático. A contagem é somada durante um período contínuo de vários meses. A predefinição é 3.

   Exemplo de comando e resultado

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "X-Goog-User-Project: my-project-123" \
     https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig?updateMask=numUniqueUsersThreshold \
     -d '{
     "name": "projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig",
       "numUniqueUsersThreshold": 6
     }'
     
   
   {
   "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/completionConfig",
     "matchingOrder": "exact-prefix",
     "maxSuggestions": 20,
     "minPrefixLength": 1,
     "queryModel": "automatic",
     "enableMode": "AUTOMATIC",
     "numUniqueUsersThreshold": 6,
     "queryFrequencyThreshold": 30
   }
   

Atualize as anotações de campos preenchíveis no esquema

Para ativar o preenchimento automático de campos no esquema de dados estruturados, siga estes passos:

Consola

1. Na Google Cloud consola, aceda à página Aplicações de IA.

   Aplicações de IA

2. Clique no nome da app que quer editar. Tem de usar dados estruturados.

3. Clique em Dados.

4. Clique no separador Esquema.

5. Clique em Editar para selecionar os campos de esquema a marcar como completable.

6. Clique em Guardar para guardar as configurações de campos atualizadas. Estas sugestões demoram cerca de um dia a serem geradas e devolvidas.

Envie pedidos de preenchimento automático

Os exemplos seguintes mostram como enviar pedidos de preenchimento automático.

REST

Para enviar um pedido de preenchimento automático através da API, siga estes passos:

1. Encontre o ID da loja de dados. Se já tiver o ID do armazenamento de dados, avance para o passo seguinte.

   1. Na Google Cloud consola, aceda à página Aplicações de IA e, no menu de navegação, clique em Armazenamentos de dados.

      Aceda à página Armazenamentos de dados

   2. Clique no nome do seu arquivo de dados.

   3. Na página Dados da sua loja de dados, obtenha o ID da loja de dados.

2. Chame o método dataStores.completeQuery.

   curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID:completeQuery?query=QUERY_STRING"
   

   Substitua o seguinte:

   • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .

   • DATA_STORE_ID: o ID do repositório de dados associado à sua app.

   • QUERY_STRING: a entrada de preenchimento automático usada para obter sugestões.

Envie um pedido de preenchimento automático para um modelo diferente

Para enviar um pedido de preenchimento automático com um modelo de sugestões de consultas diferente, siga estes passos:

1. Encontre o ID da loja de dados. Se já tiver o ID do armazenamento de dados, avance para o passo seguinte.

   1. Na Google Cloud consola, aceda à página Aplicações de IA e, no menu de navegação, clique em Armazenamentos de dados.

      Aceda à página Armazenamentos de dados

   2. Clique no nome do seu arquivo de dados.

   3. Na página Dados da sua loja de dados, obtenha o ID da loja de dados.

2. Chame o método dataStores.completeQuery.

   curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID:completeQuery?query=QUERY_STRING&query_model=QUERY_SUGGESTIONS_MODEL"
   

   Substitua o seguinte:

   • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .

   • DATA_STORE_ID: o ID exclusivo do arquivo de dados associado à sua app.

   • QUERY_STRING: a entrada de preenchimento automático usada para obter sugestões.

   • AUTOCOMPLETE_MODEL: os dados de preenchimento automático

   • QUERY_SUGGESTIONS_MODEL: o modelo de sugestões de consultas a usar para o pedido: document, document-completable, search-history ou user-event. Para dados de cuidados de saúde, use healthcare-default.

C#

Para mais informações, consulte a documentação de referência da API C# de aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

using Google.Cloud.DiscoveryEngine.V1;

public sealed partial class GeneratedCompletionServiceClientSnippets
{
    /// <summary>Snippet for CompleteQuery</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 CompleteQueryRequestObject()
    {
        // Create client
        CompletionServiceClient completionServiceClient = CompletionServiceClient.Create();
        // Initialize request argument(s)
        CompleteQueryRequest request = new CompleteQueryRequest
        {
            DataStoreAsDataStoreName = DataStoreName.FromProjectLocationDataStore("[PROJECT]", "[LOCATION]", "[DATA_STORE]"),
            Query = "",
            QueryModel = "",
            UserPseudoId = "",
            IncludeTailSuggestions = false,
        };
        // Make the request
        CompleteQueryResponse response = completionServiceClient.CompleteQuery(request);
    }
}

Go

Para mais informações, consulte a documentação de referência da API Go de aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.NewCompletionClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.CompleteQueryRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#CompleteQueryRequest.
	}
	resp, err := c.CompleteQuery(ctx, req)
	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 de aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.discoveryengine.v1.CompleteQueryRequest;
import com.google.cloud.discoveryengine.v1.CompleteQueryResponse;
import com.google.cloud.discoveryengine.v1.CompletionServiceClient;
import com.google.cloud.discoveryengine.v1.DataStoreName;

public class SyncCompleteQuery {

  public static void main(String[] args) throws Exception {
    syncCompleteQuery();
  }

  public static void syncCompleteQuery() 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 (CompletionServiceClient completionServiceClient = CompletionServiceClient.create()) {
      CompleteQueryRequest request =
          CompleteQueryRequest.newBuilder()
              .setDataStore(
                  DataStoreName.ofProjectLocationDataStoreName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]")
                      .toString())
              .setQuery("query107944136")
              .setQueryModel("queryModel-184930495")
              .setUserPseudoId("userPseudoId-1155274652")
              .setIncludeTailSuggestions(true)
              .build();
      CompleteQueryResponse response = completionServiceClient.completeQuery(request);
    }
  }
}

Node.js

Para mais informações, consulte a documentação de referência da API Node.js de aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. The parent data store resource name for which the completion is
 *  performed, such as
 *  `projects/* /locations/global/collections/default_collection/dataStores/default_data_store`.
 */
// const dataStore = 'abc123'
/**
 *  Required. The typeahead input used to fetch suggestions. Maximum length is
 *  128 characters.
 */
// const query = 'abc123'
/**
 *  Specifies the autocomplete data model. This overrides any model specified
 *  in the Configuration > Autocomplete section of the Cloud console. Currently
 *  supported values:
 *  * `document` - Using suggestions generated from user-imported documents.
 *  * `search-history` - Using suggestions generated from the past history of
 *  SearchService.Search google.cloud.discoveryengine.v1.SearchService.Search 
 *  API calls. Do not use it when there is no traffic for Search API.
 *  * `user-event` - Using suggestions generated from user-imported search
 *  events.
 *  * `document-completable` - Using suggestions taken directly from
 *  user-imported document fields marked as completable.
 *  Default values:
 *  * `document` is the default model for regular dataStores.
 *  * `search-history` is the default model for site search dataStores.
 */
// const queryModel = 'abc123'
/**
 *  A unique identifier for tracking visitors. For example, this could be
 *  implemented with an HTTP cookie, which should be able to uniquely identify
 *  a visitor on a single device. This unique identifier should not change if
 *  the visitor logs in or out of the website.
 *  This field should NOT have a fixed value such as `unknown_visitor`.
 *  This should be the same identifier as
 *  UserEvent.user_pseudo_id google.cloud.discoveryengine.v1.UserEvent.user_pseudo_id 
 *  and
 *  SearchRequest.user_pseudo_id google.cloud.discoveryengine.v1.SearchRequest.user_pseudo_id.
 *  The field must be a UTF-8 encoded string with a length limit of 128
 *  characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
 */
// const userPseudoId = 'abc123'
/**
 *  Indicates if tail suggestions should be returned if there are no
 *  suggestions that match the full query. Even if set to true, if there are
 *  suggestions that match the full query, those are returned and no
 *  tail suggestions are returned.
 */
// const includeTailSuggestions = true

// Imports the Discoveryengine library
const {CompletionServiceClient} = require('@google-cloud/discoveryengine').v1;

// Instantiates a client
const discoveryengineClient = new CompletionServiceClient();

async function callCompleteQuery() {
  // Construct request
  const request = {
    dataStore,
    query,
  };

  // Run request
  const response = await discoveryengineClient.completeQuery(request);
  console.log(response);
}

callCompleteQuery();

Python

Para mais informações, consulte a documentação de referência da API Python de aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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_complete_query():
    # Create a client
    client = discoveryengine_v1.CompletionServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.CompleteQueryRequest(
        data_store="data_store_value",
        query="query_value",
    )

    # Make the request
    response = client.complete_query(request=request)

    # Handle the response
    print(response)

Ruby

Para mais informações, consulte a documentação de referência da API Ruby de aplicações de IA.

Para se autenticar em aplicações de IA, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

require "google/cloud/discovery_engine/v1"

##
# Snippet for the complete_query call in the CompletionService 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::CompletionService::Client#complete_query.
#
def complete_query
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::CompletionService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::CompleteQueryRequest.new

  # Call the complete_query method.
  result = client.complete_query request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1::CompleteQueryResponse.
  p result
end

Use uma lista de exclusão do preenchimento automático

Pode usar uma lista de recusa para impedir que termos específicos sejam apresentados como sugestões de preenchimento automático.

Por exemplo, considere uma empresa farmacêutica. Se um medicamento já não estiver aprovado pela FDA, mas for mencionado em documentos na respetiva base de dados, o anunciante pode querer impedir que esse medicamento seja apresentado como uma consulta sugerida. A empresa pode adicionar o nome desse medicamento a uma lista de exclusões para impedir que seja sugerido.

Aplicam-se os seguintes limites:

• Uma lista de negações por armazenamento de dados
• O carregamento de uma lista de negações substitui qualquer lista de negações existente para essa base de dados
• Até 1000 termos por lista de negações
• Os termos não são sensíveis a maiúsculas e minúsculas
• Após a importação de uma lista de recusa, esta demora 1 a 2 dias a entrar em vigor

Cada entrada da sua lista de exclusões consiste num blockPhrase e num matchOperator:

• blockPhrase: introduza uma string como termo da lista de exclusões. Os termos não são sensíveis a maiúsculas e minúsculas.
• matchOperator: aceita os seguintes valores:
  • EXACT_MATCH: impede que uma correspondência exata do termo da lista de recusa apareça como uma consulta sugerida.
  • CONTAINS: impede a apresentação de qualquer sugestão que contenha o termo da lista de exclusão.

Segue-se um exemplo de uma lista de exclusão com quatro entradas:

{
    "entries": [
        {"blockPhrase":"Oranges","matchOperator":"CONTAINS"},
        {"blockPhrase":"bAd apples","matchOperator":"EXACT_MATCH"},
        {"blockPhrase":"Cool as A Cucumber","matchOperator":"EXACT_MATCH"},
        {"blockPhrase":"cherry pick","matchOperator":"CONTAINS"}
    ]
}

Antes de importar uma lista de recusa, verifique se os controlos de acesso necessários estão definidos para o acesso de editor do motor de descoberta.

As listas de recusa podem ser importadas de dados JSON locais ou do Cloud Storage. Para remover uma lista de recusa de uma base de dados, limpe a lista de recusa.

Importe uma lista de exclusões de dados JSON locais

Para importar uma lista de exclusões de um ficheiro JSON local que contenha a sua lista de exclusões, faça o seguinte:

1. Crie a sua lista de exclusões num ficheiro JSON local com o seguinte formato. Certifique-se de que cada entrada da lista de exclusões está numa nova linha sem quebras de linha.

   {
       "inlineSource": {
           "entries": [
               { "blockPhrase":"TERM_1","matchOperator":"MATCH_OPERATOR_1" },
               { "blockPhrase":"TERM_2","matchOperator":"MATCH_OPERATOR_2" }
           ]
       }
   }

2. Faça um pedido POST ao método suggestionDenyListEntries:import, indicando o nome do seu ficheiro JSON.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data @DENYLIST_FILE \
     "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/suggestionDenyListEntries:import"
   

   Substitua o seguinte:

   • DENYLIST_FILE: o caminho local do ficheiro JSON que contém os termos da lista de exclusão.

   • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .

   • DATA_STORE_ID: o ID do armazenamento de dados associado à sua app.

Após importar a lista de recusas, a filtragem de sugestões demora 1 a 2 dias a começar.

Importe uma lista de exclusão do Cloud Storage

Para importar uma lista de exclusões de um ficheiro JSON no Cloud Storage, faça o seguinte:

1. Crie a sua lista de exclusões num ficheiro JSON com o seguinte formato e importe-o para um contentor do Cloud Storage. Certifique-se de que cada entrada da lista de recusa está numa nova linha sem quebras de linha.

   { "blockPhrase":"TERM_1","matchOperator":"MATCH_OPERATOR_1" }
   { "blockPhrase":"TERM_2","matchOperator":"MATCH_OPERATOR_2" }

2. Crie um ficheiro JSON local que contenha o objeto gcsSource. Use esta opção para indicar a localização do ficheiro de lista de exclusões num contentor do Cloud Storage.

   {
       "gcsSource": {
           "inputUris": [ "DENYLIST_STORAGE_LOCATION" ]
       }
   }

   Substitua DENYLIST_STORAGE_LOCATION pela localização da sua lista de exclusões no Cloud Storage. Só pode introduzir um URI. O URI tem de ser introduzido neste formato: gs://BUCKET/FILE_PATH.

3. Faça um pedido POST para o método suggestionDenyListEntries:import, incluindo o objeto gcsSource.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data @GCS_SOURCE_FILE \
      "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/suggestionDenyListEntries:import"
   

   Substitua o seguinte:

   • GCS_SOURCE_FILE: o caminho local do ficheiro que contém o objeto gcsSource que aponta para a sua lista de exclusões.

   • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .

   • DATA_STORE_ID: o ID do armazenamento de dados associado à sua app.

Após importar a lista de recusas, a filtragem de sugestões demora 1 a 2 dias a começar.

Remova completamente uma lista de negações

Para limpar uma lista de exclusões da sua base de dados, faça o seguinte:

1. Faça um pedido POST ao método suggestionDenyListEntries:purge.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/suggestionDenyListEntries:purge"
   

   Substitua o seguinte:

   • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .

   • DATA_STORE_ID: o ID do armazenamento de dados associado à sua app.

Use uma lista importada de sugestões de preenchimento automático

Pode optar por fornecer a sua própria lista de sugestões de preenchimento automático em vez de usar sugestões de preenchimento automático geradas a partir de um modelo de dados de preenchimento automático.

Atenção: para sugestões importadas, o texto é apresentado exatamente como na lista. Não é aplicada nenhuma verificação ortográfica, filtros da SafeSearch nem remoção de duplicados.

Para a maioria das aplicações, a utilização de sugestões geradas a partir de um dos modelos de dados de preenchimento automático produz melhores resultados. No entanto, podem existir algumas situações raras em que as sugestões do modelo não correspondem às suas necessidades e o fornecimento de uma lista discreta de sugestões oferece aos utilizadores uma melhor experiência de preenchimento automático.

Por exemplo, uma pequena livraria online importa a respetiva lista de títulos de livros como sugestões de preenchimento automático. Quando um cliente começa a escrever na barra de pesquisa, a sugestão de preenchimento automático é sempre o título de um livro da lista importada. Quando a lista de livros muda, a livraria limpa a lista atual e importa a nova lista. Um excerto da lista pode ter o seguinte aspeto:

{"suggestion": "Wuthering Heights", "globalScore": "0.52" },
{"suggestion": "The Time Machine", "globalScore": "0.26" },
{"suggestion": "Nicholas Nickleby", "globalScore": "0.38" },
{"suggestion": "A Little Princess", "globalScore": "0.71" },
{"suggestion": "The Scarlet Letter", "globalScore": "0.32" }

O globalScore é um número de vírgula flutuante no intervalo [0, 1] usado para classificar a sugestão. Em alternativa, pode usar uma pontuação frequency, que é um número inteiro superior a um. A pontuação frequency é usada para classificar as sugestões quando o globalScore não está disponível (definido como nulo).

Nota: embora nos dados possa fornecer apenas uma classificação (globalScore ou frequency), nos passos seguintes para criar uma tabela do BigQuery, globalScore e frequency são obrigatórios no esquema. Um esquema incorreto vai provocar a falha da importação de sugestões.

Configure e importe sugestões de preenchimento automático

Para configurar e importar uma lista de sugestões de preenchimento automático a partir do BigQuery, siga estes passos:

1. Crie a sua lista de sugestões e carregue-a numa tabela do BigQuery.

   No mínimo, tem de fornecer cada sugestão como uma string e uma pontuação global ou uma frequência.

   Use o seguinte esquema de tabela para a sua lista de sugestões:

   [
     {
       "description": "The suggestion text",
       "mode": "REQUIRED",
       "name": "suggestion",
       "type": "STRING"
     },
     {
       "description": "Global score of this suggestion. Control how this suggestion would be scored and ranked. Set global score or frequency; not both.",
       "mode": "NULLABLE",
       "name": "globalScore",
       "type": "FLOAT"
     },
     {
       "description": "Frequency of this suggestion. Used to rank suggestions when the global score is not available.",
       "mode": "NULLABLE",
       "name": "frequency",
       "type": "INTEGER"
     }
   ]
   

   Consulte a documentação do BigQuery para obter instruções sobre como criar uma tabela do BigQuery e carregar a tabela com a sua lista de sugestões de preenchimento automático.

2. Importe a lista do BigQuery.

   Faça um pedido POST para o método completionSuggestions:import, incluindo o objeto bigquerySource.

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/completionSuggestions:import" \
    -d '{
         "bigquery_source": {"project_id": "PROJECT_ID_SOURCE", "dataset_id": "DATASET_ID", "table_id": "TABLE_ID"}
    }'
   

   Substitua o seguinte:

   • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .
   • DATA_STORE_ID: o ID do arquivo de dados do Vertex AI Search.
   • PROJECT_ID_SOURCE: o projeto que contém o conjunto de dados que quer importar.
   • DATASET_ID: o ID do conjunto de dados da lista de sugestões que quer importar
   • TABLE_ID: o ID da tabela da lista de sugestões que quer importar

   Exemplo de comando e resultado

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/dataStores/my-data-store/completionSuggestions:import" \
    -d '{
   "bigquery_source": {"project_id": "my-project-123", "dataset_id": "autocomplete", "table_id": "import_suggestion2"}
   }'
       
   
   {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/operations/import-completion-suggestion-7659310803143180509",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.ImportCompletionSuggestionsMetadata"
     }
   }
   

3. Opcional: tome nota do valor name devolvido e siga as instruções em Obtenha detalhes sobre uma operação de longa duração para ver quando a operação de importação está concluída.

4. Se não ativou o preenchimento automático para a app, siga o procedimento Atualize as definições de preenchimento automático. Certifique-se de que define a opção Permitir preenchimento automático como Agora.

5. Aguarde alguns dias para que a indexação seja concluída e as sugestões importadas fiquem disponíveis.

Envie um pedido de preenchimento automático

Para enviar um pedido de preenchimento automático que devolve uma sugestão importada em vez de uma sugestão de um modelo de preenchimento automático:

1. Siga o procedimento para enviar um pedido de preenchimento automático a um modelo diferente e defina AUTOCOMPLETE_MODEL como imported-suggestion.

   Exemplo de comando e resultado

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "X-Goog-User-Project: my-project-123" \
       "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store:completeQuery?query=t&query_model=imported-suggestion"
       
   
   Response:
   {
     "querySuggestions": [
       {
         "suggestion": "The Time Machine"
       },
       {
         "suggestion": "The Scarlet Letter"
       }
     ]
   }
   

Limpe a lista de sugestões de preenchimento automático importadas

Antes de importar uma nova lista de sugestões de preenchimento automático, remova a existente.

Para limpar uma lista existente de sugestões de preenchimento automático, siga este passo:

1. Faça um pedido POST ao método completionSuggestions:purge.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/dataStores/DATA_STORE_ID/completionSuggestions:purge"
   

   Substitua o seguinte:

   • PROJECT_ID: o número ou o ID do seu projeto Google Cloud .

   • DATA_STORE_ID: o ID do armazenamento de dados associado à sua app.

   Exemplo de comando e resultado

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/dataStores/my-data-store/completionSuggestions:purge"
       
   
   {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/operations/purge-customer-imported_suggestions-3197526711414652502",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.PurgeCompletionSuggestionsMetadata",
       "createTime": "2024-06-27T17:07:09.551726728Z",
       "updateTime": "2024-06-27T17:07:09.551726728Z"
     },
     "done": true,
     "response": {
       "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.PurgeCompletionSuggestionsResponse",
       "purgeSucceeded": true
     }
   }
   

Modelo de dados de documentos avançado

Experimental

Esta funcionalidade está sujeita aos "Termos de ofertas de pré-disponibilidade geral" na secção de Termos de Utilização Gerais dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

As aplicações de IA oferecem um modelo de dados avançado para o preenchimento automático. Com base nos documentos que importa, este modelo de dados gera sugestões de preenchimento automático de alta qualidade através dos modelos de linguagem (conteúdo extenso) (MDLs/CEs) da Google.

Esta funcionalidade é experimental. Se tiver interesse em usar esta funcionalidade, contacte a sua Google Cloud equipa da conta e peça para ser adicionado à lista de autorizações.

O modelo de dados de documentos avançado não está disponível para a pesquisa de cuidados de saúde nem nas multirregiões dos EUA e da UE.