Method: projects.locations.collections.dataStores.servingConfigs.search

Faz uma pesquisa.

Pedido HTTP

POST https://discoveryengine.googleapis.com/v1/{servingConfig=projects/*/locations/*/collections/*/dataStores/*/servingConfigs/*}:search

O URL usa a sintaxe de transcodificação de gRPC.

Parâmetros de caminho

Parâmetros
servingConfig

string

Obrigatório. O nome do recurso da configuração de publicação servingConfigs.search, como projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config ou projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config. Este campo é usado para identificar o nome da configuração de publicação, o conjunto de modelos usados para fazer a pesquisa.

Corpo do pedido

O corpo do pedido contém dados com a seguinte estrutura:

Representação JSON 
{
  "branch": string,
  "query": string,
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "userInfo": {
    object (UserInfo)
  },
  "languageCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  }
}
Campos
branch

string

O nome do recurso da ramificação, como projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0.

Use default_branch como o ID do ramo ou deixe este campo vazio para pesquisar documentos no ramo predefinido.
query

string

Consulta de pesquisa não processada.
imageQuery

object (ImageQuery)

Consulta de imagem RAW.
pageSize

integer

Número máximo de Documents a devolver. O valor máximo permitido depende do tipo de dados. Os valores acima do valor máximo são convertidos para o valor máximo.

  • Websites com indexação básica: predefinição 10, máximo 25.
  • Websites com indexação avançada: predefinição 25, máximo 50.
  • Outro: predefinição 50, máximo 100.

Se este campo for negativo, é devolvido um INVALID_ARGUMENT.
pageToken

string

Um token de página recebido de uma chamada SearchService.Search anterior. Faculte este valor para obter a página seguinte.

Quando paginar, todos os outros parâmetros fornecidos a SearchService.Search têm de corresponder à chamada que forneceu o token da página. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
offset

integer

Um número inteiro com índice 0 que especifica o deslocamento atual (ou seja, a localização do resultado inicial, entre os Documents considerados relevantes pela API) nos resultados da pesquisa. Este campo só é considerado se pageToken não estiver definido.

Se este campo for negativo, é devolvido um INVALID_ARGUMENT.

Um desvio grande pode ser limitado a um limite razoável.
oneBoxPageSize

integer

O número máximo de resultados a devolver para o OneBox. Isto aplica-se a cada tipo de OneBox individualmente. O número predefinido é 10.
dataStoreSpecs[]

object (DataStoreSpec)

Especificações que definem os DataStores específicos a serem pesquisados, juntamente com as configurações desses repositórios de dados. Isto só é considerado para Engines com várias lojas de dados. Para motores com um único armazenamento de dados, devem ser usadas as especificações diretamente abaixo de SearchRequest.
filter

string

A sintaxe do filtro consiste numa linguagem de expressão para criar um predicado a partir de um ou mais campos dos documentos que estão a ser filtrados. A expressão de filtro é sensível a maiúsculas e minúsculas.

Se este campo não for reconhecível, é devolvido um INVALID_ARGUMENT.

A filtragem em Vertex AI servingConfigs.search é feita através do mapeamento da chave do filtro do lado esquerdo para uma propriedade de chave definida no back-end do Vertex AI servingConfigs.search. Este mapeamento é definido pelo cliente no respetivo esquema. Por exemplo, um cliente de multimédia pode ter um campo "name" no respetivo esquema. Neste caso, o filtro teria o seguinte aspeto: filter --> name:'ANY("king kong")'

Para mais informações sobre a filtragem, incluindo a sintaxe e os operadores de filtro, consulte o artigo Filtrar
canonicalFilter

string

O filtro predefinido que é aplicado quando um utilizador faz uma pesquisa sem selecionar filtros na página de pesquisa.

O filtro aplicado a cada pedido de pesquisa quando é necessário um melhoramento da qualidade, como a expansão de consultas. No caso de uma consulta não ter uma quantidade suficiente de resultados, este filtro é usado para determinar se o fluxo de expansão de consultas deve ou não ser ativado. O filtro original continua a ser usado para a pesquisa expandida da consulta. Este campo é vivamente recomendado para alcançar uma elevada qualidade de pesquisa.

Para mais informações sobre a sintaxe de filtros, consulte SearchRequest.filter.
orderBy

string

A ordem pela qual os documentos são devolvidos. Os documentos podem ser ordenados por um campo num objeto Document. Deixe-o não definido se a ordenação for por relevância. A expressão orderBy é sensível a maiúsculas e minúsculas.

Para mais informações sobre a ordenação dos resultados da pesquisa de Websites, consulte o artigo Ordene os resultados da pesquisa na Web. Para mais informações sobre a ordenação dos resultados da pesquisa de cuidados de saúde, consulte o artigo Ordene os resultados da pesquisa de cuidados de saúde. Se este campo não for reconhecível, é devolvido um INVALID_ARGUMENT.
userInfo

object (UserInfo)

Informações sobre o utilizador final. Altamente recomendado para estatísticas e personalização. UserInfo.user_agent é usado para deduzir deviceType para estatísticas.
languageCode

string

O código de idioma BCP-47, como "en-US" ou "sr-Latn". Para mais informações, consulte o artigo Campos padrão. Este campo ajuda a interpretar melhor a consulta. Se não for especificado um valor, o código do idioma da consulta é detetado automaticamente, o que pode não ser preciso.
facetSpecs[]

object (FacetSpec)

Especificações de facetas para a pesquisa com filtros. Se estiver vazio, não são devolvidas facetas.

São permitidos, no máximo, 100 valores. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
boostSpec

object (BoostSpec)

Especificação de aumento para aumentar determinados documentos. Para mais informações sobre o aumento, consulte o artigo Aumentar
params

map (key: string, value: value (Value format))

Parâmetros de pesquisa adicionais.

Para a pesquisa de Websites públicos apenas, os valores suportados são:

  • user_country_code: string. Predefinição vazia. Se for definido como não vazio, os resultados são restritos ou melhorados com base na localização fornecida. Por exemplo, user_country_code: "au"

Para ver os códigos disponíveis, consulte Códigos dos países

  • searchType: duplo. Predefinição vazia. Ativa a pesquisa de conteúdo que não seja de páginas Web, consoante o valor. O único valor não predefinido válido é 1, que ativa a pesquisa de imagens. Por exemplo, searchType: 1
queryExpansionSpec

object (QueryExpansionSpec)

A especificação de expansão de consultas que especifica as condições em que a expansão de consultas ocorre.
spellCorrectionSpec

object (SpellCorrectionSpec)

A especificação de correção ortográfica que especifica o modo em que a correção ortográfica entra em vigor.
userPseudoId

string

Um identificador exclusivo para acompanhar os visitantes. Por exemplo, isto pode ser implementado com um cookie HTTP, que deve ser capaz de identificar de forma exclusiva um visitante num único dispositivo. Este identificador exclusivo não deve ser alterado se o visitante iniciar ou terminar sessão no Website.

Este campo NÃO deve ter um valor fixo, como unknown_visitor.

Este deve ser o mesmo identificador que UserEvent.user_pseudo_id e CompleteQueryRequest.user_pseudo_id

O campo tem de ser uma string codificada em UTF-8 com um limite de 128 carateres. Caso contrário, é devolvido um erro INVALID_ARGUMENT.
contentSearchSpec

object (ContentSearchSpec)

Uma especificação para configurar o comportamento da pesquisa de conteúdo.
rankingExpression

string

Opcional. A expressão de classificação controla a classificação personalizada nos documentos de obtenção. Esta opção substitui ServingConfig.ranking_expression. A sintaxe e as funcionalidades suportadas dependem do valor de rankingExpressionBackend. Se rankingExpressionBackend não for fornecido, a predefinição é RANK_BY_EMBEDDING.

Se rankingExpressionBackend não for fornecido ou for definido como RANK_BY_EMBEDDING, deve ser uma única função ou várias funções unidas por "+".

  • rankingExpression = function, { " + ", function };

Funções suportadas:

  • double * relevanceScore
  • double * dotProduct(embedding_field_path)

Variáveis de função:

  • relevanceScore: palavras-chave predefinidas, usadas para medir a relevância entre a consulta e o documento.
  • embedding_field_path: o campo de incorporação de documentos usado com o vetor de incorporação de consultas.
  • dotProduct: função de incorporação entre embedding_field_path e o vetor de incorporação de consultas.

Exemplo de expressão de classificação:

Se o documento tiver um campo de incorporação doc_embedding, a expressão de classificação pode ser 0.5 * relevanceScore + 0.3 * dotProduct(doc_embedding).

Se rankingExpressionBackend estiver definido como RANK_BY_FORMULA, são suportados os seguintes tipos de expressões (e combinações destes encadeados com operadores + ou *):

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0) -- transformação de classificação recíproca com o segundo argumento a ser uma constante do denominador.
  • isNan(signal) -- devolve 0 se o sinal for NaN e 1 caso contrário.
  • fillNan(signal1, signal2 | double) -- se signal1 for NaN, devolve signal2 | double; caso contrário, devolve signal1.

Seguem-se alguns exemplos de fórmulas de classificação que usam os tipos de expressões de classificação suportados:

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) -- a classificação baseia-se principalmente no logaritmo de keywordSimilarityScore com um ligeiro ajuste de semantic_smilarity_score.
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore) -- classificar pelo expoente de semanticSimilarityScore preenchendo o valor com 0 se for NaN, também adicionar o ajuste constante de 0,3 à pontuação final se semanticSimilarityScore for NaN.
  • 0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16): principalmente, a classificação é feita pela classificação recíproca de keywordSimilarityScore com um ligeiro ajuste da classificação recíproca de semantic_smilarity_score.

Os seguintes sinais são suportados:

  • semanticSimilarityScore: ajuste de semelhança semântica calculado através das incorporações geradas por um modelo proprietário da Google. Esta pontuação determina a semelhança semântica entre uma consulta de pesquisa e um documento.
  • keywordSimilarityScore: o ajuste de correspondência de palavras-chave usa a função de classificação Best Match 25 (BM25). Esta pontuação é calculada através de um modelo probabilístico para estimar a probabilidade de um documento ser relevante para uma determinada consulta.
  • relevanceScore: ajuste da relevância semântica que usa um modelo proprietário da Google para determinar o significado e a intenção por detrás da consulta de um utilizador no contexto do conteúdo dos documentos.
  • pctrRank: ajuste da taxa de conversão prevista como utilização de classificação. A taxa de cliques prevista (pCTR) é usada para avaliar a relevância e a atratividade de um resultado da pesquisa na perspetiva do utilizador. Uma pCTR mais elevada sugere que o resultado tem maior probabilidade de satisfazer a consulta e a intenção do utilizador, o que o torna um sinal valioso para a classificação.
  • freshnessRank: ajuste de atualização como classificação
  • documentAge: o tempo em horas decorrido desde a última atualização do documento, um número de vírgula flutuante (por exemplo, 0,25 significa 15 minutos).
  • topicalityRank: ajuste da relevância como classificação. Usa um modelo proprietário da Google para determinar a sobreposição baseada em palavras-chave entre a consulta e o documento.
  • baseRank: a classificação predefinida do resultado
rankingExpressionBackend

enum (RankingExpressionBackend)

Opcional. O back-end a usar para a avaliação da expressão de classificação.
userLabels

map (key: string, value: string)

As etiquetas de utilizador aplicadas a um recurso têm de cumprir os seguintes requisitos:

  • Cada recurso pode ter várias etiquetas, até um máximo de 64.
  • Cada etiqueta tem de ser um par chave-valor.
  • As chaves têm um comprimento mínimo de 1 carater e um comprimento máximo de 63 carateres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 carateres.
  • As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões. Todos os carateres têm de usar a codificação UTF-8, e são permitidos carateres internacionais.
  • A parte da chave de uma etiqueta tem de ser exclusiva. No entanto, pode usar a mesma chave com vários recursos.
  • As chaves têm de começar com uma letra minúscula ou um caráter internacional.

Consulte o documento do Google Cloud para ver mais detalhes.
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

Opcional. Configuração para capacidades de compreensão de consultas de linguagem natural, como a extração de filtros de campos estruturados da consulta. Consulte esta documentação para mais informações. Se naturalLanguageQueryUnderstandingSpec não for especificado, não é feita nenhuma compreensão adicional de consultas de linguagem natural.
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

servingConfigs.search as you type configuration. Apenas suportado para a vertical IndustryVertical.MEDIA.
displaySpec

object (DisplaySpec)

Opcional. Configuração para a funcionalidade de apresentação, como o realce de correspondências nos resultados da pesquisa.
session

string

O nome do recurso da sessão. Opcional.

A sessão permite que os utilizadores façam chamadas API de várias interações/pesquisa ou coordenação entre chamadas API de pesquisa e chamadas API de resposta.

Exemplo n.º 1 (várias interações/chamadas da API /search): chame a API /search com o ID da sessão gerado na primeira chamada. Aqui, a consulta de pesquisa anterior é considerada na posição da consulta. Ou seja, se a primeira consulta for "Como se saiu a Alphabet em 2022?" e a consulta atual for "E em 2023?", a consulta atual vai ser interpretada como "Qual foi o desempenho da Alphabet em 2023?".

Exemplo n.º 2 (coordenação entre chamadas da API /search e chamadas da API /answer): chame a API /answer com o ID da sessão gerado na primeira chamada. Aqui, a geração de respostas ocorre no contexto dos resultados da pesquisa da primeira chamada de pesquisa.

A funcionalidade de pesquisa multi-interação servingConfigs.search está atualmente na fase de GA privada. Use a versão v1alpha ou v1beta antes de lançarmos esta funcionalidade para a disponibilidade geral pública. Em alternativa, peça a inclusão na lista de autorizações através da equipa de apoio técnico da Google.
sessionSpec

object (SessionSpec)

Especificação da sessão.

Só pode ser usado quando session está definido.
relevanceThreshold

enum (RelevanceThreshold)

O limite de relevância dos resultados da pesquisa.

Usar o limite definido pela Google, tirando partido de um equilíbrio entre a precisão e a capacidade de memorização para apresentar resultados altamente precisos e uma cobertura abrangente de informações relevantes.

Esta funcionalidade não é compatível com a pesquisa de cuidados de saúde.
relevanceScoreSpec

object (RelevanceScoreSpec)

Opcional. A especificação para devolver a pontuação de relevância.

Corpo da resposta

Se for bem-sucedido, o corpo da resposta contém uma instância de SearchResponse.

Âmbitos de autorização

Requer um dos seguintes âmbitos do OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

Para mais informações, consulte o Authentication Overview.

Autorizações de IAM

Requer a seguinte autorização de IAM no recurso servingConfig:

  • discoveryengine.servingConfigs.search

Para mais informações, consulte a documentação do IAM.