Importar dados de preenchimento automático para pesquisa

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O preenchimento automático é um recurso que prevê o restante de uma palavra que um usuário está digitando, o que pode melhorar a experiência de pesquisa do usuário. Ele pode fazer sugestões com base no conjunto de dados fornecido ou nos eventos de usuário.

Importe dados de preenchimento automático apenas se quiser ter controles adicionais (não remover lista, lista de bloqueio) ou se precisar usar seus próprios dados de preenchimento automático. Ativar o aprendizado automático é suficiente na maioria dos casos em que o preenchimento automático é necessário. Ele oferece um conjunto de dados de sugestões baseado em eventos de pesquisa do usuário. Consulte Preenchimento automático para saber como ativar o aprendizado automático.

Observação :desde setembro de 2022, é possível usar a interface do Console do Cloud > Controles > Controles UI automático para acionar a importação de dados.

Estas instruções servem apenas para fazer o upload dos seus próprios dados de preenchimento automático. Mantenha-o atualizado se você planeja usar seu conjunto de dados de preenchimento automático o tempo todo. Para receber os resultados do preenchimento automático no momento da consulta, consulte CompletionService.CompleteQuery. Os dados de preenchimento automático são usados somente para pesquisa. Esses dados não são usados por recomendações.

Antes de começar

Antes de importar as informações de preenchimento automático, conclua as instruções da seção Antes de começar, especificamente como configurar o projeto, criar uma conta de serviço e adicionar a conta de serviço ao ambiente local.

Você precisa ter o papel do IAM de editor de varejo para realizar a importação.

Práticas recomendadas para a importação do preenchimento automático

Ao importar dados de preenchimento automático, implemente estas práticas recomendadas:

• Leia o esquema do BigQuery listado nas seções e na documentação da API a seguir.

• Não use valores de marcador.

• Inclua o maior número possível de campos.

• Mantenha seu conjunto de dados de preenchimento automático atualizado se quiser usar o próprio conjunto de dados enviado.

• Não é permitido importar dados de outro projeto.

Importar dados de preenchimento automático

Importar dados de preenchimento automático do BigQuery

A Vertex AI para Pesquisa para varejo é compatível com a importação de dados do BigQuery para a lista de bloqueio, a lista "Não remover" e a lista de termos de sugestão. Confira mais detalhes no Autocomplete.

Para importar dados de preenchimento automático no formato correto do BigQuery, use o esquema de preenchimento automático da Vertex AI para Pesquisa para varejo a fim de criar uma tabela do BigQuery com o formato correto e carregar a tabela com seus dados de preenchimento automático. Em seguida, faça upload dos dados na Vertex AI para Pesquisa no varejo.

Para mais ajuda com as tabelas do BigQuery, consulte Introdução às tabelas. Para ajuda com as consultas do BigQuery, consulte Visão geral da consulta de dados do BigQuery.

Local do conjunto de dados do BigQuery

Ao criar o conjunto de dados do BigQuery pela primeira vez para as tabelas de preenchimento automático do BigQuery, verifique se o local do conjunto de dados está definido como o local multirregional "US". Não defini-lo corretamente fará com que sua solicitação de importação falhe mais tarde. Para saber mais sobre os locais dos conjuntos de dados do BigQuery, consulte Locais de conjuntos de dados na documentação do BigQuery.

Preencher dados no BigQuery

Use o esquema de preenchimento automático da Vertex AI para Pesquisa para varejo para fazer upload dos dados de preenchimento automático para o BigQuery.

O BigQuery pode usar o esquema para validar se os dados formatados em JSON têm nomes e tipos de campo corretos (como STRING, INTEGER e RECORD), mas não podem realizar validações como determinando:

• se um campo de string foi mapeado para um valor de enumeração reconhecível;
• se um campo de string está usando o formato correto;
• se um campo de número inteiro ou flutuante tem valor em um intervalo válido;
• se um campo ausente é obrigatório.

Para garantir a qualidade dos seus dados e da experiência de pesquisa do usuário final, consulte a documentação de esquema e referência para detalhes sobre valores e formato.

Configurar o acesso ao conjunto de dados do BigQuery

Para configurar o acesso, verifique se o conjunto de dados do BigQuery está no mesmo projeto que o serviço da Vertex AI para Pesquisa para varejo e conclua as etapas a seguir.

1. Abra a página "IAM" no console do Google Cloud.

   Abrir a página do IAM

2. Selecione seu projeto da Vertex AI para Pesquisa para varejo.

3. Na página IAM e administrador, clique em  Conceder acesso.

4. Em Novos principais, insira [e-mail] e selecione o papel BigQuery > Leitor de dados do BigQuery.

   Se você não quiser fornecer o papel de visualizador de dados a todo o projeto, adicione esse papel diretamente ao conjunto de dados. Saiba mais.

5. Clique em Salvar.

Acionar a importação de dados para a Vertex AI para Pesquisa no varejo

Console

1. Acessar a página "Controles"

2. Acesse a guia Controles de preenchimento automático.

3. Na seção Listas de termos, encontre o tipo de lista que você planeja importar (Lista de bloqueio, Não remover lista ou Lista de termos sugeridos) e clique em Importar ou Substituir.

   O painel Importar é aberto.

4. Insira o caminho do BigQuery do local dos dados ou selecione Procurar para selecionar o local.

   O caminho do BigQuery precisa estar no mesmo projeto, e o esquema dele precisa estar correto. Para verificar isso, clique em Procurar e no nome da tabela para ver o conteúdo dela no console do BigQuery.

5. No painel Import, clique em Import.

   A importação começa. É possível sair da página sem interromper a importação.

cURL

1. Crie um arquivo de dados para os parâmetros de entrada para a importação. Os valores do parâmetro de entrada dependem da importação do Cloud Storage ou do BigQuery.

   Use o objeto BigQuerySource para apontar para o conjunto de dados do BigQuery.

   • dataset-id: o ID do conjunto de dados do BigQuery.
   • table-id: o ID da tabela do BigQuery que contém os dados.
   • data-schema: para a propriedade dataSchema, use o valor suggestions (padrão), allowlist e denylist. Use o esquema de preenchimento automático da Vertex AI para Pesquisa para varejo.

   {
     "inputConfig":{
       "bigQuerySource": {
         "datasetId":"dataset-id",
         "tableId":"table-id",
         "dataSchema":"data-schema"
       }
     }
   }
   

2. Importe suas informações de preenchimento automático para a Vertex AI para Pesquisa para varejo fazendo uma solicitação POST para o método REST CompletionData:import, fornecendo o nome do arquivo de dados (mostrado como input.json no exemplo abaixo).

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Content-Type: application/json; charset=utf-8" -d @./input.json
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionData:import"
   

   É possível verificar o status de maneira programática usando a API. Você receberá um objeto de resposta com esta aparência:

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "done": false
   }
   

   O campo de nome é o ID do objeto de operação. Para solicitar o status desse objeto, substitua o campo de nome pelo valor retornado pelo método de importação. Quando a importação for concluída, o campo done será retornado como true:

   curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456"
   

   Quando a operação for concluída, o objeto retornado terá um valor done de true e incluirá um objeto Status semelhante ao exemplo a seguir:

   {
     "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
       "createTime": "2020-01-01T03:33:33.000001Z",
       "updateTime": "2020-01-01T03:34:33.000001Z",
       "successCount": "2",
       "failureCount": "1"
     },
     "done": true
     "response": {
       "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
     }
   }
   

Formato de dados de preenchimento automático

O arquivo JSON será semelhante aos exemplos a seguir. As quebras de linha são para facilitar a leitura. Você deve fornecer uma sugestão inteira em uma única linha. Cada sugestão precisa estar em uma linha.

Campos obrigatórios mínimos da sugestão:

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

Ou:

{
  "suggestion": "ABC",
  "frequency": "100"
}

Duração da importação de dados do preenchimento automático

Geralmente, leva de alguns minutos a uma hora para que uma importação do BigQuery seja concluída.

Quando a importação do conjunto de dados for concluída, o campo done no objeto da operação será marcado como verdadeiro. Depois disso, pode levar de um a dois dias para que os dados sejam indexados e usados na disponibilização de produção.

Manter seu conjunto de dados de preenchimento automático atualizado

Se você planeja usar o conjunto de dados do qual foi feito o upload, a prática recomendada é mantê-lo atualizado regularmente.

Atualização em lote

Você pode usar o método de importação para atualizar em lote o preenchimento automático. Faça isso da mesma maneira que a importação inicial. Siga as etapas em Como importar dados de preenchimento automático. Isso substituirá todo o conjunto de dados importado.

Monitorar a integridade da importação

É importante manter seu próprio conjunto de dados atualizado para conseguir resultados de sugestão de alta qualidade ao usá-lo. Monitore as taxas de erro de importação e tome as medidas necessárias.

Esquema de preenchimento automático da Vertex AI para Pesquisa para varejo

Ao importar o conjunto de dados de preenchimento automático do BigQuery, use o esquema da Vertex AI para Pesquisa para varejo abaixo a fim de criar tabelas do BigQuery com o formato correto e carregá-las com seus dados de preenchimento automático.

Esquema de sugestões

Esse conjunto de dados é usado para fornecer suas próprias frases de sugestão de preenchimento automático com suas próprias pontuações.

JSON do esquema de sugestões de preenchimento automático da Vertex AI para Pesquisa para varejo

JSON

[
  {
    "description": "The suggestion text",
    "mode": "NULLABLE",
    "name": "suggestion",
    "type": "STRING"
  },
  {
    "description": "Global score of this suggestion. Control how this suggestion would be scored / ranked. Only one of this and frequency should be set.",
    "mode": "NULLABLE",
    "name": "globalScore",
    "type": "FLOAT"
  },
  {
    "description": "Frequency of this suggestion. Will be used to rank suggestions when score is not available.",
    "mode": "NULLABLE",
    "name": "frequency",
    "type": "INTEGER"
  },
  {
    "description": "BCP-47 language code of this suggestion.",
    "mode": "NULLABLE",
    "name": "languageCode",
    "type": "STRING"
  },
  {
    "description": "If two suggestions have the same groupID, they will not be returned together. Instead the one ranked higher will be returned. This can be used to deduplicate semantically identical suggestions.",
    "mode": "NULLABLE",
    "name": "groupID",
    "type": "STRING"
  },
  {
    "description": "The score of this suggestion within its group",
    "mode": "NULLABLE",
    "name": "groupScore",
    "type": "FLOAT"
  },
  {
    "description": "Device type for this suggestion.",
    "mode": "NULLABLE",
    "name": "deviceType",
    "type": "STRING"
  },
  {
    "description": "Alternative matching phrases for this suggestion.",
    "mode": "REPEATED",
    "name": "alternativePhrases",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "description": "The name of the custom attribute.",
        "mode": "NULLABLE",
        "name": "key",
        "type": "STRING"
      },
      {
        "fields": [
          {
            "description": "The textual values of this custom attribute.",
            "mode": "REPEATED",
            "name": "text",
            "type": "STRING"
          },
          {
            "description": "The numerical values of this custom attribute.",
            "mode": "REPEATED",
            "name": "numbers",
            "type": "FLOAT"
          }
        ],
        "mode": "NULLABLE",
        "name": "value",
        "type": "RECORD"
      }
    ],
    "description": "A custom attribute that is not explicitly modeled, which can be retrieved together with the suggestion at serving time.",
    "mode": "REPEATED",
    "name": "customAttributes",
    "type": "RECORD"
  }
]

Esquema para a lista de bloqueio

Esse conjunto de dados é usado como uma lista de bloqueio para impedir que frases sejam sugeridas.

JSON do esquema da lista de bloqueio de preenchimento automático da Vertex AI para Pesquisa para varejo

JSON

[
  {
    "description": "The phrase to block from autocomplete suggestions.",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Choose whether to block the exact phrase, or block any suggestions containing this phrase. Supported value \"EXACT_MATCH\", \"CONTAINS\"",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]

Esquema para colocar na lista de permissões

Esse conjunto de dados é usado para pular processos de postagem, como correção ortográfica e filtragem de resultado zero, em todas as frases nessa lista de permissões.

JSON do esquema da lista de permissões de preenchimento automático da Vertex AI para Pesquisa para varejo

JSON

[
  {
    "description": "The phrase to be exempted from autocomplete post processing, e.g. spell correction, filtering",
    "mode": "REQUIRED",
    "name": "phrase",
    "type": "STRING"
  },
  {
    "description": "The operator to apply for this phrase. Whether to match the exact phrase, or any suggestions contain this phrase. Supported values are \"EXACT_MATCH\", \"CONTAINS\".",
    "mode": "REQUIRED",
    "name": "operator",
    "type": "STRING"
  }
]