Receber resultados da pesquisa (legado)

Esta página mostra como receber resultados da pesquisa usando a API.

É possível fazer chamadas de API e integrá-las ao seu servidor ou aplicativo. Esta página inclui exemplos de código sobre como fazer consultas de pesquisa usando as bibliotecas de cliente gRPC com uma conta de serviço.

Receber resultados da pesquisa

É possível receber resultados da pesquisa usando a API.

REST

Para usar a API e receber resultados da pesquisa de um app com dados estruturados ou não estruturados dados, use o engines.servingConfigs.search método:

  1. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

    1. No Google Cloud console, acesse a página Gemini Enterprise.

      Acessar "Apps".

    2. Na página Apps, encontre o nome do seu app e o ID dele na coluna ID.

  2. Visualizar os resultados da pesquisa.

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
-d '{
"query": "QUERY",
"userPseudoId": "USER_PSEUDO_ID",
"pageSize": "PAGE_SIZE",
"offset": "OFFSET",
"orderBy": "ORDER_BY",
"filter": "FILTER",
"boostSpec": "BOOST_SPEC",
"facetSpec": "FACET_SPEC",
"queryExpansionSpec": "QUERY_EXPANSION_SPEC",
"spellCorrectionSpec": "SPELL_CORRECTION_SPEC",
"contentSearchSpec": "CONTENT_SEARCH_SPEC",
"dataStoreSpecs": [{"DATA_STORE_SPEC"}],
}'

    Substitua:

    • PROJECT_ID: ID do projeto.
    • APP_ID: ID do app que você quer consultar.
    • QUERY: o texto da consulta para pesquisar.
    • USER_PSEUDO_ID: uma string codificada em UTF-8, que funciona como um identificador pseudonimizado exclusivo que rastreia os usuários. Ele pode ter um comprimento máximo de 128 caracteres. O Google recomenda o uso desse campo porque ele melhora a performance do modelo e a qualidade da personalização. Você pode usar um cookie HTTP para esse campo, que identifica exclusivamente um visitante em um único dispositivo. Confira algumas considerações importantes:

      • Esse identificador não muda quando o visitante faz login ou logout de um site.
      • Esse campo não pode ser definido como o mesmo identificador para vários usuários. Caso contrário, o uso do mesmo ID de usuário para várias pessoas pode combinar históricos de eventos de usuários diferentes e degradar a qualidade do modelo.
      • Esse campo não pode incluir informações de identificação pessoal (PII).
      • Para uma determinada solicitação de pesquisa ou navegação, esse campo precisa ser mapeado para o campo userPseudoId correspondente nos eventos do usuário.

      Para mais informações, consulte userPseudoId.

    • PAGE_SIZE: o número de resultados retornados pela pesquisa. O tamanho máximo permitido da página depende do tipo de dados. Os tamanhos de página acima do valor máximo são forçados para o valor máximo.

    • OFFSET: opcional. O índice inicial dos resultados. O valor padrão é 0.

      Por exemplo, se o deslocamento for 2, o tamanho da página for 10 e houver 15 resultados a serem retornados, os resultados de 2 a 11 serão retornados na primeira página.

    • ORDER_BY: opcional. A ordem em que os resultados são organizados.

    • FILTER: opcional. Um campo de texto para filtrar a pesquisa usando uma expressão de filtro. O valor padrão é uma string vazia, o que significa que nenhum filtro é aplicado.

      Exemplo: color: ANY("red", "blue") AND score: IN(*, 100.0e)

      Para mais informações, consulte Filtrar a pesquisa de dados estruturados ou não estruturados dados.

    • BOOST_SPEC: opcional. Uma especificação para promover ou ocultar documentos. Valores:

      • BOOST: um número de ponto flutuante no intervalo [-1,1]. Quando o valor é negativo, os resultados são rebaixados (aparecem mais abaixo nos resultados). Quando o valor é positivo, os resultados são promovidos (aparecem mais acima nos resultados).
      • CONDITION: uma expressão de filtro de texto para selecionar os documentos a que o aumento é aplicado. O filtro precisa ser avaliado como um valor booleano.

      Para saber mais sobre o aumento da pesquisa estruturada, consulte Promover resultados da pesquisa.

    • FACET_SPEC: opcional. Uma especificação de atributos para realizar a pesquisa de atributos.

    • QUERY_EXPANSION_SPEC: opcional. Uma especificação para determinar em quais condições a expansão de consulta deve ocorrer. O padrão é DISABLED.

    • SPELL_CORRECTION_SPEC: opcional. Uma especificação para determinar em quais condições a correção ortográfica deve ocorrer. O padrão é AUTO.

    • CONTENT_SEARCH_SPEC: opcional. Para receber snippets, respostas extrativas, segmentos extrativos e resumos de pesquisa. Apenas para dados não estruturados. Para mais informações, consulte:

    • DATA_STORE_SPEC: filtros para um repositório de dados específico para pesquisar. Isso pode ser usado se o app de pesquisa estiver conectado a vários repositórios de dados. Para mais informações, consulte DataStoreSpec.

    • Visualizar resultados da pesquisa guiada na resposta da pesquisa:

      Os resultados da pesquisa guiada são retornados com respostas de pesquisa estruturada e não estruturada. O resultado da pesquisa guiada contém uma lista de pares de chave-valor de atributos extraídos com base em documentos de resultados da pesquisa. Isso permite que os usuários refinem os resultados da pesquisa usando algumas chaves e valores de atributos como filtros.

      Neste exemplo de resposta, a cor verde foi usada para refinar os resultados da pesquisa emitindo uma nova solicitação de pesquisa com o campo de filtro especificado como _gs.color: ANY("green"):

      {
"guidedSearchResult": {
  "refinementAttributes": [
    {
      "attributeKey": "_gs.color",
      "attributeValue": "green"
    },
    {
      "attributeKey": "_gs.category",
      "attributeValue": "shoe"
    }
  ]
}
}

Receber pontuações de relevância do documento com resultados da pesquisa

As pontuações de relevância do documento são baseadas na similaridade da consulta com o documento. As pontuações são colocadas em 11 buckets no intervalo: 0, 0,1, 0,2, … a 1,0. Quanto maior a pontuação, mais relevante o documento.

Considere as pontuações de relevância do documento para estes casos de uso:

  • Filtragem pós-pesquisa com base na pontuação de relevância para remover resultados irrelevantes

  • Classificação pós-pesquisa ou como entrada para outros aplicativos

  • Depuração: as pontuações de relevância podem fornecer insights sobre por que alguns resultados da pesquisa são retornados

Para cada resultado da pesquisa, uma pontuação de relevância pode ser retornada:

  "results": [
    {
      "id": "DOCUMENT_ID",
      "document": {
      ...
      },
      "modelScores": {
        "relevance_score": {
          "values": [
            DOCUMENT-RELEVANCE-SCORE
          ]
        }
      }
    },
    ...

Consulte também o comando de exemplo no procedimento abaixo.

Antes de começar:verifique se o app de pesquisa está associado a um repositório de dados estruturados ou não estruturados.

REST

Para solicitar que as pontuações de relevância do documento sejam retornadas com os resultados da pesquisa, use o engines.servingConfigs.search método da seguinte maneira:

  1. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

    1. No Google Cloud console, acesse a página Gemini Enterprise.

      Acessar "Apps".

    2. Na página Apps, encontre o nome do seu app e o ID dele na coluna ID.

  2. Execute o comando curl a seguir para receber as pontuações retornadas com os resultados da pesquisa.

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
-d '{
     "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search",
     "query": "QUERY",
     "relevanceScoreSpec": {
       "returnRelevanceScore": true
     }
}'
    • PROJECT_ID: ID do projeto.
    • APP_ID: ID do app que você quer consultar.
    • QUERY: o texto da consulta para pesquisar.

O resumo da pesquisa varia de acordo com o modelo

Se você gerar resumos de pesquisa para suas consultas, poderá notar que os resumos são diferentes entre os resultados do console e os resultados da API. Se isso acontecer, o motivo provável é que o console está usando um modelo de LLM diferente da API. Os exemplos de curl e código nesta página usam o modelo de LLM estável.

  • Para mudar ou visualizar o modelo de LLM usado na página Visualização da UI, acesse a página Configurações > guia Interface do seu app.

  • Para chamadas de método, o modelo estável é o modelo padrão. Para usar um modelo de LLM diferente do modelo estável, consulte Especificar o modelo de resumo e Especificar o modelo de resposta.