Esta página foi traduzida pela API Cloud Translation.

Obtenha resultados da pesquisa

Esta página mostra como pré-visualizar os resultados da pesquisa através da consola Google Cloud e obter resultados da pesquisa através da API.

Além disso, em vez de usar a IU da app Web, pode fazer chamadas API e integrar essas chamadas no seu servidor ou aplicação. Esta página inclui exemplos de código sobre como fazer consultas de pesquisa usando as bibliotecas cliente gRPC com uma conta de serviço.

Obtenha resultados da pesquisa

Pode pré-visualizar os resultados da pesquisa a partir da Google Cloud consola ou obter resultados da pesquisa através da API.

Consola

Para usar a Google Cloud consola para pré-visualizar os resultados da pesquisa de uma app com dados estruturados ou não estruturados, siga estes passos:

Abra a página Pré-visualização na consola.
Escreva uma consulta de pesquisa.
1. Se ativou o preenchimento automático no passo 1, vê uma lista de sugestões de preenchimento automático abaixo da barra de pesquisa à medida que escreve.
(Opcional) Se associou várias bases de dados à sua app, mas quer resultados apenas de uma base de dados específica, selecione a base de dados a partir da qual quer obter resultados.
Clique em Enter para enviar a consulta.
1. É apresentada uma lista de resultados da pesquisa abaixo da barra de pesquisa.
2. Se não for definida nenhuma associação de atributos na página Configurações, cada resultado da pesquisa é apresentado como uma lista de nomes e valores de atributos não processados.
3. Se foram guardados mapeamentos de atributos na página Configurações, os resultados da pesquisa apresentam as mesmas imagens que vê na pré-visualização da página Configurações.
Se tiverem sido especificadas facetas na página Configurações, estas são apresentadas da mesma forma.
Clique na seta abaixo da lista de resultados para carregar a página de resultados seguinte.

REST

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

Nota: pode pesquisar numa app através do método engines.servingConfigs.search e pode pesquisar num arquivo de dados através do método dataStores.servingConfigs.search. Para o procedimento seguinte, a Google recomenda que pesquise através do método engines.servingConfigs.search.

Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.
1. Na Google Cloud consola, aceda à página Gemini Enterprise.
  
  Aceda a Apps
2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.
Pré-visualizar resultados da pesquisa.

Termo-chave: no Gemini Enterprise, o termo app pode ser usado de forma intercambiável com o termo motor no contexto das APIs. Um motor do Gemini Enterprise é um motor 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 o seguinte:
- PROJECT_ID: o ID do seu projeto.
- APP_ID: o ID da app que quer consultar.
- QUERY: o texto da consulta a pesquisar.
- USER_PSEUDO_ID: uma string codificada em UTF-8 que funciona como um identificador pseudonimizado exclusivo que acompanha os utilizadores. Pode ter um comprimento máximo de 128 carateres. A Google recomenda vivamente a utilização deste campo, uma vez que melhora o desempenho do modelo e a qualidade da personalização. Pode usar um cookie HTTP para este campo, que identifica de forma exclusiva um visitante num único dispositivo. Seguem-se algumas considerações importantes:
  - Este identificador não se altera quando o visitante inicia ou termina sessão num Website.
  - Este campo não pode ser definido com o mesmo identificador para vários utilizadores. Caso contrário, a utilização do mesmo ID do utilizador para vários utilizadores pode combinar os históricos de eventos de diferentes utilizadores e degradar a qualidade do modelo.
  - Este campo não pode incluir informações de identificação pessoal (PII).
  - Para um determinado pedido de pesquisa ou navegação, este campo tem de ser mapeado para o campo userPseudoId correspondente nos eventos do utilizador.
  Para mais informações, consulte userPseudoId.
- PAGE_SIZE: o número de resultados devolvidos pela pesquisa. O tamanho máximo permitido da página depende do tipo de dados. Os tamanhos das páginas acima do valor máximo são forçados para o valor máximo.
- OFFSET: opcional. O índice inicial dos resultados. O valor predefinido é 0.
  
  Por exemplo, se o desvio for 2, o tamanho da página for 10 e houver 15 resultados a devolver, os resultados 2 a 11 são devolvidos na primeira página.
- ORDER_BY: opcional. A ordem pela qual os resultados são organizados.
- FILTER: opcional. Um campo de texto para filtrar a pesquisa com uma expressão de filtro. O valor predefinido é uma string vazia, o que significa que não é aplicado nenhum filtro.
  
  Exemplo: color: ANY("red", "blue") AND score: IN(*, 100.0e)
  
  Para mais informações, consulte o artigo Filtre a pesquisa de dados estruturados ou não estruturados.
- BOOST_SPEC: opcional. Uma especificação para realçar ou ocultar documentos. Valores:
  - BOOST: um número de vírgula flutuante no intervalo [-1,1]. Quando o valor é negativo, os resultados são despromovidos (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 aos quais o aumento é aplicado. O filtro tem de ser avaliado como um valor booleano.
  Para saber mais sobre o aumento da pesquisa estruturada, consulte o artigo Aumente os resultados da pesquisa.
- FACET_SPEC: opcional. Uma especificação de faceta para realizar uma pesquisa com filtros.
- QUERY_EXPANSION_SPEC: opcional. Uma especificação para determinar em que condições deve ocorrer a expansão de consultas. Predefinição é DISABLED.
- SPELL_CORRECTION_SPEC: opcional. Uma especificação para determinar em que condições deve ocorrer a correção ortográfica. Predefinição é AUTO.
- CONTENT_SEARCH_SPEC: opcional. Para receber fragmentos, respostas extrativas, segmentos extrativos e resumos de pesquisa. Apenas para dados não estruturados. Para mais informações, consulte:
  - Use fragmentos e conteúdo extrativo
  - Receba resumos de pesquisas
- DATA_STORE_SPEC: filtra uma loja de dados específica na qual pesquisar. Isto pode ser usado se a sua app de pesquisa estiver ligada a várias bases de dados. Para mais informações, consulte o artigo DataStoreSpec.
- Visualizar resultados da pesquisa guiada na resposta de pesquisa:
  
  Os resultados da pesquisa guiada são devolvidos com as respostas da pesquisa para a 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. Isto permite aos utilizadores refinar os resultados da pesquisa através da utilização de algumas chaves de atributos e valores como filtros.
  
  Neste exemplo de resposta, a cor verde foi usada para refinar os resultados da pesquisa através da emissão de um novo pedido 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"
    }
  ]
}
}
```

Obtenha classificações de relevância de documentos com os resultados da pesquisa

As pontuações de relevância do documento baseiam-se na semelhança da consulta com o documento. As pontuações são colocadas em 11 contentores no intervalo: 0, 0,1, 0,2, … a 1,0. Quanto mais elevada for a pontuação, mais relevante é o documento.

Considere as pontuações de relevância dos documentos para estes exemplos de utilização:

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 outras aplicações
Depuração: as classificações de relevância podem fornecer informações sobre o motivo pelo qual alguns resultados da pesquisa são devolvidos

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

  "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: certifique-se de que a app de pesquisa está associada a um arquivo de dados estruturados ou não estruturados.

REST

Para pedir que as classificações de relevância dos documentos sejam devolvidas com os resultados da pesquisa, use o método engines.servingConfigs.search da seguinte forma:

Encontre o ID da app. Se já tiver o ID da app, avance para o passo seguinte.
1. Na Google Cloud consola, aceda à página Gemini Enterprise.
  
  Aceda a Apps
2. Na página Apps, encontre o nome da sua app e obtenha o ID da app na coluna ID.

Execute o seguinte comando curl para obter as classificações devolvidas 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: o ID do seu projeto.
APP_ID: o ID da app que quer consultar.
QUERY: o texto da consulta a pesquisar.

Comando de exemplo 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 da pesquisa difere consoante o modelo

Se gerar resumos de pesquisa para as suas consultas, pode reparar que os resumos diferem entre os resultados da consola e os resultados da API. Se vir esta mensagem, o motivo provável é que a consola está a usar um modelo de MDG diferente do da API. Os exemplos de curl e código nesta página usam o modelo de GML estável.

Para alterar ou ver o modelo de MDG usado na página Pré-visualização da IU, aceda à página Configurações > separador IU da sua app.
Para chamadas de métodos, o modelo estável é o modelo predefinido. Para usar um modelo de MDG diferente do modelo estável, consulte os artigos Especifique o modelo de resumo e Especifique o modelo de resposta.