Questa pagina è stata tradotta dall'API Cloud Translation.

Ottenere risultati di ricerca

Questa pagina mostra come visualizzare l'anteprima dei risultati di ricerca utilizzando la console Google Cloud e come ottenere i risultati di ricerca utilizzando l'API.

Inoltre, anziché utilizzare la UI dell'app web, puoi effettuare chiamate API e integrarle nel server o nell'applicazione. Questa pagina include esempi di codice per come eseguire query di ricerca utilizzando le librerie client gRPC con un account di servizio.

Ottenere risultati di ricerca

Puoi visualizzare l'anteprima dei risultati di ricerca dalla console Google Cloud o ottenere i risultati di ricerca utilizzando l'API.

Console

Per utilizzare la console Google Cloud per visualizzare l'anteprima dei risultati di ricerca per un'app con dati strutturati o non strutturati, segui questi passaggi:

Apri la pagina Anteprima nella console.
Digita una query di ricerca.
1. Se hai attivato il completamento automatico nel passaggio 1, vedrai un elenco di suggerimenti per il completamento automatico sotto la barra di ricerca mentre digiti.
(Facoltativo) Se hai collegato più datastore alla tua app, ma vuoi risultati solo da un datastore specifico, seleziona il datastore da cui ottenere i risultati.
Fai clic su Invio per inviare la query.
1. Sotto la barra di ricerca viene visualizzato un elenco di risultati di ricerca.
2. Se non è definita alcuna mappatura degli attributi nella pagina Configurazioni, ogni risultato di ricerca viene visualizzato come un elenco di nomi e valori degli attributi non elaborati.
3. Se sono stati salvati mapping degli attributi nella pagina Configurazioni, i risultati di ricerca mostrano le stesse immagini visualizzate nell'anteprima della pagina Configurazioni.
Se sono state specificate sfaccettature nella pagina Configurazioni, queste vengono visualizzate nello stesso modo.
Fai clic sulla freccia sotto l'elenco dei risultati per caricare la pagina successiva.

REST

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

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

Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.
1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.
  
  Vai ad App
2. Nella pagina App, trova il nome della tua app e recupera il relativo ID dalla colonna ID.
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 per cui vuoi eseguire una query.
- QUERY: il testo della query da cercare.
- USER_PSEUDO_ID: una stringa con codifica UTF-8 che funge da identificatore pseudonimizzato univoco che monitora gli 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. Ecco alcuni aspetti importanti da considerare:
  - Questo identificatore non cambia quando il visitatore accede o esce 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 userPseudoId corrispondente negli eventi utente.
  Per ulteriori informazioni, vedi 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 maggiori informazioni, vedi Filtrare la ricerca di dati strutturati o non strutturati.
- BOOST_SPEC: facoltativo. Una specifica per aumentare o diminuire la visibilità dei documenti. Valori:
  - BOOST: un numero in virgola mobile nell'intervallo [-1,1]. Quando il valore è negativo, i risultati vengono declassati (vengono visualizzati più in basso nei risultati). Quando il valore è positivo, i risultati vengono promossi (vengono visualizzati più in alto nei risultati).
  - CONDITION: un'espressione di filtro di testo per selezionare i documenti a cui viene applicato il boost. Il filtro deve restituire un valore booleano.
  Per scoprire di più sul boost per la ricerca strutturata, consulta Migliorare i risultati di ricerca.
- FACET_SPEC: facoltativo. Una specifica del 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 essere eseguita la correzione ortografica. Il valore predefinito è AUTO.
- CONTENT_SEARCH_SPEC: facoltativo. Per ottenere snippet, risposte estrattive, segmenti estrattivi e riepiloghi della ricerca. Solo per dati non strutturati. Per ulteriori informazioni, vedi:
  - Utilizzare snippet e contenuti estrattivi
  - Ottenere riepiloghi della 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 maggiori informazioni, consulta DataStoreSpec.
- Visualizzazione dei 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 degli attributi estratte in base ai documenti dei risultati di ricerca. In questo modo, gli utenti possono perfezionare i risultati di ricerca utilizzando alcune chiavi e alcuni valori degli 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 del 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, … a 1,0. Più alto è il punteggio, più pertinente è il documento.

Prendi in considerazione i punteggi di pertinenza dei documenti per questi casi d'uso:

Filtraggio post-ricerca in base al punteggio di pertinenza per rimuovere i risultati non pertinenti
Classifica 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 può essere restituito 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 strutturato o non strutturato.

REST

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

Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.
1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.
  
  Vai ad App
2. Nella pagina App, trova il nome della tua app e recupera il relativo ID dalla colonna ID.

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 per cui vuoi eseguire una 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": {}
}

Il riepilogo delle ricerche varia in base al modello

Se generi riepiloghi della ricerca per le tue query, potresti notare che i riepiloghi differiscono tra i risultati della console e quelli dell'API. Se visualizzi questo messaggio, il motivo è probabilmente che la console utilizza un modello LLM diverso dall'API. Gli esempi di curl e di codice 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 è quello predefinito. Per utilizzare un modello LLM diverso dal modello stabile, consulta Specificare il modello di riepilogo e Specificare il modello di risposta.