Ottenere risultati di ricerca (legacy)

Importante: Gemini Enterprise recupera i risultati di ricerca dall'assistente utilizzando StreamAssist. Ti consigliamo di utilizzare StreamAssist anziché Ricerca e risposta. Per saperne di più, consulta Ottenere risultati di ricerca utilizzando StreamAssist.

Questa pagina mostra come ottenere risultati di ricerca utilizzando l'API.

Puoi effettuare chiamate API e integrarle nel server o nell'applicazione. Questa pagina include esempi di codice su come eseguire query di ricerca utilizzando le librerie client gRPC con un account di servizio.

Nota: a seconda della quantità di dati, la generazione di un'anteprima può richiedere ore dopo importazione dati dati.

Ottenere risultati di ricerca

Puoi ottenere risultati di ricerca utilizzando l'API.

REST

Per utilizzare l'API per ottenere risultati di ricerca per un'app con dati strutturati o non strutturati dati, utilizza il engines.servingConfigs.search metodo:

Nota: puoi eseguire ricerche in un'app utilizzando il engines.servingConfigs.search metodo e in un datastore utilizzando il dataStores.servingConfigs.search metodo. Per la seguente procedura, Google consiglia di eseguire la ricerca utilizzando il metodo engines.servingConfigs.search.

1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

   1. Nella Google Cloud console, vai alla pagina Gemini Enterprise.

      Vai ad App

   2. Nella pagina App, trova il nome dell'app e recupera l'ID dell'app dalla colonna ID.

2. Visualizza l'anteprima dei risultati di ricerca.

   Termine chiave: in Gemini Enterprise, il termine app può essere utilizzato in modo intercambiabile con il termine motore nel contesto delle API. Un motore Gemini Enterprise è un motore di ricerca generico in cui il campo app_type è impostato su 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"}],
   }'
   

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto.
   • APP_ID: l'ID dell'app su cui vuoi eseguire la query.
   • QUERY: il testo della query da cercare.
   • USER_PSEUDO_ID: una stringa con codifica UTF-8, che funge da identificatore pseudonimizzato univoco che tiene traccia degli utenti. Può avere una lunghezza massima di 128 caratteri. Google consiglia vivamente di utilizzare questo campo perché migliora il rendimento del modello e la qualità della personalizzazione. Puoi utilizzare un cookie HTTP per questo campo, che identifica in modo univoco un visitatore su un singolo dispositivo. Di seguito sono riportate alcune considerazioni importanti:
     • Questo identificatore non cambia quando il visitatore esegue l'accesso o la disconnessione da un sito web.
     • Questo campo non deve essere impostato sullo stesso identificatore per più utenti. In caso contrario, l'utilizzo dello stesso ID utente per più utenti può combinare le cronologie degli eventi di utenti diversi e ridurre la qualità del modello.
     • Questo campo non deve includere informazioni che consentono l'identificazione personale (PII).
     • Per una determinata richiesta di ricerca o navigazione, questo campo deve essere mappato al campo corrispondente userPseudoId negli eventi utente.

     Per saperne di più, consulta userPseudoId.

   • PAGE_SIZE: il numero di risultati restituiti dalla ricerca. La dimensione massima consentita della pagina dipende dal tipo di dati. Le dimensioni della pagina superiori al valore massimo vengono forzate al valore massimo.

   • OFFSET: facoltativo. L'indice iniziale dei risultati. Il valore predefinito è 0.

     Ad esempio, se l'offset è 2, la dimensione della pagina è 10 e ci sono 15 risultati da restituire, i risultati da 2 a 11 vengono restituiti nella prima pagina.

   • ORDER_BY: facoltativo. L'ordine in cui vengono disposti i risultati.

   • FILTER: facoltativo. Un campo di testo per filtrare la ricerca utilizzando un'espressione di filtro. Il valore predefinito è una stringa vuota, il che significa che non viene applicato alcun filtro.

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

     Per saperne di più, consulta Filtrare la ricerca di dati strutturati o non strutturati dati.

   • BOOST_SPEC: facoltativo. Una specifica per promuovere o nascondere i documenti. Valori:

     • BOOST: un numero in virgola mobile nell'intervallo [-1,1]. Quando il valore è negativo, i risultati vengono declassati (appaiono più in basso nei risultati). Quando il valore è positivo, i risultati vengono promossi (appaiono più in alto nei risultati).
     • CONDITION: un'espressione di filtro di testo per selezionare i documenti a cui viene applicata la promozione. Il filtro deve restituire un valore booleano.

     Per scoprire di più sulla promozione per la ricerca strutturata, consulta Promuovere i risultati di ricerca.

   • FACET_SPEC: facoltativo. Una specifica di facet per eseguire la ricerca con facet.

   • QUERY_EXPANSION_SPEC: facoltativo. Una specifica per determinare in quali condizioni deve verificarsi l'espansione della query. Il valore predefinito è DISABLED.

   • SPELL_CORRECTION_SPEC: facoltativo. Una specifica per determinare in quali condizioni deve verificarsi la correzione ortografica. Il valore predefinito è AUTO.

   • CONTENT_SEARCH_SPEC: facoltativo. Per ottenere snippet, risposte estrattive, segmenti estrattivi e riepiloghi di ricerca. Solo per dati non strutturati. Per saperne di più, vedi:

     • Utilizzare snippet e contenuti estrattivi
     • Ottenere riepiloghi di ricerca

   • DATA_STORE_SPEC: filtri per un datastore specifico in cui eseguire la ricerca. Può essere utilizzato se l'app di ricerca è collegata a più datastore. Per saperne di più, consulta DataStoreSpec.

   • Visualizzare i risultati della ricerca guidata nella risposta di ricerca:

     I risultati della ricerca guidata vengono restituiti con le risposte di ricerca per la ricerca strutturata e non strutturata. Il risultato della ricerca guidata contiene un elenco di coppie chiave-valore di attributi estratti in base ai documenti dei risultati di ricerca. In questo modo, gli utenti possono perfezionare i risultati di ricerca utilizzando alcune chiavi e valori di attributi come filtri.

     In questa risposta di esempio, il colore verde è stato utilizzato per perfezionare i risultati di ricerca inviando una nuova richiesta di ricerca con il campo filtro specificato come _gs.color: ANY("green"):

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

Ottenere i punteggi di pertinenza dei documenti con i risultati di ricerca

I punteggi di pertinenza dei documenti si basano sulla somiglianza della query con il documento. I punteggi vengono inseriti in 11 bucket nell'intervallo: 0, 0.1, 0.2, … fino a 1.0. Più alto è il punteggio, più pertinente è il documento.

Considera i punteggi di pertinenza dei documenti per questi casi d'uso:

• Filtro post-ricerca basato sul punteggio di pertinenza per rimuovere i risultati non pertinenti

• Ranking post-ricerca o come input per altre applicazioni

• Debug: i punteggi di pertinenza possono fornire informazioni sul motivo per cui vengono restituiti alcuni risultati di ricerca

Per ogni risultato di ricerca, è possibile restituire un punteggio di pertinenza:

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

Vedi anche il comando di esempio nella procedura riportata di seguito.

Prima di iniziare: assicurati che l'app di ricerca sia associata a un datastore di dati strutturati o non strutturati.

REST

Per richiedere che i punteggi di pertinenza dei documenti vengano restituiti con i risultati di ricerca, utilizza il engines.servingConfigs.search metodo come segue:

Nota: i punteggi potrebbero non essere sempre restituiti. Assicurati che la post-elaborazione dei risultati di ricerca non si basi sulla presenza dei punteggi.

1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

   1. Nella Google Cloud console, vai alla pagina Gemini Enterprise.

      Vai ad App

   2. Nella pagina App, trova il nome dell'app e recupera l'ID dell'app dalla colonna ID.

2. Esegui il seguente comando curl per ottenere i punteggi restituiti con i risultati di ricerca.

   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: l'ID progetto.
   • APP_ID: l'ID dell'app su cui vuoi eseguire la query.
   • QUERY: il testo della query da cercare.

   Esempio di comando e risultato parziale

   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": {}
   }
   

Nota: questo punteggio di pertinenza dei documenti è diverso e più preciso del livello di pertinenza utilizzato per filtrare i documenti restituiti da una ricerca.

Il riepilogo della ricerca varia a seconda del modello

Se generi riepiloghi di ricerca per le tue query, potresti notare che i riepiloghi differiscono tra i risultati della console e i risultati dell'API. Se noti questa differenza, il motivo è probabilmente che la console utilizza un modello LLM diverso dall'API. Gli esempi di codice e curl in questa pagina utilizzano il modello LLM stabile.

• Per modificare o visualizzare il modello LLM utilizzato nella pagina Anteprima dell'interfaccia utente, vai alla pagina Configurazioni > scheda UI per la tua app.

• Per le chiamate di metodi, il modello stabile è il modello predefinito. Per utilizzare un modello LLM diverso dal modello stabile, consulta Specificare il modello di riepilogo e Specificare il modello di risposta.