Esta página foi traduzida pela API Cloud Translation.

Receber resultados da pesquisa

Nesta página, mostramos como visualizar os resultados da pesquisa usando o console Google Cloud e como receber os resultados da pesquisa usando a API.

Além disso, em vez de usar a UI do app da Web, você pode fazer chamadas de API e integrá-las ao 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 conferir os resultados da pesquisa no console Google Cloud ou usar a API para receber os resultados.

Console

Para usar o Google Cloud console e visualizar os resultados da pesquisa de um app com dados estruturados ou não estruturados, siga estas etapas:

Abra a página Prévia no console.
Digite uma consulta de pesquisa.
1. Se você ativou o preenchimento automático na etapa 1, uma lista de sugestões vai aparecer abaixo da barra de pesquisa enquanto você digita.
(Opcional) Se você conectou vários repositórios de dados ao app, mas quer resultados apenas de um repositório de dados específico, selecione o repositório de dados para receber resultados dele.
Clique em Enter para enviar a consulta.
1. Uma lista de resultados de pesquisa aparece abaixo da barra de pesquisa.
2. Se nenhum mapeamento de atributos for definido na página Configurações, cada resultado da pesquisa vai aparecer como uma lista de nomes e valores de atributos brutos.
3. Se algum mapeamento de atributo foi salvo na página Configurações, os resultados da pesquisa vão mostrar as mesmas imagens que você vê na prévia da página Configurações.
Se alguma faceta foi especificada na página Configurações, ela será mostrada da mesma forma.
Clique na seta abaixo da lista de resultados para carregar a próxima página.

REST

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

Observação:é possível pesquisar em um app usando o método engines.servingConfigs.search e em um repositório de dados usando o método dataStores.servingConfigs.search. Para o procedimento a seguir, o Google recomenda pesquisar usando o método engines.servingConfigs.search.

Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.
1. No console Google Cloud , acesse a página Gemini Enterprise.
  
  Acessar "Apps".
2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.
Visualizar os resultados da pesquisa.

Termo-chave:no Gemini Enterprise, o termo app pode ser usado de forma intercambiável com o termo mecanismo no contexto das APIs. Um mecanismo do Gemini Enterprise é um mecanismo de pesquisa genérico em que o campo app_type está definido como APP_TYPE_INTRANET.
```
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: o ID do app que você quer consultar.
- QUERY: o texto da consulta a ser pesquisado.
- USER_PSEUDO_ID: uma string codificada em UTF-8 que funciona como um identificador pseudônimo exclusivo que rastreia os usuários. Ele pode ter um tamanho máximo de 128 caracteres. O Google recomenda usar esse 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 um visitante em um único dispositivo. 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 com o mesmo identificador para vários usuários. Caso contrário, usar o mesmo ID para vários usuários pode combinar os históricos de eventos de diferentes usuários e prejudicar 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 ver 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. Tamanhos de página acima do valor máximo são revertidos 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 sua 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.
- BOOST_SPEC: opcional. Uma especificação para aumentar ou diminuir a relevância de 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 em que o aumento é aplicado. O filtro precisa ser avaliado como um valor booleano.
  Para saber mais sobre o aumento da pesquisa estruturada, consulte Aumentar os resultados da pesquisa.
- FACET_SPEC: opcional. Uma especificação de atributo para realizar pesquisa de atributos.
- QUERY_EXPANSION_SPEC: opcional. Uma especificação para determinar em quais condições a expansão da 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, trechos extrativos e resumos de pesquisa. Apenas para dados não estruturados. Veja mais informações em:
  - Usar snippets e conteúdo extrativo
  - Receber resumos de pesquisa
- DATA_STORE_SPEC: filtros para um repositório de dados específico em que a pesquisa será feita. Isso pode ser usado se o app de pesquisa estiver conectado a vários repositórios de dados. Para mais informações, consulte DataStoreSpec.
- Como ver os resultados da pesquisa guiada na resposta da pesquisa:
  
  Os resultados da pesquisa guiada são retornados com respostas de pesquisa para 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 nos 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 ao emitir 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 os resultados da pesquisa

As pontuações de relevância do documento são baseadas na semelhança da consulta com o documento. As pontuações são colocadas em 11 intervalos 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 de 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 método engines.servingConfigs.search da seguinte maneira:

Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.
1. No console Google Cloud , acesse a página Gemini Enterprise.
  
  Acessar "Apps".
2. Na página Apps, encontre o nome do app e confira o ID dele na coluna ID.

Execute o comando curl a seguir para receber 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: o ID do app que você quer consultar.
QUERY: o texto da consulta a ser pesquisado.

Exemplo de comando e resultado parcial

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search:search" \
-d '{
      "servingConfig": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/default_search",
      "query": "When was Verily founded and what is its mission?",
      "relevanceScoreSpec": {
        "returnRelevanceScore": true
      }
}'

{
  "results": [
    {
      "id": "f1b0d98bd2a078a6dfb4f809c3028565",
      "document": {
        "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/f1b0d98bd2a078a6dfb4f809c3028565",
        "id": "f1b0d98bd2a078a6dfb4f809c3028565",
        "derivedStructData": {
          "link": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2019_alphabet_annual_report.pdf",
          "extractive_answers": [
            {
              "pageNumber": "70",
              "content": "VERILY Verily is a life science and healthcare company with a mission to make the world's health data useful so that people enjoy healthier lives. In December 2018, Verily received $900 million in cash from a $1.0 billion investment round. The remaining $100 million was received in the first quarter of 2019."
            }
          ],
          "title": "2019_alphabet_annual_report"
        }
      },
      "modelScores": {
        "relevance_score": {
          "values": [
            0.7
          ]
        }
      }
    },
    {
      "id": "0371b29bfa18ac43896b86a7b63d00b0",
      "document": {
        "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/0371b29bfa18ac43896b86a7b63d00b0",
        "id": "0371b29bfa18ac43896b86a7b63d00b0",
        "derivedStructData": {
          "link": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/20190429_alphabet_10Q.pdf",
          "title": "GOOG 10-Q Q1 2019",
          "extractive_answers": [
            {
              "content": "Verily Verily is a life science company with a mission to make the world's health data useful so that people enjoy healthier lives. In December 2018, Verily received $900 million in cash from a $1.0 billion investment round. The remaining $100 million was received in the first quarter of 2019.",
              "pageNumber": "21"
            }
          ]
        }
      },
     "modelScores": {
        "relevance_score": {
          "values": [
            0.5
          ]
        }
      }
    },
    ...
    {
      "id": "e6bbd0d82dc2a2fc7ccf1bd82ac6334f",
      "document": {
        "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/branches/0/documents/e6bbd0d82dc2a2fc7ccf1bd82ac6334f",
        "id": "e6bbd0d82dc2a2fc7ccf1bd82ac6334f",
        "derivedStructData": {
          "title": "2021_Q1_Earnings_Transcript",
          "link": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2021_Q1_Earnings_Transcript.pdf",
          "extractive_answers": [
            {
              "pageNumber": "2",
              "content": "Our strength in AI and ML is also helping Financial Services customers improve efficiency of payments, reduce fraud and risk, and deliver faster payment solutions."
            }
          ]
        }
      },
      "modelScores": {
        "relevance_score": {
          "values": [
            0
          ]
        }
      }
    }
  ],
  "totalSize": 76,
  "attributionToken": "8QHw8AoLCIW4_b0GELHd3lgSJDY3YmU1ZGMwLTAwMDAtMmM1OC04NzcyLTc0NzQ0NjNiOGMyNSIHR0VORVJJQyqcAcb77TDHy_MX8tntMI6-nRWK4uQwwvCeFYX77TDvifIwq8SKLauR3zCq-LMt0IrIMNSynRWc1rctv_7kML7l3zDZveQwkPeyMMP77TD12e0wpd_hMIfi5DCRv9owgvvtMJWSxTCOkckwu-XfMK7Eii3sifIwqJHfMKjf4TCt-LMtlL_aMJ_Wty23t4wto4CXIs2KyDDcveQwwv7kMDABShIweDU3MGFkYWI4MzQ4NmY0MGE",
  "nextPageToken": "UjMjhjYzYDN0cDN30iM3cDOtgTNjJTLwADMw0iZiRWNlJ2N2QiGBUd0gWLEG4bjhWICMIBM1IgC",
  "summary": {},
  "queryExpansionInfo": {}
}

O resumo de pesquisa varia de acordo com o modelo

Se você gerar resumos de pesquisa para suas consultas, poderá notar que eles são diferentes entre os resultados do console e da API. Se isso acontecer, provavelmente 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 conferir o modelo de LLM usado na página Prévia da UI, acesse a página Configurações > guia Interface do seu app.
Para chamadas de método, o modelo estável é o padrão. Para usar um modelo LLM diferente do estável, consulte Especificar o modelo de resumo e Especificar o modelo de resposta.