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

Fornisce un suggerimento, che richiede un evento utente contestuale.

Richiesta HTTP

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

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
servingConfig

string

Obbligatorio. Nome completo della risorsa di un ServingConfig: projects/*/locations/global/collections/*/engines/*/servingConfigs/* o projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

Viene creata una configurazione di pubblicazione predefinita insieme al motore per suggerimenti. L'ID motore viene utilizzato come ID della configurazione di pubblicazione predefinita. Ad esempio, per Engine projects/*/locations/global/collections/*/engines/my-engine, puoi utilizzare projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine per le richieste RecommendationService.Recommend.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
Campi
userEvent

object (UserEvent)

Obbligatorio. Contesto dell'utente, cosa sta guardando e quale azione ha intrapreso per attivare la richiesta servingConfigs.recommend. Tieni presente che questo dettaglio dell'evento utente non verrà importato nei log userEvent. Pertanto, per la registrazione degli eventi è necessaria una richiesta di scrittura userEvent separata.

Non impostare UserEvent.user_pseudo_id o UserEvent.user_info.user_id sullo stesso ID fisso per utenti diversi. Se stai cercando di ricevere consigli non personalizzati (non consigliato, in quanto può influire negativamente sul rendimento del modello), imposta UserEvent.user_pseudo_id su un ID univoco casuale e lascia UserEvent.user_info.user_id non impostato.
pageSize

integer

Il numero massimo di risultati da restituire. Imposta questa proprietà sul numero di risultati dei suggerimenti necessari. Se è zero, il servizio sceglie un valore predefinito ragionevole. Il valore massimo consentito è 100. I valori superiori a 100 vengono impostati su 100.
filter

string

Filtro per limitare i risultati dei suggerimenti con un limite di lunghezza di 5000 caratteri. Al momento sono supportate solo le espressioni di filtro sull'attributo filterTags.

Esempi:

  • (filterTags: ANY("Red", "Blue") OR filterTags: ANY("Hot", "Cold"))
  • (filterTags: ANY("Red", "Blue")) AND NOT (filterTags: ANY("Green"))

Se attributeFilteringSyntax è impostato su true nel campo params, sono previste espressioni basate sugli attributi anziché la sintassi basata sui tag descritta sopra. Esempi:

  • (language: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
  • (available: true) AND (language: ANY("en", "es")) OR (categories: ANY("Movie"))

Se il filtro blocca tutti i risultati, l'API restituisce documenti popolari generici (non filtrati). Se vuoi solo risultati che corrispondano esattamente ai filtri, imposta strictFiltering su true in RecommendRequest.params per ricevere risultati vuoti.

Tieni presente che l'API non restituisce mai Document con storageStatus come EXPIRED o DELETED indipendentemente dalle scelte di filtro.
validateOnly

boolean

Utilizza la modalità di sola convalida per questa query di suggerimento. Se impostato su true, viene utilizzato un modello fittizio che restituisce ID documento arbitrari. Tieni presente che la modalità di sola convalida deve essere utilizzata solo per testare l'API o se il modello non è pronto.
params

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

Parametri aggiuntivi specifici del dominio per i consigli.

Valori consentiti:

  • returnDocument: booleano. Se impostato su true, l'oggetto Documento associato viene restituito in RecommendResponse.RecommendationResult.document.
  • returnScore: booleano. Se impostato su true, il punteggio di raccomandazione corrispondente a ogni documento restituito viene impostato in RecommendResponse.RecommendationResult.metadata. Il punteggio indicato indica la probabilità di conversione di un documento in base al contesto e alla cronologia dell'utente.
  • strictFiltering: booleano. Il valore predefinito è true. Se impostato su false, il servizio restituisce documenti popolari generici (non filtrati) anziché vuoti se il filtro blocca tutti i risultati dei consigli.
  • diversityLevel: stringa. Il valore predefinito è vuoto. Se è impostato su un valore non vuoto, deve essere uno dei seguenti:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity In questo modo, il controllo viene eseguito a livello di richiesta e i risultati dei suggerimenti vengono modificati in base alla categoria del documento.
  • attributeFilteringSyntax: booleano. False per impostazione predefinita. Se impostato su true, il campo filter viene interpretato in base alla nuova sintassi basata sugli attributi.
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 saperne di più, consulta la sezione Requisiti per le etichette.

Corpo della risposta

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

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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

Per ulteriori informazioni, consulta Authentication Overview.

Autorizzazioni IAM

Richiede la seguente autorizzazione IAM per la risorsa servingConfig:

  • discoveryengine.servingConfigs.recommend

Per saperne di più, consulta la documentazione di IAM.