Method: projects.locations.collections.engines.servingConfigs.searchLite

Esegue una ricerca. Simile al metodo SearchService.Search, ma una versione Lite che consente la chiave API per l'autenticazione, in cui non sono necessari controlli OAuth e IAM.

Questo metodo supporta solo la ricerca di siti web pubblici. Se vengono specificati datastore e motori non associati alla ricerca di siti web pubblici, viene restituito un errore FAILED_PRECONDITION.

Questo metodo può essere utilizzato per un onboarding semplice senza dover implementare un backend di autenticazione. Tuttavia, è consigliabile utilizzare SearchService.Search con i controlli OAuth e IAM richiesti per garantire una migliore sicurezza dei dati.

Richiesta HTTP

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:searchLite

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
servingConfig

string

Obbligatorio. Il nome risorsa della configurazione di pubblicazione servingConfigs.search, ad esempio projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config o projects/*/locations/global/collections/default_collection/dataStores/default_data_store/servingConfigs/default_serving_config. Questo campo viene utilizzato per identificare il nome della configurazione di pubblicazione, l'insieme di modelli utilizzati per eseguire la ricerca.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "branch": string,
  "query": string,
  "imageQuery": {
    object (ImageQuery)
  },
  "pageSize": integer,
  "pageToken": string,
  "offset": integer,
  "oneBoxPageSize": integer,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "filter": string,
  "canonicalFilter": string,
  "orderBy": string,
  "userInfo": {
    object (UserInfo)
  },
  "languageCode": string,
  "regionCode": string,
  "facetSpecs": [
    {
      object (FacetSpec)
    }
  ],
  "boostSpec": {
    object (BoostSpec)
  },
  "params": {
    string: value,
    ...
  },
  "queryExpansionSpec": {
    object (QueryExpansionSpec)
  },
  "spellCorrectionSpec": {
    object (SpellCorrectionSpec)
  },
  "userPseudoId": string,
  "contentSearchSpec": {
    object (ContentSearchSpec)
  },
  "embeddingSpec": {
    object (EmbeddingSpec)
  },
  "rankingExpression": string,
  "rankingExpressionBackend": enum (RankingExpressionBackend),
  "safeSearch": boolean,
  "userLabels": {
    string: string,
    ...
  },
  "naturalLanguageQueryUnderstandingSpec": {
    object (NaturalLanguageQueryUnderstandingSpec)
  },
  "searchAsYouTypeSpec": {
    object (SearchAsYouTypeSpec)
  },
  "displaySpec": {
    object (DisplaySpec)
  },
  "session": string,
  "sessionSpec": {
    object (SessionSpec)
  },
  "relevanceThreshold": enum (RelevanceThreshold),
  "personalizationSpec": {
    object (PersonalizationSpec)
  },
  "relevanceScoreSpec": {
    object (RelevanceScoreSpec)
  },
  "searchAddonSpec": {
    object (SearchAddonSpec)
  }
}
Campi
branch

string

Il nome della risorsa del ramo, ad esempio projects/*/locations/global/collections/default_collection/dataStores/default_data_store/branches/0.

Utilizza default_branch come ID ramo o lascia vuoto questo campo per cercare documenti nel ramo predefinito.
query

string

Query di ricerca non elaborata.
imageQuery

object (ImageQuery)

Query di immagini RAW.
pageSize

integer

Il numero massimo di Document da restituire. Il valore massimo consentito dipende dal tipo di dati. I valori superiori al valore massimo vengono forzati al valore massimo.

  • Siti web con indicizzazione di base: Predefinito 10, Massimo 25.
  • Siti web con indicizzazione avanzata: Predefinita 25, Massima 50.
  • Altro: predefinito 50, massimo 100.

Se questo campo è negativo, viene restituito un INVALID_ARGUMENT.
pageToken

string

Un token di pagina ricevuto da una precedente chiamata SearchService.Search. Forniscilo per recuperare la pagina successiva.

Durante la paginazione, tutti gli altri parametri forniti a SearchService.Search devono corrispondere alla chiamata che ha fornito il token di pagina. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
offset

integer

Un numero intero con indice 0 che specifica l'offset corrente (ovvero la posizione del risultato iniziale tra i Document considerati pertinenti dall'API) nei risultati di ricerca. Questo campo viene preso in considerazione solo se pageToken non è impostato.

Se questo campo è negativo, viene restituito un INVALID_ARGUMENT.

Un offset elevato potrebbe essere limitato a una soglia ragionevole.
oneBoxPageSize

integer

Il numero massimo di risultati da restituire per OneBox. Questo si applica a ogni tipo di OneBox singolarmente. Il numero predefinito è 10.
dataStoreSpecs[]

object (DataStoreSpec)

Specifiche che definiscono i DataStore specifici da cercare, insieme alle configurazioni per questi datastore. Questo aspetto viene preso in considerazione solo per i Engine con più datastore. Per i motori con un unico datastore, devono essere utilizzate le specifiche direttamente sotto SearchRequest.
filter

string

La sintassi del filtro è costituita da un linguaggio di espressione per costruire un predicato da uno o più campi dei documenti da filtrare. L'espressione del filtro è sensibile alle maiuscole.

Se questo campo non è riconoscibile, viene restituito un INVALID_ARGUMENT.

Il filtro in Vertex AI servingConfigs.search viene eseguito mappando la chiave di filtro LHS a una proprietà chiave definita nel backend di Vertex AI servingConfigs.search. Questa mappatura viene definita dal cliente nello schema. Ad esempio, un cliente del settore dei media potrebbe avere un campo "nome" nel proprio schema. In questo caso, il filtro sarà simile a questo: filter --> name:'ANY("king kong")'

Per saperne di più sul filtraggio, inclusi sintassi e operatori di filtro, consulta Filtro.
canonicalFilter

string

Il filtro predefinito applicato quando un utente esegue una ricerca senza selezionare alcun filtro nella pagina di ricerca.

Il filtro applicato a ogni richiesta di ricerca quando è necessario un miglioramento della qualità, ad esempio l'espansione della query. Nel caso in cui una query non abbia un numero sufficiente di risultati, questo filtro verrà utilizzato per determinare se attivare o meno il flusso di espansione della query. Il filtro originale verrà comunque utilizzato per la ricerca con query estesa. Questo campo è vivamente consigliato per ottenere una qualità di ricerca elevata.

Per ulteriori informazioni sulla sintassi dei filtri, consulta SearchRequest.filter.
orderBy

string

L'ordine in cui vengono restituiti i documenti. I documenti possono essere ordinati in base a un campo in un oggetto Document. Lascia il campo vuoto se l'ordine è per pertinenza. L'espressione orderBy è sensibile alle maiuscole.

Per saperne di più sull'ordinamento dei risultati di ricerca sul sito web, vedi Ordinare i risultati di ricerca sul web. Per saperne di più sull'ordinamento dei risultati di ricerca relativi all'assistenza sanitaria, consulta Ordinare i risultati di ricerca relativi all'assistenza sanitaria. Se questo campo non è riconoscibile, viene restituito un INVALID_ARGUMENT.
userInfo

object (UserInfo)

Informazioni sull'utente finale. Consigliato vivamente per l'analisi e la personalizzazione. UserInfo.user_agent viene utilizzato per dedurre deviceType per l'analisi.
languageCode

string

Il codice lingua BCP-47, ad esempio "en-US" o "sr-Latn". Per ulteriori informazioni, vedi Campi standard. Questo campo aiuta a interpretare meglio la query. Se non viene specificato un valore, il codice della lingua della query viene rilevato automaticamente, ma potrebbe non essere preciso.
regionCode

string

Il codice Unicode paese/regione (CLDR) di una località, ad esempio "US" e "419". Per ulteriori informazioni, vedi Campi standard. Se impostato, i risultati verranno migliorati in base al codice regione fornito.
facetSpecs[]

object (FacetSpec)

Specifiche dei facet per la ricerca con facet. Se è vuoto, non vengono restituite sfaccettature.

Sono consentiti massimo 100 valori. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
boostSpec

object (BoostSpec)

Aumenta la specifica per aumentare la visibilità di determinati documenti. Per ulteriori informazioni sul boosting, consulta la sezione Boosting.
params

map (key: string, value: value (Value format))

Parametri di ricerca aggiuntivi.

Solo per la ricerca di siti web pubblici, i valori supportati sono:

  • user_country_code: stringa. Il valore predefinito è vuoto. Se impostato su un valore non vuoto, i risultati vengono limitati o migliorati in base alla località fornita. Ad esempio, user_country_code: "au"

Per i codici disponibili, consulta Codici paese.

  • searchType: doppio. Il valore predefinito è vuoto. Consente la ricerca di elementi diversi dalle pagine web a seconda del valore. L'unico valore non predefinito valido è 1, che attiva la ricerca di immagini. Ad esempio, searchType: 1
queryExpansionSpec

object (QueryExpansionSpec)

La specifica di espansione delle query che specifica le condizioni in cui si verifica l'espansione delle query.
spellCorrectionSpec

object (SpellCorrectionSpec)

La specifica di correzione ortografica che specifica la modalità in cui la correzione ortografica ha effetto.
userPseudoId

string

Un identificatore univoco per il monitoraggio dei visitatori. Ad esempio, questa operazione può essere implementata con un cookie HTTP, che dovrebbe essere in grado di identificare in modo univoco un visitatore su un singolo dispositivo. Questo identificatore univoco non deve cambiare se il visitatore accede o esce dal sito web.

Questo campo NON deve avere un valore fisso come unknown_visitor.

Deve essere lo stesso identificatore di UserEvent.user_pseudo_id e CompleteQueryRequest.user_pseudo_id

Il campo deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 128 caratteri. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
contentSearchSpec

object (ContentSearchSpec)

Una specifica per la configurazione del comportamento della ricerca dei contenuti.
embeddingSpec

object (EmbeddingSpec)

Utilizza l'incorporamento fornito per eseguire un ulteriore recupero semantico dei documenti. Il recupero si basa sul prodotto scalare di SearchRequest.EmbeddingSpec.EmbeddingVector.vector e sull'incorporamento del documento fornito in SearchRequest.EmbeddingSpec.EmbeddingVector.field_path.

Se SearchRequest.EmbeddingSpec.EmbeddingVector.field_path non viene fornito, verrà utilizzato ServingConfig.EmbeddingConfig.field_path.
rankingExpression

string

Facoltativo. L'espressione di ranking controlla il ranking personalizzato dei documenti recuperati. Questa azione sostituisce ServingConfig.ranking_expression. La sintassi e le funzionalità supportate dipendono dal valore di rankingExpressionBackend. Se rankingExpressionBackend non viene fornito, il valore predefinito è RANK_BY_EMBEDDING.

Se rankingExpressionBackend non viene fornito o è impostato su RANK_BY_EMBEDDING, deve essere una singola funzione o più funzioni unite dal segno "+".

  • rankingExpression = function, { " + ", function };

Funzioni supportate:

  • double * relevanceScore
  • double * dotProduct(embedding_field_path)

Variabili della funzione:

  • relevanceScore: parole chiave predefinite, utilizzate per misurare la pertinenza tra query e documento.
  • embedding_field_path: il campo di incorporamento del documento utilizzato con il vettore di incorporamento della query.
  • dotProduct: funzione di embedding tra embedding_field_path e il vettore di embedding della query.

Espressione di ranking di esempio:

Se il documento ha un campo di incorporamento doc_embedding, l'espressione di ranking potrebbe essere 0.5 * relevanceScore + 0.3 * dotProduct(doc_embedding).

Se rankingExpressionBackend è impostato su RANK_BY_FORMULA, sono supportati i seguenti tipi di espressioni (e le combinazioni di questi concatenati utilizzando gli operatori + o *):

  • double
  • signal
  • log(signal)
  • exp(signal)
  • rr(signal, double > 0): trasformazione del rango reciproco con il secondo argomento che è una costante del denominatore.
  • isNan(signal) -- returns 0 if signal is NaN, 1 otherwise.
  • fillNan(signal1, signal2 | double) -- if signal1 is NaN, returns signal2 | double, else returns signal1.

Ecco alcuni esempi di formule di ranking che utilizzano i tipi di espressioni di ranking supportati:

  • 0.2 * semanticSimilarityScore + 0.8 * log(keywordSimilarityScore) -- mostly rank by the logarithm of keywordSimilarityScore with slight semantic_smilarity_score adjustment.
  • 0.2 * exp(fillNan(semanticSimilarityScore, 0)) + 0.3 * isNan(keywordSimilarityScore): classifica in base all'esponente di semanticSimilarityScore, riempiendo il valore con 0 se è NaN.Aggiungi anche la costante 0,3 al punteggio finale se semanticSimilarityScore è NaN.
  • 0.2 * rr(semanticSimilarityScore, 16) + 0.8 * rr(keywordSimilarityScore, 16): per lo più classifica in base al rango reciproco di keywordSimilarityScore con un leggero aggiustamento del rango reciproco di semantic_smilarity_score.

Sono supportati i seguenti indicatori:

  • semanticSimilarityScore: aggiustamento della similarità semantica calcolato utilizzando gli incorporamenti generati da un modello proprietario di Google. Questo punteggio determina la somiglianza semantica di una query di ricerca con un documento.
  • keywordSimilarityScore: l'aggiustamento della corrispondenza delle parole chiave utilizza la funzione di ranking Best Match 25 (BM25). Questo punteggio viene calcolato utilizzando un modello probabilistico per stimare la probabilità che un documento sia pertinente a una determinata query.
  • relevanceScore: aggiustamento della pertinenza semantica che utilizza un modello proprietario di Google per determinare il significato e l'intento alla base della query di un utente nel contesto dei contenuti dei documenti.
  • pctrRank: aggiustamento del tasso di conversione previsto come utilizzo del ranking. La percentuale di clic prevista (pCTR) viene utilizzata per valutare la pertinenza e l'attrattività di un risultato di ricerca dal punto di vista dell'utente. Un pCTR più elevato suggerisce che il risultato ha maggiori probabilità di soddisfare la query e l'intenzione dell'utente, il che lo rende un indicatore prezioso per il ranking.
  • freshnessRank: aggiustamento dell'aggiornamento come ranking
  • documentAge: Il tempo in ore trascorso dall'ultimo aggiornamento del documento, un numero in virgola mobile (ad es. 0,25 significa 15 minuti).
  • topicalityRank: aggiustamento della pertinenza dell'argomento come ranking. Utilizza un modello proprietario di Google per determinare la sovrapposizione basata sulle parole chiave tra la query e il documento.
  • baseRank: il ranking predefinito del risultato
rankingExpressionBackend

enum (RankingExpressionBackend)

Facoltativo. Il backend da utilizzare per la valutazione dell'espressione di ranking.
userLabels

map (key: string, value: string)

Le etichette utente applicate a una risorsa devono soddisfare i seguenti requisiti:

  • Ogni risorsa può avere più etichette, fino a un massimo di 64.
  • Ogni etichetta deve essere una coppia chiave-valore.
  • Le chiavi hanno una lunghezza minima di 1 carattere e una lunghezza massima di 63 caratteri e non possono essere vuote. I valori possono essere vuoti e avere una lunghezza massima di 63 caratteri.
  • Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8 e sono consentiti i caratteri internazionali.
  • La parte della chiave di un'etichetta deve essere univoca. Tuttavia, puoi utilizzare la stessa chiave con più risorse.
  • Le chiavi devono iniziare con una lettera minuscola o un carattere internazionale.

Per ulteriori dettagli, consulta il documento Google Cloud.
naturalLanguageQueryUnderstandingSpec

object (NaturalLanguageQueryUnderstandingSpec)

Facoltativo. Configurazione per le funzionalità di comprensione delle query in linguaggio naturale, ad esempio l'estrazione di filtri di campi strutturati dalla query. Per ulteriori informazioni, consulta questa documentazione. Se naturalLanguageQueryUnderstandingSpec non è specificato, non verrà eseguita alcuna comprensione aggiuntiva delle query in linguaggio naturale.
searchAsYouTypeSpec

object (SearchAsYouTypeSpec)

servingConfigs.search as you type configuration. Supportato solo per la verticale IndustryVertical.MEDIA.
displaySpec

object (DisplaySpec)

Facoltativo. Configurazione per la funzionalità di visualizzazione, ad esempio l'evidenziazione delle corrispondenze nei risultati di ricerca.
session

string

Il nome della risorsa della sessione. Facoltativo.

La sessione consente agli utenti di effettuare chiamate API multi-turn /search o il coordinamento tra chiamate API /search e chiamate API /answer.

Esempio 1 (chiamate API multi-turn /search): chiama l'API /search con l'ID sessione generato nella prima chiamata. In questo caso, la query di ricerca precedente viene presa in considerazione nella posizione della query. Ad esempio, se la prima query è "Come è andata Alphabet nel 2022?" e la query attuale è "E il 2023?", la query attuale verrà interpretata come "Come è andata ad Alphabet nel 2023?".

Esempio n. 2 (coordinamento tra chiamate API /search e chiamate API /answer): chiama l'API /answer con l'ID sessione generato nella prima chiamata. In questo caso, la generazione della risposta avviene nel contesto dei risultati di ricerca della prima chiamata di ricerca.

La funzionalità Multi-turn servingConfigs.search è attualmente in fase GA privata. Utilizza la versione v1alpha o v1beta prima del lancio di questa funzionalità in disponibilità generale pubblica. In alternativa, richiedi l'inserimento nella lista consentita tramite il team di assistenza Google.
sessionSpec

object (SessionSpec)

Specifica della sessione.

Può essere utilizzato solo quando è impostato session.
relevanceThreshold

enum (RelevanceThreshold)

La soglia di pertinenza dei risultati di ricerca.

Utilizza la soglia definita da Google, sfruttando un equilibrio tra precisione e richiamo per fornire risultati altamente accurati e una copertura completa delle informazioni pertinenti.

Questa funzionalità non è supportata per la ricerca di servizi sanitari.
personalizationSpec

object (PersonalizationSpec)

La specifica per la personalizzazione.

Tieni presente che se sono impostati sia ServingConfig.personalization_spec che SearchRequest.personalization_spec, SearchRequest.personalization_spec sostituisce ServingConfig.personalization_spec.
relevanceScoreSpec

object (RelevanceScoreSpec)

Facoltativo. La specifica per la restituzione del punteggio di pertinenza.
searchAddonSpec

object (SearchAddonSpec)

Facoltativo. SearchAddonSpec viene utilizzato per disattivare i componenti aggiuntivi per la ricerca in base al nuovo modello di ricalcolo dei prezzi. Questo campo è supportato solo per le richieste di ricerca.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di SearchResponse.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite

Per ulteriori informazioni, consulta Authentication Overview.