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

Gibt eine Empfehlung ab, für die ein kontextbezogenes Nutzerereignis erforderlich ist.

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
servingConfig

string

Erforderlich. Vollständiger Ressourcenname eines ServingConfig: projects/*/locations/global/collections/*/engines/*/servingConfigs/* oder projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

Beim Erstellen des Empfehlungssystems wird eine Standardbereitstellungskonfiguration erstellt. Die Engine-ID wird als ID der Standardkonfiguration für die Anzeigenauslieferung verwendet. Für Engine projects/*/locations/global/collections/*/engines/my-engine können Sie beispielsweise projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine für Ihre RecommendationService.Recommend-Anfragen verwenden.

Anfragetext

Der Anfragetext enthält Daten mit folgender Struktur:

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

object (UserEvent)

Erforderlich. Kontext zum Nutzer, zu den Inhalten, die er sich ansieht, und zu den Aktionen, die er ausgeführt hat, um die servingConfigs.recommend-Anfrage auszulösen. Diese Nutzerereignisdetails werden nicht in Nutzerereignisprotokolle aufgenommen. Daher ist für die Ereignisprotokollierung eine separate userEvent-Schreibanfrage erforderlich.

Legen Sie UserEvent.user_pseudo_id oder UserEvent.user_info.user_id nicht für verschiedene Nutzer auf dieselbe feste ID fest. Wenn Sie nicht personalisierte Empfehlungen erhalten möchten (nicht empfohlen, da dies die Modellleistung beeinträchtigen kann), legen Sie stattdessen UserEvent.user_pseudo_id auf eine zufällige eindeutige ID fest und lassen Sie UserEvent.user_info.user_id nicht festgelegt.
pageSize

integer

Maximale Anzahl der zurückzugebenden Ergebnisse. Legen Sie diese Property auf die Anzahl der benötigten Empfehlungsergebnisse fest. Wenn der Wert null ist, wählt der Dienst einen angemessenen Standardwert aus. Der maximal zulässige Wert beträgt 100. Werte über 100 werden auf 100 festgelegt.
filter

string

Filter zum Einschränken von Empfehlungsergebnissen mit einer Längenbeschränkung von 5.000 Zeichen. Derzeit werden nur Filterausdrücke für das Attribut filterTags unterstützt.

Beispiele:

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

Wenn attributeFilteringSyntax im Feld params auf „true“ gesetzt ist, werden attributbasierte Ausdrücke anstelle der oben beschriebenen tagbasierten Syntax erwartet. Beispiele:

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

Wenn Ihr Filter alle Ergebnisse blockiert, gibt die API generische (ungefilterte) beliebte Dokumente zurück. Wenn Sie nur Ergebnisse erhalten möchten, die genau den Filtern entsprechen, setzen Sie strictFiltering in RecommendRequest.params auf true, um stattdessen leere Ergebnisse zu erhalten.

Die API gibt niemals Document mit storageStatus als EXPIRED oder DELETED zurück, unabhängig von den Filteroptionen.
validateOnly

boolean

Verwende für diese Empfehlungsanfrage nur den Validierungsmodus. Wenn auf true festgelegt, wird ein gefälschtes Modell verwendet, das beliebige Dokument-IDs zurückgibt. Der Modus „Nur validieren“ sollte nur zum Testen der API oder verwendet werden, wenn das Modell noch nicht bereit ist.
params

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

Zusätzliche domainspezifische Parameter für die Empfehlungen.

Zulässige Werte:

  • returnDocument: Boolesch. Wenn auf true gesetzt, wird das zugehörige Document-Objekt in RecommendResponse.RecommendationResult.document zurückgegeben.
  • returnScore: Boolesch. Wenn der Wert auf „true“ gesetzt ist, wird der Empfehlungswert für jedes zurückgegebene Dokument in RecommendResponse.RecommendationResult.metadata festgelegt. Die angegebene Punktzahl gibt die Wahrscheinlichkeit einer Dokumentkonvertierung an, die auf dem Kontext und dem Verlauf des Nutzers basiert.
  • strictFiltering: Boolesch. Standardmäßig „true“. Wenn der Wert auf false gesetzt ist, gibt der Dienst allgemeine (ungefilterte) beliebte Dokumente zurück, anstatt leer zu sein, wenn Ihr Filter alle Empfehlungsergebnisse blockiert.
  • diversityLevel: String. Standardmäßig leer. Wenn der Wert nicht leer ist, muss er einer der folgenden Werte sein:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity So haben Sie die Kontrolle auf Anfrageebene und die Empfehlungsergebnisse werden basierend auf der Dokumentkategorie angepasst.
  • attributeFilteringSyntax: Boolesch. Standardmäßig „false“. Wenn „true“, wird das Feld filter gemäß der neuen attributbasierten Syntax interpretiert.
userLabels

map (key: string, value: string)

Die Nutzerlabels, die auf eine Ressource angewendet werden, müssen die folgenden Anforderungen erfüllen:

  • Jede Ressource kann bis zu 64 Labels haben.
  • Jedes Label muss ein Schlüssel/Wert-Paar sein.
  • Schlüssel haben eine Mindestlänge von einem Zeichen und eine maximale Länge von 63 Zeichen und dürfen nicht leer sein. Werte dürfen leer sein und haben eine maximale Länge von 63 Zeichen.
  • Schlüssel und Werte dürfen nur Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche enthalten. Alle Zeichen müssen UTF-8-codiert sein. Internationale Zeichen sind zulässig.
  • Der Schlüsselabschnitt eines Labels darf nur einmal vorkommen. Sie können jedoch denselben Schlüssel für mehrere Ressourcen verwenden.
  • Schlüssel müssen mit einem Kleinbuchstaben oder einem internationalen Zeichen beginnen.

Weitere Informationen finden Sie unter Anforderungen für Labels.

Antworttext

Wenn der Vorgang erfolgreich abgeschlossen wurde, enthält der Antworttext eine Instanz von RecommendResponse.

Autorisierungsbereiche

Erfordert einen der folgenden OAuth-Bereiche:

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

Weitere Informationen finden Sie unter Authentication Overview.

IAM-Berechtigungen

Erfordert die folgende IAM-Berechtigung für die Ressource servingConfig:

  • discoveryengine.servingConfigs.recommend

Weitere Informationen finden Sie in der IAM-Dokumentation.