Method: projects.locations.dataStores.servingConfigs.search

Realiza uma pesquisa.

Solicitação HTTP

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

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

Parâmetros de caminho

Parâmetros
servingConfig

string

Obrigatório. O nome do recurso da configuração de veiculaçã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. Esse campo é usado para identificar o nome da configuração de veiculação, o conjunto de modelos usados para fazer a pesquisa.

Corpo da solicitação

O corpo da solicitação 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,
  "regionCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "useLatestData": boolean,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "embeddingSpec": {
    object (EmbeddingSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "customFineTuningSpec": {
    object (CustomFineTuningSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "personalizationSpec": {
    object (PersonalizationSpec)
  },
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  },
  "searchAddonSpec": {
    object (SearchAddonSpec)
  }
}
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 da ramificação ou deixe esse campo vazio para pesquisar documentos na ramificação padrão.
query

string

Consulta de pesquisa bruta.
imageQuery

object (ImageQuery)

Consulta de imagem bruta.
pageSize

integer

Número máximo de Documents a serem retornados. O valor máximo permitido depende do tipo de dados. Valores acima do máximo são convertidos para o máximo.

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

Se esse campo for negativo, um INVALID_ARGUMENT será retornado.
pageToken

string

Um token de página recebido de uma chamada SearchService.Search anterior. Forneça isso para recuperar a página subsequente.

Ao paginar, todos os outros parâmetros fornecidos para SearchService.Search precisam corresponder à chamada que forneceu o token da página. Caso contrário, um erro INVALID_ARGUMENT será retornado.
offset

integer

Um número inteiro com índice zero que especifica o deslocamento atual (ou seja, o local do resultado inicial, entre os Documents considerados relevantes pela API) nos resultados da pesquisa. Este campo só é considerado quando pageToken não está definido.

Se esse campo for negativo, um INVALID_ARGUMENT será retornado.

Um grande valor de ajuste pode ser limitado a um limite razoável.
oneBoxPageSize

integer

O número máximo de resultados a serem retornados para a OneBox. Isso se aplica a cada tipo de OneBox individualmente. O número padrão é 10.
dataStoreSpecs[]

object (DataStoreSpec)

Especificações que definem os DataStores específicos a serem pesquisados, além das configurações desses armazenamentos de dados. Isso só é considerado para Engines com vários repositórios de dados. Para mecanismos com um único repositório de dados, use as especificações diretamente em SearchRequest.
filter

string

A sintaxe do filtro consiste em uma linguagem de expressão para construir um predicado a partir de um ou mais campos dos documentos que estão sendo filtrados. A expressão de filtro diferencia maiúsculas de minúsculas.

Se esse campo não for reconhecido, um INVALID_ARGUMENT será retornado.

A filtragem em "servingConfigs.search" da Vertex AI é feita mapeando a chave de filtro do lado esquerdo para uma propriedade de chave definida no back-end "servingConfigs.search" da Vertex AI. Esse mapeamento é definido pelo cliente no esquema dele. Por exemplo, um cliente de mídia pode ter um campo "name" no esquema. Nesse caso, o filtro ficaria assim: filter --> name:'ANY("king kong")'

Para mais informações sobre filtragem, incluindo sintaxe e operadores de filtro, consulte Filtrar.
canonicalFilter

string

O filtro padrão aplicado quando um usuário faz uma pesquisa sem marcar nenhum filtro na página de pesquisa.

O filtro aplicado a cada solicitação de pesquisa quando é necessário melhorar a qualidade, como a expansão de consultas. Se uma consulta não tiver resultados suficientes, esse filtro será usado para determinar se o fluxo de expansão de consulta será ativado ou não. O filtro original ainda será usado na pesquisa expandida da consulta. Recomendamos usar esse campo para alcançar uma alta qualidade da pesquisa.

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

string

A ordem em que os documentos são retornados. Os documentos podem ser ordenados por um campo em um objeto Document. Deixe em branco se a ordenação for por relevância. A expressão orderBy diferencia maiúsculas de minúsculas.

Para mais informações sobre como ordenar os resultados da pesquisa no site, consulte Ordenar resultados da pesquisa na Web. Para mais informações sobre como ordenar os resultados da pesquisa de saúde, consulte Ordenar resultados da pesquisa de saúde. Se esse campo não for reconhecido, um INVALID_ARGUMENT será retornado.
userInfo

object (UserInfo)

Informações sobre o usuário final. Altamente recomendado para análises e personalização. UserInfo.user_agent é usado para deduzir deviceType para análise.
languageCode

string

O código de idioma BCP-47, como pt-BR ou en-US. Para mais informações, consulte Campos padrão. Esse campo ajuda a interpretar melhor a consulta. Se um valor não for especificado, o código do idioma da consulta será detectado automaticamente, o que pode não ser preciso.
regionCode

string

O código de país/região Unicode (CLDR) de um local, como "US" e "419". Para mais informações, consulte Campos padrão. Se definido, os resultados serão promovidos com base no regionCode fornecido.
facetSpecs[]

object (FacetSpec)

Especificações de atributos para pesquisa de atributos. Se estiver vazio, nenhum atributo será retornado.

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

object (BoostSpec)

Aumente a especificação para impulsionar determinados documentos. Para mais informações sobre o aumento, consulte Aumento.
params

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

Parâmetros de pesquisa adicionais.

Para pesquisa de sites públicos, os valores aceitos são:

  • user_country_code: string. O padrão é vazio. Se definido como não vazio, os resultados serão restritos ou promovidos com base no local fornecido. Por exemplo, user_country_code: "au"

Para ver os códigos disponíveis, consulte Códigos de país.

  • searchType: double. O padrão é vazio. Ativa a pesquisa de conteúdo que não seja de páginas da Web, dependendo do valor. O único valor válido que não é o padrão é 1, que ativa a pesquisa de imagens. Por exemplo, searchType: 1
queryExpansionSpec

object (QueryExpansionSpec)

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

object (SpellCorrectionSpec)

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

string

Um identificador exclusivo para rastrear visitantes. Por exemplo, isso pode ser implementado com um cookie HTTP, que deve ser capaz de identificar um visitante de maneira exclusiva em um único dispositivo. Esse identificador exclusivo não deve mudar se o visitante fizer login ou logout no site.

Esse campo NÃO pode ter um valor fixo, como unknown_visitor.

Precisa ser o mesmo identificador de UserEvent.user_pseudo_id e CompleteQueryRequest.user_pseudo_id.

O campo precisa ser uma string codificada em UTF-8 com um limite de 128 caracteres. Caso contrário, um erro INVALID_ARGUMENT será retornado.
useLatestData

boolean

usa o Engine, o ServingConfig e o Control recém-lidos do banco de dados.

Observação: isso ignora o cache de configuração e introduz a dependência de bancos de dados, o que pode aumentar significativamente a latência da API. Ele só deve ser usado para testes, não para atender usuários finais.
contentSearchSpec

object (ContentSearchSpec)

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

object (EmbeddingSpec)

Usa o embedding fornecido para fazer outra recuperação semântica de documentos. A recuperação é baseada no produto escalar de SearchRequest.EmbeddingSpec.EmbeddingVector.vector e a incorporação do documento fornecida em SearchRequest.EmbeddingSpec.EmbeddingVector.field_path.

Se SearchRequest.EmbeddingSpec.EmbeddingVector.field_path não for fornecido, ServingConfig.EmbeddingConfig.field_path será usado.
rankingExpression

string

Opcional. A expressão de classificação controla a classificação personalizada nos documentos de recuperação. Isso substitui ServingConfig.ranking_expression. A sintaxe e os recursos compatíveis dependem do valor de rankingExpressionBackend. Se rankingExpressionBackend não for fornecido, o padrão será RANK_BY_EMBEDDING.

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

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

Funções compatíveis:

  • 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 embedding de documento usado com o vetor de embedding de consulta.
  • dotProduct: função de embedding entre embedding_field_path e o vetor de embedding de consulta.

Exemplo de expressão de classificação:

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

Se rankingExpressionBackend for definido como RANK_BY_FORMULA, os seguintes tipos de expressão (e combinações deles encadeados usando operadores + ou *) serão compatíveis:

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0): transformação de classificação recíproca com o segundo argumento sendo uma constante de denominador.
  • isNan(signal): retorna 0 se o indicador for NaN e 1 caso contrário.
  • fillNan(signal1, signal2 | double): se signal1 for NaN, retorna signal2 | double. Caso contrário, retorna signal1.

Confira alguns exemplos de fórmulas de classificação que usam os tipos de expressões de classificação aceitos:

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore): principalmente classificação pelo logaritmo de keywordSimilarityScore com um pequeno ajuste de semantic_smilarity_score.
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore): classifica pelo expoente de semanticSimilarityScore, preenchendo o valor com 0 se for NaN.Também adiciona um ajuste constante de 0,3 à pontuação final se semanticSimilarityScore for NaN.
  • 0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16): principalmente classificação pela posição recíproca de keywordSimilarityScore com um pequeno ajuste da posição recíproca de semantic_smilarity_score.

Há suporte para os seguintes indicadores:

  • semanticSimilarityScore: ajuste de similaridade semântica calculado usando os embeddings gerados por um modelo proprietário do Google. Essa pontuação determina o grau de semelhança semântica entre uma consulta de pesquisa e um documento.
  • keywordSimilarityScore: o ajuste de correspondência de palavra-chave usa a função de classificação Best Match 25 (BM25). Essa pontuação é calculada usando um modelo probabilístico para estimar a probabilidade de um documento ser relevante para uma determinada consulta.
  • relevanceScore: ajuste de relevância semântica que usa um modelo proprietário do Google para determinar o significado e a intenção por trás da consulta de um usuário no contexto do conteúdo dos documentos.
  • pctrRank: ajuste previsto da taxa de conversão como um uso de classificação. A taxa de cliques prevista (pCTR) é usada para avaliar a relevância e o atrativo de um resultado da pesquisa do ponto de vista do usuário. Uma pCTR mais alta sugere que o resultado tem mais chances de satisfazer a consulta e a intenção do usuário, o que o torna um indicador valioso para a classificação.
  • freshnessRank: ajuste de atualização como uma classificação
  • documentAge: o tempo em horas decorrido desde a última atualização do documento, um número de ponto flutuante (por exemplo, 0,25 significa 15 minutos.
  • topicalityRank: ajuste de relevância como uma classificação. Usa o modelo proprietário do Google para determinar a sobreposição baseada em palavras-chave entre a consulta e o documento.
  • baseRank: a classificação padrão do resultado
rankingExpressionBackend

enum (RankingExpressionBackend)

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

map (key: string, value: string)

Os rótulos de usuário aplicados a um recurso precisam atender aos seguintes requisitos:

  • Cada recurso pode ter vários rótulos, até um máximo de 64.
  • Cada rótulo precisa ser um par de chave-valor.
  • As chaves têm comprimento mínimo de um caractere e comprimento máximo de 63 caracteres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 caracteres.
  • As chaves e os valores podem conter apenas letras minúsculas, caracteres numéricos, sublinhados e traços. Todos os caracteres precisam usar a codificação UTF-8, e os caracteres internacionais são permitidos.
  • A parte da chave de um rótulo precisa ser única. No entanto, é possível usar a mesma chave com vários recursos.
  • As chaves precisam começar com uma letra minúscula ou um caractere internacional.

Consulte o documento do Google Cloud para mais detalhes.
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

Opcional. Configuração para recursos de compreensão de consultas em linguagem natural, como extrair filtros de campos estruturados da consulta. Consulte esta documentação para mais informações. Se naturalLanguageQueryUnderstandingSpec não for especificado, não será feita nenhuma compreensão adicional de consultas em linguagem natural.
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

Configuração de pesquisa enquanto você digita para "servingConfigs". Compatível apenas com a categoria IndustryVertical.MEDIA.
customFineTuningSpec

object (CustomFineTuningSpec)

Configurações de ajuste refinado personalizadas. Se definido, ele terá prioridade maior do que as configurações definidas em ServingConfig.custom_fine_tuning_spec.
displaySpec

object (DisplaySpec)

Opcional. Configuração para recursos de exibição, como o destaque de correspondências nos resultados da pesquisa.
session

string

O nome do recurso da sessão. Opcional.

A sessão permite que os usuários façam chamadas de API /search de várias rodadas ou a coordenação entre chamadas de API /search e /answer.

Exemplo 1 (chamadas de API /search com várias interações): 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. Por exemplo, se a primeira consulta for "Como foi o desempenho da Alphabet em 2022?" e a consulta atual for "E 2023?", ela será interpretada como "Como foi o desempenho da Alphabet em 2023?".

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

No momento, o recurso "servingConfigs.search" de várias rodadas está na fase de GA particular. Use a versão v1alpha ou v1beta antes de lançarmos esse recurso para disponibilidade geral pública ou peça a inclusão na lista de permissões para a equipe de suporte do 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.

Use o limite definido pelo Google, aproveitando um equilíbrio entre precisão e recall para fornecer resultados altamente precisos e cobertura abrangente de informações relevantes.

Esse recurso não é compatível com a pesquisa de saúde.
personalizationSpec

object (PersonalizationSpec)

A especificação da personalização.

Se ServingConfig.personalization_spec e SearchRequest.personalization_spec estiverem definidos, SearchRequest.personalization_spec vai substituir ServingConfig.personalization_spec.
relevanceScoreSpec

object (RelevanceScoreSpec)

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

object (SearchAddonSpec)

Opcional. O SearchAddonSpec é usado para desativar complementos de pesquisa de acordo com o novo modelo de reprecificação. Esse campo só é compatível com solicitações de pesquisa.

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de SearchResponse.

Escopos de autorização

Requer um dos seguintes escopos 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 Authentication Overview.

Permissões do IAM

Requer a seguinte permissão do IAM no recurso servingConfig:

  • discoveryengine.servingConfigs.search

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