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/v1beta/{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 eine Standardbereitstellungskonfiguration erstellt. Die Engine-ID wird als ID der Standardbereitstellungskonfiguration 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 userEvent-Logs aufgenommen. Daher ist für das Ereignis-Logging 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 benötigten 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 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 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 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, 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 true festgelegt 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 auf true gesetzt, wird das zugehörige Dokumentobjekt in RecommendResponse.RecommendationResult.document zurückgegeben.
  • returnScore: Boolesch. Wenn auf „true“ gesetzt, wird die Empfehlungsquote für jedes zurückgegebene Dokument in RecommendResponse.RecommendationResult.metadata festgelegt. Die angegebene Quote 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 eines leeren Werts, 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“ festgelegt 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
  • https://www.googleapis.com/auth/discoveryengine.serving.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.