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

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

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Pfadparameter

Parameter
servingConfig

string

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

Beim Erstellen des Empfehlungssystems wird auch eine Standardbereitstellungskonfiguration erstellt. Die Engine-ID wird als ID der Standardbereitstellungskonfiguration verwendet. Für die Engine projects/*/locations/global/collections/*/engines/my-engine können Sie für Ihre RecommendationService.Recommend-Anfragen beispielsweise projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine 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 angesehenen Inhalten und den Aktionen, die ausgeführt wurden, um die „servingConfigs.recommend“-Anfrage auszulösen. Diese Nutzerereignisdetails werden jedoch nicht in die „userEvent“-Logs aufgenommen. Daher ist für die Ereignisprotokollierung eine separate „userEvent“-Schreibanfrage erforderlich.

Legen Sie für verschiedene Nutzer nicht dieselbe feste ID für UserEvent.user_pseudo_id oder UserEvent.user_info.user_id fest. Wenn Sie nicht personalisierte Empfehlungen erhalten möchten (nicht empfohlen, da dies die Modellleistung beeinträchtigen kann), legen Sie UserEvent.user_pseudo_id stattdessen 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 dieses Attribut auf die Anzahl der gewünschten Empfehlungsergebnisse fest. Wenn der Wert null ist, wählt der Dienst einen angemessenen Standardwert aus. Der maximal zulässige Wert ist 100. Werte über 100 werden auf 100 festgelegt.
filter

string

Filter zum Einschränken der Empfehlungsergebnisse mit einer Längenbeschränkung von 5.000 Zeichen. Aktuell 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 Tag-basierten 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 allgemeine (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, unabhängig von den Filtereinstellungen, niemals Documents mit dem storageStatus EXPIRED oder DELETED zurück.
validateOnly

boolean

Verwendet für diese Empfehlungsanfrage den Modus „Nur validieren“. Wenn dieser Wert auf true gesetzt ist, wird ein fiktives Modell verwendet, das beliebige Dokument-IDs zurückgibt. Der Modus „Nur validieren“ sollte nur zum Testen der API verwendet werden oder wenn das Modell noch nicht bereit ist.
params

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

Zusätzliche domainspezifische Parameter für Empfehlungen

Zulässige Werte:

  • returnDocument: boolesch. Wenn auf true gesetzt, wird in RecommendResponse.RecommendationResult.document das verknüpfte Dokumentobjekt zurückgegeben.
  • returnScore: boolesch. Wenn auf „true“ gesetzt, wird in RecommendResponse.RecommendationResult.metadata die Empfehlungspunktzahl für jedes zurückgegebene Dokument festgelegt. Die angegebene Punktzahl zeigt die Wahrscheinlichkeit für eine Dokument-Conversion an, basierend auf dem Kontext und dem Verlauf des Nutzers.
  • strictFiltering: boolesch. Standardmäßig „true“. Wenn auf false gesetzt, gibt der Dienst allgemeine (ungefilterte) beliebte Dokumente zurück, anstatt leere Ergebnisse, wenn Ihr Filter alle Empfehlungsergebnisse blockiert.
  • diversityLevel: String. Standardmäßig leer. Wenn nicht leer, muss einer der folgenden Werte angegeben werden:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity – Damit haben Sie Steuerungsmöglichkeiten auf Anfrageebene und die Empfehlungsergebnisse werden anhand der Dokumentkategorie angepasst.
  • attributeFilteringSyntax: boolesch. Standardmäßig „false“. Wenn auf „true“ gesetzt, wird das Feld filter gemäß der neuen, attributbasierten Syntax interpretiert.
userLabels

map (key: string, value: string)

Für die auf Ressourcen angewendeten Nutzerlabels gilt Folgendes:

  • Jede Ressource kann bis zu 64 Labels haben.
  • Jedes Label muss ein Schlüssel/Wert-Paar sein.
  • Schlüssel sind mindestens 1 Zeichen und höchstens 63 Zeichen lang 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 Labels für Projekte erstellen und aktualisieren.

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.