Questa pagina mostra come ottenere i risultati di ricerca utilizzando l'API.
Puoi effettuare chiamate API e integrarle nel server o nell'applicazione. Questa pagina include esempi di codice per eseguire query di ricerca utilizzando le librerie client gRPC con un service account.
Ottieni risultati di ricerca
Puoi ottenere i risultati di ricerca utilizzando l'API.
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:
Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.
Nella console Google Cloud , vai alla pagina Gemini Enterprise.
Nella pagina App, trova il nome della tua app e recupera l'ID app dalla colonna ID.
Visualizza l'anteprima dei 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 '{ "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 monitora gli utenti. Può avere una lunghezza massima di 128 caratteri. Google consiglia vivamente di utilizzare questo campo perché migliora le prestazioni del modello e la qualità della personalizzazione. Per questo campo puoi utilizzare un cookie HTTP, 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 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 peggiorare 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
userPseudoIdcorrispondente negli eventi utente.
Per saperne di più, 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 sono 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 per dati strutturati o non strutturati.
BOOST_SPEC: facoltativo. Una specifica per aumentare o diminuire la priorità dei documenti. Valori:BOOST: un numero in virgola mobile nell'intervallo [-1,1]. Quando il valore è negativo, i risultati vengono retrocessi (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 Aumenta 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 avvenire 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 di ricerca. Solo per i dati non strutturati. Per saperne di più, vedi:DATA_STORE_SPEC: filtra in base a 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.Visualizzazione dei risultati di ricerca guidata nella risposta di ricerca:
I risultati di ricerca guidata vengono restituiti con le risposte di ricerca per la ricerca strutturata e non strutturata. Il risultato di 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 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" } ] } }
Ottieni 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.
Prendi in considerazione i punteggi di rilevanza dei documenti per i seguenti 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 rilevanza 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 rilevanza 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.
Nella console Google Cloud , vai alla pagina Gemini Enterprise.
Nella pagina App, trova il nome della tua app e recupera l'ID app 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 su cui vuoi eseguire la query.QUERY: il testo della query da cercare.
Il riepilogo della ricerca varia in base al modello
Se generi riepiloghi di ricerca per le tue query, potresti notare che i riepiloghi differiscono tra i risultati della console e quelli dell'API. Se vedi questo messaggio, è probabile che la console utilizzi un modello LLM diverso dall'API. Gli esempi di curl e codice in questa pagina utilizzano il modello LLM stabile.
Per modificare o visualizzare il modello LLM utilizzato nella pagina Anteprima della UI, vai alla pagina Configurazioni > scheda UI per la tua app.
Per le chiamate al metodo, il modello stabile è quello predefinito. Per utilizzare un modello LLM diverso dal modello stabile, consulta Specifica il modello di riassunto e Specifica il modello di risposta.