Method: projects.locations.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/*/dataStores/*/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 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 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 legen Sie UserEvent.user_info.user_id nicht fest.
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 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. 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, nie Documents mit dem storageStatus EXPIRED oder DELETED zurück.
validateOnly

boolean

Verwenden Sie 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 die Empfehlungen

Zulässige Werte:

  • returnDocument: Boolesch. Wenn dieser Wert auf true gesetzt ist, wird in RecommendResponse.RecommendationResult.document das verknüpfte Dokumentobjekt zurückgegeben.
  • returnScore: Boolesch. Wenn dieser Wert auf „true“ gesetzt ist, wird in RecommendResponse.RecommendationResult.metadata die Empfehlungspunktzahl für jedes zurückgegebene Dokument festgelegt. Die angegebene Punktzahl zeigt die Wahrscheinlichkeit für eine Dokumentkonvertierung an, die auf dem Kontext und dem Verlauf des Nutzers basiert.
  • strictFiltering: Boolesch. Standardmäßig „true“. Wenn dieser Wert auf false gesetzt ist, gibt der Dienst allgemeine (ungefilterte) beliebte Dokumente zurück, anstatt leere Ergebnisse, wenn Ihr Filter alle Empfehlungsergebnisse blockiert.
  • diversityLevel: String. Standardmäßig leer. Wenn dieser Wert nicht leer ist, müssen Sie einen der folgenden Werte verwenden:
    • 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 dieser Wert auf „true“ gesetzt ist, 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 Anforderungen an 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.